FreeCalypso > hg > gsm-codec-lib
comparison doc/FR1-library-API @ 298:a45f806cada9
doc/FR1-library-API: document stateless utility functions
| author | Mychaela Falconia <falcon@freecalypso.org> |
|---|---|
| date | Mon, 15 Apr 2024 17:29:56 +0000 |
| parents | 6b479cfb06a4 |
| children | 59751c8fc773 |
comparison
equal
deleted
inserted
replaced
| 297:6b479cfb06a4 | 298:a45f806cada9 |
|---|---|
| 207 | 207 |
| 208 The "fulldec" layer also adds the decoder homing feature: | 208 The "fulldec" layer also adds the decoder homing feature: |
| 209 gsmfr_fulldec_good_frame() detects decoder homing frames and invokes | 209 gsmfr_fulldec_good_frame() detects decoder homing frames and invokes |
| 210 gsmfr_fulldec_reset() when required, and also implements EHF output per the | 210 gsmfr_fulldec_reset() when required, and also implements EHF output per the |
| 211 spec. | 211 spec. |
| 212 | |
| 213 Stateless utility functions | |
| 214 =========================== | |
| 215 | |
| 216 Conversions between RTP packed format and broken-down codec parameters are | |
| 217 stateless and implemented with highly efficient code. There are two versions; | |
| 218 this version converts between packed frames and struct gsmfr_param_frame used | |
| 219 by 06.10 encoder and decoder functions: | |
| 220 | |
| 221 void gsmfr_pack_frame(const struct gsmfr_param_frame *param, uint8_t *frame); | |
| 222 void gsmfr_unpack_frame(const uint8_t *frame, struct gsmfr_param_frame *param); | |
| 223 | |
| 224 and this version converts between packed frames and a straight linear array of | |
| 225 76 parameters: | |
| 226 | |
| 227 void gsmfr_pack_from_array(const int16_t *params, uint8_t *frame); | |
| 228 void gsmfr_unpack_to_array(const uint8_t *frame, int16_t *params); | |
| 229 | |
| 230 The latter functions gsmfr_pack_from_array() and gsmfr_unpack_to_array() are | |
| 231 drop-in replacements for gsm_implode() and gsm_explode() from old libgsm. The | |
| 232 order of parameters in this array is the canonical one: first all LARc, then | |
| 233 all params for the first subframe, then the second subframe, then the third and | |
| 234 the fourth. OTOH, struct gsmfr_param_frame uses functional grouping, chosen | |
| 235 for ease of porting of original libgsm code. | |
| 236 | |
| 237 Both unpacking functions (gsmfr_unpack_frame() and gsmfr_unpack_to_array()) | |
| 238 ignore the upper nibble of the first byte, i.e., the 0xD signature is not | |
| 239 enforced. However, this signature is always set correctly by gsmfr_pack_frame() | |
| 240 and gsmfr_pack_from_array(), and also by gsmfr_0610_encode_frame() function | |
| 241 which calls gsmfr_pack_frame() as its finishing step. | |
| 242 | |
| 243 The last remaining stateless utility function performs SID classification of | |
| 244 received GSM-FR frames: | |
| 245 | |
| 246 int gsmfr_preproc_sid_classify(const uint8_t *frame); | |
| 247 | |
| 248 This function analyzes an RTP-encoded FR frame (the upper nibble of the first | |
| 249 byte is NOT checked for 0xD signature) for the SID codeword of GSM 06.12 and | |
| 250 classifies the frame as SID=0, SID=1 or SID=2 per the rules of GSM 06.31 | |
| 251 section 6.1.1. This classification is the first processing step performed by | |
| 252 gsmfr_preproc_good_frame(). |