FreeCalypso > hg > freecalypso-sw

comparison doc/RVTMUX @ 973:285505f98013

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/RVTMUX: major updates triggered by new understanding of TM/ETM relationship
author Mychaela Falconia <falcon@ivan.Harhan.ORG>
date Sun, 15 Nov 2015 01:42:50 +0000
parents 14618bd924ec
children
comparison
equal deleted inserted replaced
972:6de5661d1fe1 973:285505f98013
58 one physical serial port, and the first byte of every packet indicates which 58 one physical serial port, and the first byte of every packet indicates which
59 logical channel it belongs to. Any component within the GSM firmware suite can 59 logical channel it belongs to. Any component within the GSM firmware suite can
60 send packets to RVT for transmission on this serial interface, and can also 60 send packets to RVT for transmission on this serial interface, and can also
61 register to receive packets beginning with a particular type ID byte. 61 register to receive packets beginning with a particular type ID byte.
62 62
63 Debug trace output
64 ==================
65
66 All GSM device firmwares that are based on TI's Calypso chipset reference fw
67 continuously emit quite voluminous debug trace output on their RVTMUX serial
68 port, whether it is hidden or exposed on a given device. Like all RVTMUX
69 traffic, this debug trace output takes the form of binary packets as explained
70 above, but the content of these packets is mostly ASCII with some binary header
71 bytes prepended. FreeCalypso host utility rvtdump captures all serial output
72 from a GSM device's RVTMUX port, parses the packet structure and displays this
73 output in line-oriented pure ASCII with all binary parts decoded.
74
75 Test Mode commands
76 ==================
77
78 The other major use of the RVTMUX interface is sending so-called Test Mode
79 commands from an external host to a running GSM device. Depending on the
80 firmware version, a GSM device can be commanded to do any of the following
81 things through this mechanism:
82
83 * Exercise RF test modes, e.g., transmit continuously at a set frequency and
84 power level;
85 * Read and write arbitrary memory locations in the Calypso ARM7 address space;
86 * Read and write ABB chip registers;
87 * Reboot or power off;
88 * Access and manipulate the device's flash file system (FFS).
89
90 In the segment of history of interest to us TI has produced two different
91 target firmware components that can receive, interpret and act upon Test Mode
92 command packets:
93
94 * The original Test Mode component of Layer 1, called L1TM or TML1: this
95 component handles all RF test modes (needed for RF calibration on device
96 production lines), and originally it also implemented memory and ABB register
97 read and write commands, and provided access to TMFFS1 (see below). In the
98 original implementation this component registered itself as the handler for
99 the "TM" RVTMUX channel (RVT packet type 0x14), so it would receive all TM
100 packets sent to the device.
101
102 * Enhanced Test Mode (ETM) is a later invention. It registers itself (instead
103 of the old TM in L1) with RVT as the handler for the "TM" RVTMUX channel, and
104 then provides a registration service of its own, such that various components
105 in the fw suite can register to receive external command packets passing
106 first through RVT, then through ETM, and can send responses passing through
107 ETM, then through RVT back to the external host. If a given fw version
108 contains both ETM and L1TM, then L1TM registers itself with ETM; an external
109 host would send exactly the same binary command packets to exercise RF test
110 modes, but inside the firmware they now pass through ETM on their way to L1TM.
111
112 The ETM_CORE module contained within ETM itself provides some low-level debug
113 commands: by sending the right binary command packets to the GSM device via the
114 RVTMUX serial channel, an external host can examine or modify any memory
115 location and any hardware register, cause the device to reset, etc. Prior to
116 ETM some of these functions (but not all) could be exercised through older TM3
117 commands, but in FreeCalypso we became familiar with the ETM versions of these
118 commands long before the older ones because we got the ETM component in full
119 source form, whereas our copy of TCS211 (TI's reference fw) has L1TM in a
120 binary library.
121
122 Our TCS211/leo2moko reference fw has both ETM and L1TM, thus it accepts both
123 ETM and TM3 command packets. ETM commands (including TMFFS2, see below) work
124 on Pirelli's fw, but Mot/Compal's original fw for the C139 has only the
125 original non-enhanced Test Mode, not ETM.
126
127 FFS access via TM/ETM
128 =====================
129
130 One of the essential facilities provided in one form or another in all known
131 incarnations of the Test Mode mechanism is the ability to access and manipulate
132 the GSM device's flash file system (FFS). See TIFFS-Overview for a description
133 of this file system. TI's TMFFS1 and TMFFS2 protocols provide a command and
134 response packet interface to the FFS API functions inside the fw, and enable an
135 external host connected to the GSM device via the RVTMUX channel to perform
136 arbitrary read and write operations on the device file system.
137
138 In the segment of history of interest to us TI has produced two different
139 and entirely incompatible versions of the TMFFS protocol: TMFFS1 and TMFFS2.
140 Or rather, what is now called TMFFS1 was originally just TMFFS, and then came
141 TMFFS2. TMFFS2 works only through ETM, whereas TMFFS1 predates ETM: in the
142 original implementation the tm_ffs() function in the FFS code was called from
143 L1TM code.
144
145 Our copy of TCS211 reference fw includes the source for both TMFFS1 and TMFFS2;
146 it is theoretically possible to build a firmware image that includes both TMFFS
147 versions (they won't conflict because they respond to different command
148 packets), but it is pretty clear that TI never intended to have both enabled
149 at the same time. Our copy of TCS211 came with TMFFS1 enabled and we didn't
150 change it when we made the moko12 (leo2moko-r1) fw release for the Openmoko
151 community (the previous proprietary mokoN firmwares also implement TMFFS1),
152 but we have subsequently switched to TMFFS2 for our current TCS211-based work.
153
154 Pirelli's fw implements TMFFS2: we don't have any source for this fw, but our
155 FreeCalypso host utilities written to talk the TMFFS2 protocol based on our
156 available TCS211 source work beautifully when run against Pirelli's fw.
157
63 Use in FreeCalypso 158 Use in FreeCalypso
64 ================== 159 ==================
65 160
66 The FreeCalypso project has adopted the same general firmware architecture as 161 The FreeCalypso project has adopted the same general firmware architecture as
67 that exhibited by TI's standard firmwares from the Moko/Pirelli time frame. We 162 that exhibited by TI's standard firmwares from the Moko/Pirelli time frame. We
68 use TI's RiViera framework lifted directly out of the TCS211 reference fw, and 163 use TI's RiViera framework lifted directly out of the TCS211 reference fw, and
69 that includes the RVT module and the RVTMUX interface it presents. At the 164 that includes the RVT module and the RVTMUX interface it presents. Our GSM fw
70 present time (early development stage, none of the actual GSM functionality has 165 emits the same 3 kinds of debug traces (RV, L1 and GPF) as the pre-existing
71 been integrated yet) this RVTMUX interface is put to the following uses in our 166 firmwares with which we are seeking functional parity, and for Test Mode
72 own gsm-fw: 167 functionality we have the option of including ETM, TMFFS1 and/or TMFFS2 in our
73 168 firmware builds. (Both TMFFS versions require ETM in our implementation, and
74 * Debug trace output from various components sent via the rvf_send_trace() 169 it is possible to build a firmware image with both included.)
75 function - it is the RiViera Trace output in the proper sense; 170
76 171 We have adopted ETM and TMFFS2 as the standard combination for FreeCalypso,
77 * The ETM module and the associated FFS access protocol described below. 172 i.e., ETM_CORE for memory and ABB register reads and writes and TMFFS2 for
78 173 external FFS access. We needed to develop our own host tools for operating on
79 In the existing proprietary firmwares which serve as our reference, the RVTMUX 174 GSM device FFS via one of the two TMFFS protocols, and after studying the fw
80 serial channel is continuously spewing very voluminous debug output. This debug 175 source implementing both, I (Space Falcon) came to the conclusion that TMFFS2
81 output exhibits 3 different packet types: RV traces described above, and also 176 is both more capable and more reliable; my guess is that TMFFS1 was likely kept
82 L1 and G23 traces, each in its own format. We expect that our own gsm-fw will 177 around only because some of TI's crappy Weendoze host software depended on it.
83 become just like these reference versions in this regard, once we integrate 178 (See gsm-fw/services/ffs/tmffs.c if you would like to judge for yourself.)
84 those code layers. 179
85 180 We have the following host tools for communicating with TI-based GSM firmwares
86 ETM and FFS access 181 (both our own and some of the existing proprietary ones):
87 ================== 182
88 183 rvtdump This tool produces a human-readable dump of all output emitted
89 Another component which we have lifted out of the TCS211 reference fw is ETM, 184 by a TI-based GSM fw in the form of RVTMUX binary packets. It
90 which stands for Enhanced Test Mode. This module registers its own "top level" 185 can also log this dump to a file.
91 protocol over RVTMUX, and provides a registration service of its own, such that 186
92 various components in the fw suite can register to receive external command 187 rvinterf This tool is a superset of rvtdump: it not only dumps and/or
93 packets passing first through RVT, then through ETM, and can send responses 188 logs all output from the GSM fw, but also provides a mechanism
94 passing through ETM, then through RVT back to the external host. 189 for sending command packets to it.
95 190
96 The ETM_CORE module contained within ETM itself provides some low-level debug 191 Rvinterf is the engine behind the following host tools that send Test Mode
97 commands: by sending the right binary command packets to the GSM device via the 192 commands to a target:
98 RVTMUX serial channel, an external host can examine or modify any memory 193
99 location and any hardware register, cause the device to reset, etc. 194 fc-tmsh This is our basic tool for sending Test Mode commands to a
100 195 running GSM fw. It is strictly asynchronous in that commands
101 The only other ETM-based functionality currently integrated in our gsm-fw 196 entered by the operator get sent to the target, and any response
102 besides ETM_CORE is TMFFS (Test Mode for FFS), which is the external access 197 packets received from the target are displayed as they come in.
103 channel to the device file system - see TIFFS-Overview. The TMFFS1 and TMFFS2 198 The tool has no knowledge of any correspondence between commands
104 protocols provide a command/response packet interface to the FFS API functions 199 being sent and whatever responses they should elicit, i.e., it
105 inside the fw, and enable an external host connected to the GSM device via the 200 is perfectly suited for experimental discovery of firmware
106 RVTMUX channel to perform arbitrary read and write operations on the device 201 behaviour in response to Test Mode commands.
107 file system. 202
108 203 This tool was written before we realized that there was/is an
109 TMFFS protocol versions 204 older, more basic Test Mode predating ETM, hence in many place
205 we say "ETM" when we really should have said "TM". Oh well...
206
207 fc-fsio This tool speaks the TMFFS2 protocol and allows a user or
208 developer to perform a wide range of operations on the file
209 system of a GSM device. It operates synchronously, i.e., it
210 sends ETM/TMFFS2 commands and expects responses in strict
211 lock-step; a single user command may translate into a large
212 number of ETM/TMFFS2 command packet exchanges.
213
214 AT commands over RVTMUX
110 ======================= 215 =======================
111 216
112 TI made two different and entirely incompatible versions of the TMFFS protocol 217 There is one more use to which we put the RVTMUX debug serial interface that is
113 for accessing a device's FFS via RVT/ETM: TMFFS1 and TMFFS2. The fw sources 218 an original FreeCalypso invention: communicating with the AT command interpreter
114 available to us contain implementations of both versions, so we have the freedom 219 (ATI). TI's original architecture assumes that if a product is to offer a
115 to use whichever we like better for FreeCalypso. After studying the fw source 220 standard AT command interface (the product is either a GSM/GPRS modem for which
116 implementing the two TMFFS protocols, I (Space Falcon) came to the conclusion 221 this AT command interface is the sole mode of usage or a feature phone that
117 that TMFFS2 is both more capable and more reliable; my guess is that TMFFS1 was 222 offers a data port as one of its features), then it will be presented on a
118 likely kept around only because some of TI's crappy Weendoze host software 223 dedicated UART separate from RVTMUX.
119 depended on it. (See gsm-fw/services/ffs/tmffs.c if you would like to judge 224
120 for yourself.) Thus TMFFS2 is currently the "officially adopted" version for 225 However, many of our target devices have only one UART practically accessible,
121 FreeCalypso. 226 and even when we use Openmoko's modem as our development platform, the RVTMUX
122 227 interface is more convenient because it connects externally, whereas the MODEM
123 Our fc-tmsh utility (see below and ../rvinterf/README) allows a developer- 228 UART is connected to the application processor of the smartphone. Therefore,
124 operator to send TMFFS "get version" queries to a running GSM fw in both 229 we developed a way to pass AT commands over RVTMUX. We created a new RVTMUX
125 ETM_FFS1 and ETM_FFS2 formats; this capability allows us to determine 230 channel for this interface and assigned it RVT packet type 0x1A. Packets sent
126 experimentally which protocol (if any) is implemented by a given proprietary 231 from an external host to the GSM device carry AT commands and SMS string input,
127 firmware version. Experiments reveal that Openmoko's moko11 firmware 232 whereas packets flowing the other way carry ATI's responses to commands and
128 implements TMFFS1, whereas Pirelli's fw implements TMFFS2. 233 asynchronous notifications such as incoming calls.
129 234
130 The leo2moko-r1 firmware produced by the FreeCalypso project in 2013-10 235 The host utility for talking AT commands to a FreeCalypso GSM device via RVTMUX
131 implements TMFFS1, simply because that was the selected configuration in the 236 is fc-shell; it works via rvinterf just like fc-fsio and fc-tmsh.
132 found Leonardo source that transitional fw is based on, and that release was
133 made before I learned RVTMUX, FFS, ETM and TMFFS properly. All future
134 FreeCalypso firmwares will use TMFFS2, or at least that's the current plan.
135
136 Host utility support
137 ====================
138
139 As one would naturally expect, the FreeCalypso project has developed some host
140 tools that allow a PC running GNU/Linux (or other Unix systems) to interface to
141 running firmwares on GSM devices via RVTMUX. See the rvinterf subtree of
142 freecalypso-sw for the source and documentation.