FreeCalypso > hg > freecalypso-tools

annotate doc/RF_tables @ 1011:6d9b10633f10 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
etmsync Pirelli IMEI retrieval: fix poor use of printf() Bug reported by Vadim Yanitskiy <fixeria@osmocom.org>: the construct where a static-allocated string was passed to printf() without any format arguments causes newer compilers to report a security problem. Given that formatted output is not needed here, just fixed string output, change printf() to fputs(), and direct the error message to stderr while at it.
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 23 May 2024 17:29:57 +0000
parents 817f3b5f019e
children
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
402
817f3b5f019e doc/RF_tables: typo fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 309
diff changeset
93 singular as in the Test Mode protocol, not triple as in FFS.