--- a/doc/Compal-unlock	Sat Dec 12 03:48:19 2015 +0000
+++ b/doc/Compal-unlock	Sat Dec 12 08:24:08 2015 +0000
@@ -40,14 +40,15 @@
 this feature enabled unconditionally, but some of the newer versions have a
 malfeature whereby the serial boot interrupt and code download possibility may
 be disabled.  Some C1xx phones out in the wild, particularly all North American
-C139s with TracFone branding, have such maliciously-locked firmware in them.
+C139s with TracFone branding and some of the Cingular-branded ones as well,
+have such maliciously-locked firmware in them.
 
-Fortunately though, these maliciously-locked firmwares (or at least the most
-common TFC139 one) have been found to have another hole through which we can
-break in, as described in the TFC139-breakin article.  We can exploit this hole
-in the TFC139 firmware to gain code execution access to the Calypso, and then
-use the latter to reprogram the flash, replacing the ultra-malicious firmware
-with some other version that, although still proprietary, is a little less evil.
+Fortunately though, these maliciously-locked firmwares (or at least all versions
+we've encountered so far) have been found to have another hole through which we
+can break in, as described in the TFC139-breakin article.  We can exploit this
+hole in the firmware to gain code execution access to the Calypso, and then use
+the latter to reprogram the flash, replacing the ultra-malicious firmware with
+some other version that, although still proprietary, is a little less evil.
 
 Making first contact
 ====================
@@ -111,20 +112,26 @@
    albeit at 57600 baud instead of TI's default of 115200.
 
 4. Connect the headset jack serial cable if it wasn't already connected, and
-   run this FreeCalypso hack-utility:
+   run this FreeCalypso utility:
 
    tfc139 /dev/ttyXXX
 
+(The name tfc139 is historical; the current version is expected to work with
+ all Mot C1xx firmwares.)
+
 Compal's TI-based firmware implements some of TI's Test Mode commands, and one
-of these commands is a raw memory write.  Our tfc139 hack-utility will try to
-break into the phone (gain code execution access) by using this Test Mode
-command to write a little payload into a particular RAM location (beginning of
-IRAM), and then doing more memory writes by the same method, seeking to smash
-the stack and cause control to be transferred to the sent payload by
-overwriting a function return address on the stack.
+of these commands is a raw memory write.  It also implements some of TI's GPF
+"system primitive" commands, including the MEMCHECK command that causes the
+firmware to report some info on all running GPF tasks, including the location
+of each task's stack.  Our tfc139 utility will try to break into the phone
+(gain code execution access) by querying the target fw for the location of the
+L1A task's stack, and then using Test Mode memory write commands to write a
+piece of shellcode into an unused RAM location and to make this code execute by
+overwriting a function return address on the stack of the L1A task that
+processes these Test Mode commands.
 
-If the stack smashing hack succeeds, the code injected by tfc139 will send a
-message out the serial port indicating this success, and then re-enable the
+If the stack smashing hack succeeds, the shellcode injected by tfc139 will send
+a message out the serial port indicating this success, and then re-enable the
 Calypso boot ROM and jump to it.  Once the boot ROM code gains control, it will
 wait forever for a serial code download following its standard protocol.  If
 tfc139 gets the success indication from the target, it will announce this
@@ -137,28 +144,26 @@
 be in full control of the phone via fc-loadtool.
 
 There is one additional quirk worth mentioning.  It appears that Mot/Compal's
-main fw (at least TF's version 8.8.17, which is the version we break into with
-tfc139; other versions are anyone's guess) keeps resetting the RTC alarm
-registers in the Calypso DBB as it runs, always keeping the alarm time in the
-near future relative to the current time.  When one breaks into this firmware
-with tfc139 and takes over the control of the device with fc-loadtool, this
-alarm time will almost certainly be reached, and the RTC alarm will go off.
-This alarm has no effect on loadtool operation (i.e., it cannot reset the CPU
-or otherwise wrestle control away from loadtool, so it doesn't add any bricking
-risk), but it has one quite surprising effect upon exit, i.e., when you are
-done with your loadtool session and give it the exit command.
+main fw keeps resetting the RTC alarm registers in the Calypso DBB as it runs,
+always keeping the alarm time in the near future relative to the current time.
+When one breaks into this firmware with tfc139 and takes over the control of
+the device with fc-loadtool, this alarm time will almost certainly be reached,
+and the RTC alarm will go off.  This alarm has no effect on loadtool operation
+(i.e., it cannot reset the CPU or otherwise wrestle control away from loadtool,
+so it doesn't add any bricking risk), but it has one quite surprising effect
+upon exit, i.e., when you are done with your loadtool session and give it the
+exit command.
 
 Loadtool's configured default exit action for this target is to send a power-off
 command to the Iota ABB, leaving the device cleanly powered off.  However, if
 the RTC alarm has gone off previously during the session, the ABB will instantly
 power the phone back on, and put it through a new boot cycle.  The firmware
-(again, the only version this stuff can be tested on is the one that works with
-tfc139) handles this special form of boot rather oddly: it proceeds to the same
-end state it would have reached via a normal power button hold-down boot
-(powered on with the "Insert SIM" message on the LCD), but it reaches this state
-almost instantly, without going through the power-on LCD logo and buzz phase.
-Odd, but harmless.  This explanation has been included to save other hackers
-the hours of bewildered head-scratching I spent chasing this quirk down.
+handles this special form of boot rather oddly: it proceeds to the same end
+state it would have reached via a normal power button hold-down boot (powered
+on with the "Insert SIM" message on the LCD), but it reaches this state almost
+instantly, without going through the power-on LCD logo and buzz phase.  Odd,
+but harmless.  This explanation has been included to save other hackers the
+hours of bewildered head-scratching I spent chasing this quirk down.
 
 Dumping and reloading flash
 ===========================
@@ -244,7 +249,7 @@
 
 Unzip it, and you'll get c139-unlocked-fw.bin - that is the image you'll need
 to flash into your phone.  Get in with fc-loadtool (using tfc139 if necessary
-for locked-down Tracfones) and make a backup of the original flash content.
+for bootloader-locked phones) and make a backup of the original flash content.
 Then reflash the firmware as follows:
 
 flash erase-program-boot c139-unlocked-fw.bin 2000

--- a/doc/TFC139-breakin	Sat Dec 12 03:48:19 2015 +0000
+++ b/doc/TFC139-breakin	Sat Dec 12 08:24:08 2015 +0000
@@ -48,15 +48,14 @@
   its ability to ever run a different firmware version, like a kamikaze pilot's
   plane that has discarded its landing gear and can only crash now.
 
-TFC139 recovery
-===============
+Recovery procedure
+==================
 
-While it probably was Compal's, Motorola's and TracFone's intent that the
-bootloader lock on their phones be truly irreversible, some genius out there
-(we may never know who this person was/is) has found a way to recover the
-reflashing capability on at least one very common flock of locked-down phones:
-North American C139 units (1900+850 MHz hardware) sold with TracFone branding,
-firmware version 8.8.17.  Here is how it goes:
+While it probably was Compal's, Motorola's and various carriers' intent that the
+bootloader lock on their phones be truly irreversible, the unlocking community
+has now developed a method for recovering these phones (restoring their ability
+to run any firmware of the user's choice) which (we hope) will work with all of
+the existing locked-down firmware versions.  It works as follows:
 
 * Even though the bootloader is locked down, if one boots the full fw regularly,
   one can still access the RVTMUX interface which the TI-based fw implements
@@ -74,11 +73,10 @@
   under a mistaken belief that these commands were Compal's inventions, until
   we discovered TI's original TM predating ETM.)
 
-* The ingenious idea our hero came up with is that one can use the RVTMUX TM
-  memory write command to write a piece of "shellcode" into an unused RAM
-  location, and then use those very same memory write commands to cause a
-  transfer of control to this code by overwriting a function return address on
-  the stack!
+* The ability to write arbitrary bytes into arbitrary RAM locations while the
+  phone firmware is running means that we can inject a piece of shellcode into
+  an unused RAM location and then cause this shellcode to gain execution by
+  overwriting a function return address on the stack.
 
 * Once you can execute your own code on the Calypso, everything becomes possible
   once again.  At that point one can trivially reverse the bootloader lock by
@@ -86,9 +84,36 @@
   or even better, rewriting this boot sector with an older version of the boot
   code that lacks the locking malfeature altogether.
 
-In the FreeCalypso suite the tfc139 host utility performs the break-in using
-the RVTMUX TM memory write and stack smashing method just described.  The
-"shellcode" injected by tfc139 re-enables the Calypso chip's own boot ROM and
+Procedure variations: old mot931c.exe vs. new tfc139
+====================================================
+
+We first became aware of the possibility of recovering locked-down phones as
+described above in the spring of 2014 when FreeCalypso developer Space Falcon
+became aware of the existence of Windows utility mot931c.exe (binary w/o source)
+that performs a variant of this unlocking procedure specific to one particular
+locked-down firmware version: C139 phones with TracFone branding, fw version
+8.8.17.  At first we had replicated the operation of this Windows tool verbatim
+in our own Unix/Linux-based tfc139 libre tool; this variant of the shellcode-
+based unlocking procedure worked well on TFC139 units, but could not crack other
+locked-down fw versions, e.g., Cingular-branded C139 phones with fw version
+1.9.24.
+
+Subsequent investigation revealed that whoever wrote that mot931c.exe Windows
+tool had not studied the operation of Motorola/Compal's TI-based firmware deeply
+enough, and implemented their shellcode injection quite suboptimally: the stack
+smashing process is hitting the wrong stack (not the stack of the L1A task in
+whose context the Test Mode commands sent over the UART are executing), and it
+is only through dumb luck that this version of the break-in procedure worked
+at all.  The limitation of working only with one specific fw version results
+from this poor method of shellcode injection (mindless choice of the wrong stack
+for smashing), and instead of adapting it in a version-specific manner to other
+particular locked-down fw versions at hand, I (Space Falcon) reimplemented our
+tfc139 utility to smash the right stack (that of the L1A task), and thereby
+made it generic to all Mot C1xx firmware versions.
+
+Our Compal firmware break-in utility is still called tfc139, but it is no longer
+specific to TFC139 phones; instead it should work with all Mot C1xx firmwares.
+The shellcode injected by tfc139 re-enables the Calypso chip's own boot ROM and
 jumps to it; this boot ROM will endlessly wait for a serial download because
 the word at 0x2000 contains neither 0 nor 1 (it is part of an identifying ASCII
 string in Mot/Compal's fw), and the operator can then run fc-loadtool to