--- /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.