--- a/README	Sun Nov 01 17:25:37 2015 +0000
+++ b/README	Sun Nov 01 19:39:44 2015 +0000
@@ -1,20 +1,177 @@
-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.
+This semi-source tree contains a hacked version of TI's TCS211 firmware that
+has been made to run on the Motorola C139.  The UI part of TI's reference fw
+has not been ported over yet, hence the version presented here currently builds
+and works only in the modem-like ACI configuration, i.e., control via AT
+commands only.
+
+TI's original fw was/is designed to make use of two UARTs, one for the classic
+AT command interface and the other for their RVTMUX debug/calibration/etc
+interface.  Unfortunately though, our present target hw has only one UART
+practically accessible (Calypso's MODEM UART brought out on the headset jack),
+thus the classic AT command interface had to be sacrificed.  Instead the AT
+command interface (which is currently the only way to control the GSM
+functionality in the absence of a UI ported to the present target) needs to be
+accessed through the RVTMUX binary packet interface using FreeCalypso host
+tools rvinterf and fc-shell.
+
+The present fw has been built from a semi-src (half source, half binary objects)
+TI firmware release which was made for some manufacturer that made GSM/GPRS
+modems, rather than voice handsets, hence the present configuration is
+unfortunately highly suboptimal for our use case.  The entire mass of code
+supporting CSD, fax and GPRS data services is included and cannot be removed
+because that part of the fw is in binary blobs, but all this code is pure dead
+weight in the present configuration: the phone UI layer (when we get around to
+porting it) won't make any use of data functionality (nowhere near enough
+resources on this hw to implement a WAP browser or MMS), and because we had to
+give up the standard AT command channel, the option of having the phone dual-
+function as a laptop-tethered modem is not available either.
+
+Building the present firmware from semi-source requires using a Wine environment
+to run TI's proprietary compiler toolchain and other build tools which exist
+only as M$ Windows binaries.  The necessary environment can be downloaded here:
+
+ftp://ftp.freecalypso.org/pub/GSM/TI_src/wine/
+
+You will also need the mokosrec2bin utility, which is needed for one of the
+finishing steps in generating an image that can be usefully flashed into a C139:
+
+ftp://ftp.freecalypso.org/pub/GSM/GTA02/gsm-fw/mokosrec2bin.c
 
-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:
+Once you have the necessary build tools installed, you should be able to
+compile the present fw by running first winebuild.sh, then copyout.sh in the
+g23m subdirectory.  Then you can flash this firmware you just built into an
+actual C139 phone with FreeCalypso host tool fc-loadtool.  Flash sector 0 (the
+brickable boot sector) needs to contain our patched bootloader version
+compal-flash-boot-for-fc.bin (this brickable sector only needs to be rewritten
+once when first installing some FreeCalypso fw on the phone; no need to touch
+this dangerous sector on subsequent updates from one FC fw version to another),
+and the main fw image needs to be flashed starting at 0x10000.  The image to
+flash is aci-build.progbin - it has TI's bootloader code stripped off, as we
+are using compal-flash-boot-for-fc instead.
+
+The phones in question have a data structure in flash at 0x3FC000 (in an 8 KiB
+short sector) that must contain factory programming, including each phone's
+unique IMEI and RF calibration values.  However, we don't understand how to
+grok this data structure.  Therefore, our firmware features the following
+points of inconvenience:
+
+* You have to set your own IMEI.  It's entirely up to you whether you set the
+  same IMEI as the phone had originally or a different one, but our fw has no
+  way of reading the original from Mot/Compal's factory flash programming.
+  You probably won't be able to connect to a live commercial GSM network until
+  you set some IMEISV which the network will accept as valid.
+
+* Because Mot/Compal stored their RF calibration values in some format
+  (different from TI's) which we can't grok, a phone running our aftermarket fw
+  will run UNCALIBRATED.  It may have difficulty connecting to networks if it
+  can't acquire the frequency burst lacking VCXO calibration, and the Tx power
+  levels are almost certainly wrong (out of spec) - BEWARE!
+
+* Our fw does not even know whether your C139 is the 900+1800 MHz version or
+  850+1900 MHz.  You will need to set the correct rfcap configuration at the
+  same time when you set your IMEISV.
+
+Flashing and usage instructions
+===============================
+
+If you are not scared off by all of the above and you still wish to try this
+experimental fw on your C139, you can install it as follows:
+
+1. Connect to the phone with fc-loadtool, preceded by tfc139 if necessary -
+   see loadtools documentation.
+
+2. If the C139 in question does not already have some other FreeCalypso fw
+   version in its flash, replace the bootloader:
+
+loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin
+
+3. Flash the main fw image:
 
-* Same AT-over-RVTMUX mechanism as implemented in FreeCalypso mainline;
+loadtool> flash erase 10000 220000
+loadtool> flash program-bin 10000 aci-build.progbin
+
+(If your serial cable setup supports the special GSM high baud rates,
+ you can speed the process up by issuing a baud 406250 or baud 812500
+ command first.)
+
+4. Erase the sectors where our firmware's non-volatile flash file system
+   (aftermarket FFS configuration) will reside:
+
+loadtool> flash erase 3C0000 30000
+
+5. Cleanly end your fc-loadtool session, which will power the phone off:
+
+loadtool> exit
+
+Now your phone has FreeCalypso firmware in its flash, but it no longer works
+as a "normal" phone.  Gotchas to be aware of:
+
+* Mot/Compal's original firmwares (like all other production phone fws)
+  implement on a guard on the power-on button: you have to hold it down for a
+  little while to confirm that you really mean to power the phone on; a
+  momentary press of the power-on button is interpreted as spurious by standard
+  fws, and they power the phone back off.  However, the present hack-fw has no
+  such guard, hence even a momentary press of the power-on button will launch
+  the firmware into full boot.
+
+* Because our present fw has no UI, the LCD will remain dark and the buttons
+  won't do anything.  A momentary press of the power button will turn the phone
+  on, but you won't know that it's on - it will just silently and invisibly eat
+  the battery.  Furthermore, the only way to power it off (aside from yanking
+  the battery) is to connect a serial cable and send a poweroff command via
+  fc-shell - there is no way to command a power-off from the keypad.  (Pressing
+  and holding the power button produces some kind of hang or crash - to be
+  investigated - instead of a proper power-off.)
+
+* The present fw includes TI's LCC (low-cost charger) code that came with
+  TCS211, but it is not clear whether or not this code drives the charging
+  circuitry correctly for Mot/Compal's hardware.  Therefore, plan on having
+  the phone with FC firmware draining batteries only, and have another phone
+  running official fw (or a standalone charger) to charge them back up.
 
-* 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.
+What all of these gotchas practically mean is that the phone with FC fw in it
+should not have a battery inserted on a regular basis; instead you should use
+it as follows:
+
+1. Begin each FC hacking session by inserting the SIM you wish to use, then
+   inserting the battery - but don't touch the power button yet.
+
+2. Connect the serial cable and run rvinterf on your host.
+
+3. Press the power button, and see the firmware boot output in the rvinterf
+   window.
+
+4. Run fc-shell, fc-fsio, fc-tmsh etc as desired during your hacking session.
+
+5. End the session by yanking the battery, killing rvinterf and stowing away
+   your serial cable.
+
+First session
+=============
 
-* 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.
+Remember the notes above regarding this fw not being able to read the factory
+IMEI record?  That's right, you'll need to set your own IMEISV.  Furthermore,
+because we are using our own "aftermarket" FFS configuration for non-volatile
+data storage (you erased the flash sectors to be used for this FFS when you
+flashed the fw with fc-loadtool, or at least you should have), this FFS needs
+to be initialized before the fw can function correctly.
+
+Initialize your FFS as follows:
+
+1. Connect the serial cable, run rvinterf and boot the fw as above.
+
+2. Before you try issuing any AT commands via fc-shell, run fc-fsio first.
+
+3. Initialize the FFS via fc-fsio as follows:
+
+fsio> format /
+fsio> mk-std-dirs
+fsio> set-imeisv fc XXXXXXXX-YYYYYY-ZZ (punctuation optional, place anywhere)
+fsio> set-rfcap dual-eu (if you have 900+1800 MHz hardware)
+or
+fsio> set-rfcap dual-us (if you have 850+1900 MHz hardware)
+
+After the above steps, you can exit fc-fsio (or leave it running), run fc-shell
+and exercise the GSM MS via AT commands - try connecting to a network!  With my
+US band C139 (former Tracfone, now a Crackfone) on Operator 310260's network,
+both voice calls and SMS work like a charm.  YMMV.