FreeCalypso > hg > gsm-codec-lib

annotate doc/FR1-library-desc @ 533:3a617e4e9b27

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
libgsmfr2: add const words with struct sizes
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 19 Sep 2024 21:58:10 +0000
parents 6b479cfb06a4
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
297
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 Themyscira libgsmfr2 is our new (2024) library offering for GSM FRv1 codec,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 replacing the previous combination of libgsm (classic 1990s free sw offering)
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 and libgsmfrp (our add-on). That combination appeared satisfactory at first
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 because of how the decoder processing chain is defined for FRv1 (the Rx DTX
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 handler forms a modular piece, passing a frame of 260 bits to unmodified "pure"
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 GSM 06.10 decoder), but use of legacy libgsm presents some difficulties:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 * Inconvenience and inconsistency: for all other supported GSM speech codecs,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 Themyscira libraries provide the complete solution, not depending on anyone
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 else's software, but for FRv1 we depended on a library that was created in a
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 different era for non-GSM applications but just happens, almost by accident,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 to be a bit-exact implementation of GSM 06.10 spec.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 * Poor design in frame packing and unpacking functions: the operations of
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 bit-shuffling a GSM-FR codec frame between the array of parameters form
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 (76 words) and the packed RTP format used in IP-based GSM RAN (33 bytes) are
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 stateless pure functions, but their implementations in libgsm (gsm_explode()
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 and gsm_implode()) require a state structure. (Libgsm supports WAV49 format
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 in addition to the RTP-adopted one, and WAV49 packing is stateful - but this
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 WAV49 feature is of no use and no relevance in real GSM applications.)
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 * No ability to implement homing: the internal state structure used by libgsm
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 is set to the home state when it is allocated with gsm_create(), but there is
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 no reset function, and such function cannot be implemented externally when
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 the state structure is private to the library and not exposed. Therefore,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 the optional codec homing feature defined in later versions of GSM 06.10 spec
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 cannot be implemented in a wrapper around legacy libgsm, causing the resulting
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 FOSS implementation to be inferior to existing commercial implementations
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 (deployed in practice by incumbent nation-scale networks) which do implement
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 this feature.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 In response to the above issues, we now have a new library named libgsmfr2 that
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 provides all needed functions for GSM-FR codec "under one roof", harmonized
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 with our support for other GSM speech codecs. However, the modularity that is
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 inherent in the way this codec is defined in the specs (contrast with EFR) is
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 still retained in the design of our library, which exhibits the following 4
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 functional divisions:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 1) Libgsmfr2 includes a "pure" GSM 06.10 encoder and decoder, directly
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 corresponding to old libgsm. This code is in fact lifted from libgsm,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 ported into Themyscira gsm-codec-lib style in terms of C dialect, defined
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 types and naming conventions. The reset function that is missing in libgsm
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 is now provided, however, fixing that defect.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 2) The Rx DTX handler component is unchanged from our previous libgsmfrp. Per
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 the relevant specs (GSM 06.11, 06.12 and 06.31) this component is a modular
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 piece: it emits a standard 260-bit frame of GSM 06.10 parameters that can be
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 fed to anyone else's implementation of the latter standard.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 3) Full decoder: this component is a wrapper around an 06.10 decoder instance
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 and an Rx DTX instance, providing functionality equivalent to the standard
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 decoder function in other GSM speech codecs.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 4) Stateless utility functions for frame format conversions (packing and
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 unpacking) and for incoming SID classification. An application can freely
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 use just these functions, without pulling in any encoder or decoder or
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 stateful preprocessor functionality, making the present library very
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 convenient for debug utilities.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 The homing feature is available in both encoder and decoder directions, but it
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 is implemented differently between the two:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 * In the encoder direction, if the application wishes to enable the possibility
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 of in-band homing, it needs to call gsmfr_0610_encoder_homing() after the
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 regular call to gsmfr_0610_encode_frame() or gsmfr_0610_encode_params().
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 * In the decoder direction, the homing feature is always included if one uses
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 the "fulldec" (full decoder) wrapper (it is implemented in that layer), and
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 never included if one uses the "basic" GSM 06.10 decoder by itself, or the
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 Rx DTX handler block by itself.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 The only major feature of GSM-FR codec that is currently absent in libgsmfr2 is
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 application of DTX in the encoder direction: GSM 06.32 VAD followed by DTX
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 hangover logic and SID output. This omission is currently acceptable for
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 Themyscira Wireless: DTXd (DTX in the radio downlink direction) is not allowed
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 when each BTS operates at only one carrier frequency, which makes it pointless
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 to enable DTX for speech encoding at the network edge transcoder, and we are not
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 trying to replace TI Calypso DSP on the MS side of GSM. However, if this
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 situation changes and some need arises for a FOSS implementation of DTX-enabled
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 GSM-FR encoder, the architecture of Themyscira libgsmfr2 should make it possible
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 to integrate such addition.