gsm660.c File Reference

GSM 06.60 - GSM EFR Codec. More...

#include <stdint.h>
#include <stdbool.h>
#include <osmocom/core/bitvec.h>
#include <osmocom/core/utils.h>
#include <osmocom/codec/codec.h>

Functions
bool	osmo_efr_check_sid (const uint8_t *rtp_payload, size_t payload_len)
	Check whether RTP frame contains EFR SID code word according to TS 101 318 §5.3.2. More...
enum osmo_gsm631_sid_class	osmo_efr_sid_classify (const uint8_t *rtp_payload)
	Classify potentially-SID EFR codec frame in RTP format according to the rules of GSM 06.81 §6.1.1. More...
void	osmo_efr_sid_reset (uint8_t *rtp_payload)
	Reset the SID field of a potentially corrupted, but still valid GSM-EFR SID frame in RTP encoding to its pristine state (full SID code word). More...
bool	osmo_efr_sid_preen (uint8_t *rtp_payload)
	Preen potentially-SID EFR codec frame in RTP format, ensuring that it is either a speech frame or a valid SID, and if the latter, making it a perfect, error-free SID frame. More...

Variables
const uint16_t	gsm660_bitorder [260]
static const uint8_t	sid_code_word_bits [95]

Detailed Description

GSM 06.60 - GSM EFR Codec.

Function Documentation

osmo_efr_check_sid()

bool osmo_efr_check_sid	(	const uint8_t *	rtp_payload,
		size_t	payload_len
	)

Check whether RTP frame contains EFR SID code word according to TS 101 318 §5.3.2.

Parameters

[in]	rtp_payload	Buffer with RTP payload
[in]	payload_len	Length of payload

Returns

true if code word is found, false otherwise

References ARRAY_SIZE, bitvec_get_bit_pos(), bitvec::data, bitvec::data_len, ONE, and sid_code_word_bits.

osmo_efr_sid_classify()

enum osmo_gsm631_sid_class osmo_efr_sid_classify

(

const uint8_t *

rtp_payload

)

Classify potentially-SID EFR codec frame in RTP format according to the rules of GSM 06.81 §6.1.1.

Parameters

[in]

rtp_payload

Buffer with RTP payload

Returns

enum osmo_gsm631_sid_class, with symbolic values OSMO_GSM631_SID_CLASS_SPEECH, OSMO_GSM631_SID_CLASS_INVALID or OSMO_GSM631_SID_CLASS_VALID corresponding to the 3 possible bit-counting classifications prescribed by the spec.

Differences between the more familiar osmo_efr_check_sid() and the present function are:

1. osmo_efr_check_sid() returns true only if the SID frame is absolutely perfect, with all 95 bits of the SID code word set. However, the rules of GSM 06.81 §6.1.1 allow up to one bit to be in error, and the frame is still accepted as valid SID.
2. The third possible state of invalid SID is not handled at all by the simpler osmo_efr_check_sid() function.
3. osmo_efr_check_sid() includes a check for 0xC RTP signature, and returns false if that signature nibble is wrong. That check is not included in the present version because there is no place for it in the ETSI-prescribed classification, it is neither speech nor SID. The assumption is that this function is used to classify the bit content of received codec frames, not their RTP encoding - the latter needs to be validated beforehand.

Which function should one use? The answer depends on the specific circumstances, and needs to be addressed on a case-by-case basis.

References ARRAY_SIZE, bitvec_get_bit_pos(), bitvec::data, bitvec::data_len, GSM_EFR_BYTES, n, ONE, OSMO_GSM631_SID_CLASS_INVALID, OSMO_GSM631_SID_CLASS_SPEECH, OSMO_GSM631_SID_CLASS_VALID, and sid_code_word_bits.

Referenced by osmo_efr_is_any_sid(), and osmo_efr_sid_preen().

osmo_efr_sid_preen()

bool osmo_efr_sid_preen

(

uint8_t *

rtp_payload

)

Preen potentially-SID EFR codec frame in RTP format, ensuring that it is either a speech frame or a valid SID, and if the latter, making it a perfect, error-free SID frame.

Parameters

[in]

rtp_payload

Buffer with RTP payload - must be writable!

Returns

true if the frame is good, false otherwise

References OSMO_ASSERT, osmo_efr_sid_classify(), osmo_efr_sid_reset(), OSMO_GSM631_SID_CLASS_INVALID, OSMO_GSM631_SID_CLASS_SPEECH, and OSMO_GSM631_SID_CLASS_VALID.

osmo_efr_sid_reset()

void osmo_efr_sid_reset

(

uint8_t *

rtp_payload

)

Reset the SID field of a potentially corrupted, but still valid GSM-EFR SID frame in RTP encoding to its pristine state (full SID code word).

Parameters

[in]

rtp_payload

Buffer with RTP payload - must be writable!

Per GSM 06.62 section 5.3, a freshly minted SID frame consists of 58 bits of comfort noise parameters (LSF and 4 times fixed codebook gain), 95 bits of SID code word (all 1s) and 91 unused bits (all 0s). Network elements that receive SID frames from call leg A uplink and need to retransmit them on leg B downlink should "rejuvenate" received SID frames prior to retransmission by resetting the SID field to its pristine state of all 1s; this function does the job.

Potential TODO: it would be nice to also zero out the remaining 91 bits which the spec leaves as reserved, clearing out leg A radio bit errors - but do we really need to?

Referenced by osmo_efr_sid_preen().

Variable Documentation

gsm660_bitorder

const uint16_t gsm660_bitorder[260]

sid_code_word_bits

const uint8_t sid_code_word_bits[95]

static

Initial value:

= {
        
           45,  46,  48,  49,  50,  51,  52,  53,  54,  55,
           56,  57,  58,  59,  60,  61,  62,  63,  64,  65,
           66,  67,  68,  94,  95,  96,  98,  99, 100, 101,
          102, 103, 104, 105, 106, 107, 108, 109, 110, 111,
          112, 113, 114, 115, 116, 117, 118, 148, 149, 150,
          151, 152, 153, 154, 155, 156, 157, 158, 159, 160,
          161, 162, 163, 164, 165, 166, 167, 168, 169, 170,
          171, 196, 197, 198, 199, 200, 201, 202, 203, 204,
          205, 206, 207, 208, 209, 212, 213, 214, 215, 216,
          217, 218, 219, 220, 221
}

Referenced by osmo_efr_check_sid(), and osmo_efr_sid_classify().