FreeCalypso > hg > freecalypso-tools

annotate doc/RF_tables @ 399:5e91b1c107eb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fc-shell help file: documented key, keydown and keyup commands
author Mychaela Falconia <falcon@freecalypso.org>
date Fri, 16 Mar 2018 01:47:08 +0000
parents 158fef5f4b82
children 817f3b5f019e
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
309
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
48 format with the save-rf-table command.
148
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
309
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
54 analysis. The conversion is lossless.
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
55
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
56 * Any RF table in our ASCII format can be converted back into the corresponding
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
57 native binary with our fc-cal2bin utility.
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
58
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
59 * Each RF table type for which there is a directly corresponding file in FFS
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
60 can be uploaded into the FFS of a FreeCalypso GSM device directly from our
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
61 ASCII format with the fc-fsio utility's upload-rf-table command.
148
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 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
64 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
65 Mode commands:
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 * 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
68 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
69 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
70 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
71 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
72 /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
73 are 3 separate tables.
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74
0e7a85356130 doc/RF_tables write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 * 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
76 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
77 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
78 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
79 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
80 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
81 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
82
309
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
83 Our FreeCalypso ASCII RF table format includes support for a table of type
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
84 tx-ramps; these ramps tables can be written by fc-cal2text, converted back to
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
85 native binary with fc-cal2bin and uploaded with fc-fsio's upload-rf-table
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
86 command, but cannot be uploaded with fc-tmsh's rftw command corresponding to
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
87 the RF_TABLE_WRITE Test Mode command. There is also an ASCII format for a
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
88 single Tx ramp template that can be uploaded with the ttw command; templates
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
89 read back via the ttr command can be saved in the same format with the
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
90 save-tx-ramp command.
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
91
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
92 In the case of the il2agc table, a FreeCalypso ASCII RF table of type il2agc is
158fef5f4b82 doc/RF_tables: updated for the newly implemented more complete support
Mychaela Falconia <falcon@freecalypso.org>
parents: 148
diff changeset
93 singular as in the Test Mode protocal, not triple as in FFS.