Philipp Maier | 40def49 | 2017-12-16 03:42:15 +0700 | [diff] [blame] | 1 | /* |
| 2 | * (C) 2017 by sysmocom - s.f.m.c. GmbH |
| 3 | * (C) 2017 by Philipp Maier <pmaier@sysmocom.de> |
Philipp Maier | 40def49 | 2017-12-16 03:42:15 +0700 | [diff] [blame] | 4 | * All Rights Reserved |
| 5 | * |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 6 | * Significantly reworked in 2023 by Mother |
| 7 | * Mychaela N. Falconia <falcon@freecalypso.org> - however, |
| 8 | * Mother Mychaela's contributions are NOT subject to copyright. |
| 9 | * No rights reserved, all rights relinquished. |
| 10 | * Portions of this code are based on Themyscira libgsmfrp, |
| 11 | * a public domain library by the same author. |
| 12 | * |
Philipp Maier | 40def49 | 2017-12-16 03:42:15 +0700 | [diff] [blame] | 13 | * This program is free software; you can redistribute it and/or modify |
| 14 | * it under the terms of the GNU General Public License as published by |
| 15 | * the Free Software Foundation; either version 2 of the License, or |
| 16 | * (at your option) any later version. |
| 17 | * |
| 18 | * This program is distributed in the hope that it will be useful, |
| 19 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 20 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 21 | * GNU General Public License for more details. |
| 22 | * |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 23 | * |
| 24 | * The present ECU implementation for GSM-FR is closely based on the |
| 25 | * TS 46.011 spec from 3GPP; more specifically, it is based on the |
| 26 | * Example solution presented in Chapter 6 of that spec, adapted for |
| 27 | * libosmocodec ECU architecture, and comes as close to fulfilling |
| 28 | * the spec's officially stated requirements (Chapter 5) as is |
| 29 | * possible within this Osmocom-imposed architecture. Please note |
| 30 | * the following areas where the present implementation fails to |
| 31 | * fulfill the original intent of GSM spec authors: |
| 32 | * |
| 33 | * - The "lost SID" criterion, defined in GSM 06.31, is based on the |
| 34 | * TAF bit from the Radio Subsystem. However, libosmocodec ECU API |
| 35 | * does not include this flag, thus spec requirements related to |
| 36 | * lost SID conditions cannot be implemented in a strictly compliant |
| 37 | * manner. The present implementation improvises its own "lost SID" |
| 38 | * detector (not strictly spec-compliant) by counting frame_out() |
| 39 | * calls in between good traffic frame inputs via frame_in(). |
| 40 | * |
| 41 | * - In the architecture envisioned and assumed in the GSM specs, |
| 42 | * the ECU function of GSM 06.11 was never intended to be a fully |
| 43 | * modular component with its own bona fide I/O interfaces - this |
| 44 | * approach appears to be an Osmocom invention - instead this ECU |
| 45 | * function was intended to be subsumed in the Rx DTX handler |
| 46 | * component of GSM 06.31, also incorporating the comfort noise |
| 47 | * generator of GSM 06.12 - and unlike the narrower-scope ECU, |
| 48 | * this slightly-larger-scope Rx DTX handler is a modular component |
| 49 | * with well-defined I/O interfaces. In the case of BFI conditions |
| 50 | * following a SID, GSM 06.11 spec was written with the assumption |
| 51 | * that the ECU controls the comfort noise generator via internal |
| 52 | * signals, as opposed to emitting "corrected" SID frames on a |
| 53 | * modular interface going to a CN generator located somewhere else. |
| 54 | * Thus the "correct" behavior for a fully modularized ECU is unclear, |
| 55 | * and an argument can be made that the very existence of such a |
| 56 | * fully modularized ECU is incorrect in itself. The present |
| 57 | * implementation re-emits a "rejuvenated" form of the last saved |
| 58 | * SID frame during BFI conditions following a SID within the |
| 59 | * permitted window of 48 frames, then starts emitting muted SIDs |
| 60 | * with Xmaxc decreasing by 4 on each frame, and finally switches |
| 61 | * to emitting non-SID silence frames (Table 1 of TS 46.011) |
| 62 | * once Xmaxc reaches 0. |
Philipp Maier | 40def49 | 2017-12-16 03:42:15 +0700 | [diff] [blame] | 63 | */ |
| 64 | |
| 65 | #include <stdbool.h> |
| 66 | #include <string.h> |
| 67 | #include <stdint.h> |
| 68 | #include <errno.h> |
| 69 | |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 70 | #include <osmocom/core/prbs.h> |
| 71 | |
Philipp Maier | 40def49 | 2017-12-16 03:42:15 +0700 | [diff] [blame] | 72 | #include <osmocom/codec/codec.h> |
| 73 | #include <osmocom/codec/ecu.h> |
Philipp Maier | 9b1e22d | 2023-12-04 12:20:17 +0100 | [diff] [blame] | 74 | #include <osmocom/core/linuxlist.h> |
Philipp Maier | 40def49 | 2017-12-16 03:42:15 +0700 | [diff] [blame] | 75 | |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 76 | /* See TS 46.011, Chapter 6 Example solution */ |
| 77 | #define GSM611_XMAXC_REDUCE 4 |
| 78 | |
| 79 | /* The first 5 bytes of RTP encoding neatly contain the magic nibble |
| 80 | * and LARc parameters, which also happens to be the part of SID frames |
| 81 | * that needs to be passed through as-is. */ |
| 82 | #define SID_PREFIX_LEN 5 |
| 83 | |
| 84 | enum ecu_principal_state { |
| 85 | STATE_NO_DATA, |
| 86 | STATE_SPEECH, |
| 87 | STATE_SP_MUTING, |
| 88 | STATE_SID, |
| 89 | STATE_SID_MUTING, |
| 90 | }; |
| 91 | |
| 92 | struct fr_ecu_state { |
Philipp Maier | 9b1e22d | 2023-12-04 12:20:17 +0100 | [diff] [blame] | 93 | struct osmo_ecu_state ecu_state; |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 94 | enum ecu_principal_state pr_state; |
| 95 | uint8_t speech_frame[GSM_FR_BYTES]; |
| 96 | uint8_t sid_prefix[SID_PREFIX_LEN]; |
| 97 | uint8_t sid_xmaxc; |
| 98 | uint8_t sid_reemit_count; |
| 99 | struct osmo_prbs_state prng; |
Mychaela N. Falconia | 315e78a | 2023-06-23 18:42:11 +0000 | [diff] [blame] | 100 | bool last_input_was_sid; |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 101 | }; |
| 102 | |
| 103 | /* This function is the frame input to the ECU - all inputs to this |
| 104 | * function have been received by the Radio Subsystem as good traffic |
| 105 | * frames in the GSM 06.31 definition. |
| 106 | */ |
| 107 | static void fr_ecu_input(struct fr_ecu_state *fr, const uint8_t *frame) |
| 108 | { |
| 109 | enum osmo_gsm631_sid_class sidc; |
| 110 | |
| 111 | sidc = osmo_fr_sid_classify(frame); |
| 112 | switch (sidc) { |
| 113 | case OSMO_GSM631_SID_CLASS_SPEECH: |
| 114 | memcpy(fr->speech_frame, frame, GSM_FR_BYTES); |
| 115 | fr->pr_state = STATE_SPEECH; |
Mychaela N. Falconia | 315e78a | 2023-06-23 18:42:11 +0000 | [diff] [blame] | 116 | fr->last_input_was_sid = false; |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 117 | return; |
| 118 | case OSMO_GSM631_SID_CLASS_INVALID: |
| 119 | /* GSM 06.31 section 6.1.2 says: "an invalid SID frame |
| 120 | * shall be substituted by the last valid SID frame |
| 121 | * and the procedure for valid SID frames be applied." |
| 122 | * However, libosmocodec ECU architecture prevents us |
| 123 | * from doing what the spec says: the frame_in() method |
| 124 | * gets a const frame that can't be modified, and |
| 125 | * frame_out() will never get called when BFI=0, even |
| 126 | * when the "good traffic frame" (in the BFI=0 sense) |
| 127 | * is an invalid SID by the bit-counting rule. |
| 128 | * Thus there is no place where we can re-emit a cached |
| 129 | * copy of the last valid SID upon receiving an invalid SID. |
| 130 | * |
| 131 | * In the standard GSM architecture this problem never |
| 132 | * arises because the ECU is not a separate component |
| 133 | * but is coupled with the CN generator, thus the output |
| 134 | * from the Rx DTX handler block will be a CN frame, |
| 135 | * for both valid-SID and invalid-SID inputs to the block. |
| 136 | * But what can we do within the constraints of libosmocodec |
| 137 | * ECU framework? We treat the invalid SID almost like a |
| 138 | * BFI, doing almost nothing in the frame_in() method, |
| 139 | * but we reset sid_reemit_count because by the rules of |
| 140 | * GSM 06.31 an invalid SID is still an accepted SID frame |
| 141 | * for the purpose of "lost SID" logic. */ |
| 142 | fr->sid_reemit_count = 0; |
Mychaela N. Falconia | 315e78a | 2023-06-23 18:42:11 +0000 | [diff] [blame] | 143 | fr->last_input_was_sid = true; |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 144 | return; |
| 145 | case OSMO_GSM631_SID_CLASS_VALID: |
| 146 | /* save LARc part */ |
| 147 | memcpy(fr->sid_prefix, frame, SID_PREFIX_LEN); |
| 148 | /* save Xmaxc from the last subframe */ |
| 149 | fr->sid_xmaxc = ((frame[27] & 0x1F) << 1) | (frame[28] >> 7); |
| 150 | fr->pr_state = STATE_SID; |
| 151 | fr->sid_reemit_count = 0; |
Mychaela N. Falconia | 315e78a | 2023-06-23 18:42:11 +0000 | [diff] [blame] | 152 | fr->last_input_was_sid = true; |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 153 | return; |
| 154 | default: |
| 155 | /* There are only 3 possible SID classifications per GSM 06.31 |
| 156 | * section 6.1.1, thus any other return value is a grave error |
| 157 | * in the code. */ |
| 158 | OSMO_ASSERT(0); |
| 159 | } |
| 160 | } |
| 161 | |
| 162 | /* Reduce all 4 Xmaxc fields in the frame. When all 4 Xmaxc fields |
| 163 | * reach 0, the function will return true for "mute". |
| 164 | */ |
| 165 | static bool reduce_xmaxc(uint8_t *frame) |
| 166 | { |
| 167 | bool mute_flag = true; |
| 168 | uint8_t sub, xmaxc; |
| 169 | |
| 170 | for (sub = 0; sub < 4; sub++) { |
| 171 | xmaxc = ((frame[sub*7+6] & 0x1F) << 1) | (frame[sub*7+7] >> 7); |
| 172 | if (xmaxc > GSM611_XMAXC_REDUCE) { |
| 173 | xmaxc -= GSM611_XMAXC_REDUCE; |
| 174 | mute_flag = false; |
| 175 | } else |
| 176 | xmaxc = 0; |
| 177 | frame[sub*7+6] &= 0xE0; |
| 178 | frame[sub*7+6] |= xmaxc >> 1; |
| 179 | frame[sub*7+7] &= 0x7F; |
| 180 | frame[sub*7+7] |= (xmaxc & 1) << 7; |
| 181 | } |
| 182 | return mute_flag; |
| 183 | } |
| 184 | |
| 185 | /* TS 46.011 chapter 6, paragraph 4, last sentence: "The grid position |
| 186 | * parameters are chosen randomly between 0 and 3 during this time." |
| 187 | * (The "during this time" qualifier refers to the speech muting state.) |
| 188 | * This sentence in the spec must have been overlooked by previous ECU |
| 189 | * implementors, as this aspect of the muting logic was missing. |
| 190 | */ |
| 191 | static void random_grid_pos(struct fr_ecu_state *fr, uint8_t *frame) |
| 192 | { |
| 193 | uint8_t sub; |
| 194 | |
| 195 | for (sub = 0; sub < 4; sub++) { |
| 196 | frame[sub*7+6] &= 0x9F; |
| 197 | frame[sub*7+6] |= osmo_prbs_get_ubit(&fr->prng) << 6; |
| 198 | frame[sub*7+6] |= osmo_prbs_get_ubit(&fr->prng) << 5; |
| 199 | } |
| 200 | } |
| 201 | |
| 202 | /* Like reduce_xmaxc() above, but for comfort noise rather than speech. */ |
| 203 | static bool reduce_xmaxc_sid(struct fr_ecu_state *fr) |
| 204 | { |
| 205 | if (fr->sid_xmaxc > GSM611_XMAXC_REDUCE) { |
| 206 | fr->sid_xmaxc -= GSM611_XMAXC_REDUCE; |
| 207 | return false; |
| 208 | } |
| 209 | fr->sid_xmaxc = 0; |
| 210 | return true; |
| 211 | } |
| 212 | |
| 213 | /* This function implements the part which is peculiar to the present |
| 214 | * "standalone" packaging of GSM-FR ECU, without a directly coupled |
| 215 | * comfort noise generator - it re-emits synthetic SID frames during |
| 216 | * DTX pauses, initially unchanged from the saved SID and later muted. |
| 217 | */ |
| 218 | static void reemit_sid(struct fr_ecu_state *fr, uint8_t *frame) |
| 219 | { |
| 220 | uint8_t *p, sub; |
| 221 | |
| 222 | memcpy(frame, fr->sid_prefix, SID_PREFIX_LEN); |
| 223 | p = frame + SID_PREFIX_LEN; |
| 224 | for (sub = 0; sub < 4; sub++) { |
| 225 | *p++ = 0; |
| 226 | *p++ = fr->sid_xmaxc >> 1; |
| 227 | *p++ = (fr->sid_xmaxc & 1) << 7; |
| 228 | *p++ = 0; |
| 229 | *p++ = 0; |
| 230 | *p++ = 0; |
| 231 | *p++ = 0; |
| 232 | } |
| 233 | } |
| 234 | |
| 235 | /* This function is responsible for generating the ECU's output |
| 236 | * in the event that the Radio Subsystem does not have a good |
| 237 | * traffic frame - conditions corresponding to BFI=1 in the specs. |
| 238 | */ |
| 239 | static void fr_ecu_output(struct fr_ecu_state *fr, uint8_t *frame) |
| 240 | { |
| 241 | bool mute; |
| 242 | |
| 243 | switch (fr->pr_state) { |
| 244 | case STATE_NO_DATA: |
| 245 | memcpy(frame, osmo_gsm611_silence_frame, GSM_FR_BYTES); |
| 246 | return; |
| 247 | case STATE_SPEECH: |
| 248 | /* TS 46.011 chapter 6: "The first lost speech frame is |
| 249 | * replaced at the speech decoder input by the previous |
| 250 | * good speech frame." */ |
| 251 | memcpy(frame, fr->speech_frame, GSM_FR_BYTES); |
| 252 | fr->pr_state = STATE_SP_MUTING; |
| 253 | return; |
| 254 | case STATE_SP_MUTING: |
| 255 | mute = reduce_xmaxc(fr->speech_frame); |
| 256 | memcpy(frame, fr->speech_frame, GSM_FR_BYTES); |
| 257 | random_grid_pos(fr, frame); |
| 258 | if (mute) |
| 259 | fr->pr_state = STATE_NO_DATA; |
| 260 | return; |
| 261 | case STATE_SID: |
| 262 | fr->sid_reemit_count++; |
| 263 | if (fr->sid_reemit_count >= 48) { |
| 264 | fr->pr_state = STATE_SID_MUTING; |
| 265 | reduce_xmaxc_sid(fr); |
| 266 | } |
| 267 | reemit_sid(fr, frame); |
| 268 | return; |
| 269 | case STATE_SID_MUTING: |
| 270 | if (reduce_xmaxc_sid(fr)) { |
| 271 | fr->pr_state = STATE_NO_DATA; |
| 272 | memcpy(frame, osmo_gsm611_silence_frame, GSM_FR_BYTES); |
| 273 | } else |
| 274 | reemit_sid(fr, frame); |
| 275 | return; |
| 276 | default: |
| 277 | /* a severe bug in the state machine! */ |
| 278 | OSMO_ASSERT(0); |
| 279 | } |
| 280 | } |
| 281 | |
Harald Welte | 750d831 | 2019-08-01 20:05:05 +0200 | [diff] [blame] | 282 | /*********************************************************************** |
| 283 | * Integration with ECU core |
| 284 | ***********************************************************************/ |
| 285 | |
| 286 | static struct osmo_ecu_state *ecu_fr_init(void *ctx, enum osmo_ecu_codec codec) |
| 287 | { |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 288 | struct fr_ecu_state *fr; |
Harald Welte | 750d831 | 2019-08-01 20:05:05 +0200 | [diff] [blame] | 289 | |
Philipp Maier | 9b1e22d | 2023-12-04 12:20:17 +0100 | [diff] [blame] | 290 | fr = talloc_zero(ctx, struct fr_ecu_state); |
| 291 | fr->ecu_state.codec = codec; |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 292 | fr->pr_state = STATE_NO_DATA; |
| 293 | osmo_prbs_state_init(&fr->prng, &osmo_prbs15); |
Harald Welte | 750d831 | 2019-08-01 20:05:05 +0200 | [diff] [blame] | 294 | |
Philipp Maier | 9b1e22d | 2023-12-04 12:20:17 +0100 | [diff] [blame] | 295 | return (struct osmo_ecu_state *) fr; |
| 296 | } |
| 297 | |
| 298 | static inline struct fr_ecu_state *_osmo_ecu_state_get_fr(struct osmo_ecu_state *st) |
| 299 | { |
| 300 | return (struct fr_ecu_state *)container_of(st, struct fr_ecu_state, ecu_state); |
Harald Welte | 750d831 | 2019-08-01 20:05:05 +0200 | [diff] [blame] | 301 | } |
| 302 | |
| 303 | static int ecu_fr_frame_in(struct osmo_ecu_state *st, bool bfi, const uint8_t *frame, |
| 304 | unsigned int frame_bytes) |
| 305 | { |
Philipp Maier | 9b1e22d | 2023-12-04 12:20:17 +0100 | [diff] [blame] | 306 | struct fr_ecu_state *fr = _osmo_ecu_state_get_fr(st); |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 307 | |
Harald Welte | 750d831 | 2019-08-01 20:05:05 +0200 | [diff] [blame] | 308 | if (bfi) |
| 309 | return 0; |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 310 | if (frame_bytes != GSM_FR_BYTES) |
| 311 | return 0; |
| 312 | if ((frame[0] & 0xF0) != 0xD0) |
| 313 | return 0; |
Harald Welte | 750d831 | 2019-08-01 20:05:05 +0200 | [diff] [blame] | 314 | |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 315 | fr_ecu_input(fr, frame); |
Harald Welte | 750d831 | 2019-08-01 20:05:05 +0200 | [diff] [blame] | 316 | return 0; |
| 317 | } |
| 318 | |
| 319 | static int ecu_fr_frame_out(struct osmo_ecu_state *st, uint8_t *frame_out) |
| 320 | { |
Philipp Maier | 9b1e22d | 2023-12-04 12:20:17 +0100 | [diff] [blame] | 321 | struct fr_ecu_state *fr = _osmo_ecu_state_get_fr(st); |
Harald Welte | 750d831 | 2019-08-01 20:05:05 +0200 | [diff] [blame] | 322 | |
Mychaela N. Falconia | 5eb356b | 2023-05-12 17:21:25 +0000 | [diff] [blame] | 323 | fr_ecu_output(fr, frame_out); |
| 324 | return GSM_FR_BYTES; |
Harald Welte | 750d831 | 2019-08-01 20:05:05 +0200 | [diff] [blame] | 325 | } |
| 326 | |
Mychaela N. Falconia | 315e78a | 2023-06-23 18:42:11 +0000 | [diff] [blame] | 327 | static bool ecu_fr_is_dtx_pause(struct osmo_ecu_state *st) |
| 328 | { |
Philipp Maier | 9b1e22d | 2023-12-04 12:20:17 +0100 | [diff] [blame] | 329 | struct fr_ecu_state *fr = _osmo_ecu_state_get_fr(st); |
Mychaela N. Falconia | 315e78a | 2023-06-23 18:42:11 +0000 | [diff] [blame] | 330 | |
| 331 | return fr->last_input_was_sid; |
| 332 | } |
| 333 | |
Harald Welte | 750d831 | 2019-08-01 20:05:05 +0200 | [diff] [blame] | 334 | static const struct osmo_ecu_ops osmo_ecu_ops_fr = { |
| 335 | .init = ecu_fr_init, |
| 336 | .frame_in = ecu_fr_frame_in, |
| 337 | .frame_out = ecu_fr_frame_out, |
Mychaela N. Falconia | 315e78a | 2023-06-23 18:42:11 +0000 | [diff] [blame] | 338 | .is_dtx_pause = ecu_fr_is_dtx_pause, |
Harald Welte | 750d831 | 2019-08-01 20:05:05 +0200 | [diff] [blame] | 339 | }; |
| 340 | |
| 341 | static __attribute__((constructor)) void on_dso_load_ecu_fr(void) |
| 342 | { |
| 343 | osmo_ecu_register(&osmo_ecu_ops_fr, OSMO_ECU_CODEC_FR); |
| 344 | } |