270
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
1 TI's Calypso GSM/GPRS baseband processor chip has not one but two UART serial
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
2 ports, called "MODEM" and "IrDA" in the hardware documentation. In hardware
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
3 terms, both support basic data-leads-only UART operation at a fixed baud rate,
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
4 but their extended capabilities differ: the IrDA UART adds IrDA capability (no
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
5 surprise), whereas the MODEM UART adds hardware flow control and autobaud. If
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
6 one is not implementing an actual IrDA interface, then the so-called "IrDA"
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
7 UART becomes a strict subset of the MODEM one in terms of hw capabilities -
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
8 just an extra UART, but a somewhat less capable one.
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
9
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
10 In a classic modem design such as that present in the GTA0x smartphones made by
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
11 FIC/Openmoko, the Calypso presents a standard AT command interface on its MODEM
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
12 UART port. (In the case of GTA0x phones this serial channel is wired to the
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
13 phone's application processor; in a standalone modem it would be wired to a
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
14 USB-serial chip or even to a classic RS-232 DB25 port.) However, what is less
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
15 known is that the standard firmware for such modems simultaneously presents an
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
16 entirely different interface on the IrDA UART - an interface intended for
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
17 development, debugging and factory production testing (which includes RF
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
18 calibration and IMEI etc programming), rather than for "normal" end users.
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
19
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
20 Normally this debug/development serial interface (called RVTMUX as will be
|
|
272
|
21 explained momentarily) is hidden from "ordinary" users - for example, on FIC
|
270
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
22 GTA0x phones it is wired to the analog headset jack through a hardware switch
|
|
388
|
23 which needs to be enabled through a GPIO signal from the AP. On Mot C139 and
|
|
|
24 its siblings the situation is similar: one needs to key in the secret magic
|
|
|
25 sequence **16379#, and then the firmware presents a hidden menu for switching
|
|
|
26 the analog headset jack between its "normal" function and the UART carrying
|
|
|
27 RVTMUX.
|
|
|
28
|
|
|
29 But there also exist some oddball devices on which the RVTMUX interface is
|
|
|
30 presented "in your face". The Pirelli DP-L10 phone has a USB charging port
|
|
|
31 which is also wired (through a CP2102 USB-serial chip) to the IrDA UART on the
|
|
|
32 Calypso - that's right, IrDA, not MODEM - a design decision with which this
|
|
|
33 hacker strongly disagrees. (It'll definitely be wired to the MODEM UART
|
|
|
34 instead on our own semi-clone of this phone, but I digress.) Apparently Foxconn
|
|
|
35 (the designers of this phone) had no desire to provide a standard AT command
|
|
|
36 interface, and instead the only "official" way to use the "data" function of
|
|
|
37 their USB port (rather than the charging function) is for their "PC sync"
|
|
|
38 feature, i.e., their proprietary Weendoze software. And guess what, their
|
|
|
39 proprietary "PC sync" feature works over TI's RVTMUX interface, as that is
|
|
|
40 what's presented on Calypso's IrDA UART behind the CP2102!
|
270
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
41
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
42 OK, so what is this RVTMUX? RV stands for RiViera, an application framework
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
43 which TI added to their GSM firmware suite in the early 2000s, T stands for
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
44 trace, and MUX stands for multiplexor. It's a binary packet interface, although
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
45 many of these packets contain ASCII debug messages inside. The framing format
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
46 is the same in both directions: each packet begins and ends with an STX (0x02)
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
47 byte, all payload bytes except 0x02 and 0x10 are sent literally, and there is a
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
48 DLE (0x10) byte prepended before any 0x02 or 0x10 in the payload. It's the same
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
49 general principle as asynchronous HDLC (RFC 1662): packets can contain any
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
50 binary data, and the framing provides packet boundaries - although TI's version
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
51 is a little less robust than async-HDLC when it comes to recovering after lost
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
52 synchronization.
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
53
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
54 The firmware suite component responsible for actually sending and receiving
|
|
388
|
55 these packets over the assigned UART port (usually IrDA, but can be MODEM too,
|
|
|
56 as on Compal phones for example) is called RVT (RiViera Trace), and it
|
|
|
57 implements a MUX function. There are several logical channels multiplexed over
|
|
|
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
|
|
|
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.
|
270
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
62
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
63 Use in FreeCalypso
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
64 ==================
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
65
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
66 The FreeCalypso project has adopted the same general firmware architecture as
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
67 that exhibited by TI's standard firmwares from the Moko/Pirelli time frame. We
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
68 use TI's RiViera framework lifted directly out of the TCS211 reference fw, and
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
69 that includes the RVT module and the RVTMUX interface it presents. At the
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
70 present time (early development stage, none of the actual GSM functionality has
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
71 been integrated yet) this RVTMUX interface is put to the following uses in our
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
72 own gsm-fw:
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
73
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
74 * Debug trace output from various components sent via the rvf_send_trace()
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
75 function - it is the RiViera Trace output in the proper sense;
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
76
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
77 * The ETM module and the associated FFS access protocol described below.
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
78
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
79 In the existing proprietary firmwares which serve as our reference, the RVTMUX
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
80 serial channel is continuously spewing very voluminous debug output. This debug
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
81 output exhibits 3 different packet types: RV traces described above, and also
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
82 L1 and G23 traces, each in its own format. We expect that our own gsm-fw will
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
83 become just like these reference versions in this regard, once we integrate
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
84 those code layers.
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
85
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
86 ETM and FFS access
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
87 ==================
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
88
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
89 Another component which we have lifted out of the TCS211 reference fw is ETM,
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
90 which stands for Enhanced Test Mode. This module registers its own "top level"
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
91 protocol over RVTMUX, and provides a registration service of its own, such that
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
92 various components in the fw suite can register to receive external command
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
93 packets passing first through RVT, then through ETM, and can send responses
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
94 passing through ETM, then through RVT back to the external host.
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
95
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
96 The ETM_CORE module contained within ETM itself provides some low-level debug
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
97 commands: by sending the right binary command packets to the GSM device via the
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
98 RVTMUX serial channel, an external host can examine or modify any memory
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
99 location and any hardware register, cause the device to reset, etc.
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
100
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
101 The only other ETM-based functionality currently integrated in our gsm-fw
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
102 besides ETM_CORE is TMFFS (Test Mode for FFS), which is the external access
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
103 channel to the device file system - see TIFFS-Overview. The TMFFS1 and TMFFS2
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
104 protocols provide a command/response packet interface to the FFS API functions
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
105 inside the fw, and enable an external host connected to the GSM device via the
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
106 RVTMUX channel to perform arbitrary read and write operations on the device
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
107 file system.
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
108
|
|
272
|
109 TMFFS protocol versions
|
|
|
110 =======================
|
|
|
111
|
|
|
112 TI made two different and entirely incompatible versions of the TMFFS protocol
|
|
388
|
113 for accessing a device's FFS via RVT/ETM: TMFFS1 and TMFFS2. The fw sources
|
|
272
|
114 available to us contain implementations of both versions, so we have the freedom
|
|
|
115 to use whichever we like better for FreeCalypso. After studying the fw source
|
|
|
116 implementing the two TMFFS protocols, I (Space Falcon) came to the conclusion
|
|
|
117 that TMFFS2 is both more capable and more reliable; my guess is that TMFFS1 was
|
|
|
118 likely kept around only because some of TI's crappy Weendoze host software
|
|
|
119 depended on it. (See gsm-fw/services/ffs/tmffs.c if you would like to judge
|
|
|
120 for yourself.) Thus TMFFS2 is currently the "officially adopted" version for
|
|
|
121 FreeCalypso.
|
|
|
122
|
|
430
|
123 Our fc-tmsh utility (see below and ../rvinterf/README) allows a developer-
|
|
|
124 operator to send TMFFS "get version" queries to a running GSM fw in both
|
|
|
125 ETM_FFS1 and ETM_FFS2 formats; this capability allows us to determine
|
|
|
126 experimentally which protocol (if any) is implemented by a given proprietary
|
|
|
127 firmware version. Experiments reveal that Openmoko's moko11 firmware
|
|
|
128 implements TMFFS1, whereas Pirelli's fw implements TMFFS2.
|
|
272
|
129
|
|
|
130 The leo2moko-r1 firmware produced by the FreeCalypso project in 2013-10
|
|
|
131 implements TMFFS1, simply because that was the selected configuration in the
|
|
|
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
|
|
388
|
134 FreeCalypso firmwares will use TMFFS2, or at least that's the current plan.
|
|
272
|
135
|
270
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
136 Host utility support
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
137 ====================
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
138
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
139 As one would naturally expect, the FreeCalypso project has developed some host
|
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff
changeset
|
140 tools that allow a PC running GNU/Linux (or other Unix systems) to interface to
|
|
430
|
141 running firmwares on GSM devices via RVTMUX. See the rvinterf subtree of
|
|
|
142 freecalypso-sw for the source and documentation.
|
