falconia has uploaded this change for review.
trau_frame cosmetic: document exact behavior for C1..C5
For historical reasons, osmo_trau_frame_encode() API has quirky
behavior with regard to output of control bits C1..C5: for some
frame types these bits are set to user-controlled values taken
from fr->c_bits[], yet for other frame types the function fills
in what it "knows" to be the correct frame type code, ignoring
the first 5 bits out of user-supplied fr->c_bits[]. One particular
combination of frame type and direction is even more bizarre,
taking only fr->c_bits[3] while fixing the other 4 C-bits.
Unfortunately this behavior cannot be changed without breaking
API compatibility with previous released versions, i.e., without
breaking external applications that rely on this library behavior.
Therefore, we do the next best thing: thoroughly and succinctly
document these quirks.
Change-Id: Id1824c7cc8845ee2a730d556bec807c3cfa75beb
---
M src/trau/trau_frame.c
1 file changed, 19 insertions(+), 0 deletions(-)
git pull ssh://gerrit.osmocom.org:29418/libosmo-abis refs/changes/68/39668/1
diff --git a/src/trau/trau_frame.c b/src/trau/trau_frame.c
index b8085c2..652c703 100644
--- a/src/trau/trau_frame.c
+++ b/src/trau/trau_frame.c
@@ -1246,6 +1246,25 @@
* where C1..C5 may need to be modified (especially TFO-AMR where this C1..C5
* modification must be done before CRC computation), please use
* osmo_trau_frame_encode_tfo().
+ *
+ * The following list summarizes the behavior of the present function with
+ * regard to C1..C5 bits for different frame types:
+ *
+ * - For all TRAU-16k frame types in both UL and DL directions, and for
+ * OSMO_TRAU8_SPEECH (TRAU-8k for HRv1 speech) in UL direction, the first 5
+ * bits of fr->c_bits[] are ignored and replaced with internally supplied
+ * constant values.
+ *
+ * - For OSMO_TRAU8_SPEECH in DL direction, only fr->c_bits[3] is used to set
+ * C4; constant values for C1..C3 and odd parity value for C5 are fixed
+ * by the function.
+ *
+ * - For OSMO_TRAU8_DATA, OSMO_TRAU8_OAM and all AMR-8k frame types,
+ * user-supplied fr->c_bits[] are always used.
+ *
+ * This unfortunate manipulation applies only to C1..C5 as listed above;
+ * for control bits C6 and higher (for frame types that have them),
+ * user-supplied fr->c_bits[] are always used.
*/
int osmo_trau_frame_encode(ubit_t *bits, size_t n_bits, const struct osmo_trau_frame *fr)
{
To view, visit change 39668. To unsubscribe, or for help writing mail filters, visit settings.