view doc/RF_tables @ 322:ee6443191465

CHANGES: documented fc-fsio additions
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 17 Dec 2017 03:41:05 +0000
parents 158fef5f4b82
children 817f3b5f019e
line wrap: on
line source

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 with the save-rf-table command.

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

* Any RF table in our ASCII format can be converted back into the corresponding
  native binary with our fc-cal2bin utility.

* Each RF table type for which there is a directly corresponding file in FFS
  can be uploaded into the FFS of a FreeCalypso GSM device directly from our
  ASCII format with the fc-fsio utility's upload-rf-table command.

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.

Our FreeCalypso ASCII RF table format includes support for a table of type
tx-ramps; these ramps tables can be written by fc-cal2text, converted back to
native binary with fc-cal2bin and uploaded with fc-fsio's upload-rf-table
command, but cannot be uploaded with fc-tmsh's rftw command corresponding to
the RF_TABLE_WRITE Test Mode command.  There is also an ASCII format for a
single Tx ramp template that can be uploaded with the ttw command; templates
read back via the ttr command can be saved in the same format with the
save-tx-ramp command.

In the case of the il2agc table, a FreeCalypso ASCII RF table of type il2agc is
singular as in the Test Mode protocal, not triple as in FFS.