--- a/README	Fri Sep 23 16:52:05 2016 +0000
+++ b/README	Fri Sep 23 19:58:17 2016 +0000
@@ -1,20 +1,76 @@
-This is a special debug version of leo2moko intended for use by FreeCalypso
-developers only; it does not provide any additional features for Freerunner
-users beyond standard leo2moko-r1 aka moko12; non-developer users are advised
-to stay with the just-mentioned stable release.
+The intended purpose of this source tree is to serve as the official version of
+the stable TCS211 firmware for FreeCalypso modem products, i.e., for hardware
+devices designed and built under the auspices of the FreeCalypso Project - if
+we ever succeed in actually producing any such hardware.
+
+This tree introduces a few simple hacks which allow us to build slightly
+different firmware images as required for different targets (all supported
+targets must be simple modems close to the original Leonardo, no Compal/Pirelli
+targets!) from the same source - a capability not envisioned at all in TI's
+semi-source delivery scheme.  At the present moment only two targets are
+supported: gtamodem and fcdev3b.
 
-The primary intended use of this debug fw version is to enable FreeCalypso
-developers to troubleshoot misbehavior in our current gcc-built fw version
-by comparing the operation of the fw against a known working reference;
-the debug features added in this version are:
+VERY IMPORTANT NOTE: As of this writing, the FCDEV3B has not been physically
+built yet (at least not openly - it is possible that some anonymous company may
+have built some in secrecy without our involvement, but naturally we have no
+way of knowing whether or not any such thing happened), thus the preliminary
+support for the fcdev3b target in this source tree is of the "pre-hardware"
+kind.  I expect that some additional work will be needed before this code will
+actually be correct for the FCDEV3B, but I don't plan on doing this work until
+we get the boards physically built and I have some real hardware to play with.
+
+The takeaway from this situation is as follows: if anyone attempts to build
+their own FCDEV3B hardware in secrecy, bypassing the FreeCalypso core team,
+don't expect our software to work on such unethically-built hardware: more
+likely than not, it WON'T work.  So instead of trying to bypass us, please work
+*with us*.
+
+=====================
+Building the firmware
+=====================
 
-* Same AT-over-RVTMUX mechanism as implemented in FreeCalypso mainline;
+Like all TCS211 variants, this firmware builds with TI's proprietary compiler
+which exists only in the form of Windows binaries sans source.  However, we
+run TI's Windows-targeted build environment only under Wine under Slackware
+Linux and never under real Windows; furthermore, we have made a few add-ons of
+our own to TI's build system, and these _required_ add-ons are implemented as
+native Unix/Linux Bourne shell scripts, not Windows - hence if you are a Windows
+user, you are on your own.
+
+Therefore, the following instructions assume that your native OS is GNU/Linux
+(preferably Slackware) and that you are using the Wine environment we have
+packaged:
+
+ftp://ftp.freecalypso.org/pub/GSM/TI_src/wine/
+
+As explained in the README file in the above FTP directory, you will need to
+extract the installed-env.tar.xz tarball into your ~/.wine/drive_c directory.
+You will also need to compile and install the nowhine.c wrapper, or edit
+g23m/winebuild.sh to invoke wine directly instead of nowhine.
+
+You will also need this utility:
+
+ftp://ftp.freecalypso.org/pub/GSM/GTA02/gsm-fw/mokosrec2bin.c
 
-* ETM FFS access protocol changed from TMFFS1 (used by some TI Windows tools,
-  apparently) to TMFFS2 (the version adopted for FreeCalypso) to allow the
-  flash file system to be manipulated with fc-fsio while this fw is running.
+Once you have all necessary tools installed on your build machine, the actual
+build needs to be performed as follows:
+
+cd g23m
+./select_target.sh gtamodem
+./winebuild.sh
+./copyout.sh
 
-* The pf_TaskEntry() function in the guts of GPF has been patched to not
-  disable system traces.  Verbose traces from various entities still need
-  to be enabled explicitly, but the expected responses to sysprim commands
-  are no longer suppressed.
+The argument to the select_target.sh script selects the hardware target for
+which the firmware should be built: right now only the gtamodem configuration
+works; once we get the FCDEV3B physically built and make the necessary code
+changes for it, you'll be able to run './select_target.sh fcdev3b' instead and
+build firmware for the FCDEV3B.
+
+The winebuild.sh script performs the actual build once the target selection has
+been set; the build output will be in the __out__/gsm_<blah>/bin directory.
+The copyout.sh script is a workaround for the insanely long file and directory
+names: it copies and renames the final output files from TI's nasty build
+system, giving them shorter names that one can actually remember and type.  It
+also converts the firmware image file from TI's m0 format (byte-swapped SREC)
+to straight binary for more convenient flashing with fc-loadtool; this latter
+conversion is what the mokosrec2bin utility is for.