# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1713202196 0
# Node ID a45f806cada90a87cb1254ceb70674e2dfb2c8a6
# Parent  6b479cfb06a4510901420676345d89c349fb3c4c
doc/FR1-library-API: document stateless utility functions

diff -r 6b479cfb06a4 -r a45f806cada9 doc/FR1-library-API
--- a/doc/FR1-library-API	Mon Apr 15 07:12:31 2024 +0000
+++ b/doc/FR1-library-API	Mon Apr 15 17:29:56 2024 +0000
@@ -209,3 +209,44 @@
 gsmfr_fulldec_good_frame() detects decoder homing frames and invokes
 gsmfr_fulldec_reset() when required, and also implements EHF output per the
 spec.
+
+Stateless utility functions
+===========================
+
+Conversions between RTP packed format and broken-down codec parameters are
+stateless and implemented with highly efficient code.  There are two versions;
+this version converts between packed frames and struct gsmfr_param_frame used
+by 06.10 encoder and decoder functions:
+
+void gsmfr_pack_frame(const struct gsmfr_param_frame *param, uint8_t *frame);
+void gsmfr_unpack_frame(const uint8_t *frame, struct gsmfr_param_frame *param);
+
+and this version converts between packed frames and a straight linear array of
+76 parameters:
+
+void gsmfr_pack_from_array(const int16_t *params, uint8_t *frame);
+void gsmfr_unpack_to_array(const uint8_t *frame, int16_t *params);
+
+The latter functions gsmfr_pack_from_array() and gsmfr_unpack_to_array() are
+drop-in replacements for gsm_implode() and gsm_explode() from old libgsm.  The
+order of parameters in this array is the canonical one: first all LARc, then
+all params for the first subframe, then the second subframe, then the third and
+the fourth.  OTOH, struct gsmfr_param_frame uses functional grouping, chosen
+for ease of porting of original libgsm code.
+
+Both unpacking functions (gsmfr_unpack_frame() and gsmfr_unpack_to_array())
+ignore the upper nibble of the first byte, i.e., the 0xD signature is not
+enforced.  However, this signature is always set correctly by gsmfr_pack_frame()
+and gsmfr_pack_from_array(), and also by gsmfr_0610_encode_frame() function
+which calls gsmfr_pack_frame() as its finishing step.
+
+The last remaining stateless utility function performs SID classification of
+received GSM-FR frames:
+
+int gsmfr_preproc_sid_classify(const uint8_t *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.  This classification is the first processing step performed by
+gsmfr_preproc_good_frame().