diff options
Diffstat (limited to 'src/codec')
| -rw-r--r-- | src/codec/Makefile.am | 19 | ||||
| -rw-r--r-- | src/codec/ecu.c | 20 | ||||
| -rw-r--r-- | src/codec/ecu_fr.c | 387 | ||||
| -rw-r--r-- | src/codec/ecu_fr_old.c | 166 | ||||
| -rw-r--r-- | src/codec/gsm610.c | 160 | ||||
| -rw-r--r-- | src/codec/gsm620.c | 72 | ||||
| -rw-r--r-- | src/codec/gsm660.c | 166 | ||||
| -rw-r--r-- | src/codec/gsm690.c | 4 | ||||
| -rw-r--r-- | src/codec/hr_sid_class.c | 176 |
9 files changed, 983 insertions, 187 deletions
diff --git a/src/codec/Makefile.am b/src/codec/Makefile.am index 778eb2ad..17227b67 100644 --- a/src/codec/Makefile.am +++ b/src/codec/Makefile.am @@ -1,10 +1,10 @@ # This is _NOT_ the library release version, it's an API version. # Please read chapter "Library interface versions" of the libtool documentation # before making any modifications: https://www.gnu.org/software/libtool/manual/html_node/Versioning.html -LIBVERSION=2:0:2 +LIBVERSION=4:1:0 -AM_CPPFLAGS = -I$(top_srcdir)/include -I$(top_builddir)/include $(TALLOC_CFLAGS) -AM_CFLAGS = -Wall +AM_CPPFLAGS = -I$(top_srcdir)/include -I$(top_builddir)/include -I$(top_builddir) +AM_CFLAGS = -Wall $(TALLOC_CFLAGS) if ENABLE_PSEUDOTALLOC AM_CPPFLAGS += -I$(top_srcdir)/src/pseudotalloc @@ -13,6 +13,15 @@ endif lib_LTLIBRARIES = libosmocodec.la -libosmocodec_la_SOURCES = gsm610.c gsm620.c gsm660.c gsm690.c ecu.c ecu_fr.c +libosmocodec_la_SOURCES = \ + gsm610.c \ + gsm620.c \ + gsm660.c \ + gsm690.c \ + hr_sid_class.c \ + ecu.c \ + ecu_fr.c \ + ecu_fr_old.c \ + $(NULL) libosmocodec_la_LDFLAGS = -version-info $(LIBVERSION) -no-undefined -libosmocodec_la_LIBADD = $(top_builddir)/src/libosmocore.la +libosmocodec_la_LIBADD = $(top_builddir)/src/core/libosmocore.la diff --git a/src/codec/ecu.c b/src/codec/ecu.c index db7148ce..cdb3e62e 100644 --- a/src/codec/ecu.c +++ b/src/codec/ecu.c @@ -14,10 +14,6 @@ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * - * You should have received a copy of the GNU General Public License along - * with this program; if not, write to the Free Software Foundation, Inc., - * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - * */ /* As the developer and copyright holder of the related code, I hereby @@ -48,7 +44,7 @@ static const struct osmo_ecu_ops *g_ecu_ops[_NUM_OSMO_ECU_CODECS]; /*! initialize an ECU instance for given codec. * \param[in] ctx talloc context from which to allocate - * \parma[in] codec codec for which to initialize/create ECU */ + * \param[in] codec codec for which to initialize/create ECU */ struct osmo_ecu_state *osmo_ecu_init(void *ctx, enum osmo_ecu_codec codec) { if (codec >= ARRAY_SIZE(g_ecu_ops)) @@ -100,6 +96,20 @@ int osmo_ecu_frame_out(struct osmo_ecu_state *st, uint8_t *frame_out) return g_ecu_ops[st->codec]->frame_out(st, frame_out); } +/*! check if the current state of this ECU is a DTX pause. + * \param[in] st ECU state/instance on which to operate + * \return true if DTX pause, false otherwise */ +bool osmo_ecu_is_dtx_pause(struct osmo_ecu_state *st) +{ + if (st->codec >= ARRAY_SIZE(g_ecu_ops)) + return false; + if (!g_ecu_ops[st->codec]) + return false; + if (!g_ecu_ops[st->codec]->is_dtx_pause) + return false; + return g_ecu_ops[st->codec]->is_dtx_pause(st); +} + /*********************************************************************** * low-level API for ECU implementations ***********************************************************************/ diff --git a/src/codec/ecu_fr.c b/src/codec/ecu_fr.c index 4545172a..45ba0cc8 100644 --- a/src/codec/ecu_fr.c +++ b/src/codec/ecu_fr.c @@ -1,9 +1,15 @@ /* * (C) 2017 by sysmocom - s.f.m.c. GmbH * (C) 2017 by Philipp Maier <pmaier@sysmocom.de> - * * All Rights Reserved * + * Significantly reworked in 2023 by Mother + * Mychaela N. Falconia <falcon@freecalypso.org> - however, + * Mother Mychaela's contributions are NOT subject to copyright. + * No rights reserved, all rights relinquished. + * Portions of this code are based on Themyscira libgsmfrp, + * a public domain library by the same author. + * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or @@ -14,10 +20,46 @@ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * - * You should have received a copy of the GNU General Public License along - * with this program; if not, write to the Free Software Foundation, Inc., - * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. * + * The present ECU implementation for GSM-FR is closely based on the + * TS 46.011 spec from 3GPP; more specifically, it is based on the + * Example solution presented in Chapter 6 of that spec, adapted for + * libosmocodec ECU architecture, and comes as close to fulfilling + * the spec's officially stated requirements (Chapter 5) as is + * possible within this Osmocom-imposed architecture. Please note + * the following areas where the present implementation fails to + * fulfill the original intent of GSM spec authors: + * + * - The "lost SID" criterion, defined in GSM 06.31, is based on the + * TAF bit from the Radio Subsystem. However, libosmocodec ECU API + * does not include this flag, thus spec requirements related to + * lost SID conditions cannot be implemented in a strictly compliant + * manner. The present implementation improvises its own "lost SID" + * detector (not strictly spec-compliant) by counting frame_out() + * calls in between good traffic frame inputs via frame_in(). + * + * - In the architecture envisioned and assumed in the GSM specs, + * the ECU function of GSM 06.11 was never intended to be a fully + * modular component with its own bona fide I/O interfaces - this + * approach appears to be an Osmocom invention - instead this ECU + * function was intended to be subsumed in the Rx DTX handler + * component of GSM 06.31, also incorporating the comfort noise + * generator of GSM 06.12 - and unlike the narrower-scope ECU, + * this slightly-larger-scope Rx DTX handler is a modular component + * with well-defined I/O interfaces. In the case of BFI conditions + * following a SID, GSM 06.11 spec was written with the assumption + * that the ECU controls the comfort noise generator via internal + * signals, as opposed to emitting "corrected" SID frames on a + * modular interface going to a CN generator located somewhere else. + * Thus the "correct" behavior for a fully modularized ECU is unclear, + * and an argument can be made that the very existence of such a + * fully modularized ECU is incorrect in itself. The present + * implementation re-emits a "rejuvenated" form of the last saved + * SID frame during BFI conditions following a SID within the + * permitted window of 48 frames, then starts emitting muted SIDs + * with Xmaxc decreasing by 4 on each frame, and finally switches + * to emitting non-SID silence frames (Table 1 of TS 46.011) + * once Xmaxc reaches 0. */ #include <stdbool.h> @@ -25,144 +67,216 @@ #include <stdint.h> #include <errno.h> -#include <osmocom/core/bitvec.h> +#include <osmocom/core/prbs.h> -#include <osmocom/codec/gsm610_bits.h> #include <osmocom/codec/codec.h> #include <osmocom/codec/ecu.h> +#include <osmocom/core/linuxlist.h> + +/* See TS 46.011, Chapter 6 Example solution */ +#define GSM611_XMAXC_REDUCE 4 + +/* The first 5 bytes of RTP encoding neatly contain the magic nibble + * and LARc parameters, which also happens to be the part of SID frames + * that needs to be passed through as-is. */ +#define SID_PREFIX_LEN 5 + +enum ecu_principal_state { + STATE_NO_DATA, + STATE_SPEECH, + STATE_SP_MUTING, + STATE_SID, + STATE_SID_MUTING, +}; -/* See also GSM 06.11, chapter 6 Example solution */ -#define GSM610_XMAXC_REDUCE 4 -#define GSM610_XMAXC_LEN 6 +struct fr_ecu_state { + struct osmo_ecu_state ecu_state; + enum ecu_principal_state pr_state; + uint8_t speech_frame[GSM_FR_BYTES]; + uint8_t sid_prefix[SID_PREFIX_LEN]; + uint8_t sid_xmaxc; + uint8_t sid_reemit_count; + struct osmo_prbs_state prng; + bool last_input_was_sid; +}; -/** - * Reduce the XMAXC field. When the XMAXC field reaches - * zero the function will return true. +/* This function is the frame input to the ECU - all inputs to this + * function have been received by the Radio Subsystem as good traffic + * frames in the GSM 06.31 definition. */ -static bool reduce_xmaxcr(struct bitvec *frame_bitvec, - const unsigned int index) +static void fr_ecu_input(struct fr_ecu_state *fr, const uint8_t *frame) { - unsigned int field_index; - uint64_t field; - - field_index = index; - field = bitvec_read_field(frame_bitvec, &field_index, GSM610_XMAXC_LEN); - if (field > GSM610_XMAXC_REDUCE) - field -= GSM610_XMAXC_REDUCE; - else - field = 0; - - field_index = index; - bitvec_write_field(frame_bitvec, &field_index, field, GSM610_XMAXC_LEN); - - return field == 0; + enum osmo_gsm631_sid_class sidc; + + sidc = osmo_fr_sid_classify(frame); + switch (sidc) { + case OSMO_GSM631_SID_CLASS_SPEECH: + memcpy(fr->speech_frame, frame, GSM_FR_BYTES); + fr->pr_state = STATE_SPEECH; + fr->last_input_was_sid = false; + return; + case OSMO_GSM631_SID_CLASS_INVALID: + /* GSM 06.31 section 6.1.2 says: "an invalid SID frame + * shall be substituted by the last valid SID frame + * and the procedure for valid SID frames be applied." + * However, libosmocodec ECU architecture prevents us + * from doing what the spec says: the frame_in() method + * gets a const frame that can't be modified, and + * frame_out() will never get called when BFI=0, even + * when the "good traffic frame" (in the BFI=0 sense) + * is an invalid SID by the bit-counting rule. + * Thus there is no place where we can re-emit a cached + * copy of the last valid SID upon receiving an invalid SID. + * + * In the standard GSM architecture this problem never + * arises because the ECU is not a separate component + * but is coupled with the CN generator, thus the output + * from the Rx DTX handler block will be a CN frame, + * for both valid-SID and invalid-SID inputs to the block. + * But what can we do within the constraints of libosmocodec + * ECU framework? We treat the invalid SID almost like a + * BFI, doing almost nothing in the frame_in() method, + * but we reset sid_reemit_count because by the rules of + * GSM 06.31 an invalid SID is still an accepted SID frame + * for the purpose of "lost SID" logic. */ + fr->sid_reemit_count = 0; + fr->last_input_was_sid = true; + return; + case OSMO_GSM631_SID_CLASS_VALID: + /* save LARc part */ + memcpy(fr->sid_prefix, frame, SID_PREFIX_LEN); + /* save Xmaxc from the last subframe */ + fr->sid_xmaxc = ((frame[27] & 0x1F) << 1) | (frame[28] >> 7); + fr->pr_state = STATE_SID; + fr->sid_reemit_count = 0; + fr->last_input_was_sid = true; + return; + default: + /* There are only 3 possible SID classifications per GSM 06.31 + * section 6.1.1, thus any other return value is a grave error + * in the code. */ + OSMO_ASSERT(0); + } } -/** - * Reduce all XMAXC fields in the frame. When all XMAXC fields - * reach zero, then the function will return true. +/* Reduce all 4 Xmaxc fields in the frame. When all 4 Xmaxc fields + * reach 0, the function will return true for "mute". */ -static bool reduce_xmaxcr_all(struct bitvec *frame_bitvec) +static bool reduce_xmaxc(uint8_t *frame) { - bool silent = true; - - silent &= reduce_xmaxcr(frame_bitvec, GSM610_RTP_XMAXC00); - silent &= reduce_xmaxcr(frame_bitvec, GSM610_RTP_XMAXC10); - silent &= reduce_xmaxcr(frame_bitvec, GSM610_RTP_XMAXC20); - silent &= reduce_xmaxcr(frame_bitvec, GSM610_RTP_XMAXC30); - - return silent; + bool mute_flag = true; + uint8_t sub, xmaxc; + + for (sub = 0; sub < 4; sub++) { + xmaxc = ((frame[sub*7+6] & 0x1F) << 1) | (frame[sub*7+7] >> 7); + if (xmaxc > GSM611_XMAXC_REDUCE) { + xmaxc -= GSM611_XMAXC_REDUCE; + mute_flag = false; + } else + xmaxc = 0; + frame[sub*7+6] &= 0xE0; + frame[sub*7+6] |= xmaxc >> 1; + frame[sub*7+7] &= 0x7F; + frame[sub*7+7] |= (xmaxc & 1) << 7; + } + return mute_flag; } -/* Use certain modifications to conceal the errors in a full rate frame */ -static int conceal_frame(uint8_t *frame) +/* TS 46.011 chapter 6, paragraph 4, last sentence: "The grid position + * parameters are chosen randomly between 0 and 3 during this time." + * (The "during this time" qualifier refers to the speech muting state.) + * This sentence in the spec must have been overlooked by previous ECU + * implementors, as this aspect of the muting logic was missing. + */ +static void random_grid_pos(struct fr_ecu_state *fr, uint8_t *frame) { - struct bitvec *frame_bitvec; - unsigned int len; - bool silent; - int rc = 0; - - /* In case we already deal with a silent frame, - * there is nothing to, we just abort immediately */ - if (osmo_fr_check_sid(frame, GSM_FR_BYTES)) - return 0; - - /* Attempt to allocate memory for bitvec */ - frame_bitvec = bitvec_alloc(GSM_FR_BYTES, NULL); - if (!frame_bitvec) - return -ENOMEM; + uint8_t sub; - /* Convert a frame to bitvec */ - len = bitvec_unpack(frame_bitvec, frame); - if (len != GSM_FR_BYTES) { - rc = -EIO; - goto leave; - } - - /* Fudge frame parameters */ - silent = reduce_xmaxcr_all(frame_bitvec); - - /* If we reached silence level, mute the frame - * completely, this also means that we can - * save the bitvec_pack operation */ - if (silent) { - memset(frame, 0x00, GSM_FR_BYTES); - frame[0] = 0xd0; - goto leave; + for (sub = 0; sub < 4; sub++) { + frame[sub*7+6] &= 0x9F; + frame[sub*7+6] |= osmo_prbs_get_ubit(&fr->prng) << 6; + frame[sub*7+6] |= osmo_prbs_get_ubit(&fr->prng) << 5; } +} - /* Convert back to packed byte form */ - len = bitvec_pack(frame_bitvec, frame); - if (len != GSM_FR_BYTES) { - rc = -EIO; - goto leave; +/* Like reduce_xmaxc() above, but for comfort noise rather than speech. */ +static bool reduce_xmaxc_sid(struct fr_ecu_state *fr) +{ + if (fr->sid_xmaxc > GSM611_XMAXC_REDUCE) { + fr->sid_xmaxc -= GSM611_XMAXC_REDUCE; + return false; } - -leave: - bitvec_free(frame_bitvec); - return rc; + fr->sid_xmaxc = 0; + return true; } -/*! - * To be called when a good frame is received. - * This function will then create a backup of the frame - * and reset the internal state. - * \param[in] state The state object for the ECU - * \param[out] frame The valid frame (GSM_FR_BYTES bytes in RTP payload format) +/* This function implements the part which is peculiar to the present + * "standalone" packaging of GSM-FR ECU, without a directly coupled + * comfort noise generator - it re-emits synthetic SID frames during + * DTX pauses, initially unchanged from the saved SID and later muted. */ -void osmo_ecu_fr_reset(struct osmo_ecu_fr_state *state, const uint8_t *frame) +static void reemit_sid(struct fr_ecu_state *fr, uint8_t *frame) { - state->subsequent_lost_frame = false; - memcpy(state->frame_backup, frame, GSM_FR_BYTES); + uint8_t *p, sub; + + memcpy(frame, fr->sid_prefix, SID_PREFIX_LEN); + p = frame + SID_PREFIX_LEN; + for (sub = 0; sub < 4; sub++) { + *p++ = 0; + *p++ = fr->sid_xmaxc >> 1; + *p++ = (fr->sid_xmaxc & 1) << 7; + *p++ = 0; + *p++ = 0; + *p++ = 0; + *p++ = 0; + } } -/*! - * To be called when a bad frame is received. - * This function will then generate a replacement frame - * that can be used to conceal the dropout. - * \param[in] state The state object for the ECU - * \param[out] frame The buffer to fill with GSM_FR_BYTES of replacement frame - * \returns 0 if the frame was sucessfully filled +/* This function is responsible for generating the ECU's output + * in the event that the Radio Subsystem does not have a good + * traffic frame - conditions corresponding to BFI=1 in the specs. */ -int osmo_ecu_fr_conceal(struct osmo_ecu_fr_state *state, uint8_t *frame) +static void fr_ecu_output(struct fr_ecu_state *fr, uint8_t *frame) { - int rc; - - /* For subsequent frames we run the error concealment - * functions on the backed up frame before we restore - * the backup */ - if (state->subsequent_lost_frame) { - rc = conceal_frame(state->frame_backup); - if (rc) - return rc; + bool mute; + + switch (fr->pr_state) { + case STATE_NO_DATA: + memcpy(frame, osmo_gsm611_silence_frame, GSM_FR_BYTES); + return; + case STATE_SPEECH: + /* TS 46.011 chapter 6: "The first lost speech frame is + * replaced at the speech decoder input by the previous + * good speech frame." */ + memcpy(frame, fr->speech_frame, GSM_FR_BYTES); + fr->pr_state = STATE_SP_MUTING; + return; + case STATE_SP_MUTING: + mute = reduce_xmaxc(fr->speech_frame); + memcpy(frame, fr->speech_frame, GSM_FR_BYTES); + random_grid_pos(fr, frame); + if (mute) + fr->pr_state = STATE_NO_DATA; + return; + case STATE_SID: + fr->sid_reemit_count++; + if (fr->sid_reemit_count >= 48) { + fr->pr_state = STATE_SID_MUTING; + reduce_xmaxc_sid(fr); + } + reemit_sid(fr, frame); + return; + case STATE_SID_MUTING: + if (reduce_xmaxc_sid(fr)) { + fr->pr_state = STATE_NO_DATA; + memcpy(frame, osmo_gsm611_silence_frame, GSM_FR_BYTES); + } else + reemit_sid(fr, frame); + return; + default: + /* a severe bug in the state machine! */ + OSMO_ASSERT(0); } - - /* Restore the backed up frame and set flag in case - * we receive even more bad frames */ - memcpy(frame, state->frame_backup, GSM_FR_BYTES); - state->subsequent_lost_frame = true; - - return 0; } /*********************************************************************** @@ -171,44 +285,57 @@ int osmo_ecu_fr_conceal(struct osmo_ecu_fr_state *state, uint8_t *frame) static struct osmo_ecu_state *ecu_fr_init(void *ctx, enum osmo_ecu_codec codec) { - struct osmo_ecu_state *st; - size_t size = sizeof(*st) + sizeof(struct osmo_ecu_fr_state); + struct fr_ecu_state *fr; - st = talloc_named_const(ctx, size, "ecu_state_FR"); - if (!st) - return NULL; + fr = talloc_zero(ctx, struct fr_ecu_state); + fr->ecu_state.codec = codec; + fr->pr_state = STATE_NO_DATA; + osmo_prbs_state_init(&fr->prng, &osmo_prbs15); - memset(st, 0, size); - st->codec = codec; + return (struct osmo_ecu_state *) fr; +} - return st; +static inline struct fr_ecu_state *_osmo_ecu_state_get_fr(struct osmo_ecu_state *st) +{ + return (struct fr_ecu_state *)container_of(st, struct fr_ecu_state, ecu_state); } static int ecu_fr_frame_in(struct osmo_ecu_state *st, bool bfi, const uint8_t *frame, unsigned int frame_bytes) { - struct osmo_ecu_fr_state *fr = (struct osmo_ecu_fr_state *) &st->data; + struct fr_ecu_state *fr = _osmo_ecu_state_get_fr(st); + if (bfi) return 0; + if (frame_bytes != GSM_FR_BYTES) + return 0; + if ((frame[0] & 0xF0) != 0xD0) + return 0; - osmo_ecu_fr_reset(fr, frame); + fr_ecu_input(fr, frame); return 0; } static int ecu_fr_frame_out(struct osmo_ecu_state *st, uint8_t *frame_out) { - struct osmo_ecu_fr_state *fr = (struct osmo_ecu_fr_state *) &st->data; + struct fr_ecu_state *fr = _osmo_ecu_state_get_fr(st); + + fr_ecu_output(fr, frame_out); + return GSM_FR_BYTES; +} + +static bool ecu_fr_is_dtx_pause(struct osmo_ecu_state *st) +{ + struct fr_ecu_state *fr = _osmo_ecu_state_get_fr(st); - if (osmo_ecu_fr_conceal(fr, frame_out) == 0) - return GSM_FR_BYTES; - else - return -1; + return fr->last_input_was_sid; } static const struct osmo_ecu_ops osmo_ecu_ops_fr = { .init = ecu_fr_init, .frame_in = ecu_fr_frame_in, .frame_out = ecu_fr_frame_out, + .is_dtx_pause = ecu_fr_is_dtx_pause, }; static __attribute__((constructor)) void on_dso_load_ecu_fr(void) diff --git a/src/codec/ecu_fr_old.c b/src/codec/ecu_fr_old.c new file mode 100644 index 00000000..cfefce14 --- /dev/null +++ b/src/codec/ecu_fr_old.c @@ -0,0 +1,166 @@ +/* + * (C) 2017 by sysmocom - s.f.m.c. GmbH + * (C) 2017 by Philipp Maier <pmaier@sysmocom.de> + * + * All Rights Reserved + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * + * This module implements legacy, deprecated osmo_ecu_fr_reset() and + * osmo_ecu_fr_conceal() functions only - see ecu_fr.c for the new + * GSM-FR ECU implementation. + */ + +#include <stdbool.h> +#include <string.h> +#include <stdint.h> +#include <errno.h> + +#include <osmocom/core/bitvec.h> + +#include <osmocom/codec/gsm610_bits.h> +#include <osmocom/codec/codec.h> +#include <osmocom/codec/ecu.h> + +/* See also GSM 06.11, chapter 6 Example solution */ +#define GSM610_XMAXC_REDUCE 4 +#define GSM610_XMAXC_LEN 6 + +/** + * Reduce the XMAXC field. When the XMAXC field reaches + * zero the function will return true. + */ +static bool reduce_xmaxcr(struct bitvec *frame_bitvec, + const unsigned int index) +{ + unsigned int field_index; + uint64_t field; + + field_index = index; + field = bitvec_read_field(frame_bitvec, &field_index, GSM610_XMAXC_LEN); + if (field > GSM610_XMAXC_REDUCE) + field -= GSM610_XMAXC_REDUCE; + else + field = 0; + + field_index = index; + bitvec_write_field(frame_bitvec, &field_index, field, GSM610_XMAXC_LEN); + + return field == 0; +} + +/** + * Reduce all XMAXC fields in the frame. When all XMAXC fields + * reach zero, then the function will return true. + */ +static bool reduce_xmaxcr_all(struct bitvec *frame_bitvec) +{ + bool silent = true; + + silent &= reduce_xmaxcr(frame_bitvec, GSM610_RTP_XMAXC00); + silent &= reduce_xmaxcr(frame_bitvec, GSM610_RTP_XMAXC10); + silent &= reduce_xmaxcr(frame_bitvec, GSM610_RTP_XMAXC20); + silent &= reduce_xmaxcr(frame_bitvec, GSM610_RTP_XMAXC30); + + return silent; +} + +/* Use certain modifications to conceal the errors in a full rate frame */ +static int conceal_frame(uint8_t *frame) +{ + struct bitvec *frame_bitvec; + unsigned int len; + bool silent; + int rc = 0; + + /* In case we already deal with a silent frame, + * there is nothing to, we just abort immediately */ + if (osmo_fr_check_sid(frame, GSM_FR_BYTES)) + return 0; + + /* Attempt to allocate memory for bitvec */ + frame_bitvec = bitvec_alloc(GSM_FR_BYTES, NULL); + if (!frame_bitvec) + return -ENOMEM; + + /* Convert a frame to bitvec */ + len = bitvec_unpack(frame_bitvec, frame); + if (len != GSM_FR_BYTES) { + rc = -EIO; + goto leave; + } + + /* Fudge frame parameters */ + silent = reduce_xmaxcr_all(frame_bitvec); + + /* If we reached silence level, mute the frame + * completely, this also means that we can + * save the bitvec_pack operation */ + if (silent) { + memset(frame, 0x00, GSM_FR_BYTES); + frame[0] = 0xd0; + goto leave; + } + + /* Convert back to packed byte form */ + len = bitvec_pack(frame_bitvec, frame); + if (len != GSM_FR_BYTES) { + rc = -EIO; + goto leave; + } + +leave: + bitvec_free(frame_bitvec); + return rc; +} + +/*! + * To be called when a good frame is received. + * This function will then create a backup of the frame + * and reset the internal state. + * \param[in] state The state object for the ECU + * \param[out] frame The valid frame (GSM_FR_BYTES bytes in RTP payload format) + */ +void osmo_ecu_fr_reset(struct osmo_ecu_fr_state *state, const uint8_t *frame) +{ + state->subsequent_lost_frame = false; + memcpy(state->frame_backup, frame, GSM_FR_BYTES); +} + +/*! + * To be called when a bad frame is received. + * This function will then generate a replacement frame + * that can be used to conceal the dropout. + * \param[in] state The state object for the ECU + * \param[out] frame The buffer to fill with GSM_FR_BYTES of replacement frame + * \returns 0 if the frame was successfully filled + */ +int osmo_ecu_fr_conceal(struct osmo_ecu_fr_state *state, uint8_t *frame) +{ + int rc; + + /* For subsequent frames we run the error concealment + * functions on the backed up frame before we restore + * the backup */ + if (state->subsequent_lost_frame) { + rc = conceal_frame(state->frame_backup); + if (rc) + return rc; + } + + /* Restore the backed up frame and set flag in case + * we receive even more bad frames */ + memcpy(frame, state->frame_backup, GSM_FR_BYTES); + state->subsequent_lost_frame = true; + + return 0; +} diff --git a/src/codec/gsm610.c b/src/codec/gsm610.c index a05eabab..5cc4f148 100644 --- a/src/codec/gsm610.c +++ b/src/codec/gsm610.c @@ -17,10 +17,6 @@ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * - * You should have received a copy of the GNU General Public License along - * with this program; if not, write to the Free Software Foundation, Inc., - * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - * */ #include <stdint.h> @@ -300,6 +296,35 @@ const uint16_t gsm610_bitorder[260] = { 29, /* LARc5:0 */ }; +/* + * Table 1 in section 6 of 3GPP TS 46.011 (substitution and muting of lost + * frames) specifies a silence frame in the form of GSM 06.10 parameters; + * the following const datum is this GSM 06.11 silence frame in GSM-FR + * RTP encoding. + */ +const uint8_t osmo_gsm611_silence_frame[GSM_FR_BYTES] = { + 0xDA, 0xA7, 0xAA, 0xA5, 0x1A, + 0x50, 0x20, 0x38, 0xE4, 0x6D, 0xB9, 0x1B, + 0x50, 0x20, 0x38, 0xE4, 0x6D, 0xB9, 0x1B, + 0x50, 0x20, 0x38, 0xE4, 0x6D, 0xB9, 0x1B, + 0x50, 0x20, 0x38, 0xE4, 0x6D, 0xB9, 0x1B, +}; + +static const uint16_t sid_code_word_bits[95] = { + /* bit numbers are relative to the RTP frame beginning, + * with signature bits included in the count. */ + 57, 58, 60, 61, 63, 64, 66, 67, 69, 70, 72, 73, + 75, 76, 78, 79, 81, 82, 84, 85, 87, 88, 90, 91, + 93, 94, 113, 114, 116, 117, 119, 120, 122, 123, + 125, 126, 128, 129, 131, 132, 134, 135, 137, + 138, 140, 141, 143, 144, 146, 147, 149, 150, + 169, 170, 172, 173, 175, 176, 178, 179, 181, + 182, 184, 185, 187, 188, 190, 191, 193, 194, + 196, 197, 199, 200, 202, 203, 205, 206, 225, + 226, 228, 229, 231, 232, 234, 235, 237, 240, + 243, 246, 249, 252, 255, 258, 261 +}; + /*! Check whether RTP frame contains FR SID code word according to * TS 101 318 §5.1.2 * \param[in] rtp_payload Buffer with RTP payload @@ -309,16 +334,7 @@ const uint16_t gsm610_bitorder[260] = { bool osmo_fr_check_sid(const uint8_t *rtp_payload, size_t payload_len) { struct bitvec bv; - uint16_t i, z_bits[] = { 57, 58, 60, 61, 63, 64, 66, 67, 69, 70, 72, 73, - 75, 76, 78, 79, 81, 82, 84, 85, 87, 88, 90, 91, - 93, 94, 113, 114, 116, 117, 119, 120, 122, 123, - 125, 126, 128, 129, 131, 132, 134, 135, 137, - 138, 140, 141, 143, 144, 146, 147, 149, 150, - 169, 170, 172, 173, 175, 176, 178, 179, 181, - 182, 184, 185, 187, 188, 190, 191, 193, 194, - 196, 197, 199, 200, 202, 203, 205, 206, 225, - 226, 228, 229, 231, 232, 234, 235, 237, 240, - 243, 246, 249, 252, 255, 258, 261 }; + uint16_t i; /* signature does not match Full Rate SID */ if ((rtp_payload[0] >> 4) != 0xD) @@ -327,10 +343,120 @@ bool osmo_fr_check_sid(const uint8_t *rtp_payload, size_t payload_len) bv.data = (uint8_t *) rtp_payload; bv.data_len = payload_len; - /* code word is all 0 at given bits, numbered from 1 */ - for (i = 0; i < ARRAY_SIZE(z_bits); i++) - if (bitvec_get_bit_pos(&bv, z_bits[i]) != ZERO) + /* code word is all 0 at given bits */ + for (i = 0; i < ARRAY_SIZE(sid_code_word_bits); i++) { + if (bitvec_get_bit_pos(&bv, sid_code_word_bits[i]) != ZERO) return false; + } return true; } + +/*! Classify potentially-SID FR codec frame in RTP format according + * to the rules of GSM 06.31 §6.1.1 + * \param[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_fr_check_sid() and the present + * function are: + * + * 1. osmo_fr_check_sid() returns true only if the SID frame is absolutely + * perfect, with all 95 bits of the SID code word zeroed. However, the + * rules of GSM 06.31 §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_fr_check_sid() function. + * + * 3. osmo_fr_check_sid() includes a check for 0xD 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. + */ +enum osmo_gsm631_sid_class osmo_fr_sid_classify(const uint8_t *rtp_payload) +{ + struct bitvec bv; + uint16_t i, n; + + bv.data = (uint8_t *) rtp_payload; + bv.data_len = GSM_FR_BYTES; + + /* count not-SID-matching bits per the spec */ + n = 0; + for (i = 0; i < ARRAY_SIZE(sid_code_word_bits); i++) { + if (bitvec_get_bit_pos(&bv, sid_code_word_bits[i]) != ZERO) + n++; + if (n >= 16) + return OSMO_GSM631_SID_CLASS_SPEECH; + } + if (n >= 2) + return OSMO_GSM631_SID_CLASS_INVALID; + else + return OSMO_GSM631_SID_CLASS_VALID; +} + +/*! Reset the SID field and the unused bits of a potentially corrupted, + * but still valid GSM-FR SID frame in RTP encoding to their pristine state. + * \param[in] rtp_payload Buffer with RTP payload - must be writable! + * + * Per GSM 06.12 section 5.2, a freshly minted SID frame carries 60 bits + * of comfort noise parameters (LARc and 4 times Xmaxc), while the remaining + * 200 bits are all zeros; the latter 200 all-0 bits further break down into + * 95 bits of SID field (checked by receivers to detect SID) and 105 unused + * bits which receivers are told to ignore. 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; + * this function does the job. + */ +void osmo_fr_sid_reset(uint8_t *rtp_payload) +{ + uint8_t *p, sub; + + p = rtp_payload + 5; /* skip magic+LARc */ + for (sub = 0; sub < 4; sub++) { + *p++ = 0; + *p++ &= 0x1F; /* upper 5 bits of Xmaxc field */ + *p++ &= 0x80; /* and the lsb spilling into the next byte */ + *p++ = 0; + *p++ = 0; + *p++ = 0; + *p++ = 0; + } +} + +/*! Preen potentially-SID FR 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. + * \param[in] rtp_payload Buffer with RTP payload - must be writable! + * \returns true if the frame is good, false otherwise + */ +bool osmo_fr_sid_preen(uint8_t *rtp_payload) +{ + enum osmo_gsm631_sid_class sidc; + + sidc = osmo_fr_sid_classify(rtp_payload); + switch (sidc) { + case OSMO_GSM631_SID_CLASS_SPEECH: + return true; + case OSMO_GSM631_SID_CLASS_INVALID: + return false; + case OSMO_GSM631_SID_CLASS_VALID: + /* "Rejuvenate" this SID frame, correcting any errors */ + osmo_fr_sid_reset(rtp_payload); + return true; + default: + /* There are only 3 possible SID classifications per GSM 06.31 + * section 6.1.1, thus any other return value is a grave error + * in the code. */ + OSMO_ASSERT(0); + } +} diff --git a/src/codec/gsm620.c b/src/codec/gsm620.c index 282781fd..49ee7243 100644 --- a/src/codec/gsm620.c +++ b/src/codec/gsm620.c @@ -17,17 +17,12 @@ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * - * You should have received a copy of the GNU General Public License along - * with this program; if not, write to the Free Software Foundation, Inc., - * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - * */ #include <stdint.h> #include <stdbool.h> +#include <string.h> -#include <osmocom/core/bitvec.h> -#include <osmocom/core/utils.h> #include <osmocom/codec/codec.h> /* GSM HR unvoiced (mode=0) frames - subjective importance bit ordering */ @@ -268,30 +263,63 @@ const uint16_t gsm620_voiced_bitorder[112] = { 81, /* Code 3:7 */ }; -static inline uint16_t mask(const uint8_t msb) -{ - const uint16_t m = (uint16_t)1 << (msb - 1); - return (m - 1) ^ m; -} - /*! Check whether RTP frame contains HR SID code word according to * TS 101 318 §5.2.2 * \param[in] rtp_payload Buffer with RTP payload * \param[in] payload_len Length of payload * \returns true if code word is found, false otherwise + * + * Note that this function checks only for a perfect, error-free SID. + * Unlike GSM 06.31 for FR or GSM 06.81 for EFR, GSM 06.41 spec for HR + * does not prescribe exact bit counting rules, hence detection of + * partially corrupted SID frames in downstream network elements + * without out-of-band indication is not possible. */ bool osmo_hr_check_sid(const uint8_t *rtp_payload, size_t payload_len) { - uint8_t i, bits[] = { 1, 2, 8, 9, 5, 4, 9, 5, 4, 9, 5, 4, 9, 5 }; - struct bitvec bv; - bv.data = (uint8_t *) rtp_payload; - bv.data_len = payload_len; - bv.cur_bit = 33; + static const uint8_t all_ff_bytes[9] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, + 0xFF, 0xFF, 0xFF, 0xFF}; - /* code word is all 1 at given bits, numbered from 1, MODE is always 3 */ - for (i = 0; i < ARRAY_SIZE(bits); i++) - if (bitvec_get_uint(&bv, bits[i]) != mask(bits[i])) - return false; + if (payload_len < GSM_HR_BYTES) + return false; - return true; + /* A SID frame is identified by a SID codeword consisting of 79 bits + * which are all 1, so we basically check if all bits in range + * r34..r112 (inclusive) are 1. However, given the position of + * these bits in the frame, the most efficient way to perform + * this check does not use any bit-level operations. */ + if ((rtp_payload[4] & 0x7F) != 0x7F) + return false; + if (memcmp(rtp_payload + 5, all_ff_bytes, 9) == 0) + return true; + else + return false; +} + +/*! Reset the SID field of a potentially corrupted, but still valid GSM-HR + * SID frame in TS 101 318 format to its pristine state (full SID codeword). + * \param[in] rtp_payload Buffer with RTP payload - must be writable! + * + * Per GSM 06.22 section 5.3, a freshly minted SID frame consists of 33 bits + * of comfort noise parameters and 79 bits of SID codeword (all 1s). 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. + * + * Important note: because of HR-specific quirks (lack of exact bit counting + * rules in GSM 06.41 spec compared to 06.31 & 06.81, plus the fact that such + * bit counting can only be done efficiently in the GSM 05.03 channel decoder + * prior to bit reordering based on voiced or unvoiced mode), a generic + * (usable from any network element) SID classification function similar to + * osmo_{fr,efr}_sid_classify() unfortunately cannot exist for HR. Therefore, + * the triggering condition for invoking this SID rejuvenation/reset function + * can only be an out-of-band SID indication, as in GSM 08.61 TRAU frames + * or RFC 5993 ToC octet. + */ +void osmo_hr_sid_reset(uint8_t *rtp_payload) +{ + /* set all 79 SID codeword bits to 1 */ + rtp_payload[4] |= 0x7F; + memset(rtp_payload + 5, 0xFF, 9); } diff --git a/src/codec/gsm660.c b/src/codec/gsm660.c index 4f7bb099..b15bdf37 100644 --- a/src/codec/gsm660.c +++ b/src/codec/gsm660.c @@ -17,13 +17,13 @@ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * - * You should have received a copy of the GNU General Public License along - * with this program; if not, write to the Free Software Foundation, Inc., - * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - * */ #include <stdint.h> +#include <stdbool.h> + +#include <osmocom/core/bitvec.h> +#include <osmocom/core/utils.h> #include <osmocom/codec/codec.h> /* GSM EFR - subjective importance bit ordering */ @@ -257,3 +257,161 @@ const uint16_t gsm660_bitorder[260] = { 243, /* 258 -> PULSE 4_9: b0 */ 246, /* 259 -> PULSE 4_10: b0 */ }; + +static const uint8_t sid_code_word_bits[95] = { + /* bit numbers are relative to "pure" EFR frame beginning, + * not counting the signature bits. */ + 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 +}; + +/*! Check whether RTP frame contains EFR SID code word according to + * TS 101 318 §5.3.2 + * \param[in] rtp_payload Buffer with RTP payload + * \param[in] payload_len Length of payload + * \returns true if code word is found, false otherwise + */ +bool osmo_efr_check_sid(const uint8_t *rtp_payload, size_t payload_len) +{ + struct bitvec bv; + uint16_t i; + + /* signature does not match Enhanced Full Rate SID */ + if ((rtp_payload[0] >> 4) != 0xC) + return false; + + bv.data = (uint8_t *) rtp_payload; + bv.data_len = payload_len; + + /* code word is all 1 at given bits */ + for (i = 0; i < ARRAY_SIZE(sid_code_word_bits); i++) { + if (bitvec_get_bit_pos(&bv, sid_code_word_bits[i]+4) != ONE) + return false; + } + + return true; +} + +/*! Classify potentially-SID EFR codec frame in RTP format according + * to the rules of GSM 06.81 §6.1.1 + * \param[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. + */ +enum osmo_gsm631_sid_class osmo_efr_sid_classify(const uint8_t *rtp_payload) +{ + struct bitvec bv; + uint16_t i, n; + + bv.data = (uint8_t *) rtp_payload; + bv.data_len = GSM_EFR_BYTES; + + /* count not-SID-matching bits per the spec */ + n = 0; + for (i = 0; i < ARRAY_SIZE(sid_code_word_bits); i++) { + if (bitvec_get_bit_pos(&bv, sid_code_word_bits[i]+4) != ONE) + n++; + if (n >= 16) + return OSMO_GSM631_SID_CLASS_SPEECH; + } + if (n >= 2) + return OSMO_GSM631_SID_CLASS_INVALID; + else + return OSMO_GSM631_SID_CLASS_VALID; +} + +/*! 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). + * \param[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? + */ +void osmo_efr_sid_reset(uint8_t *rtp_payload) +{ + /* set all 95 SID code word bits to 1 */ + rtp_payload[6] |= 0x6F; + rtp_payload[7] = 0xFF; + rtp_payload[8] = 0xFF; + rtp_payload[9] |= 0x80; + rtp_payload[12] |= 0x3B; + rtp_payload[13] = 0xFF; + rtp_payload[14] = 0xFF; + rtp_payload[15] |= 0xE0; + rtp_payload[19] = 0xFF; + rtp_payload[20] = 0xFF; + rtp_payload[21] = 0xFF; + rtp_payload[25] = 0xFF; + rtp_payload[26] |= 0xFC; + rtp_payload[27] = 0xFF; + rtp_payload[28] |= 0xC0; +} + +/*! 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. + * \param[in] rtp_payload Buffer with RTP payload - must be writable! + * \returns true if the frame is good, false otherwise + */ +bool osmo_efr_sid_preen(uint8_t *rtp_payload) +{ + enum osmo_gsm631_sid_class sidc; + + sidc = osmo_efr_sid_classify(rtp_payload); + switch (sidc) { + case OSMO_GSM631_SID_CLASS_SPEECH: + return true; + case OSMO_GSM631_SID_CLASS_INVALID: + return false; + case OSMO_GSM631_SID_CLASS_VALID: + /* "Rejuvenate" this SID frame, correcting any errors */ + osmo_efr_sid_reset(rtp_payload); + return true; + default: + /* There are only 3 possible SID classifications per GSM 06.81 + * section 6.1.1, thus any other return value is a grave error + * in the code. */ + OSMO_ASSERT(0); + } +} diff --git a/src/codec/gsm690.c b/src/codec/gsm690.c index cc6cdf0c..3b2e6694 100644 --- a/src/codec/gsm690.c +++ b/src/codec/gsm690.c @@ -18,10 +18,6 @@ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * - * You should have received a copy of the GNU General Public License along - * with this program; if not, write to the Free Software Foundation, Inc., - * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - * */ #include <stdint.h> diff --git a/src/codec/hr_sid_class.c b/src/codec/hr_sid_class.c new file mode 100644 index 00000000..6c5ba3d2 --- /dev/null +++ b/src/codec/hr_sid_class.c @@ -0,0 +1,176 @@ +/* + * This module implements osmo_hr_sid_classify() function - an independent + * reimplementation of the logic that was recommended (but not stipulated + * as normative) by ETSI for classifying received TCH/HS frames as + * valid SID, invalid SID or non-SID speech. + * + * Author: Mychaela N. Falconia <falcon@freecalypso.org>, 2024 - however, + * Mother Mychaela's contributions are NOT subject to copyright. + * No rights reserved, all rights relinquished. + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + */ + +#include <stdint.h> +#include <stdbool.h> + +#include <osmocom/codec/codec.h> + +/* + * Input to the table: any 4-bit nibble. + * Output from the table: number of 1 bits in that nibble. + */ +static const uint8_t ones_in_nibble[16] = {0, 1, 1, 2, 1, 2, 2, 3, + 1, 2, 2, 3, 2, 3, 3, 4}; + +/* + * This helper function takes two byte arrays of equal length (data and mask), + * applies the mask to the data, then counts how many bits are set to 1 + * under the mask, and returns that number. + */ +static unsigned count_ones_under_mask(const uint8_t *data, const uint8_t *mask, + unsigned nbytes) +{ + unsigned n, accum; + uint8_t and; + + accum = 0; + for (n = 0; n < nbytes; n++) { + and = *data++ & *mask++; + accum += ones_in_nibble[and >> 4] + ones_in_nibble[and & 0xF]; + } + return accum; +} + +/* + * When a GSM-HR SID frame has been decoded correctly in voiced mode, + * the 79 bits of the SID field will be the last bits in the frame. + * In the packed format of TS 101 318, the bits of interest will be + * in the last 10 bytes. The following array is the mask to be applied. + */ +static const uint8_t sid_field_last10_mask[10] = { + 0x7F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF +}; + +/* + * When a GSM-HR SID frame has been incorrectly decoded in unvoiced mode + * (both mode bits got flipped to 0 by channel errors), the 79 bits + * of the SID field will be badly misordered all over the frame. + * However, they can still be counted for the purpose of SID detection. + * The following array is the mask to be applied to the whole frame + * (14 bytes) to locate the misordered SID field. + */ +static const uint8_t sid_field_misordered[14] = { + 0x08, 0xEF, 0x1F, 0x3F, 0xF3, 0xFC, 0xA4, + 0xFF, 0xFA, 0x3F, 0xFF, 0x47, 0xFF, 0xEC +}; + +/* + * In the channel coding scheme on TCH/HS, the HR codec frame of 112 bits + * is divided into 95 class 1 bits and 17 class 2 bits. In the packed + * format of TS 101 318, all 17 class 2 bits will always be in the last + * 4 bytes; however, the specific bits will be different depending on + * whether the frame was decoded in voiced or unvoiced mode. + * The following two arrays are masks to be applied to the last 4 bytes. + */ +static const uint8_t class2_mask_voiced[4] = {0x7F, 0x80, 0x3F, 0xE0}; +static const uint8_t class2_mask_unvoiced[4] = {0x07, 0x07, 0xFF, 0xE0}; + +/* + * osmo_hr_sid_classify() - this function is an independent reimplementation + * of the logic that was recommended (but not stipulated as normative) by ETSI + * for classifying received TCH/HS frames as valid SID, invalid SID or non-SID + * speech. ETSI's original version is swSidDetection() function in reid.c + * in GSM 06.06 source; the present version implements exactly the same + * logic (same inputs will produce same output), but differs in the following + * ways: + * + * - The frame of channel-decoded 112 payload bits was passed in the form + * of an array of 18 codec parameters in ETSI's version; the present version + * uses the packed format of TS 101 318 instead. + * + * - The C code implementation was written anew by Mother Mychaela; no code + * in this file has been copied directly from GSM 06.06 code drop. + * + * This function is meant to be used only in the same network element + * that performs GSM 05.03 channel decoding (OsmoBTS, new implementations + * of GSM MS), _*NOT*_ in programs or network elements that receive + * HRv1 codec frames from other elements via RTP or Abis-E1 etc! + * + * The BCI logic recommended by ETSI and implemented in practice by at least + * one vendor whose implementation has been reverse-engineered (TI Calypso) + * is included in this function. To understand this logic, please refer + * to this wiki description: + * + * https://osmocom.org/projects/retro-gsm/wiki/HRv1_error_flags + */ +enum osmo_gsm631_sid_class osmo_hr_sid_classify(const uint8_t *rtp_payload, + bool bci_flag, + bool *bfi_from_bci) +{ + uint8_t mode_bits = rtp_payload[4] & 0x30; + unsigned sid_field_ones, class1_ones, class2_ones; + unsigned sid_field_zeros, class1_zeros; + unsigned invalid_sid_threshold; + enum osmo_gsm631_sid_class sidc; + + if (mode_bits != 0) { /* decoded as voiced */ + sid_field_ones = count_ones_under_mask(rtp_payload + 4, + sid_field_last10_mask, 10); + class2_ones = count_ones_under_mask(rtp_payload + 10, + class2_mask_voiced, 4); + } else { /* decoded as unvoiced */ + sid_field_ones = count_ones_under_mask(rtp_payload, + sid_field_misordered, 14); + class2_ones = count_ones_under_mask(rtp_payload + 10, + class2_mask_unvoiced, 4); + } + /* All class 2 bits are in SID field, hence class2_ones can never + * be greater than sid_field_ones. */ + class1_ones = sid_field_ones - class2_ones; + /* 79 is the total number of bits in the SID field */ + sid_field_zeros = 79 - sid_field_ones; + /* 62 is the total number of class 1 bits in TCH/HS frame */ + class1_zeros = 62 - class1_ones; + + /* frame classification logic recommended by ETSI */ + if (bci_flag) + invalid_sid_threshold = 16; + else + invalid_sid_threshold = 11; + + if (class1_zeros < 3) + sidc = OSMO_GSM631_SID_CLASS_VALID; + else if (sid_field_zeros < invalid_sid_threshold) + sidc = OSMO_GSM631_SID_CLASS_INVALID; + else + sidc = OSMO_GSM631_SID_CLASS_SPEECH; + + /* If the mode bits got corrupted and the frame was channel-decoded + * as unvoiced, it cannot be taken as valid SID because the bits + * that hold CN parameters have been misordered. Therefore, + * we have to turn it into invalid SID classification. + */ + if (mode_bits == 0 && sidc == OSMO_GSM631_SID_CLASS_VALID) + sidc = OSMO_GSM631_SID_CLASS_INVALID; + + /* ETSI's peculiar logic that "upgrades" BCI error flag to BFI + * (from lowest to highest error severity) when the decoded bit + * pattern matches a set criterion. We leave it up to applications + * whether they choose to apply this logic or not. If this logic + * is not wanted, pass NULL pointer as the last argument. + */ + if (bci_flag && bfi_from_bci && + sid_field_zeros >= 16 && sid_field_zeros <= 25) + *bfi_from_bci = true; + + return sidc; +} |