# HG changeset patch # User Mychaela Falconia # Date 1488184471 0 # Node ID 0e7a85356130ab41c21e626bdf4a639b9bace7ea # Parent d2a79b68789b0c70666b95dea003c09138fce26e doc/RF_tables write-up added diff -r d2a79b68789b -r 0e7a85356130 doc/RF_tables --- /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.