+
−At the level of provided functionality and architectural structure, ETSI GSM
+
−specifications for DTX (discontinuous transmission) are very symmetric between
+
−FR and EFR: the same DTX functionality is specified for both codecs, with the
+
−same overall architecture.  However, there is one important difference: in the
+
−case of EFR the complete implementation of all DTX functions (for both Tx and
+
−Rx) forms an integral and inseparable part of the reference codec (implemented
+
−in C) from the beginning, whereas in the case of FR1 the addition of DTX is
+
−somewhat of an afterthought.  GSM 06.10 defines a "pure" FR codec without any
+
−DTX functions, and this most basic spec can be and has been implemented in this
+
−"pure" form - classic Unix libgsm from 1990s is a proper, fully compliant
+
−implementation of GSM 06.10, but only this spec, without any DTX.  In contrast,
+
−there has never existed a "pure" implementation of GSM 06.60 EFR codec without
+
−associated Tx and Rx DTX functions.  Furthermore, there is an important
+
−distinction between Tx and Rx DTX handlers for FR1:
+
−
+
−* Anyone who seeks to implement Tx DTX for FR1 would have to dig into the guts
+
−  of GSM 06.10 encoder and augment it with VAD and SID encoding functions per
+
−  GSM 06.32 and 06.12 specs.
+
−
+
−* In contrast, the Rx DTX handler for FR1 is modular: the way it is specified
+
−  in GSM 06.11, 06.12 and 06.31 is a front-end to unmodified GSM 06.10 decoder.
+
−  On the Rx side, the interface from the radio subsystem to the Rx DTX handler
+
−  consists of 260 bits of frame plus BFI and TAF flags (the spec also defines a
+
−  SID flag, but it is determined from frame payload bits), and then the
+
−  interface from the Rx DTX handler to the GSM 06.10 decoder is another FR frame
+
−  of 260 bits.
+
−
+
−What are the implications of this situation for the GSM published-source
+
−software community?  Prior to the present libgsmfrp offering, there has always
+
−been libgsm, but no Rx DTX handler.  If you are working with a GSM uplink RTP
+
−stream from a BTS or a GSM downlink frame stream read out of TI Calypso DSP or
+
−some other GSM MS PHY, feeding that stream directly to libgsm (without passing
+
−through an Rx DTX handler) is NOT acceptable: a "bare" GSM 06.10 decoder won't
+
−recognize SID frames and won't produce the expected comfort noise output, and
+
−what are you going to do in those 20 ms windows in which no good traffic frame
+
−was received?  The situation becomes especially bad (unkind on ears) if you are
+
−reading received downlink frames out of TI Calypso DSP: the DSP's buffer will
+
−have *some* bit content in every 20 ms window, but naturally this bit content
+
−will be garbage during those frame windows when no good frame was received;
+
−feeding that garbage to libgsm produces noises that are very unkind on ears.
+
−
+
−The correct solution is to implement an Rx DTX handler, pass the stream of
+
−frames and flags from the BTS or the MS PHY to this handler first, and then pass
+
−the output of this handler to libgsm 06.10 decoder.  Themyscira libgsmfrp is a
+
−Free Software implementation of Rx DTX handler for GSM FR, implementing SID
+
−classification, comfort noise generation and error concealment.
+
−
+
−Effect of extra preprocessing
+
−=============================
+
−
+
−One key detail deserves extra emphasis before going into library API details:
+
−if the input to libgsmfrp consists entirely of good speech frames (no SID frames
+
−and no BFIs), then the preprocessor becomes an identity transform.  Therefore,
+
−if the output of our libgsmfrp preprocessor were to be fed to an additional
+
−instance of the same further down the processing chain, no extra transformation
+
−of any kind will happen.
+
−
+
−Using libgsmfrp
+
−===============
+
−
+
−The external public interface to Themyscira libgsmfrp consists of a single
+
−header file <gsm_fr_preproc.h>; it should be installed in the same system
+
−include directory as <gsm.h> from libgsm.  Please note that <gsm_fr_preproc.h>
+
−includes <gsm.h>, as needed for gsm_byte and gsm_frame defined types.
+
−
+
−The dialect of C we chose for libgsmfrp is ANSI C (function prototypes), const
+
−qualifier is used where appropriate; however, unlike libgsmefr, the interface
+
−to libgsmfrp is defined in terms of gsm_byte type defined in <gsm.h>, included
+
−from <gsm_fr_preproc.h>.
+
−
+
−State allocation and freeing
+
−============================
+
−
+
−The Rx DTX handler is stateful, hence you will need to allocate a preprocessor
+
−state structure in addition to the usual libgsm state structure for your GSM FR
+
−Rx session.  The necessary function is:
+
−
+
−extern struct gsmfr_preproc_state *gsmfr_preproc_create(void);
+
−
+
−struct gsmfr_preproc_state is an opaque structure to library users: you only get
+
−a pointer which you remember and pass around, but <gsm_fr_preproc.h> does not
+
−give you a full definition of this struct.  As a library user, you don't even
+
−get to know the size of this struct, hence the necessary malloc() operation
+
−happens inside gsmfr_preproc_create().  However, the structure is malloc'ed as
+
−a single chunk, hence when you are done with it, simply call free() on the
+
−pointer you got from gsmfr_preproc_create().
+
−
+
−gsmfr_preproc_create() can fail if the malloc() call inside fails, in which case
+
−it returns NULL.
+
−
+
−Preprocessing good frames
+
−=========================
+
−
+
−For every good traffic frame (BFI=0) you receive from the radio subsystem, you
+
−need to call this preprocessor function:
+
−
+
−extern void gsmfr_preproc_good_frame(struct gsmfr_preproc_state *state,
+
−				     gsm_byte *frame);
+
−
+
−The second argument is both input and output, i.e., the frame is modified in
+
−place.  If the received frame is not SID (specifically, if the SID field
+
−deviates from the SID codeword by 16 or more bits, per GSM 06.31 section 6.1.1),
+
−then the frame (considered a good speech frame) will be left unmodified (i.e.,
+
−it is to be passed unchanged to the GSM 06.10 decoder), but preprocessor state
+
−will be updated.  OTOH, if the received frame is classified as either valid or
+
−invalid SID per GSM 06.31, then the output frame will contain comfort noise
+
−generated by the preprocessor using a PRNG, or a silence frame in one particular
+
−corner case.
+
−
+
−GSM-FR RTP (or libgsm) 0xD magic: the upper nibble of the first byte can be
+
−anything on input to gsmfr_preproc_good_frame(), but the output frame will
+
−always have the correct magic in it.
+
−
+
−Handling BFI conditions
+
−=======================
+
−
+
−If you received a lost/missing frame indication instead of a good traffic frame,
+
−call this preprocessor function:
+
−
+
−extern void gsmfr_preproc_bfi(struct gsmfr_preproc_state *state, int taf,
+
−			      gsm_byte *frame_out);
+
−
+
−TAF is a flag defined in GSM 06.31 section 6.1.1; if you don't have this flag,
+
−pass 0 - you will lose the function of comfort noise muting in the event of
+
−prolonged SID loss, but all other Rx DTX functions will still work the same.
+
−
+
−With this function the 33-byte frame buffer is only an output, i.e., prior
+
−buffer content is a don't-care and there is no provision for making any use of
+
−erroneous frames like in EFR.  The frame generated by the preprocessor may be
+
−substitution/muting, comfort noise or silence depending on the state.
+
−
+
−Other miscellaneous functions
+
−=============================
+
−
+
−extern void gsmfr_preproc_reset(struct gsmfr_preproc_state *state);
+
−
+
−This function resets the preprocessor state to what it is right out of
+
−gsmfr_preproc_create(), which is naturally just a combination of malloc() and
+
−gsmfr_preproc_reset().  Given that our Rx DTX handler state is much simpler
+
−than, for example, EFR codec state, there does not seem to be any need for
+
−explicit resets, but the reset function is made public for the sake of
+
−completeness.
+
−
+
−extern int gsmfr_preproc_sid_classify(const gsm_byte *frame);
+
−
+
−This function analyzes an RTP-encoded FR frame (the upper nibble of the first
+
−byte is NOT checked for 0xD signature) for the SID codeword of GSM 06.12 and
+
−classifies the frame as SID=0, SID=1 or SID=2 per the rules of GSM 06.31
+
−section 6.1.1.
+
−
+
−Silence frame datum
+
−===================
+
−
+
−extern const gsm_frame gsmfr_preproc_silence_frame;
+
−
+
−Many implementors make the mistake of thinking that a GSM FR silence frame is a
+
−frame of 260 zero bits, but the official specs disagree: the silence frame given
+
−in GSM 06.11 (3GPP TS 46.011, at the very end of the spec) is quite different.
+
−Themyscira libgsmfrp implements the correct silence frame per the spec, and that
+
−datum is also made public.
+
−
+
−libgsmfrp change history: version 1.0.1 to version 1.0.2
+
−========================================================
+
−
+
−There are only two changes, both involving corner cases with invalid SID frames
+
−being received:
+
−
+
−1) An invalid SID frame was received immediately following a good speech frame.
+
−   In this case we start CN generation, but we take the needed LARc and Xmaxc
+
−   parameters from the last speech frame, instead of the usual procedure of
+
−   extracting them from a valid SID frame.  The change from 1.0.1 to 1.0.2
+
−   concerns the Xmaxc parameter in this corner case: in 1.0.1 we took Xmaxc
+
−   from the last subframe and used it for ensuing CN generation, but in 1.0.2
+
−   we compute a more proper mean Xmaxc from all 4 subframes, by dequantizing,
+
−   summing and requantizing.
+
−
+
−2) An invalid SID frame was received in the speech muting state.  The sequence
+
−   of inputs would have to be:
+
−
+
−   - a good speech frame;
+
−   - one or more BFIs, but not too many, so that the cached speech frame
+
−     does not decay fully by Xmaxc reduction;
+
−   - an invalid SID frame.
+
−
+
−   In version 1.0.1 we handled this even more obscure corner case by entering
+
−   the CN muting state, i.e., the state that is normally entered upon the
+
−   second lost SID.  In version 1.0.2 we ignore invalid SID in the speech
+
−   muting state and act as if we got BFI, i.e., continue speech muting rather
+
−   than switch to CN muting.
+
−
+
−libgsmfrp change history: version 1.0.0 to version 1.0.1
+
−========================================================
+
−
+
−Version 1.0.0 exhibited the following defects, which are fixed in 1.0.1:
+
−
+
−1) The last received valid SID was cached forever for the purpose of
+
−   handling future invalid SIDs - we could have received some valid
+
−   SID ages ago, then lots of speech or NO_DATA, and if we then get
+
−   an invalid SID, we would resurrect the last valid SID from ancient
+
−   history - a bad design.  In our new design, we handle invalid SID
+
−   based on the current state, much like BFI.
+
−
+
−2) GSM 06.11 spec says clearly that after the second lost SID
+
−   (received BFI=1 && TAF=1 in CN state) we need to gradually decrease
+
−   the output level, rather than jump directly to emitting silence
+
−   frames - we previously failed to implement such logic.
+
−
+
−3) Per GSM 06.12 section 5.2, Xmaxc should be the same in all 4 subframes
+
−   in a SID frame.  What should we do if we receive an otherwise valid
+
−   SID frame with different Xmaxc?  Our previous approach would
+
−   replicate this Xmaxc oddity in every subsequent generated CN frame,
+
−   which is rather bad.  In our new design, the very first CN frame
+
−   (which can be seen as a transformation of the SID frame itself)
+
−   retains the original 4 distinct Xmaxc, but all subsequent CN frames
+
−   are based on the Xmaxc from the last subframe of the most recent SID.