--- a/rvinterf/README	Sat Jun 21 17:27:17 2014 +0000
+++ b/rvinterf/README	Sat Jun 21 19:36:32 2014 +0000
@@ -1,89 +1,70 @@
-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
+You are looking at the suite of FreeCalypso tools for talking to the RVTMUX
+interface provided by TI-based GSM firmwares.  If you haven't already, please
+read ../doc/RVTMUX first.
 
-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.
+The fundamental difference between these tools and loadtools is that loadtools
+operate on a GSM device while its regular firmware is shut down, whereas the
+present rvinterf tools talk to active running GSM firmwares.
 
-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:
+The following tools are currently implemented:
 
 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.
+		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.
 
-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		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)) both for 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		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.
+g23sh		Like fc-tmsh (same asynchronous design), but for GPF/G23 rather
+		than ETM.  This tool and FreeCalypso project's understanding of
+		GPF/G23 in general are currently in the earliest stages, so it
+		is premature to try to describe it any further at this point.
+
+fc-sendsp	Precursor to g23sh; even less worthy of further documentation.
 
-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. :-)
+fc-fsio		This program uses RVTMUX, ETM and TMFFS2 to access the live file
+		system of a running GSM firmware.  Of the existing proprietary
+		firmwares, the only one that implements the TMFFS2 protocol
+		required for fc-fsio is Pirelli's, to the best of our knowledge.
+		This program connects to the target through rvinterf, but it
+		differs from fc-tmsh in that it operates in a synchronous
+		manner: the flow of operation is driven by user commands (just
+		like in fc-loadtool), and every time the program sends an ETM
+		command packet to the target, it expects a lock-step response.
+
+tfc139		See ../doc/Compal-unlock
+
+The fc-fsio, fc-tmsh and g23sh tools connect to the target not directly, but
+via rvinterf.  Two usage scenarios are supported:
+
+1. The user explicitly runs rvinterf (either directly or secondary to fc-xram,
+   when testing an experimental FreeCalypso firmware ramImage), leaves it
+   running (either backgrounded or in its own terminal window), and then runs
+   one of the "client" programs: fc-fsio, fc-tmsh or g23sh.  The two programs
+   connect via local UNIX domain sockets on the host machine.
+
+2. All of the "client" programs under discussion can also launch rvinterf
+   themselves.  An instance of rvinterf lauched in this manner becomes a child
+   process of the "client" program, terminating together with it, and the two
+   processes communicate via an unnamed and unbound socket pair.