--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Host-tools-overview	Sat Nov 07 03:01:50 2015 +0000
@@ -0,0 +1,117 @@
+FreeCalypso host tools suite features the following tools that are potentially
+useful to end users:
+
+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
+		these devices with new firmware (whether pre-existing or new
+		firmwares developed within our project), and to save and restore
+		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-shell	FreeCalypso firmwares have a feature of our own invention (not
+		present in any pre-existing ones) to accept AT commands over
+		the RVTMUX interface.  It is useful when no second UART is
+		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 locked-down Mot C139 phones sold with
+		TracFone branding, allowing you to reflash them with new
+		firmware with fc-loadtool.
+
+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.
+
+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-getpirimei	This utility retrieves the factory-programmed IMEI of a Pirelli
+		DP-L10 phone by quering its running firmware over the RVTMUX
+		interface.
+
+fc-serterm	This tool is a trivial serial terminal program.  Its special
+		feature is that any output coming 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:
+
+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
+		"compressed trace" misfeature whereby many of the ASCII strings
+		in debug trace messages get replaced with numeric indices at
+		build time, and these numeric indices are all that gets emitted
+		on the RVTMUX serial channel.  This numeric trace output can be
+		turned back into ASCII strings if you have the str2ind.tab file
+		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-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-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-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
+		D-Sample development kit, but no suitable hardware on which we
+		could run this fw with this UI and see it in action.  We built
+		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.
+
+fc-pirhackinit	This fc-pirhackinit utility is highly specific to the
+		TCS211-on-Pirelli exercise.  DO NOT run it against Pirelli's
+		stock firmware, nor is it needed when using our full-source
+		FreeCalypso firmware.