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.