--- a/doc/Host-tools-overview	Fri May 19 06:57:19 2017 +0000
+++ b/doc/Host-tools-overview	Sat May 20 12:48:38 2017 +0000
@@ -1,5 +1,6 @@
-FreeCalypso host tools suite features the following tools that are potentially
-useful to end users:
+FreeCalypso host tools suite includes a large number of different tools, many
+of which are quite specialized and rarely needed.  The following tools are the
+most essential ones:
 
 fc-loadtool	This is the tool used to read and write the non-volatile flash
 		memory of supported GSM devices.  It can be used to reflash
@@ -8,13 +9,32 @@
 		flash backups.  This tool operates on the target device (phone
 		or modem) while its regular firmware is shut down.
 
-fc-fsio		This tool connects to GSM devices running one of the supported
-		firmware versions while the fw is running (unlike fc-loadtool
-		which operates on a device while its regular fw is shut down)
-		and allows you to manipulate (read and write) the device's
-		flash file system.  It is thus a higher-level tool than
-		fc-loadtool.  It is intended primarily for working with our own
-		firmwares, but it also works with Pirelli's original fw.
+fc-iram,	Reprogramming the non-volatile flash memory is not the only way
+fc-xram,	to run your own code on a Calypso GSM device.  If your code is
+fc-compalram	small enough to fit entirely into the available RAM on the
+		device, and you would like to just run it without flashing it
+		permanently, these tools do the job of loading code images into
+		different kinds of RAM through different download protocols.
+		Some phones have large enough RAM to allow a complete functional
+		firmware image to be run via fc-xram without flashing.
+
+rvinterf	This program is our engine for communicating with up & running
+		TI-based firmwares through the RVTMUX binary packet interface.
+		It receives and decodes all debug trace and other packets
+		emitted by the target fw, and allows the options of printing
+		them on the terminal, saving them to a log file, and/or passing
+		them to other programs that connect to rvinterf as local socket
+		clients.  In the other direction those latter client programs
+		can send arbitrary command packets to the target fw.
+
+fc-fsio		Going through rvinterf, this tool connects to GSM devices
+		running one of the supported firmware versions while the fw is
+		running (unlike fc-loadtool which operates on a device while
+		its regular fw is shut down) and allows you to manipulate
+		(read and write) the device's flash file system.  It is thus a
+		higher-level tool than fc-loadtool.  It is intended primarily
+		for working with our own firmwares, but it also works with
+		Pirelli's original fw.
 
 fc-shell	FreeCalypso firmwares have a feature of our own invention (not
 		present in any pre-existing ones) to accept AT commands over
@@ -22,47 +42,13 @@
 		available for a dedicated standard AT command interface.
 		fc-shell is the tool that allows you to send AT commands to the
 		firmware in this manner; it also allows a few other kinds of
-		asynchronous commands to be sent.
-
-tfc139		This tool breaks into Mot C1xx phones via shellcode injection,
-		a method that works despite any bootloader locks, allowing you
-		to reflash locked phones with new firmware with fc-loadtool.
-		The name of the utility is historical: previously it was
-		specific to TFC139 phones (C139s sold with TracFone branding),
-		but the current version is expected to work with all Mot C1xx
-		firmware versions.
+		asynchronous commands to be sent.  It works through rvinterf.
 
-imei-luhn	A simple utility for computing or verifying the Luhn check
-		digit of an IMEI number.
-
-The following host tools are primarily for developers, but may be useful to
-end users as well:
-
-rvtdump		This tool produces a human-readable dump of all output emitted
-		by a TI-based GSM fw on the RVTMUX binary packet interface.  It
-		can also log this dump to a file.
+And here is a listing of all other tools in mostly-alphabetical order:
 
-rvinterf	This tool is a superset of rvtdump: it not only dumps and/or
-		logs all output from the GSM fw, but also provides a mechanism
-		for sending command packets to it.  Rvinterf is the engine
-		behind fc-fsio, fc-shell and fc-tmsh.
-
-tiffs,		These tools perform "in vitro" analysis of flash file system
-mokoffs,	(FFS) images read out of GSM devices with TI-based firmwares.
-pirffs		You can list and extract the FFS content captured as a raw
-		flash image, and even perform a few "forensic" operations along
-		the lines of reading deleted files and seeing the history of
-		FFS modifications.  tiffs is the main program, whereas mokoffs
-		and pirffs are convenience wrappers for the common FFS
-		configurations from Openmoko and Pirelli.
-
-fc-serterm	This tool is a trivial serial terminal program.  Its special
-		feature is that any output coming from the serial port that
-		isn't printable ASCII is displayed as by cat -v.  It is useful
-		for talking to serially-interfaced devices that mix ASCII with
-		binary in their serial talk.
-
-The following tools are really just for developers:
+c139explore	This is a run-from-RAM (no flashing) program for Mot C139/140
+		phones that exercises their peripheral hardware: LCD, keypad
+		backlight, buzzer and vibrator.
 
 ctracedec	GSM firmwares built in TI's Windows environment (official ones
 		as well as our own hacks based on the TCS211 semi-src) have a
@@ -74,40 +60,40 @@
 		corresponding to the fw version that emitted the output in
 		question; this ctracedec utility performs that decoding.
 
-fc-iram,	Reprogramming the non-volatile flash memory is not the only way
-fc-xram,	to run your own code on a Calypso GSM device.  If your code is
-fc-compalram	small enough to fit entirely into the available RAM on the
-		device, and you would like to just run it without flashing it
-		permanently, these tools do the job of loading code images into
-		different kinds of RAM through different download protocols.
+fc-buzplay	This program plays piezoelectic buzzer melodies on an actual
+		Calypso device equipped with such a buzzer (Mot C1xx, TI's
+		D-Sample board, our planned future HSMBP) by loading a buzplayer
+		agent onto the target and feeding melodies to be played to it.
+
+fc-cal2text	This utility takes a dump of TI's /gsm/rf flash file system
+		directory subtree as input (either extracted in vitro with tiffs
+		or read out in vivo with fc-fsio) and converts all RF tables
+		found therein into a readable ASCII format.  See the RF_tables
+		article for more details.
+
+fc-dspapidump	This utility uses ETM in synchronous mode (going through
+		rvinterf) to read and dump the contents of the DSP API RAM in a
+		target Calypso GSM device while the firmware is running.
 
-fc-tmsh		TI had a tool called TMSH that stood for "test mode shell".  We
-		don't know exactly how it worked, hence we make no claim of our
-		own test mode shell being anything like TI's original, but we
-		do have a test mode shell of our own.  It sends command packets
-		to the ETM (Enhanced Test Mode) component in the GSM firmware
-		and displays its responses in a purely asynchronous manner,
-		i.e., our tool has no knowledge of any correspondence between
-		the commands it sends and the responses they elicit.  (In
-		contrast, fc-fsio described above also talks to ETM, but it
-		does so synchronously.)
+fc-e1decode	This utility decodes a melody in TI's Melody E1 format from the
+		the native binary format to our own ASCII-based representation;
+		see the Melody_E1 article for more information.
+
+fc-e1gen	This utility compiles an E1 melody from our own ASCII source
+		format into binary bits to be loaded into a FreeCalypso phone;
+		see the Melody_E1 article for more information.
 
-fc-memdump	This tool captures a memory dump from a GSM device whose
-		firmware implements one of TI's Test Mode memory read commands,
-		either the old TM3 version or the new ETM one.  It works with
-		FreeCalypso Citrine, with TCS211-based firmwares including
-		FreeCalypso Magnetite, with really old TI firmwares which
-		predate ETM, and with Mot C1xx original firmwares.
+fc-fr2tch	This hack-utility converts a GSM 06.10 speech sample from the
+		de facto standard libgsm format (which can be recorded with
+		standard tools like SoX) into an uplink play file that can be
+		played with the tch play command in fc-shell; see the
+		TCH-bit-access article for more information.
 
-fc-rgbconv	A simple aid for phone UI development that converts RGB color
-		values between human-intuitive 8:8:8 format and the 5:6:5 format
-		used by the color LCDs in the phones targeted by FreeCalypso.
-
-The following tools are really just special-purpose hacks:
-
-fc-dspapidump	This utility uses ETM in synchronous mode to read and dump the
-		contents of the DSP API RAM in a target Calypso GSM device
-		while the firmware is running.
+fc-gsm2vm	This utility converts a GSM 06.10 speech sample from the same
+		libgsm source format into a voice memo file that can be
+		uploaded into the FFS of a FreeCalypso device and played with
+		the audio_vm_play_start() API or the AT@VMP command that
+		invokes the latter.
 
 fc-lcdemu	We have TI's TCS211 firmware semi-src that includes TI's
 		demo/prototype phone UI targeting the 176x220 pixel LCD on TI's
@@ -116,16 +102,79 @@
 		a hacked-up version of the fw that emits all raster blits
 		intended for the big LCD on the RVTMUX serial interface, and
 		this fc-lcdemu utility is a plug-in for rvinterf that actually
-		displays these LCD blits in an X11 window.
+		displays these LCD blits in an X11 window.  This program is not
+		built by default as it requires libX11 to compile and an X11
+		display to run.
 
-fc-fr2tch	This hack-utility converts a GSM 06.10 speech sample from the
-		de facto standard libgsm format (which can be recorded with
-		standard tools like SoX) into an uplink play file that can be
-		played with the tch play command in fc-shell; see the
-		TCH-bit-access article for more information.
+fc-memdump	This tool captures a memory dump from a GSM device whose
+		firmware implements one of TI's Test Mode memory read commands,
+		either the old TM3 version or the new ETM one.  It works with
+		FreeCalypso Citrine, with TCS211-based firmwares including
+		FreeCalypso Magnetite, with really old TI firmwares which
+		predate ETM, and with Mot C1xx original firmwares.  It works
+		through rvinterf.
+
+fc-rgbconv	A simple aid for phone UI development that converts RGB color
+		values between human-intuitive 8:8:8 format and the 5:6:5 format
+		used by the color LCDs in the phones targeted by FreeCalypso.
+
+fc-serterm	This tool is a trivial serial terminal program.  Its special
+		feature is that any output coming from the serial port that
+		isn't printable ASCII is displayed as by cat -v.  It is useful
+		for talking to serially-interfaced devices that mix ASCII with
+		binary in their serial talk.
 
 fc-tch2fr	This hack-utility takes a TCH downlink recording produced with
 		the tch record command in fc-shell and converts it to a playable
 		libgsm file which will most likely contain some garbage by
 		disregarding the non-understood DSP status words; see the
 		TCH-bit-access article for more information.
+
+fc-tmsh		TI-based GSM firmwares provide a rich set of Test Mode commands
+		that can be issued through the RVTMUX (debug trace) serial
+		channel, used for L1/RF test functions, production line RF
+		calibration, FFS (flash file system) access, audio configuration
+		and other miscellany.  fc-tmsh is our test mode shell for
+		sending these Test Mode commands to targets and displaying
+		decoded target responses; it works through rvinterf.  fc-tmsh
+		supports all Test Mode commands (both TM3 and ETM) implemented
+		in our target firmwares except FFS access; use fc-fsio for the
+		latter.
+
+fc-vm2hex	This utility converts the old-fashioned (non-AMR) voice memo
+		files read out of FFS into hex strings that can be analyzed by
+		a human or further fed to fc-tch2fr.
+
+imei-luhn	A simple utility for computing or verifying the Luhn check
+		digit of an IMEI number.
+
+pirexplore	This is a run-from-RAM (no flashing) program for Pirelli DP-L10
+		phones that exercises their peripheral hardware, primarily their
+		LCD.
+
+rvtdump		This tool produces a human-readable dump of all output emitted
+		by a TI-based GSM fw on the RVTMUX binary packet interface.  It
+		can also log this dump to a file.
+
+tfc139		This tool breaks into Mot C1xx phones via shellcode injection,
+		a method that works despite any bootloader locks, allowing you
+		to reflash locked phones with new firmware with fc-loadtool.
+		The name of the utility is historical: previously it was
+		specific to TFC139 phones (C139s sold with TracFone branding),
+		but the current version is expected to work with all Mot C1xx
+		firmware versions.
+
+tiaud-decomp	This utility decodes TI's audio mode configuration files read
+		out of FFS into our own ASCII format.  The tool to perform the
+		opposite conversion (compile these audio mode config files
+		"in vitro" from an ASCII text source) is planned, but has not
+		been written yet.
+
+tiffs,		These tools perform "in vitro" analysis of flash file system
+mokoffs,	(FFS) images read out of GSM devices with TI-based firmwares.
+pirffs		You can list and extract the FFS content captured as a raw
+		flash image, and even perform a few "forensic" operations along
+		the lines of reading deleted files and seeing the history of
+		FFS modifications.  tiffs is the main program, whereas mokoffs
+		and pirffs are convenience wrappers for the common FFS
+		configurations from Openmoko and Pirelli.