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

TMFFS protocol versions
=======================

TI made two different and entirely incompatible versions of the TMFFS protocol
for accessing a device's FFS via RVT/ETM: TIFFS1 and TIFFS2.  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 (described below) 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 TIFFS2, 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.  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.

fc-tmsh implements some low-level ffs2 commands (see above regarding our design
decision to use TMFFS2 rather than TMFFS1), but it is already known that this
implementation approach is a dead end, and a different host utility is planned
to be written for full FFS read/write access via the TMFFS2 protocol.