FreeCalypso > hg > freecalypso-docs
comparison Speech-codec-selection @ 98:915ff61137ee
Speech-codec-selection: document MSCAP
| author | Mychaela Falconia <falcon@freecalypso.org> |
|---|---|
| date | Tue, 06 Jun 2023 01:47:36 +0000 |
| parents | |
| children | c28a1518d268 |
comparison
equal
deleted
inserted
replaced
| 97:80f0996bfd16 | 98:915ff61137ee |
|---|---|
| 1 There exist a total of 5 speech TCH modes in classic GSM, outside of exotic | |
| 2 additions (did anyone ever implement them?) of AMR-WB and TCH-8PSK; these | |
| 3 classic 5 speech TCH modes are: | |
| 4 | |
| 5 TCH/FS (FRv1 codec) | |
| 6 TCH/HS (HRv1 codec) | |
| 7 TCH/EFS (EFR codec) | |
| 8 TCH/AFS (AMR-FR) | |
| 9 TCH/AHS (AMR-HR) | |
| 10 | |
| 11 The selection of TCH type (full-rate or half-rate) and speech version (specific | |
| 12 codec) assigned to each voice call is always done by the GSM network - the MS | |
| 13 has no direct control over these decisions. However, the MS tells the network | |
| 14 which codecs it supports by way of Bearer capability IE (information element) | |
| 15 in CC (call control) Layer 3 messages, and networks that are designed to support | |
| 16 a wide range of GSM MS technology generations (as opposed to, for example, | |
| 17 operating with a policy that excludes non-AMR-capable MS) heed these MS-declared | |
| 18 speech codec capabilities when deciding which codec and TCH type to use. | |
| 19 | |
| 20 Per the specs, every type-approved GSM MS is required to support FRv1 codec, | |
| 21 but support for all other speech codecs is optional in any combination. | |
| 22 | |
| 23 In TI's GSM MS firmware architecture there is a configuration record in the | |
| 24 Condat PCM layer that tells the protocol stack's CC component which speech | |
| 25 versions it should list as supported in the Bearer capability IE. This PCM | |
| 26 configuration record is called EF_MSCAP; normally the firmware runs with its | |
| 27 compiled-in default for this record, and that default is crafted to match the | |
| 28 capabilities of Calypso L1. However, if there is a file named /pcm/MSCAP in | |
| 29 FFS, that FFS file overrides the compiled-in default for EF_MSCAP; this MSCAP | |
| 30 override mechanism can be used to artificially restrict which codecs the MS | |
| 31 will declare to the network as supported, thereby influencing the actual codec | |
| 32 selection by the network. | |
| 33 | |
| 34 As of 2023-06-05 FreeCalypso Tourmaline firmware offers 3 different methods for | |
| 35 manipulating the speech version list sent to the network in the Bearer | |
| 36 capability IE for voice calls: | |
| 37 | |
| 38 * Writing /pcm/MSCAP with fc-fsio; | |
| 39 * Writing to EF_MSCAP more conveniently with AT%MSCAP; | |
| 40 * Setting the speech version list directly with AT%SPVER. | |
| 41 | |
| 42 MSCAP record manipulation | |
| 43 ========================= | |
| 44 | |
| 45 Writing /pcm/MSCAP with fc-fsio is the oldest method for artificially | |
| 46 restricting the selection of speech codec for voice calls - this method has been | |
| 47 available since the earliest FreeCalypso firmware versions. However, this | |
| 48 method is very inconvenient: the firmware checks FFS for the presence of | |
| 49 /pcm/MSCAP only once on boot, when the Condat PCM layer is initialized, and | |
| 50 this file is never re-read afterward. Therefore, if you create or modify or | |
| 51 delete this file with fc-fsio, your change won't have any effect whatsoever on | |
| 52 the already-booted firmware session, instead it will only take effect on the | |
| 53 next firmware boot cycle. | |
| 54 | |
| 55 The addition of AT%MSCAP private AT command solves this problem: this command | |
| 56 updates the EF_MSCAP record through the firmware's pcm_WriteFile() API, which | |
| 57 not only writes to FFS, but also updates the in-RAM copy in the PCM layer which | |
| 58 takes effect on the next voice call. This command supports both set and query | |
| 59 forms: | |
| 60 | |
| 61 AT%MSCAP=byte1,byte2,byte3[,byte4,byte5,byte6] -- set form | |
| 62 AT%MSCAP? -- query form | |
| 63 | |
| 64 This private AT command is unusual (differs from 3GPP standard commands) in that | |
| 65 each of the byte arguments is hexadecimal. The hexadecimal form is "raw", i.e., | |
| 66 just the two hexadecimal digits without any prefix or suffix. For example, the | |
| 67 following command restores the standard EF_MSCAP setting for CSD-enabled | |
| 68 firmware builds on Calypso C035 platfotms with AMR-capable DSP ROM versions: | |
| 69 | |
| 70 AT%MSCAP=B7,C7,00 | |
| 71 | |
| 72 The full EF_MSCAP record consists of 6 bytes, but only the first 3 bytes contain | |
| 73 defined bits; the last 3 bytes are unused and should be set to 0. The set form | |
| 74 of AT%MSCAP command requires the first 3 bytes to be fully specified (there is | |
| 75 no default), but the last 3 unused bytes default to 0 if left unspecified. | |
| 76 | |
| 77 The first byte of EF_MSCAP indicates supported speech codec versions, and the | |
| 78 following two bytes specify CSD capabilities. The firmware's compiled-in MSCAP | |
| 79 standard configurations are: | |
| 80 | |
| 81 Firmware build w/o CSD Firmware build with CSD | |
| 82 Early Calypso silicon w/o AMR 07,00,00 87,C7,00 | |
| 83 Final Calypso silicon with AMR 37,00,00 B7,C7,00 | |
| 84 | |
| 85 The first byte of EF_MSCAP is called chnMode and has the following bit | |
| 86 definitions (ASCII art diagrams copied from TI's source comments): | |
| 87 | |
| 88 _______________________________________________________ | |
| 89 |8 |7 |6 |5 |4 |3 |2 |1 | | |
| 90 |------|------|------|------|------|------|------|------| | |
| 91 |L1 |Tm |afs |ahs |spV3 |efrV2 |hr |spV1 | | |
| 92 ------------------------------------------------------- | |
| 93 | |
| 94 (Note the same bit numbering convention as is used in the GSM 11.11 spec for | |
| 95 EFs in the SIM file system.) | |
| 96 | |
| 97 Bit 1: indicates support for FRv1, must always be set | |
| 98 Bit 2: indicates support for HRv1 | |
| 99 Bit 3: indicates support for EFR | |
| 100 Bit 4: defined as indicating support for "EFR v3", but there is no such thing | |
| 101 Bit 5: indicates support for AMR-HR | |
| 102 Bit 6: indicates support for AMR-FR | |
| 103 Bit 7: defined as meaning "Test Mobile", not actually used | |
| 104 Bit 8: defined as meaning "L1 Version", not actually used | |
| 105 | |
| 106 The second byte is called datCap1 and has the following bit definitions: | |
| 107 | |
| 108 _______________________________________________________ | |
| 109 |8 |7 |6 |5 |4 |3 |2 |1 | | |
| 110 |------|------|------|------|------|------|------|------| | |
| 111 |14.4 |tfax |ntfax |tsyn |syn |asyn |rlp |ds | | |
| 112 ------------------------------------------------------- | |
| 113 | |
| 114 Specific bit meanings per TI's source comments: | |
| 115 | |
| 116 Bit 1: Data support | |
| 117 Bit 2: RLP data (NT Async) | |
| 118 Bit 3: T Async data support | |
| 119 Bit 4: NT Sync data support | |
| 120 Bit 5: T Sync data support | |
| 121 Bit 6: NT Fax support | |
| 122 Bit 7: T Fax support | |
| 123 Bit 8: Data rate 14.4 support | |
| 124 | |
| 125 The third byte is called datCap2 and has the following bit definitions: | |
| 126 | |
| 127 _______________________________________________________ | |
| 128 |8 |7 |6 |5 |4 |3 |2 |1 | | |
| 129 |------|------|------|------|------|------|------|------| | |
| 130 |DHR | | |NAS |TPD |NTPD |TP |NTP | | |
| 131 ------------------------------------------------------- | |
| 132 | |
| 133 Specific bit meanings per TI's source comments: | |
| 134 | |
| 135 Bit 1: NT Packet Service | |
| 136 Bit 2: T Packet Service | |
| 137 Bit 3: NT PAD Access Service | |
| 138 Bit 4: T PAD Access Service | |
| 139 Bit 5: No Alternate Services | |
| 140 Bit 8: Data Halfrate support | |
| 141 | |
| 142 Note that Calypso Layer1 as delivered by TI does not support CSD on TCH/H, only | |
| 143 on TCH/F, and this lack of CSD half-rate support is reflected in the compiled-in | |
| 144 EF_MSCAP configuration. However, the DSP does have channel mode definitions for | |
| 145 TCH/H4.8 and TCH/H2.4, suggesting at least partial support for half-rate CSD - | |
| 146 perhaps this support is incomplete and/or non-functional. ARM L1 support for | |
| 147 half-rate CSD (called IDS in the code) is very obviously missing, though. But | |
| 148 on TCH/F our TI-inherited GSM MS solution does support CSD modes from F2.4 | |
| 149 through F14.4 inclusive, with bearer services of transparent async, | |
| 150 non-transparent RLP and fax. | |
| 151 | |
| 152 Playing with AT%MSCAP and cleaning up afterward | |
| 153 ----------------------------------------------- | |
| 154 | |
| 155 The set form of AT%MSCAP command issues a pcm_WriteFile() internal API call, | |
| 156 and that operation writes /pcm/MSCAP into FFS in addition to updating the record | |
| 157 inside the PCM layer. Therefore, MSCAP changes made with this command persist | |
| 158 across firmware boot cycles. There is no way to delete /pcm/MSCAP via AT%MSCAP, | |
| 159 and thus no way to return to the standard system design state where the active | |
| 160 MSCAP record depends on the firmware build variant on development boards where | |
| 161 different fw build configurations are often being run. Therefore, the following | |
| 162 clean-up procedure is recommended: | |
| 163 | |
| 164 Step 1: set AT%MSCAP to the standard config for your currently running firmware | |
| 165 version, usually AT%MSCAP=37,00,00 or AT%MSCAP=B7,C7,00. | |
| 166 | |
| 167 Step 2: execute 'rm /pcm/MSCAP' in fc-fsio, deleting the file from FFS. |