--- a/README	Thu Nov 05 01:50:11 2015 +0000
+++ b/README	Thu Nov 05 08:09:54 2015 +0000
@@ -1,30 +1,13 @@
 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.
+has been made to run on the Motorola C139.  Once the remaining bugs get shaken
+out (there are still some crippling ones, so don't break out the champagne yet),
+one will be able to replace Motorola's firmware in flash with this one and
+*still be able to use the phone as an end user* - but now running firmware that
+we build from source ourselves, one whose internals we know and understand and
+which we can use a baseline for further functional improvements.
 
-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.
+Compiling
+=========
 
 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
@@ -38,41 +21,94 @@
 ftp://ftp.freecalypso.org/pub/GSM/GTA02/gsm-fw/mokosrec2bin.c
 
 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.
+compile the present fw as follows:
+
+cd g23m
+./winebuild.sh
+./copyout.sh
+
+The build products will be in the g23m/mfw-build directory.  mfw-build.progbin
+is the flashable image, and the other files should be saved as documentation:
+you should retain the COFF, map and str2ind.tab files that correspond exactly
+to what you have flashed, so you can debug it later.
+
+Flashing: what goes where
+=========================
+
+WARNING: C139 phones are brickable!  If you type the wrong command in
+fc-loadtool, you can brick your phone *unrecoverably*!  Flash sector 0 MUST at
+all times contain working boot code that can successfully perform the following
+functions:
 
-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:
+1. Check the headset jack UART for a possible serial download - if an external
+   host is requesting a serial code download, accept the serially loaded code
+   and jump to it.
+
+2. If no serial download is taking place, jump to the main fw image in the rest
+   of the flash for normal boot.
+
+Function (2) may differ depending on what main fw is to be used, but function
+(1) is absolutely essential: if flash sector 0 is erased and not immediately
+reprogrammed with working boot code, or if it gets programmed with some code
+version that does not perform function (1), then all ability to take control of
+the phone will be lost, and it will be forever stuck in one of two states:
+
+(a) If the boot code still performs function (2) and there happens to be a
+    working main fw image in the flash, the phone will be stuck with that fw
+    version forever, with no ability to reflash it or to load and execute any
+    code in RAM.
+
+(b) If the conditions of (a) above aren't met, the phone will be reduced to a
+    paperweight.  There is no JTAG access on these phones, and the flash chip
+    is not only a micro-BGA, but also combined with SRAM in the same package.
+    Desoldering the flash+SRAM chip and replacing it with an externally
+    programmed one is not likely to be feasible, hence bricked really means
+    bricked.  You've been warned!
 
-* 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.
+For FreeCalypso we've adopted our own version of the bootloader that performs
+function (1) exactly like Mot/Compal's original (actually slightly better, as
+we've removed the "1003" check, thus the inefficient -c 1003 fc-loadtool option
+becomes unnecessary), but we've modified function (2): in Compal's original
+design the main fw image starts at 0x2000 with the entry point at 0x20F8,
+whereas in our arrangement the main fw image starts at 0x10000 with the entry
+point at 0x10058.
+
+We've changed the starting address for the main fw image to coincide with the
+physical flash erase block boundary and thereby reduce the bricking risk.  If
+we put our main fw image starting at 0x2000 like Mot/Compal did, we would have
+to erase and reprogram flash sector 0 every time we would like to change the
+main fw, incurring the risk of bricking the phone.  But with our modified boot
+code we only have to do it once, when a given phone is first transitioned from
+Mot/Compal's original fw to one of ours.  With subsequent reflashings from one
+FreeCalypso fw version to another, we only need to reflash the main fw starting
+at 0x10000, and leave flash sector 0 alone.
+
+Besides the main fw and the critical boot code, the flash houses two more
+entities: the factory data block and the flash file system (FFS).
 
-* 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!
+Factory data block
+==================
+
+The 8 KiB flash sector at 0x3FC000 contains per-unit factory programming from
+Motorola/Compal: RF calibration values, the unit's official IMEI and Cthulhu
+knows what else.  Unfortunately we haven't been able to parse this info beyond
+a superficial level, hence we have no way to make use of any of this data.
+But of course we should not erase or overwrite it, so we just leave this flash
+sector alone.
 
-* 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.
+Flash file system
+=================
 
-Flashing and usage instructions
-===============================
+Because Mot/Compal had moved their IMEI and RF calibration values into their
+own proprietary format, these juicy items are NOT found in the FFS maintained
+by the original firmware.  Instead the original fw's FFS contains only dynamic
+state and user data, hence it is of no use to us.  We have adopted a different
+flash location for our FFS from that used by Mot/Compal's fw in order to prevent
+any possible cross-contamination, and you will need to manually initialize this
+aftermarket FFS the first time you install FreeCalypso firmware on your C139.
+
+Flashing procedure
+==================
 
 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:
@@ -85,14 +121,24 @@
 
 loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin
 
+(compal-flash-boot-for-fc.bin is our modified bootloader version, and it is
+ built from one of Compal's versions via binary patching in the freecalypso-sw
+ source tree.)
+
+Optional step: 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 at this point.
+
 3. Flash the main fw image:
 
-loadtool> flash erase 10000 220000
-loadtool> flash program-bin 10000 aci-build.progbin
+loadtool> flash erase 10000 290000
+loadtool> flash program-bin 10000 mfw-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.)
+Or you can use the supplied nifty loadtool command script:
+
+loadtool> exec ./flash-mfw
+
+The current directory must be g23m for the script method to work.
 
 4. Erase the sectors where our firmware's non-volatile flash file system
    (aftermarket FFS configuration) will reside:
@@ -103,66 +149,32 @@
 
 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.
-
-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:
+FFS initialization
+==================
 
-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.
+The first time you boot your C139 after the above flashing procedure, the phone
+should have no SIM in it.  Firmwares built with UI enabled (like the present)
+automatically fire up GSM functionality and try to connect to a network
+immediately upon boot if a SIM is present, and you don't want to do that on
+your first boot: at this point your phone has *no* IMEI and no working FFS at
+all.  When the fw boots up without a SIM, it still enables the part of the GSM
+radio protocol stack that looks for usable cells, in anticipation of the
+possibility that the user may need to make an emergency call, but it never
+transmits anything in this state (Tx fully off) unless you do dial that
+emergency call.
 
-First session
-=============
+So take the SIM out before you start the reflashing procedure, and then boot
+the SIM-less phone afterward.  You should see a message on the LCD that reads
+"Insert SIM".  But instead of inserting a SIM, you should run the fc-fsio
+utility from FreeCalypso host tools at this point.  Plug the serial cable back
+in if you unplugged it, and run fc-fsio:
 
-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.
+fc-fsio -p /dev/ttyXXX
 
-Initialize your FFS as follows:
-
-1. Connect the serial cable, run rvinterf and boot the fw as above.
+(Omit the -p argument if you already have rvinterf running for fc-fsio to
+ connect to.)
 
-2. Before you try issuing any AT commands via fc-shell, run fc-fsio first.
-
-3. Initialize the FFS via fc-fsio as follows:
+Then issue the following commands:
 
 fsio> format /
 fsio> mk-std-dirs
@@ -171,7 +183,82 @@
 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.
+Yes, you need to set your own IMEISV.  The official one is stored in the factory
+data block, but we don't know how to parse it, so it effectively does not exist
+for us.  It is entirely up to you whether you set the same IMEI as the official
+one or a different one: our fw has no psychic powers to compare.  Unless you
+have reason to do otherwise though, the default should be to keep the original
+IMEI.  It is not clear what Mot/Compal's fw puts in the SV digits, so just put
+00 in there if you don't feel like inventing version numbers.
+
+The set-rfcap command is necessary because our fw does not know otherwise
+whether your C139 is the 900+1800 MHz version or 1900+850 MHz.  If you don't
+write a /gsm/com/rfcap file with this command, the fw defaults to quadband
+(the part of the fw where this default is effected is a binary blob in the
+present version) and will waste time scanning frequencies which it can't
+receive because the corresponding RF transceiver input is unconnected
+(unsupported high band) or because they are blocked by a SAW filter
+(unsupported low band).
+
+After you have initialized your new aftermarket FFS with fc-fsio per the above,
+exit fc-fsio and power your phone off: hold the power button down until a TI
+logo appears on the LCD, then release the button; the phone will power off
+shortly, and you'll know it's off when the LCD turns off.  Now you can insert
+a SIM and boot again - this time the phone should be live!
+
+Limitations
+===========
+
+* 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 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 (see next point), the option of having the phone dual-function as a
+  laptop-tethered modem is not available either.
+
+* TI's full-featured phone firmwares allow the phone to dual-function as a
+  modem, so one could connect the phone to a laptop and make a CSD call or use
+  GPRS.  But they were 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),
+  and we absolutely need the debug interface, thus the classic AT command
+  interface had to be sacrificed.  One can still issue AT commands over RVTMUX
+  with FreeCalypso host utility fc-shell, but this mechanism works only for
+  voice and SMS commands, not CSD or GPRS.  Hence the data functions of the fw
+  remain unusable dead weight. :(
+
+* The headset functionality of the headset jack is also unavailable: because we
+  need to be able to use the debug interface at all times, we always keep the
+  electrically-controlled switch in the state that connects the headset jack to
+  the UART (presenting RVTMUX) instead of the audio circuits.
+
+* Because we don't know how to grok Mot/Compal's factory data block, our fw
+  currently runs 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!
+
+* The only 3 display configurations for which TI produced demo/prototype UI in
+  their chipset reference firmware are 84x48 pix monochrome, 176x220 pix
+  monochrome and 176x220 pix full color.  We have a 96x64 pix LCD on the C139,
+  hence we are using TI's 84x48 UI design until we can create one that makes
+  use of the slightly larger 96x64 screen.  However, TI had that 84x48 LCD on
+  their C-Sample and earlier platforms (*very* old), and as we discovered
+  empirically, the support for this 84x48 display config is already bitrotten
+  in the source tree we got, which officially targets TI's D-Sample and Leonardo
+  boards.
+
+  At first the C-Sample UI configuration did not even compile.  We got it to
+  compile by fixing it in a way that *seemed* right, but when we run this
+  resurrected C-Sample UI on our C139 hardware, one can plainly see that the UI
+  is still defective, as the expected output on the LCD is mixed with garbage.
+  We will need to delve into the UI code in more depth in order to really fix it
+  to where the display will be readable without garbage.
+
+* Battery charging has not been tried yet.  It most likely won't work without
+  additional fixes.