FreeCalypso > hg > freecalypso-tools

annotate doc/RF_tables @ 238:08ad558c1fbc

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
CHANGES: exitcodes.h addition documented
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 20 Aug 2017 18:40:03 +0000
parents 0e7a85356130
children 158fef5f4b82
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
148
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 TI's TCS211 firmware for the Calypso+Iota+Rita chipset maintains a number of
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 tables for RF calibration and configuration. These tables can be saved in the
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 non-volatile flash file system (FFS), as normally required for per-unit RF
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 calibration; tables that are saved in FFS will be automatically read when the
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 firmware boots and whenever it switches between 900+1800 and 850+1900 MHz band
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 pairs. There is also a compiled-in default for each of the tables built into
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 the firmware image; these defaults are used whenever a given table is not found
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 in FFS.
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 The firmware also provides Test Mode commands (accessed via the RVTMUX binary
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 packet interface) through which an external host can read and write the in-RAM
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 working copies of these RF calibration and configuration tables; the standard
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 expected workflow is as follows:
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 * When the firmware first boots on a freshly manufactured board with a blank
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 FFS, the in-RAM working tables are loaded from the compiled-in defaults.
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 * The factory production test and RF calibration station connects to the
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 running firmware via RVTMUX, and as it goes through the requisite calibration
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 steps, properly adjusted RF tables are formed in the firmware's working in-RAM
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 locations.
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 * The production test and calibration station sends some special command packets
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 (encoded via the MISC_ENABLE opcode) to the firmware; these commands tell the
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 firmware to take the in-RAM RF tables and save them in the non-volatile FFS.
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 There are separate me commands for saving different groups of RF tables,
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 divided into RF calibration, RF config, Tx calibration, Tx config,
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 Rx calibration and Rx config. The tables in the Tx config and Rx config
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 groups are never modified in practice, hence they are usually not written
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 into FFS and the fw uses the compiled-in versions instead.
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 * In normal operation the GSM device firmware reads the RF calibration and
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 configuration tables that have been written into FFS on the production line
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 and subsequently persist for the lifetime of the device.
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 FreeCalypso tools provide the following support for working with these tables:
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 * We have defined our own ASCII text-based format in which each of the RF tables
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 implemented by TCS211 fw can be represented. This text format is both human-
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 and machine-readable.
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 * Our fc-tmsh utility (the tool that exchanges Test Mode command packets with
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 running firmwares) supports rftw and rftr commands for reading and writing
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 the fw's in-RAM RF tables via RF_TABLE_WRITE and RF_TABLE_READ command
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 packets. Our implementation of the rftw command takes the table data input
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 in the form of ASCII text files in our format, and the tables read back from
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 the fw via the rftr command can be written out into host files in the same
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 format.
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 * RF tables that have been saved in the non-volatile FFS can be read out
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 "in vivo" via fc-fsio or "in vitro" from a raw flash dump via tiffs. They
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 are in the firmware's native binary format. Our fc-cal2text utility can be
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 used to convert these binary files into our adopted text format for easier
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 analysis. The conversion is lossless, but we do not currently have a utility
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 to perform the opposite conversion, as there does not appear to be a use case
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 for it. If such a use case does arise, it will be easy to construct the
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 appropriate tool(s).
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 In the case of two particular RF tables there is a slight difference between
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 the way they are stored in FFS and the way they are read and written via Test
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 Mode commands:
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 * The firmware maintains 3 separate tables for il2agc (input level to AGC)
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 conversion, to be used in different circumstances. As it happens, the
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 compiled-in default is the same for all 3 tables and these tables are never
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 changed in practice, but "by the book" they are still 3 separate tables.
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 In FFS all 3 tables are concatenated together in a single file
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 /gsm/rf/rx/il2agc, but for the rftw and rftr command packet exchanges they
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 are 3 separate tables.
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 * For each supported frequency band there is a table of Tx power ramp-up and
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 ramp-down profiles. Each single ramp is 16 bytes, each ramp-up & ramp-down
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 pair is 32 bytes, and the firmware allows for 16 of these stored templates.
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 The complete table is stored in FFS as a single file of 512 bytes, but it is
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 too big for the TM3 protocol. Instead the Test Mode protocol provides
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 dedicated TX_TEMPLATE_WRITE (ttw) and TX_TEMPLATE_READ (ttr) commands which
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 write or read one 32-byte template at a time.
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 The ASCII text file representation of the RF tables adopted in FreeCalypso
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 follows the Test Mode protocol model where it deviates from the FFS model:
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 fc-cal2text turns the /gsm/rf/tx/ramps.* file for each band into 16 individual
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 ramp files, and if there is a /gsm/rf/rx/il2agc file, it will be turned into
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 three separate il2agc-av, il2agc-max and il2agc-pwr table files.