--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/RF_tables	Mon Feb 27 08:34:31 2017 +0000
@@ -0,0 +1,83 @@
+TI's TCS211 firmware for the Calypso+Iota+Rita chipset maintains a number of
+tables for RF calibration and configuration.  These tables can be saved in the
+non-volatile flash file system (FFS), as normally required for per-unit RF
+calibration; tables that are saved in FFS will be automatically read when the
+firmware boots and whenever it switches between 900+1800 and 850+1900 MHz band
+pairs.  There is also a compiled-in default for each of the tables built into
+the firmware image; these defaults are used whenever a given table is not found
+in FFS.
+
+The firmware also provides Test Mode commands (accessed via the RVTMUX binary
+packet interface) through which an external host can read and write the in-RAM
+working copies of these RF calibration and configuration tables; the standard
+expected workflow is as follows:
+
+* When the firmware first boots on a freshly manufactured board with a blank
+  FFS, the in-RAM working tables are loaded from the compiled-in defaults.
+
+* The factory production test and RF calibration station connects to the
+  running firmware via RVTMUX, and as it goes through the requisite calibration
+  steps, properly adjusted RF tables are formed in the firmware's working in-RAM
+  locations.
+
+* The production test and calibration station sends some special command packets
+  (encoded via the MISC_ENABLE opcode) to the firmware; these commands tell the
+  firmware to take the in-RAM RF tables and save them in the non-volatile FFS.
+  There are separate me commands for saving different groups of RF tables,
+  divided into RF calibration, RF config, Tx calibration, Tx config,
+  Rx calibration and Rx config.  The tables in the Tx config and Rx config
+  groups are never modified in practice, hence they are usually not written
+  into FFS and the fw uses the compiled-in versions instead.
+
+* In normal operation the GSM device firmware reads the RF calibration and
+  configuration tables that have been written into FFS on the production line
+  and subsequently persist for the lifetime of the device.
+
+FreeCalypso tools provide the following support for working with these tables:
+
+* We have defined our own ASCII text-based format in which each of the RF tables
+  implemented by TCS211 fw can be represented.  This text format is both human-
+  and machine-readable.
+
+* Our fc-tmsh utility (the tool that exchanges Test Mode command packets with
+  running firmwares) supports rftw and rftr commands for reading and writing
+  the fw's in-RAM RF tables via RF_TABLE_WRITE and RF_TABLE_READ command
+  packets.  Our implementation of the rftw command takes the table data input
+  in the form of ASCII text files in our format, and the tables read back from
+  the fw via the rftr command can be written out into host files in the same
+  format.
+
+* RF tables that have been saved in the non-volatile FFS can be read out
+  "in vivo" via fc-fsio or "in vitro" from a raw flash dump via tiffs.  They
+  are in the firmware's native binary format.  Our fc-cal2text utility can be
+  used to convert these binary files into our adopted text format for easier
+  analysis.  The conversion is lossless, but we do not currently have a utility
+  to perform the opposite conversion, as there does not appear to be a use case
+  for it.  If such a use case does arise, it will be easy to construct the
+  appropriate tool(s).
+
+In the case of two particular RF tables there is a slight difference between
+the way they are stored in FFS and the way they are read and written via Test
+Mode commands:
+
+* The firmware maintains 3 separate tables for il2agc (input level to AGC)
+  conversion, to be used in different circumstances.  As it happens, the
+  compiled-in default is the same for all 3 tables and these tables are never
+  changed in practice, but "by the book" they are still 3 separate tables.
+  In FFS all 3 tables are concatenated together in a single file
+  /gsm/rf/rx/il2agc, but for the rftw and rftr command packet exchanges they
+  are 3 separate tables.
+
+* For each supported frequency band there is a table of Tx power ramp-up and
+  ramp-down profiles.  Each single ramp is 16 bytes, each ramp-up & ramp-down
+  pair is 32 bytes, and the firmware allows for 16 of these stored templates.
+  The complete table is stored in FFS as a single file of 512 bytes, but it is
+  too big for the TM3 protocol.  Instead the Test Mode protocol provides
+  dedicated TX_TEMPLATE_WRITE (ttw) and TX_TEMPLATE_READ (ttr) commands which
+  write or read one 32-byte template at a time.
+
+The ASCII text file representation of the RF tables adopted in FreeCalypso
+follows the Test Mode protocol model where it deviates from the FFS model:
+fc-cal2text turns the /gsm/rf/tx/ramps.* file for each band into 16 individual
+ramp files, and if there is a /gsm/rf/rx/il2agc file, it will be turned into
+three separate il2agc-av, il2agc-max and il2agc-pwr table files.