--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Rvinterf-tools	Sun Nov 04 09:58:50 2018 +0000
@@ -0,0 +1,235 @@
+This document describes the basic usage principles for our rvinterf suite of
+tools, which is the subset of FC host tools for talking to TI-based GSM devices
+via the RVTMUX binary packet interface.
+
+rvtdump
+=======
+
+Rvtdump is a utility that listens on a serial port, receives traces or any other
+packets emitted by the running firmware of a GSM device in TI's RVTMUX format,
+decodes them into readable ASCII and emits them to stdout and/or to a log file.
+It is to be invoked as follows:
+
+rvtdump [options] /dev/ttyXXX
+
+where the sole non-option argument is the serial port it should open and listen
+on.
+
+The available options are:
+
+-b
+
+	Normally the rvtdump process remains in the foreground and emits its
+	output on stdout.  The -b option suppresses the normal output and causes
+	rvtdump to put itself in the background: fork at startup, then have the
+	parent exit while the child remains running.  -b is not useful and not
+	allowed without -l.
+
+-B baud
+
+	Selects which RVTMUX serial channel baud rate our tool should listen
+	for.  Defaults to 115200 baud, which is TI's default and is correct for
+	our standard FreeCalypso firmwares, for Openmoko's legacy firmwares and
+	for Pirelli's proprietary fw.  Use -B 57600 for Compal's RVTMUX, the
+	one accessible via **16379#.
+
+-d <file descriptor number>
+
+	This option is not meant for direct use by human users.  It is inserted
+	automatically when rvtdump is launched from fc-xram as the secondary
+	program that immediately takes over the serial channel.
+
+-l logfile
+
+	Log all received and decoded packets into the specified file in addition
+	to (without -b) or instead of (with -b) dumping them on stdout.  Each
+	line in the log file is also time-stamped; the timestamps are in GMT
+	(gmtime(3)) instead of local time - Spacefalcon the Outlaw dislikes
+	local times.
+
+rvinterf
+========
+
+Rvinterf (the specific program by this name) is an extended version of rvtdump
+(see above) that decodes and dumps and/or logs any and all output generated by
+the firmware running on the target just like rvtdump, but also creates a local
+UNIX domain socket on the host machine to which "client" programs can connect.
+"Client" programs connecting to rvinterf via this local socket interface can:
+
+1. Receive copies of selected RVTMUX packets coming from the target;
+
+2. Send arbitrary RVTMUX packets toward the target.
+
+Rvinterf is invoked just like rvtdump:
+
+rvinterf [options] /dev/ttyXXX
+
+The following options have the same meaning as in rvtdump, see the rvtdump
+section above for the details: -b, -B, -d and -l.  The only difference is that
+-b without -l is potentially useful and thus allowed.
+
+Additional rvinterf options which don't exist in rvtdump are:
+
+-n
+
+	Suppress the output on stdout like -b, but don't fork into background.
+	This option is passed by "client" programs when they invoke rvinterf
+	behind the scenes instead of connecting to an already-running rvinterf
+	instance.
+
+-s pathname_for_socket
+
+	By default the local UNIX domain socket created by rvinterf is bound to
+	/tmp/rvinterf_socket; this option allows any other pathname to be
+	specified.
+
+-S <file descriptor number>
+
+	This option is not meant for direct use by human users.  It is passed
+	by "client" programs when they invoke rvinterf behind the scenes with
+	an unnamed and unbound socket pair instead of conecting to an already-
+	running rvinterf instance.
+
+-w number_in_seconds
+
+	Reliable UART communication with a Calypso GSM device that can
+	potentially enter the so-called "deep sleep" mode requires certain
+	special workarounds that could be described as a bit of an ugly hack:
+	see the Deep-sleep-support article for the gory details.  The hack
+	implemented in rvinterf is as follows: if a packet is to be sent to the
+	target and more than a set time has elapsed since the last transmitted
+	packet, the packet is preceded by a "wake-up shot" of 64 0 bytes
+	(outside of a packet, ignored by the fw) and a 100 ms pause.
+
+	The -w option changes the elapsed time threshold at which the "wake-up
+	shot" is sent; the default is 7 s.  Specify -w 0 to disable this hack
+	altogether.
+
+Client programs
+===============
+
+We have an entire family of so-called "client" programs which connect to
+rvinterf via the local socket interface and use rvinterf as the back-end engine
+for communicating with GSM device firmwares.  The main ones are fc-fsio,
+fc-shell and fc-tmsh described in the RVTMUX article, and the less important
+ones are fc-memdump, fc-dspapidump, fc-readcal and fc-tmsync listed in
+Host-tools-overview.  There is also the fcup-rvtat program which is invoked
+behind the scenes by fcup-* tools (see User-phone-tools) when they are used
+with the -R option.
+
+All of these client programs can work in one of two ways: they can connect to
+an already running rvinterf process through the UNIX domain socket mechanism,
+or they can launch their own private instance of rvinterf behind the scenes,
+using an unnamed and unbound socket pair.  (Don't try to have two or more
+rvinterf instances running on the same serial port, it won't work.)  The
+following command line options are standardized across all of our rvinterf
+client programs:
+
+-p /dev/ttyXXX
+
+	Don't connect to an already running rvinterf process, instead launch a
+	private instance of rvinterf on the named serial port.
+
+-B baud
+-l logfile
+-w number_in_seconds
+
+	These options are valid only when -p is used, and are passed through to
+	rvinterf.
+
+-s pathname_for_socket
+
+	Connect to a different local UNIX domain socket pathname instead of the
+	default /tmp/rvinterf_socket.  This option is valid only when -p is not
+	used.
+
+Interactive vs. one-shot operation
+==================================
+
+Our main client programs fc-fsio, fc-shell, fc-tmsh and fc-tmsync can operate
+in both interactive and one-shot modes.  If there is a specific command given
+on the invokation command line, that command is executed in the one-shot mode
+(the program executes that one command, waits for the response from the target
+if appropriate, and exits), otherwise each of the listed programs enters its
+own interactive mode with its own prompt.  The more specialized client programs
+fc-memdump, fc-dspapidump and fc-readcal always operate in the one-shot manner.
+
+fc-fsio, fc-tmsync and the just-listed specialized client programs are
+synchronous in nature: whether they are used interactively or in a one-shot
+manner (single command per program invokation), all of their operations are
+built from command-response primitives: each internal low-level function sends
+a command packet to the target via rvinterf and waits for a response from the
+target; not getting a response or getting a wrong or unexpected response is a
+fatal error.  There is no such thing as a no-wait mode (one-shot or otherwise)
+with these synchronous programs.  Furthermore, what appears to be a single
+command at the high level may consist of a large number of command-response
+packet exchanges under the hood, and the one-shot mode can be used equally
+easily to run a simple command or a script consisting of many commands.  The
+fcup-* -R mechanism (implemented by way of the fcup-rvtat back-end program) is
+also synchronous like the fc-fsio and fc-tmsync family.
+
+In contrast, fc-shell and fc-tmsh are asynchronous, and they work most naturally
+in their interactive mode.  An interactive fc-shell or fc-tmsh session is a
+select loop that listens simultaneously for both user command input on the
+terminal and packets from the target on the rvinterf socket; user commands cause
+command packets to be sent to the target and any response packets received from
+the target are decoded and displayed on the terminal, but these two directions
+are completely decoupled from each other.  The one-shot mode of operation is
+inherently less natural with these programs, and constitutes a bit of a hack.
+
+fc-tmsh offers the same repertoire of commands in both interactive and one-shot
+modes, and each of these commands sends a Test Mode command packet to the
+target.  The one-shot mode is actually two modes: one-shot with a wait for a
+target response (default) and one-shot with no wait (-n option).  One-shot with
+no wait is straighforward: fc-tmsh constructs the requested TM command packet,
+sends it to the target via rvinterf and exits.  In the other one-shot mode
+without -n, fc-tmsh sends the command packet to the target and falls into a loop
+processing input from rvinterf; as soon as some (any) packet is received from
+the target on the TM channel, that packet (which is decoded and displayed) is
+considered to be the response and the program exits with a success indication.
+
+fc-shell is the oddest of the bunch: the set of one-shot commands is a subset
+of those available in the interactive mode, as some of the commands cannot work
+outside of the interactive mode select loop environment.  Furthermore, almost
+all of the one-shot commands in fc-shell always operate in the no-wait manner
+whether -n is given or not.  The only fc-shell one-shot commands which wait for
+a target response in the absence of -n (similarly to fc-tmsh) are AT commands.
+
+Startup synchronization hack
+============================
+
+There is one annoying issue that has been seen with FTDI USB-serial adapters:
+when the serial port served by an FTDI adapter has been receiving serial traffic
+from the target while no host program is running with the port open to read it,
+and then a host program is started, that newly started host program will often
+get some stale or total garbage input from the freshly opened ttyUSBx port on
+startup.  In most usage scenarios this issue is not a killer for our rvinterf
+suite, only an annoyance: if rvinterf is started on a serial port with this
+initial garbage, there will be some garbage displayed by rvinterf initially,
+but then it will quickly regain synchronization with the running firmware
+target.  If there is any delay between the starting of rvinterf and command-
+response packet exchanges with the target (if rvinterf is run explicitly by the
+operator first and then the client program, or if the client program that
+launches rvinterf is an interactive one), no problems occur: rvinterf will be
+in sync with the target with all initial garbage flushed by the time it needs
+to do the first command-response packet exchange.
+
+There is one potentially problematic usage scenario, though: consider what
+happens when a one-shot operation is commanded, it is a type of one-shot
+operation that includes waiting for a response from the target, and rvinterf is
+being launched from the client program with -p.  In this scenario there will be
+a command packet sent to the target as soon as rvinterf starts up, and the
+client program will expect rvinterf to capture and deliver the target fw's
+response correctly, but there may not be enough time for rvinterf to clear the
+initial garbage presented by the imperfect serial port hardware+driver
+combination.
+
+Our solution to this potential trouble source is a hack: in the special case
+when rvinterf is being launched by the client program with -p and when the
+client operation to be performed falls into the category of one-shot with a wait
+for the target fw response, a 30 ms delay is inserted after the return from the
+vfork call that launches rvinterf and before any actual operations.  This hack
+has been deemed to be acceptable because this combination of doing one-shot
+operations while launching rvinterf with -p is not a very sensible way of using
+our rvinterf tools generally, hence it has been deemed acceptable to add a bit
+of slowdown to this rather contrived use case.