# HG changeset patch # User Mychaela Falconia # Date 1686016056 0 # Node ID 915ff61137ee2b5cc53ada5ab9a4a229b70cadef # Parent 80f0996bfd16f27c89672b6dec34bffc1fdd5f10 Speech-codec-selection: document MSCAP diff -r 80f0996bfd16 -r 915ff61137ee Speech-codec-selection --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Speech-codec-selection Tue Jun 06 01:47:36 2023 +0000 @@ -0,0 +1,167 @@ +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.