FreeCalypso > hg > freecalypso-sw
view doc/RVTMUX @ 933:8eb7cb176a70
compal-flash-boot-for-fc/README added
author | Mychaela Falconia <falcon@ivan.Harhan.ORG> |
---|---|
date | Sat, 31 Oct 2015 03:26:15 +0000 |
parents | 14618bd924ec |
children | 285505f98013 |
line wrap: on
line source
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 "ordinary" 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. On Mot C139 and its siblings the situation is similar: one needs to key in the secret magic sequence **16379#, and then the firmware presents a hidden menu for switching the analog headset jack between its "normal" function and the UART carrying RVTMUX. 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, as on Compal phones for example) 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. TMFFS protocol versions ======================= TI made two different and entirely incompatible versions of the TMFFS protocol for accessing a device's FFS via RVT/ETM: TMFFS1 and TMFFS2. The fw sources available to us contain implementations of both versions, so we have the freedom to use whichever we like better for FreeCalypso. After studying the fw source implementing the two TMFFS protocols, I (Space Falcon) came to the conclusion that TMFFS2 is both more capable and more reliable; my guess is that TMFFS1 was likely kept around only because some of TI's crappy Weendoze host software depended on it. (See gsm-fw/services/ffs/tmffs.c if you would like to judge for yourself.) Thus TMFFS2 is currently the "officially adopted" version for FreeCalypso. Our fc-tmsh utility (see below and ../rvinterf/README) allows a developer- operator to send TMFFS "get version" queries to a running GSM fw in both ETM_FFS1 and ETM_FFS2 formats; this capability allows us to determine experimentally which protocol (if any) is implemented by a given proprietary firmware version. Experiments reveal that Openmoko's moko11 firmware implements TMFFS1, whereas Pirelli's fw implements TMFFS2. The leo2moko-r1 firmware produced by the FreeCalypso project in 2013-10 implements TMFFS1, simply because that was the selected configuration in the found Leonardo source that transitional fw is based on, and that release was made before I learned RVTMUX, FFS, ETM and TMFFS properly. All future FreeCalypso firmwares will use TMFFS2, or at least that's the current plan. 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. See the rvinterf subtree of freecalypso-sw for the source and documentation.