FreeCalypso > hg > freecalypso-docs
view Speech-codec-selection @ 105:72a272083f46
Linux-DTR-RTS-flaw: link to new fc-linux-patch repository
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Mon, 11 Dec 2023 19:02:01 +0000 |
parents | c28a1518d268 |
children |
line wrap: on
line source
There exist a total of 5 speech TCH modes in classic GSM, outside of exotic additions (did anyone ever implement them?) of AMR-WB and TCH-8PSK; these classic 5 speech TCH modes are: TCH/FS (FRv1 codec) TCH/HS (HRv1 codec) TCH/EFS (EFR codec) TCH/AFS (AMR-FR) TCH/AHS (AMR-HR) The selection of TCH type (full-rate or half-rate) and speech version (specific codec) assigned to each voice call is always done by the GSM network - the MS has no direct control over these decisions. However, the MS tells the network which codecs it supports by way of Bearer capability IE (information element) in CC (call control) Layer 3 messages, and networks that are designed to support a wide range of GSM MS technology generations (as opposed to, for example, operating with a policy that excludes non-AMR-capable MS) heed these MS-declared speech codec capabilities when deciding which codec and TCH type to use. Per the specs, every type-approved GSM MS is required to support FRv1 codec, but support for all other speech codecs is optional in any combination. In TI's GSM MS firmware architecture there is a configuration record in the Condat PCM layer that tells the protocol stack's CC component which speech versions it should list as supported in the Bearer capability IE. This PCM configuration record is called EF_MSCAP; normally the firmware runs with its compiled-in default for this record, and that default is crafted to match the capabilities of Calypso L1. However, if there is a file named /pcm/MSCAP in FFS, that FFS file overrides the compiled-in default for EF_MSCAP; this MSCAP override mechanism can be used to artificially restrict which codecs the MS will declare to the network as supported, thereby influencing the actual codec selection by the network. As of 2023-06-05 FreeCalypso Tourmaline firmware offers 3 different methods for manipulating the speech version list sent to the network in the Bearer capability IE for voice calls: * Writing /pcm/MSCAP with fc-fsio; * Writing to EF_MSCAP more conveniently with AT%MSCAP; * Setting the speech version list directly with AT%SPVER. MSCAP record manipulation ========================= Writing /pcm/MSCAP with fc-fsio is the oldest method for artificially restricting the selection of speech codec for voice calls - this method has been available since the earliest FreeCalypso firmware versions. However, this method is very inconvenient: the firmware checks FFS for the presence of /pcm/MSCAP only once on boot, when the Condat PCM layer is initialized, and this file is never re-read afterward. Therefore, if you create or modify or delete this file with fc-fsio, your change won't have any effect whatsoever on the already-booted firmware session, instead it will only take effect on the next firmware boot cycle. The addition of AT%MSCAP private AT command solves this problem: this command updates the EF_MSCAP record through the firmware's pcm_WriteFile() API, which not only writes to FFS, but also updates the in-RAM copy in the PCM layer which takes effect on the next voice call. This command supports both set and query forms: AT%MSCAP=byte1,byte2,byte3[,byte4,byte5,byte6] -- set form AT%MSCAP? -- query form This private AT command is unusual (differs from 3GPP standard commands) in that each of the byte arguments is hexadecimal. The hexadecimal form is "raw", i.e., just the two hexadecimal digits without any prefix or suffix. For example, the following command restores the standard EF_MSCAP setting for CSD-enabled firmware builds on Calypso C035 platfotms with AMR-capable DSP ROM versions: AT%MSCAP=B7,C7,00 The full EF_MSCAP record consists of 6 bytes, but only the first 3 bytes contain defined bits; the last 3 bytes are unused and should be set to 0. The set form of AT%MSCAP command requires the first 3 bytes to be fully specified (there is no default), but the last 3 unused bytes default to 0 if left unspecified. The first byte of EF_MSCAP indicates supported speech codec versions, and the following two bytes specify CSD capabilities. The firmware's compiled-in MSCAP standard configurations are: Firmware build w/o CSD Firmware build with CSD Early Calypso silicon w/o AMR 07,00,00 87,C7,00 Final Calypso silicon with AMR 37,00,00 B7,C7,00 The first byte of EF_MSCAP is called chnMode and has the following bit definitions (ASCII art diagrams copied from TI's source comments): _______________________________________________________ |8 |7 |6 |5 |4 |3 |2 |1 | |------|------|------|------|------|------|------|------| |L1 |Tm |afs |ahs |spV3 |efrV2 |hr |spV1 | ------------------------------------------------------- (Note the same bit numbering convention as is used in the GSM 11.11 spec for EFs in the SIM file system.) Bit 1: indicates support for FRv1, must always be set Bit 2: indicates support for HRv1 Bit 3: indicates support for EFR Bit 4: defined as indicating support for "EFR v3", but there is no such thing Bit 5: indicates support for AMR-HR Bit 6: indicates support for AMR-FR Bit 7: defined as meaning "Test Mobile", not actually used Bit 8: defined as meaning "L1 Version", not actually used The second byte is called datCap1 and has the following bit definitions: _______________________________________________________ |8 |7 |6 |5 |4 |3 |2 |1 | |------|------|------|------|------|------|------|------| |14.4 |tfax |ntfax |tsyn |syn |asyn |rlp |ds | ------------------------------------------------------- Specific bit meanings per TI's source comments: Bit 1: Data support Bit 2: RLP data (NT Async) Bit 3: T Async data support Bit 4: NT Sync data support Bit 5: T Sync data support Bit 6: NT Fax support Bit 7: T Fax support Bit 8: Data rate 14.4 support The third byte is called datCap2 and has the following bit definitions: _______________________________________________________ |8 |7 |6 |5 |4 |3 |2 |1 | |------|------|------|------|------|------|------|------| |DHR | | |NAS |TPD |NTPD |TP |NTP | ------------------------------------------------------- Specific bit meanings per TI's source comments: Bit 1: NT Packet Service Bit 2: T Packet Service Bit 3: NT PAD Access Service Bit 4: T PAD Access Service Bit 5: No Alternate Services Bit 8: Data Halfrate support Note that Calypso Layer1 as delivered by TI does not support CSD on TCH/H, only on TCH/F, and this lack of CSD half-rate support is reflected in the compiled-in EF_MSCAP configuration. However, the DSP does have channel mode definitions for TCH/H4.8 and TCH/H2.4, suggesting at least partial support for half-rate CSD - perhaps this support is incomplete and/or non-functional. ARM L1 support for half-rate CSD (called IDS in the code) is very obviously missing, though. But on TCH/F our TI-inherited GSM MS solution does support CSD modes from F2.4 through F14.4 inclusive, with bearer services of transparent async, non-transparent RLP and fax. Playing with AT%MSCAP and cleaning up afterward ----------------------------------------------- The set form of AT%MSCAP command issues a pcm_WriteFile() internal API call, and that operation writes /pcm/MSCAP into FFS in addition to updating the record inside the PCM layer. Therefore, MSCAP changes made with this command persist across firmware boot cycles. There is no way to delete /pcm/MSCAP via AT%MSCAP, and thus no way to return to the standard system design state where the active MSCAP record depends on the firmware build variant on development boards where different fw build configurations are often being run. Therefore, the following clean-up procedure is recommended: Step 1: set AT%MSCAP to the standard config for your currently running firmware version, usually AT%MSCAP=37,00,00 or AT%MSCAP=B7,C7,00. Step 2: execute 'rm /pcm/MSCAP' in fc-fsio, deleting the file from FFS. Speech version preference list ============================== Whenever a GSM MS supports any additional speech codecs beyond the always- required FRv1, it needs to indicate this support to the network in the Bearer capability IE. However, the encoding of the relevant bits in this IE indicates not only which codecs the MS supports, but also their order of preference. Indicating the order of preference between supported codecs is not optional: the MS always has to transmit _some_ order-of-preference list toward the network. (For GSM MS supporting FRv1 and HRv1 but no others, there is an abbreviated version of the Bearer capability IE with octet 3a list omitted, but even then the order of preference between the two supported codecs is still indicated via the two radio channel requirement bits.) Our current FreeCalypso TCS2/TCS3 hybrid firmware indicates the following order of preference to the network, between the 5 potentially supported codecs: AMR-FR > AMR-HR > EFR > FRv1 > HRv1 (The '>' character in the above line indicates that the codec on the left is preferred over the codec on the right.) The actual Bearer capability IE is constructed by first masking off each of the 5 possible codecs as supported or not-supported per EF_MSCAP (see previous section), but those codecs that remain in the supported set are sent to the network in the order of preference following the above diagram. It appears that most GSM networks ignore the speech version preference order indicated by the MS, treating the MS-provided speech version list as an unordered checklist of supported or non-supported, and impose their own preference order set by network policy. Such behavior is implemented in Osmocom CNI software, and is also observed on the legacy GSM network of T-Mobile USA as of this writing. However, the world as a whole is big, there are many different GSM networks in different countries, and I (Mother Mychaela) deem it valuable to provide a mechanism whereby FreeCalypso-equipped GSM community members can test experimentally how their countries' GSM networks react to different speech version lists indicated by the MS, including peculiar preference orders. To facilitate such testing, FreeCalypso Tourmaline firmware provides a private debug-oriented AT command controlling the speech version list: AT%SPVER. This command takes the following forms: AT%SPVER=0 -- restore standard behavior AT%SPVER=1,sv1[,sv2[,sv3[,sv4[,sv5]]]]] -- set custom speech version list AT%SPVER? -- query current setting In the second listed form of AT%SPVER command, arguments sv1 through sv5 are speech version codes as transmitted over the air in the Bearer capability IE, as given in Table 10.5.103/3GPP TS 24.008: 0 = FRv1 1 = HRv1 2 = EFR 4 = AMR-FR 5 = AMR-HR The speech version list sent to the network will be exactly as given in the AT%SPVER command, in that order. You can list just one speech version, or all 5 of them, or any intermediate subset - but FRv1 (sv code 0) must always be included, or the AT%SPVER command will be rejected. Some examples: AT%SPVER=1,0 -- declare support for FRv1 only AT%SPVER=1,2,0,1 -- declare support for EFR, FRv1 and HRv1 in this order AT%SPVER=1,1,0 -- prefer HRv1 over FRv1 Unlike AT%MSCAP, the setting made with AT%SPVER is volatile: it is not saved anywhere in FFS, and thus does not persist across firmware boot cycles. In order to affect the Bearer capability IE in the Call confirmed message for MT calls, the AT%SPVER command needs to be given before the MT Setup message arrives from the network. For MO call testing, it is sufficient to set AT%SPVER before dialing the MO call with ATD command.