--- a/doc/Compal-unlock	Sun Nov 15 01:42:50 2015 +0000
+++ b/doc/Compal-unlock	Sun Nov 15 03:47:19 2015 +0000
@@ -44,15 +44,10 @@
 
 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 here:
-
-http://lists.osmocom.org/pipermail/baseband-devel/2014-May/004451.html
-http://lists.osmocom.org/pipermail/baseband-devel/2014-May/004455.html
-
-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.
+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.
 
 Making first contact
 ====================
@@ -120,14 +115,13 @@
 
    tfc139 /dev/ttyXXX
 
-Compal's firmware has some non-standard commands of their own invention added
-to TI's RVT/ETM interface, 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 Compal ETM 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.
+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.
 
 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
@@ -246,7 +240,7 @@
 loadtools to flash this version into your C139 whether it came with Cingular or
 TF branding originally.  Download this file:
 
-ftp.ifctf.org:/pub/GSM/Compal/c139-unlocked-fw.zip
+ftp.freecalypso.org:/pub/GSM/Compal/c139-unlocked-fw.zip
 
 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

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/TFC139-breakin	Sun Nov 15 03:47:19 2015 +0000
@@ -0,0 +1,95 @@
+Maliciously locked bootloader
+=============================
+
+When Compal (Motorola's ODM who designed and built their C1xx phones for them)
+designed the firmware architecture and flash memory layout for their phones,
+they made a bad design decision by putting the boundary between their bootloader
+and the main fw image at 0x2000, even though the flash erase block boundary
+doesn't come until 0x10000 - thus every time the main fw needs to be reflashed
+to a different version, the dangerous boot sector has to be reflashed too.
+
+But then they made things even worse in the newer versions of their fw by
+introducing a bootloader lock malfeature whereby the ability to interrupt boot
+and load code serially may be artificially disabled.  This malfeature is
+implemented as follows:
+
+* In the original firmware layout (before the addition of the malfeature in
+  question) the boot code occupies the flash range from 0 through 0x1FFF, then
+  there are some ID strings at 0x2000, 0x2020 and 0x2040, and then the part of
+  the firmware that used to be at 0x10000 in TI's reference fw starts at 0x20A0,
+  with the entry point at 0x20F8 (corresponding to TI's 0x10058).
+
+  With the addition of the bootloader lock malfeature the 32-bit word at 0x2060
+  (previously unused and filled with 0xFFFFFFFF) became a control word telling
+  the bootloader whether diversion of the boot path to serial code download
+  should be allowed or not.
+
+* When firmware images with this malfeature present are first built, the word
+  at 0x2060 contains 0xDDDDDDDD.  (Does D stand for debug or development, or
+  was the developer who implemented this malfeature fascinated by large bra
+  cups?  We may never know.)  This word MUST read as 0xDDDDDDDD in order for
+  the boot code to allow serial download: if it reads as any other value (e.g.,
+  if it contains 0xFFFFFFFF because only the 8192 byte boot code has been
+  programmed into flash sector 0, with blank flash from 0x2000 onward), no
+  serial download opportunity will ever be offered and the phone is effectively
+  bricked!
+
+* For as long as the word at 0x2060 still contained 0xDDDDDDDD, Compal's
+  developers could continue gaining access through the bootloader and reflashing
+  their firmware.  But when phones were to be shipped to customers with the
+  malicious bootloader lock activated, they probably sent some Test Mode command
+  (see RVTMUX write-up) to their running fw that caused it to write 0x00000000
+  into the flash word at 0x2060.  (Remember that any bit in a NOR flash memory
+  can be programmed from 1 to 0 at any time in any combination, but changing
+  bits from 0 back to 1 is only possible with full sector erasure.)
+
+* Once the word at 0x2060 has been programmed (in the flash memory sense) from
+  0xDDDDDDDD down to 0x00000000, the phone is irreversibly locked and has lost
+  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
+===============
+
+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:
+
+* 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
+  for debug trace and factory programming functions.  One needs to key in the
+  magic sequence **16379# into the running fw, and a hidden menu will appear,
+  giving the operator the option to enable trace.  Selecting this option will
+  cause the fw to switch the headset jack to the UART carrying RVTMUX.
+
+* Mot/Compal's firmware is based on a quite old version of TI's chipset
+  reference fw (relative to late TCS211 from the Openmoko/Pirelli era), and it
+  does not feature the Enhanced Test Mode (ETM) component with which we are
+  most familiar.  However, it does implement the older set of non-enhanced
+  Test Mode commands, and these TM commands just happen to include raw memory
+  read and write operations at an arbitrary address.  (For a while we were
+  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!
+
+* 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
+  erasing flash sector 0 and rewriting it with 0xDDDDDDDD in the 0x2060 word,
+  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
+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
+perform arbitrary flash operations.