FreeCalypso > hg > freecalypso-sw
comparison doc/RVTMUX @ 270:d1388095ab27
doc/RVTMUX write-up
author | Michael Spacefalcon <msokolov@ivan.Harhan.ORG> |
---|---|
date | Thu, 06 Feb 2014 09:54:02 +0000 |
parents | |
children | 9c34d938a645 |
comparison
equal
deleted
inserted
replaced
269:6e7410f7975c | 270:d1388095ab27 |
---|---|
1 TI's Calypso GSM/GPRS baseband processor chip has not one but two UART serial | |
2 ports, called "MODEM" and "IrDA" in the hardware documentation. In hardware | |
3 terms, both support basic data-leads-only UART operation at a fixed baud rate, | |
4 but their extended capabilities differ: the IrDA UART adds IrDA capability (no | |
5 surprise), whereas the MODEM UART adds hardware flow control and autobaud. If | |
6 one is not implementing an actual IrDA interface, then the so-called "IrDA" | |
7 UART becomes a strict subset of the MODEM one in terms of hw capabilities - | |
8 just an extra UART, but a somewhat less capable one. | |
9 | |
10 In a classic modem design such as that present in the GTA0x smartphones made by | |
11 FIC/Openmoko, the Calypso presents a standard AT command interface on its MODEM | |
12 UART port. (In the case of GTA0x phones this serial channel is wired to the | |
13 phone's application processor; in a standalone modem it would be wired to a | |
14 USB-serial chip or even to a classic RS-232 DB25 port.) However, what is less | |
15 known is that the standard firmware for such modems simultaneously presents an | |
16 entirely different interface on the IrDA UART - an interface intended for | |
17 development, debugging and factory production testing (which includes RF | |
18 calibration and IMEI etc programming), rather than for "normal" end users. | |
19 | |
20 Normally this debug/development serial interface (called RVTMUX as will be | |
21 explained momentarily) is hidden from "normal" users - for example, on FIC | |
22 GTA0x phones it is wired to the analog headset jack through a hardware switch | |
23 which needs to be enabled through a GPIO signal from the AP. But there also | |
24 exist some oddball devices on which the RVTMUX interface is presented "in your | |
25 face". The Pirelli DP-L10 phone has a USB charging port which is also wired | |
26 (through a CP2102 USB-serial chip) to the IrDA UART on the Calypso - that's | |
27 right, IrDA, not MODEM - a design decision with which this hacker strongly | |
28 disagrees. (It'll definitely be wired to the MODEM UART instead on our own | |
29 semi-clone of this phone, but I digress.) Apparently Foxconn (the designers | |
30 of this phone) had no desire to provide a standard AT command interface, and | |
31 instead the only "official" way to use the "data" function of their USB port | |
32 (rather than the charging function) is for their "PC sync" feature, i.e., their | |
33 proprietary Weendoze software. And guess what, their proprietary "PC sync" | |
34 feature works over TI's RVTMUX interface, as that is what's presented on | |
35 Calypso's IrDA UART behind the CP2102! | |
36 | |
37 OK, so what is this RVTMUX? RV stands for RiViera, an application framework | |
38 which TI added to their GSM firmware suite in the early 2000s, T stands for | |
39 trace, and MUX stands for multiplexor. It's a binary packet interface, although | |
40 many of these packets contain ASCII debug messages inside. The framing format | |
41 is the same in both directions: each packet begins and ends with an STX (0x02) | |
42 byte, all payload bytes except 0x02 and 0x10 are sent literally, and there is a | |
43 DLE (0x10) byte prepended before any 0x02 or 0x10 in the payload. It's the same | |
44 general principle as asynchronous HDLC (RFC 1662): packets can contain any | |
45 binary data, and the framing provides packet boundaries - although TI's version | |
46 is a little less robust than async-HDLC when it comes to recovering after lost | |
47 synchronization. | |
48 | |
49 The firmware suite component responsible for actually sending and receiving | |
50 these packets over the assigned UART port (usually IrDA, but can be MODEM too) | |
51 is called RVT (RiViera Trace), and it implements a MUX function. There are | |
52 several logical channels multiplexed over one physical serial port, and the | |
53 first byte of every packet indicates which logical channel it belongs to. Any | |
54 component within the GSM firmware suite can send packets to RVT for transmission | |
55 on this serial interface, and can also register to receive packets beginning | |
56 with a particular type ID byte. | |
57 | |
58 Use in FreeCalypso | |
59 ================== | |
60 | |
61 The FreeCalypso project has adopted the same general firmware architecture as | |
62 that exhibited by TI's standard firmwares from the Moko/Pirelli time frame. We | |
63 use TI's RiViera framework lifted directly out of the TCS211 reference fw, and | |
64 that includes the RVT module and the RVTMUX interface it presents. At the | |
65 present time (early development stage, none of the actual GSM functionality has | |
66 been integrated yet) this RVTMUX interface is put to the following uses in our | |
67 own gsm-fw: | |
68 | |
69 * Debug trace output from various components sent via the rvf_send_trace() | |
70 function - it is the RiViera Trace output in the proper sense; | |
71 | |
72 * The ETM module and the associated FFS access protocol described below. | |
73 | |
74 In the existing proprietary firmwares which serve as our reference, the RVTMUX | |
75 serial channel is continuously spewing very voluminous debug output. This debug | |
76 output exhibits 3 different packet types: RV traces described above, and also | |
77 L1 and G23 traces, each in its own format. We expect that our own gsm-fw will | |
78 become just like these reference versions in this regard, once we integrate | |
79 those code layers. | |
80 | |
81 ETM and FFS access | |
82 ================== | |
83 | |
84 Another component which we have lifted out of the TCS211 reference fw is ETM, | |
85 which stands for Enhanced Test Mode. This module registers its own "top level" | |
86 protocol over RVTMUX, and provides a registration service of its own, such that | |
87 various components in the fw suite can register to receive external command | |
88 packets passing first through RVT, then through ETM, and can send responses | |
89 passing through ETM, then through RVT back to the external host. | |
90 | |
91 The ETM_CORE module contained within ETM itself provides some low-level debug | |
92 commands: by sending the right binary command packets to the GSM device via the | |
93 RVTMUX serial channel, an external host can examine or modify any memory | |
94 location and any hardware register, cause the device to reset, etc. | |
95 | |
96 The only other ETM-based functionality currently integrated in our gsm-fw | |
97 besides ETM_CORE is TMFFS (Test Mode for FFS), which is the external access | |
98 channel to the device file system - see TIFFS-Overview. The TMFFS1 and TMFFS2 | |
99 protocols provide a command/response packet interface to the FFS API functions | |
100 inside the fw, and enable an external host connected to the GSM device via the | |
101 RVTMUX channel to perform arbitrary read and write operations on the device | |
102 file system. | |
103 | |
104 Host utility support | |
105 ==================== | |
106 | |
107 As one would naturally expect, the FreeCalypso project has developed some host | |
108 tools that allow a PC running GNU/Linux (or other Unix systems) to interface to | |
109 running firmwares on GSM devices via RVTMUX. The following tools are currently | |
110 available: | |
111 | |
112 rvtdump Opens the serial port, decodes TI's binary packet protocol, and | |
113 simply dumps every received/decoded packet on stdout in a human- | |
114 readable form. No provision for sending anything to the target. | |
115 Intended use: observing the debug trace output which all TI | |
116 firmwares emit as standard "background noise". This utility | |
117 allows one to observe/log/study the "noise" that appears on | |
118 Pirelli's USB-serial port (running Pirelli's original fw), | |
119 as well as that emitted on the IrDA (headset jack) port on the | |
120 GTA02 by mokoN/leo2moko firmwares. | |
121 | |
122 rvinterf Provides a bidirectional interface to RVTMUX on the host side. | |
123 It dumps and/or logs the "background noise" emitted by the | |
124 target just like rvtdump, but also creates a local UNIX domain | |
125 socket on the host machine to which other programs can connect, | |
126 replicating the MUXing function on the host side. | |
127 | |
128 fc-tmsh Interactive asynchronous test mode shell. This program connects | |
129 to a target GSM device through rvinterf and allows a developer- | |
130 operator to send various ETM commands to the target. ETM | |
131 responses are decoded (sometimes only lightly) and displayed. | |
132 fc-tmsh is fully asynchronous in that it continuously listens | |
133 (via select(2)) for both user input and for packets from the | |
134 target at the same time, translating any user-entered commands | |
135 into packets to the target and conversely, scribbling on the | |
136 terminal when a packet arrives from the target. It has no | |
137 knowledge of any correspondence between commands and responses | |
138 they normally elicit. |