gsm0503_tch_hr_decode2(): new function, emits TS101318 format

The original design of gsm0503_tch_hr_{en,de}code() functions contains
a mistake in that a pseudo-RFC5993 format was chosen for HR codec frame
input and output, instead of "pure" (agnostic to outer RTP encoding)
form of 14 bytes.  We would like to change this design so that we can
feed pure 14-byte HR codec frames to the channel coding function and
get such frames back from the channel decoding function - however,
we cannot break libosmocoding API for existing users.  In the decoding
direction, create a new function that emits TS 101 318 format, and
turn the legacy gsm0503_tch_hr_decode() API into a wrapper function
for backward compatibility.

Related: OS#5688
Change-Id: If28ddb20789e8993b7558ca08020478615b4c708

3 files changed, 41 insertions, 10 deletions

diff --git a/TODO-RELEASE b/TODO-RELEASE
index 72702572..ebda4c5d 100644
--- a/TODO-RELEASE
+++ b/TODO-RELEASE
@@ -11,3 +11,5 @@ libosmogsm  new header osmocom/gsm/protocol/gsm_44_060.h
 libosmocore ADD     new defines in osmocom/gsm/protocol/gsm_04_08.h (old ones marked deprecated)
 libosmovty	drop API		drop struct vty_parent_node from public API, it should never have been public
 libosmocore ADD     new API osmo_io_*()
+libosmocoding	ADD	new gsm0503_tch_hr_decode2() public API, previous API
+			gsm0503_tch_hr_decode() marked as deprecated
diff --git a/include/osmocom/coding/gsm0503_coding.h b/include/osmocom/coding/gsm0503_coding.h
index 2afa049b..2112b0f8 100644
--- a/include/osmocom/coding/gsm0503_coding.h
+++ b/include/osmocom/coding/gsm0503_coding.h
@@ -50,6 +50,9 @@ int gsm0503_tch_fr_decode(uint8_t *tch_data, const sbit_t *bursts, int net_order
 
 int gsm0503_tch_hr_encode(ubit_t *bursts, const uint8_t *tch_data, int len);
 int gsm0503_tch_hr_decode(uint8_t *tch_data, const sbit_t *bursts, int odd,
+	int *n_errors, int *n_bits_total)
+	OSMO_DEPRECATED("Use gsm0503_tch_hr_decode2() instead");
+int gsm0503_tch_hr_decode2(uint8_t *tch_data, const sbit_t *bursts, int odd,
 	int *n_errors, int *n_bits_total);
 
 int gsm0503_tch_afs_encode(ubit_t *bursts, const uint8_t *tch_data, int len,
diff --git a/src/coding/gsm0503_coding.c b/src/coding/gsm0503_coding.c
index 4f1ac79d..6f76824a 100644
--- a/src/coding/gsm0503_coding.c
+++ b/src/coding/gsm0503_coding.c
@@ -1572,16 +1572,14 @@ static void tch_fr_disassemble(ubit_t *b_bits,
 	}
 }
 
-/* assemble a HR codec frame in format as used inside RTP */
+/* assemble a HR codec frame in the canonical format of ETSI TS 101 318 */
 static void tch_hr_reassemble(uint8_t *tch_data, const ubit_t *b_bits)
 {
-	int i, j;
-
-	tch_data[0] = 0x00; /* F = 0, FT = 000 */
-	memset(tch_data + 1, 0, 14);
+	int i;
 
-	for (i = 0, j = 8; i < 112; i++, j++)
-		tch_data[j >> 3] |= (b_bits[i] << (7 - (j & 7)));
+	memset(tch_data, 0, GSM_HR_BYTES);
+	for (i = 0; i < 112; i++)
+		tch_data[i >> 3] |= (b_bits[i] << (7 - (i & 7)));
 }
 
 static void tch_hr_disassemble(ubit_t *b_bits, const uint8_t *tch_data)
@@ -1977,13 +1975,13 @@ coding_efr_fr:
 }
 
 /*! Perform channel decoding of a HR(v1) channel according TS 05.03
- *  \param[out] tch_data Codec frame in RTP payload format
+ *  \param[out] tch_data Codec frame in TS 101 318 canonical format
  *  \param[in] bursts buffer containing the symbols of 8 bursts
  *  \param[in] odd Odd (1) or even (0) frame number
  *  \param[out] n_errors Number of detected bit errors
  *  \param[out] n_bits_total Total number of bits
  *  \returns length of bytes used in \a tch_data output buffer; negative on error */
-int gsm0503_tch_hr_decode(uint8_t *tch_data, const sbit_t *bursts, int odd,
+int gsm0503_tch_hr_decode2(uint8_t *tch_data, const sbit_t *bursts, int odd,
 	int *n_errors, int *n_bits_total)
 {
 	sbit_t iB[912], cB[456], h;
@@ -2050,7 +2048,35 @@ int gsm0503_tch_hr_decode(uint8_t *tch_data, const sbit_t *bursts, int odd,
 
 	tch_hr_reassemble(tch_data, b);
 
-	return 15;
+	return GSM_HR_BYTES;
+}
+
+/*! Perform channel decoding of a HR(v1) channel according TS 05.03,
+ *  deprecated legacy API.
+ *  \param[out] tch_data Codec frame in pseudo-RFC5993 format
+ *  \param[in] bursts buffer containing the symbols of 8 bursts
+ *  \param[in] odd Odd (1) or even (0) frame number
+ *  \param[out] n_errors Number of detected bit errors
+ *  \param[out] n_bits_total Total number of bits
+ *  \returns length of bytes used in \a tch_data output buffer; negative on error
+ *
+ *  The HR1 codec frame format returned by this function is pseudo-RFC5993,
+ *  not true RFC 5993, as there is no SID classification being done
+ *  and the FT bits in the ToC octet are always set to 0 - but this
+ *  arguably-bogus format is the legacy public API.
+ */
+int gsm0503_tch_hr_decode(uint8_t *tch_data, const sbit_t *bursts, int odd,
+	int *n_errors, int *n_bits_total)
+{
+	int rc;
+
+	rc = gsm0503_tch_hr_decode2(tch_data, bursts, odd, n_errors,
+				    n_bits_total);
+	if (rc != GSM_HR_BYTES)
+		return rc;
+	memmove(tch_data + 1, tch_data, GSM_HR_BYTES);
+	tch_data[0] = 0x00;	/* FT=0, note absence of SID classification */
+	return GSM_HR_BYTES_RTP_RFC5993;
 }
 
 /*! Perform channel encoding on a TCH/HS channel according to TS 05.03