annotate doc/FR1-library-desc @ 581:e2d5cad04cbf

libgsmhr1 RxFE: store CN R0+LPC separately from speech In the original GSM 06.06 code the ECU for speech mode is entirely separate from the CN generator, maintaining separate state. (The main intertie between them is the speech vs CN state variable, distinguishing between speech and CN BFIs, in addition to the CN-specific function of distinguishing between initial and update SIDs.) In the present RxFE implementation I initially thought that we could use the same saved_frame buffer for both ECU and CN, overwriting just the first 4 params (R0 and LPC) when a valid SID comes in. However, I now realize it was a bad idea: the original code has a corner case (long sequence of speech-mode BFIs to put the ECU in state 6, then SID and CN-mode BFIs, then a good speech frame) that would be broken by that buffer reuse approach. We could eliminate this corner case by resetting the ECU state when passing through a CN insertion period, but doing so would needlessly increase the behavioral diffs between GSM 06.06 and our version. Solution: use a separate CN-specific buffer for CN R0+LPC parameters, and match the behavior of GSM 06.06 code in this regard.
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 13 Feb 2025 10:02:45 +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.