--- a/README	Sun Mar 06 19:49:33 2016 +0000
+++ b/README	Sun Mar 06 21:38:21 2016 +0000
@@ -1,145 +1,48 @@
-What this project is about
-==========================
-
-You are looking at the software/firmware subproject of FreeCalypso.  The goal
-of this subproject is to produce a fully functional firmware version for the
-Calypso GSM baseband chipset from Texas Instruments that is fully controlled
-by We the People (recompilation with a free compiler from full source code
-which is freely published and maintained by us, as opposed to a frozen
-impenetrable binary blob from some long-defunct vendor) and which we can use in
-two ways:
-
-a) replace the original proprietary firmware of certain pre-existing phone
-   models based on this chipset, thereby turning these historical devices into
-   libre phones;
-
-b) use as the official firmware for new phones and modems which we design and
-   build ourselves, using the same Calypso chipset.
-
-Origin of the source
-====================
-
-We are *not* attempting to reimplement a fully functional and practically
-usable GSM protocol stack from scratch in this project - such a task would be
-far beyond the capabilities of our very small and woefully underfunded team,
-and in the opinion of project leader Space Falcon, such a from-scratch
-reimplementation would be an egregious and morally impermissible waste of human
-talent.  Instead, we are using the L1 and G23M protocol stack code for TI's
-LoCosto chipset that was included in the chipset.zip public release made by the
-CEO of Peek, Inc. (the Peek mobile email device company) as that company went
-under, and porting it from the LoCosto-based Peek platform to our Calypso target
-devices of interest.
-
-Where we came from
-==================
-
-Just because we are reusing most components from TI's original firmware releases
-does not mean that our project is trivial or devoid of our own original work.
-When we started the GSM firmware subproject in the fall of 2013 (that was when
-we obtained the last missing piece of required starting source material), the
-available TI firmware sources consisted of:
-
-* A TCS211 semi-src deliverable that could be compiled into a working fw image
-  for the GSM modem in the Neo Freerunner.  While this version includes
-  recompilable source for most of the supporting components, the actual GSM
-  protocol stack is 100% linkable binary libraries sans source.  These binary
-  object components necessitate the use of TI's proprietary compiler tools to
-  rebuild the fw.  The build environment is set up for Windows only.
-
-* The source from Peek (TCS3.2_N5.24_M18_V1.11_M23BTH_PSL1_src.zip) for TI's
-  I-Sample board with the LoCosto chipset.  Mostly real source (about 95%), but
-  still has a few required components which exist only as linkable binary
-  libraries sans source.  The use of TI's proprietary compiler tools is still
-  required for the same reason, and the build environment is set up to use a
-  bunch of other Windows-only tools.
-
-* The Peek Linux project (svn.peeklinux.com) replaced the Windows-based build
-  system with a Linux-based one, but the binary-only libraries are still there,
-  hence the compiler toolchain is still the same proprietary one from TI.
-
-The above sorry state of affairs (absolute dependency on binary object code
-sans source, on proprietary compiler toolchains and on Windows) was very far
-from what we sought to accomplish (compilation from full source with gcc under
-GNU/Linux or other free Unix), hence we set out on a firmware reintegration
-project that took a year and a half.
-
-What we've done
-===============
-
-By a process of painstaking reintegration piece by piece, we have put together
-our own firmware suite for the Calypso that builds into a flashable or
-RAM-loadable image and has the following essential features/qualities/
-attributes:
-
-* Targets Calypso rather than LoCosto.  This decision is somewhat controversial,
-  i.e., one could make a valid argument that we should have gone with LoCosto
-  instead.  But in our defense, we already have several pre-existing devices
-  with the Calypso chipset on which we would like to run libre firmware; as for
-  LoCosto, we don't have a hardware platform to use as a bring-up vehicle, and
-  when we started the project, we were missing a copy of some of TI's Windows
-  tools for LoCosto.
-
-* The overall architecture of our firmware (what components are included) mimics
-  that of TCS211 (TI's official fw for Calypso platforms for which we only have
-  a semi-src): e.g., we use real RiViera rather than RV emulation atop GPF.
-  In the case of RiViera, FFS and other components for which our copy of TCS211
-  has real source, we have used that TCS211 source.
-
-* L1 and all of G23M (including ACI, CCD and AIM/SAP definitions) are the
-  version from the LoCosto source - which has an unfortunate quality of being
-  completely untested.
-
-* Configured for a feature set matching TCS211, i.e., most of the newer features
-  appearing in TCS3.2 are *not* enabled.  The GSM protocol stack is also
-  configured for the minimal voice+SMS feature set, i.e., CSD, fax and GPRS
-  haven't been integrated or enabled yet.
-
-* Everything builds from full source with gcc, i.e., *nothing* is used in the
-  form of a precompiled binary object or library.  Some parts of GPF, L1 and
-  system initialization code had to be reconstructed from disassembly of TCS211
-  binary objects, as no original or suitable substitute source could be found.
-
-* The version of Nucleus we use comes from a non-TI source; all TI GSM fw
-  sources we found have their Nucleus in binary-only libs.
-
-* To reiterate: our compiler is gcc, *not* TI's proprietary TMS470!
-
-Current status (2015-06-30)
-===========================
-
-Our current firmware can be built for two targets: Openmoko's Calypso modem
-built into their GTA01 and GTA02 smartphones (target gtamodem) and the Pirelli
-DP-L10 feature phone.  The functionality is the same on both targets: a modem
-or pseudo-modem controlled by AT commands (no local UI on the Pirelli), and
-only the voice+SMS subset, i.e., no CSD, fax or GPRS yet.  The firmware is able
-to register successfully to a live commercial GSM network (using a legitimate
-SIM of course), and SMS sending and receiving both work; all SIM interface
-functions also work as far as we've tested them.  But voice calls don't work
-yet; making them work is our next task.
-
-We have also produced some host tools for loading firmware into Calypso GSM
-devices, for communicating with running firmwares over the RVTMUX interface,
-and for manipulating TI's flash file system.  See README.hosttools for the
-details.
-
-Source tree
-===========
-
+This source repository is a top-level container for all of the main software
+and firmware components developed in the FreeCalypso project.
 The subtrees of this source tree are as follows:
 
-gsm-fw		The main FreeCalypso GSM firmware work, see above.
+compal-flash-boot-for-fc
+		A patched version of Compal's flash boot code for Mot C11x/12x
+		and C139/140 families, modified to work with main fw images from
+		FreeCalypso subprojects.  It is compatible with our own gsm-fw
+		and with tcs211-c139.
+
+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.
+
+gsm-fw		Our Calypso GSM firmware reconstruction and reintegration
+		attempt lives here; see doc/Firmware_Architecture and
+		doc/Firmware_Status for more information.
+
+loadtools	These tools allow you to load your own code into Calypso GSM
+		devices.  Using these tools, you can load code into target
+		device IRAM or XRAM and run it there, as well as dump and load
+		flash.  The operation of these tools is based on gaining
+		control of the target device either through the Calypso on-chip
+		boot ROM (on freedom-enabled devices), or through the
+		flash-resident boot code on the crippled Compal phones.
+
+lcdemu		fc-lcdemu is built here.
+
+miscutil	fc-rgbconv, fc-serterm and imei-luhn are built here.
+
+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 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.
-
-ffstools	Tools that run on a Unix or GNU/Linux host; see README.hosttools
-loadtools	for the details.
-miscutil
-rvinterf
+		loadtools (see above) to do their job.
 
 toolchain	Scripts and patches for building the gcc+binutils toolchain
 		targeting ARM7, the CPU core of the Calypso GSM/GPRS baseband