--- a/doc/RVTMUX	Tue Oct 30 00:12:26 2018 +0000
+++ b/doc/RVTMUX	Sat Nov 03 05:51:17 2018 +0000
@@ -116,12 +116,14 @@
 ETM some of these functions (but not all) could be exercised through older TM3
 commands, but in FreeCalypso we became familiar with the ETM versions of these
 commands long before the older ones because we got the ETM component in full
-source form, whereas our copy of TCS211 (TI's reference fw) has L1TM in a
-binary library.
+source form, whereas the sole surviving copy of TCS211 that serves as our golden
+reference came with L1TM in binary object form like the rest of L1, and we got
+to source-reconstructing it only much later.
 
-Our TCS211/leo2moko reference fw has both ETM and L1TM, thus it accepts both
-ETM and TM3 command packets.  ETM commands (including TMFFS2, see below) work
-on Pirelli's fw, but Mot/Compal's original fw for the C139 has only the
+Our TCS211 reference fw has both ETM and L1TM, thus it accepts both ETM and TM3
+command packets; the same holds for our current production firmwares that are
+based on this TCS211 reference.  ETM commands (including TMFFS2, see below) also
+work on Pirelli's fw, but Mot/Compal's original fw for the C139 has only the
 original non-enhanced Test Mode, not ETM.
 
 FFS access via TM/ETM
@@ -150,6 +152,7 @@
 change it when we made the moko12 (leo2moko-r1) fw release for the Openmoko
 community (the previous proprietary mokoN firmwares also implement TMFFS1),
 but we have subsequently switched to TMFFS2 for our current TCS211-based work.
+Our current production firmwares implement TMFFS2.
 
 Pirelli's fw implements TMFFS2: we don't have any source for this fw, but our
 FreeCalypso host utilities written to talk the TMFFS2 protocol based on our
@@ -158,15 +161,11 @@
 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.  Our GSM fw
-emits the same 3 kinds of debug traces (RV, L1 and GPF) as the pre-existing
-firmwares with which we are seeking functional parity, and for Test Mode
-functionality we have the option of including ETM, TMFFS1 and/or TMFFS2 in our
-firmware builds.  (Both TMFFS versions require ETM in our implementation, and
-it is possible to build a firmware image with both included.)
+Our current production firmwares for FreeCalypso modems faithfully follow the
+architecture of TI's TCS211 without any fundamental changes.  Thus the
+functionality which we present via RVTMUX is exactly the same as TI's original:
+our firmwares emit the same 3 kinds of debug traces (RV, L1 and GPF) as various
+pre-existing ones, and for Test Mode functionality we have ETM, L1TM and TMFFS2.
 
 We have adopted ETM and TMFFS2 as the standard combination for FreeCalypso,
 i.e., ETM_CORE for memory and ABB register reads and writes and TMFFS2 for
@@ -212,6 +211,13 @@
 		lock-step; a single user command may translate into a large
 		number of ETM/TMFFS2 command packet exchanges.
 
+fc-shell	This tool is asynchronous like fc-tmsh, but instead of talking
+		and listening on the TM/ETM RVTMUX channel, it talks and listens
+		on GPF's channel and on the new AT-over-RVTMUX channel which we
+		added in FreeCalypso.  fc-shell can be used to issue system
+		primitive commands to GPF (and to see firmware responses to
+		them), and to talk AT commands via RVTMUX.
+
 AT commands over RVTMUX
 =======================
 
@@ -223,40 +229,47 @@
 offers a data port as one of its features), then it will be presented on a
 dedicated UART separate from RVTMUX.
 
-However, many of our target devices have only one UART practically accessible,
-and even when we use Openmoko's modem as our development platform, the RVTMUX
-interface is more convenient because it connects externally, whereas the MODEM
-UART is connected to the application processor of the smartphone.  Therefore,
-we developed a way to pass AT commands over RVTMUX.  We created a new RVTMUX
-channel for this interface and assigned it RVT packet type 0x1A.  Packets sent
-from an external host to the GSM device carry AT commands and SMS string input,
-whereas packets flowing the other way carry ATI's responses to commands and
-asynchronous notifications such as incoming calls.
+However, in the case of our FreeCalypso family of projects about 2 years had
+passed between our first functional GSM fw attempts in 2015 and us successfully
+building our own development board in 2017; during this time we had to work on
+various crippled pre-existing Calypso devices, and many of them had only one
+UART practically accessible.  In response to this situation we developed a way
+to pass AT commands over RVTMUX.  We created a new RVTMUX channel for this
+interface and assigned it RVT packet type 0x1A.  Packets sent from an external
+host to the GSM device carry AT commands and SMS string input, whereas packets
+flowing the other way carry ATI's responses to commands and asynchronous
+notifications such as incoming calls.  The host utility for talking AT commands
+to a FreeCalypso GSM device via RVTMUX is fc-shell, described above.
 
-The host utility for talking AT commands to a FreeCalypso GSM device via RVTMUX
-is fc-shell; it works via rvinterf just like fc-fsio and fc-tmsh.
+Now that we have built a proper FreeCalypso development board with two UARTs,
+the use of this AT-over-RVTMUX hack is deprecated for general usage: this hack
+does not support any data services (CSD or GPRS), and even for SMS it is
+crippled because maximum-length messages cannot be sent in the more capable PDU
+mode.  However, it still comes in handy during certain casual testing sessions,
+and it is required if one needs to run our FreeCalypso firmware on Mot C1xx or
+Pirelli DP-L10 hardware.
 
 Keepalive mechanism
 ===================
 
-Another FreeCalypso addition to TI's RVTMUX interface is our optional keepalive
-mechanism.  The FreeCalypso family includes many subprojects, and one of these
-subprojects involves running modem-like firmware (control via AT commands only,
-no local UI) on Mot C1xx phones.  Having a device that was originally made to
-be a phone with LCD and buttons turn into a serially-controlled pseudo-modem
-(LCD stays dark, buttons do nothing) feels quite weird, and this situation is
-exacerbated on low-end Mot C1xx models that have small RAM and thus require our
-pseudo-modem fw to be flashed.
+Another FreeCalypso addition to TI's RVTMUX interface is our keepalive mechanism
+for the voice pseudo-modem hack on Mot C1xx targets.  The FreeCalypso family
+includes many subprojects, and one of these subprojects involves running modem-
+like firmware (control via AT commands only, no local UI) on Mot C1xx phones.
+Having a device that was originally made to be a phone with LCD and buttons
+turn into a serially-controlled pseudo-modem (LCD stays dark, buttons do
+nothing) feels quite weird, and this situation is exacerbated by the flashing
+requirement: the only way to run our pseudo-modem fw on Mot C1xx phones is to
+flash it, there is no way to run it out of RAM without disturbing the phone's
+original fw.
 
-Our optional keepalive mechanism is intended for the latter scenario.  There
-will be an optional feature added to pseudo-modem fw builds for C1xx targets
-(not yet implemented as of this writing) to have the firmware send periodic
-keepalive queries out the serial port, to see if there is a running rvinterf
-process on the other end of the wire, and automatically power off if there is
-no keepalive response.
+When our Magnetite and Selenite firmwares are built for a C1xx target in the
+VPM configuration, they implement the following keepalive logic: if the phone
+is powered on and running our fw, but the charging power source is not plugged
+in, the fw sends periodic keepalive queries out the serial port to see if there
+is a running rvinterf process on the other end of the wire, and automatically
+powers off if there is no keepalive response.
 
 Code has been added to rvinterf to respond with a keepalive answer packet when
 a keepalive query packet is received; the feature has been implemented on the
-rvinterf side ahead of the target fw so that when and if we do get around to
-implementing the target side, the necessary rvinterf support will be there
-waiting for us.
+rvinterf side first, and then subsequently in our Magnetite fw for C1xx targets.