--- a/README	Tue Jun 10 18:48:21 2014 +0000
+++ b/README	Tue Jun 10 20:07:13 2014 +0000
@@ -1,4 +1,11 @@
-You are looking at the top level of the freecalypso-sw source code tree.
+You are looking at the top level of the freecalypso-sw source code tree.  The
+primary aim of this project is to produce our own full-source GSM firmware that
+would fully operate the TI Calypso-based GSM phones and modems of interest to
+us; this primary subproject is being worked on in the gsm-fw subtree.  While
+that project is progressing very slowly, the associated side projects have
+already produced some useful tools for operating on these GSM devices; see
+README.hosttools for the details.
+
 The subtrees of this source tree are as follows:
 
 gsm-fw		This tree contains the early beginnings of my (Michael
@@ -10,36 +17,20 @@
 		At the present, none of the actual GSM code (L1 or G23) has
 		been integrated yet, but most of the underlying RTOS environment
 		is present and working: one can exercise RVT, ETM and FFS.
-		L1 integration will begin soon.
-
-ffstools	Here you will find tools for "in vitro" examination of FFS
-		(flash file system) images read out of TI-based GSM devices.
-		See doc/TIFFS-Overview for more information.
-
-loadtools	The suite of tools which run on a development host machine
-		(normally PC/Linux desktop or laptop) and communicate with
-		Calypso targets.  Starting from the Calypso ROM bootloader,
-		these tools allow you to peek and poke registers, read and
-		program flash, and load and execute experimental code in IRAM
-		or XRAM.
+		The OSL component of GPF is currently being worked on; L1 will
+		follow afterward.
 
-rvinterf	In common with TI's original fw, FreeCalypso GSM fw implements
-		the so-called RiViera serial MUX, which is a binary packet
-		protocol for multiplexing many kinds of debug and development
-		traffic over just one available physical serial port.  This
-		rvinterf directory contains the early beginnings of our suite
-		of tools for connecting to this RV serial interface, supporting
-		both our own gsm-fw as well as some existing proprietary
-		firmwares to the extent to which they are compatible.
+target-utils	This tree contains code that runs on Calypso targets, but is
+		not regular firmware (gsm-fw) or a part thereof.  The two key
+		components built in this tree are loadagent (needed for all
+		targets) and compalstage (for Compal phones only), which need
+		to be installed on the user's host system in order for
+		loadtools (see README.hosttools) to do their job.
 
-target-utils	These are utilities which run on Calypso targets, but which are
-		independent of Nucleus, of any other RTOS, and of any larger
-		firmware suite, i.e., totally standalone.  The two current
-		utilities are loadagent, which is common for all currently
-		supported Calypso targets and is required in order to use
-		fc-loadtool or fc-xram (see loadtools), and pirexplore - the
-		latter is a hardware exploration utility specific to the
-		Pirelli DP-L10 target.
+ffstools	Tools that run on a Unix or GNU/Linux host; see README.hosttools
+loadtools	for the details.
+miscutil
+rvinterf
 
 toolchain	Scripts and patches for building the gcc+binutils toolchain
 		targeting ARM7, the CPU core of the Calypso GSM/GPRS baseband

--- a/target-utils/README	Tue Jun 10 18:48:21 2014 +0000
+++ b/target-utils/README	Tue Jun 10 20:07:13 2014 +0000
@@ -1,16 +1,34 @@
-Two programs are currently buildable in this target-utils tree: loadagent and
-pirexplore.  Loadagent is built to be loaded and run out of the Calypso internal
-(on-chip) RAM, and does not depend on any hardware outside of the Calypso chip
-itself - thus it should run unchanged on all Calypso targets.  It expects to be
-loaded by the Calypso ROM bootloader in the UART download mode, and it reads a
-RAM variable left behind by the ROM code that indicates which UART has been used
-to perform that download - it then uses that same UART to communicate with the
-host, presenting an interactive command prompt.  You can run loadagent "raw" by
-loading loadagent.srec with fc-iram, but normally it is used "behind the scenes"
-by fc-loadtool and fc-xram.
+The following target utilities or code components are currently buildable in
+this target-utils tree:
+
+compalstage	For Compal phones only: a little piece of code that is fed to
+		the original fw's bootloader via the serial download protocol
+		provided by the latter; it re-enables the Calypso chip boot ROM
+		and jumps to it, allowing our loadagent to be loaded in the
+		same way as on freedom-enabled devices.
+
+helloapp	Template/skeleton for building programs like loadagent and
+		pirexplore.
 
-Pirexplore is built in the same manner as loadagent (also runs out of IRAM,
-expects to be loaded with fc-iram, and presents an interactive command prompt
-on the autodetected UART), but it automatically performs some hardware (board
-level) initialization specific to the Pirelli, and offers additional commands
-for exploring the hardware features of this device.
+loadagent	Loadagent is built to be loaded and run out of the Calypso
+		internal (on-chip) RAM, and does not depend on any hardware
+		outside of the Calypso chip itself - thus it should run
+		unchanged on all Calypso targets.  It expects to be loaded by
+		the Calypso ROM bootloader in the UART download mode, and it
+		reads a RAM variable left behind by the ROM code that indicates
+		which UART has been used to perform that download - it then
+		uses that same UART to communicate with the host, presenting an
+		interactive command prompt.  You can run loadagent "raw" by
+		loading loadagent.srec with fc-iram, but normally it is used
+		"behind the scenes" by fc-loadtool and fc-xram.
+
+pirexplore	For Pirelli DP-L10 target only: this program is built in the
+		same manner as loadagent (also runs out of IRAM, expects to be
+		loaded with fc-iram, and presents an interactive command prompt
+		on the autodetected UART), but it automatically performs some
+		hardware (board level) initialization specific to the Pirelli,
+		and offers additional commands for exploring the hardware
+		features of this device.
+
+tf-breakin	Here we build the payload for the tfc139 hack-utility; see
+		../rvinterf/lowlevel/tfc139.c for the ugly details.