--- /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.