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.