# HG changeset patch # User Michael Spacefalcon # Date 1391680442 0 # Node ID d1388095ab2791303bdd1dd721a67c1655b3be11 # Parent 6e7410f7975c705d1112c6987f1be2a900b0eb05 doc/RVTMUX write-up diff -r 6e7410f7975c -r d1388095ab27 doc/RVTMUX --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/RVTMUX Thu Feb 06 09:54:02 2014 +0000 @@ -0,0 +1,138 @@ +TI's Calypso GSM/GPRS baseband processor chip has not one but two UART serial +ports, called "MODEM" and "IrDA" in the hardware documentation. In hardware +terms, both support basic data-leads-only UART operation at a fixed baud rate, +but their extended capabilities differ: the IrDA UART adds IrDA capability (no +surprise), whereas the MODEM UART adds hardware flow control and autobaud. If +one is not implementing an actual IrDA interface, then the so-called "IrDA" +UART becomes a strict subset of the MODEM one in terms of hw capabilities - +just an extra UART, but a somewhat less capable one. + +In a classic modem design such as that present in the GTA0x smartphones made by +FIC/Openmoko, the Calypso presents a standard AT command interface on its MODEM +UART port. (In the case of GTA0x phones this serial channel is wired to the +phone's application processor; in a standalone modem it would be wired to a +USB-serial chip or even to a classic RS-232 DB25 port.) However, what is less +known is that the standard firmware for such modems simultaneously presents an +entirely different interface on the IrDA UART - an interface intended for +development, debugging and factory production testing (which includes RF +calibration and IMEI etc programming), rather than for "normal" end users. + +Normally this debug/development serial interface (called RVTMUX as will be +explained momentarily) is hidden from "normal" users - for example, on FIC +GTA0x phones it is wired to the analog headset jack through a hardware switch +which needs to be enabled through a GPIO signal from the AP. But there also +exist some oddball devices on which the RVTMUX interface is presented "in your +face". The Pirelli DP-L10 phone has a USB charging port which is also wired +(through a CP2102 USB-serial chip) to the IrDA UART on the Calypso - that's +right, IrDA, not MODEM - a design decision with which this hacker strongly +disagrees. (It'll definitely be wired to the MODEM UART instead on our own +semi-clone of this phone, but I digress.) Apparently Foxconn (the designers +of this phone) had no desire to provide a standard AT command interface, and +instead the only "official" way to use the "data" function of their USB port +(rather than the charging function) is for their "PC sync" feature, i.e., their +proprietary Weendoze software. And guess what, their proprietary "PC sync" +feature works over TI's RVTMUX interface, as that is what's presented on +Calypso's IrDA UART behind the CP2102! + +OK, so what is this RVTMUX? RV stands for RiViera, an application framework +which TI added to their GSM firmware suite in the early 2000s, T stands for +trace, and MUX stands for multiplexor. It's a binary packet interface, although +many of these packets contain ASCII debug messages inside. The framing format +is the same in both directions: each packet begins and ends with an STX (0x02) +byte, all payload bytes except 0x02 and 0x10 are sent literally, and there is a +DLE (0x10) byte prepended before any 0x02 or 0x10 in the payload. It's the same +general principle as asynchronous HDLC (RFC 1662): packets can contain any +binary data, and the framing provides packet boundaries - although TI's version +is a little less robust than async-HDLC when it comes to recovering after lost +synchronization. + +The firmware suite component responsible for actually sending and receiving +these packets over the assigned UART port (usually IrDA, but can be MODEM too) +is called RVT (RiViera Trace), and it implements a MUX function. There are +several logical channels multiplexed over one physical serial port, and the +first byte of every packet indicates which logical channel it belongs to. Any +component within the GSM firmware suite can send packets to RVT for transmission +on this serial interface, and can also register to receive packets beginning +with a particular type ID byte. + +Use in FreeCalypso +================== + +The FreeCalypso project has adopted the same general firmware architecture as +that exhibited by TI's standard firmwares from the Moko/Pirelli time frame. We +use TI's RiViera framework lifted directly out of the TCS211 reference fw, and +that includes the RVT module and the RVTMUX interface it presents. At the +present time (early development stage, none of the actual GSM functionality has +been integrated yet) this RVTMUX interface is put to the following uses in our +own gsm-fw: + +* Debug trace output from various components sent via the rvf_send_trace() + function - it is the RiViera Trace output in the proper sense; + +* The ETM module and the associated FFS access protocol described below. + +In the existing proprietary firmwares which serve as our reference, the RVTMUX +serial channel is continuously spewing very voluminous debug output. This debug +output exhibits 3 different packet types: RV traces described above, and also +L1 and G23 traces, each in its own format. We expect that our own gsm-fw will +become just like these reference versions in this regard, once we integrate +those code layers. + +ETM and FFS access +================== + +Another component which we have lifted out of the TCS211 reference fw is ETM, +which stands for Enhanced Test Mode. This module registers its own "top level" +protocol over RVTMUX, and provides a registration service of its own, such that +various components in the fw suite can register to receive external command +packets passing first through RVT, then through ETM, and can send responses +passing through ETM, then through RVT back to the external host. + +The ETM_CORE module contained within ETM itself provides some low-level debug +commands: by sending the right binary command packets to the GSM device via the +RVTMUX serial channel, an external host can examine or modify any memory +location and any hardware register, cause the device to reset, etc. + +The only other ETM-based functionality currently integrated in our gsm-fw +besides ETM_CORE is TMFFS (Test Mode for FFS), which is the external access +channel to the device file system - see TIFFS-Overview. The TMFFS1 and TMFFS2 +protocols provide a command/response packet interface to the FFS API functions +inside the fw, and enable an external host connected to the GSM device via the +RVTMUX channel to perform arbitrary read and write operations on the device +file system. + +Host utility support +==================== + +As one would naturally expect, the FreeCalypso project has developed some host +tools that allow a PC running GNU/Linux (or other Unix systems) to interface to +running firmwares on GSM devices via RVTMUX. The following tools are currently +available: + +rvtdump Opens the serial port, decodes TI's binary packet protocol, and + simply dumps every received/decoded packet on stdout in a human- + readable form. No provision for sending anything to the target. + Intended use: observing the debug trace output which all TI + firmwares emit as standard "background noise". This utility + allows one to observe/log/study the "noise" that appears on + Pirelli's USB-serial port (running Pirelli's original fw), + as well as that emitted on the IrDA (headset jack) port on the + GTA02 by mokoN/leo2moko firmwares. + +rvinterf Provides a bidirectional interface to RVTMUX on the host side. + It dumps and/or logs the "background noise" emitted by the + target just like rvtdump, but also creates a local UNIX domain + socket on the host machine to which other programs can connect, + replicating the MUXing function on the host side. + +fc-tmsh Interactive asynchronous test mode shell. This program connects + to a target GSM device through rvinterf and allows a developer- + operator to send various ETM commands to the target. ETM + responses are decoded (sometimes only lightly) and displayed. + fc-tmsh is fully asynchronous in that it continuously listens + (via select(2)) for both user input and for packets from the + target at the same time, translating any user-entered commands + into packets to the target and conversely, scribbling on the + terminal when a packet arrives from the target. It has no + knowledge of any correspondence between commands and responses + they normally elicit.