I (Spacefalcon the Outlaw, FreeCalypso developer) am still learning what kinds
of traffic may be passed across TI's RVTMUX binary-packet serial interface.  We
already know that much of this traffic is debug trace output, i.e.,
unidirectional and essentially unconditional output from the GSM device.  All
of the "standard" firmwares we have (mokoN, our leo2moko which functions almost
identically, and Pirelli's fw) produce massive volumes of such trace output in
normal operation.  We already know that this "unsolicited" trace output comes
in at least 3 different flavors:

* RiViera traces emitted by rvf_send_trace()
* L1 traces
* G23 traces

The RVTMUX interface can be used for more than just trace output, though: any
component in TI's fw suite can send and/or register to receive binary packets.
As I slowly work my way through various components which comprise TI's Leonardo
fw whose semi-source we use as our reference version, learning what they do and
reintegrating them in our own gsm-fw, I will undoubtedly uncover additional uses
to which the RVTMUX interface is put.

Aside from the trivial provision in the RVT module itself whereby an external
host can send a command to the target to set a filter masking some of the RV
trace output, so far the only entity I've come across which accepts packets from
an external host is ETM (Enhanced Test Mode).  ETM implements a registration
system of its own, whereby other modules can register with ETM to receive
certain external command messages passing first through RVT, then through ETM.

Because I do not yet have a clear mental picture of *every* function for which
the RVTMUX interface will ever be used, it is correspondingly impractical to
decide on a once-and-for-all design of what the host-side software for talking
to this interface should be like.  Therefore, it is currently premature to
expect any stability in the present rvinterf subdirectory of freecalypso-sw; I
may implement something one day, then toss it away the next day (without
providing much in the way of backward compatibility) when I come up with some
other idea.

The current roadmap for what the rvinterf suite of host tools is envisioned to
look like eventually is as follows:

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 has
		already been written, and it 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	My plan is to make a copy of rvtdump, called rvinterf, and have
		it act very much like rvtdump: receive TI's packets from the
		serial port, decode them and print the decoded form on stdout.
		However, rvinterf will also create a listening UNIX domain
		socket to which other programs in the present suite will
		connect.  These other programs connecting through rvinterf will
		be able to send packets to the target, as well as register to
		receive certain kinds of target->host message packets.

fc-tmsh		FreeCalypso Test Mode Shell is my vision for the utility which
		will provide a practically usable interface to ETM.  ETM's
		general mode of operation seems to be (weasel phrase inserted
		because many other fw components may connect through ETM, and I
		have yet to study all of them) command-response: an external
		host sends a command to ETM, that command gets dispatched to the
		proper registered handler, the command function is executed, a
		response packet is composed, and finally that response is sent
		back to the host.  But because all code on the target side is
		under active development and debugging, we should not expect
		perfect lock-step behaviour on the interface; instead, our
		fc-tmsh should be fundamentally asynchronous: when the user
		enters a command, the appropriate command packet is sent to the
		target, but we are prepared for target->host messages at any
		time, without enforcing strict correspondence to issued
		commands: let the developer-operator sort that out instead.

The usage scenario I envision is that one will need to run rvinterf first
(either directly or through fc-xram) in one terminal window, leave it running,
then run fc-tmsh in another terminal window, and have it connect to rvinterf
via the local UNIX domain socket interface.  Why such complexity, why not have
one program do everything?  I suspect that in many debug/experimentation
sessions it will be necessary to use fc-tmsh on "noisy" targets, i.e., in
scenarios where the target is continuously spewing its "normal" voluminous debug
trace output, such that the "interesting" output as in responses to commands
gets drowned in the noise.  In such a scenario it would be helpful to have one
terminal window in which one sees the transcript of the fc-tmsh session,
consisting of issued commands and received ETM responses without the general
noise, and another window in which one sees all RVTMUX interface activity in
real time - the latter would allow one to observe commands having side effects
outside of ETM, such as crashing the whole fw. :-)