FreeCalypso > hg > freecalypso-sw

comparison doc/RVTMUX @ 270:d1388095ab27

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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.