+
−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.