--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Compal-unlock	Sat Jun 11 00:13:35 2016 +0000
@@ -0,0 +1,389 @@
+Using FreeCalypso tools to unlock Motorola C1xx phones
+======================================================
+
+The ultimate goal of the FreeCalypso project is to produce our own complete GSM
+dumbphone firmware which We the People fully own, control and compile from
+source ourselves, running at first on some selected pre-existing hardware
+targets, and then ultimately on our own Free Dumb Phone hardware.  While that
+goal is still far past the visible horizon, what can we do in the meantime to
+make our current forced use of existing proprietary dumbphone firmwares a
+little more tolerable?  This article presents one such hack: using FreeCalypso
+loadtools to dump the flash content of Compal phones for analysis, including
+TIFFS, and to replace one existing proprietary fw version with another, e.g.,
+to remove carrier branding and the associated SIM restriction.
+
+Serial access
+
+Mot C1xx (Compal) phones have a 2.5 mm headset jack that dual-functions as a
+debug/programming serial port.  In hardware terms, there is an electrically
+controlled switch (MUX) inside that switches the external jack between the
+analog headset signals and the digital serial ones; this switch is controlled
+by a GPIO signal from the Calypso.  The hardware power-up state of this switch
+is serial; Mot/Compal's standard fw switches it to headset upon boot, but the
+serial setting persists long enough to use it to break into the bootloader.
+
+Bootloader
+
+The Calypso DBB (digital baseband) chip used in these phones has an on-chip
+boot ROM, but it also has a hardware pin that enables or disables this boot
+ROM, and unfortunately these phones have it disabled.  If the boot ROM were
+enabled in hardware, it would provide an unstoppable and unbrickable way to
+take control of the device through the externally-accessible serial port like
+we have on Openmoko and Pirelli phones, but unfortunately the hardware we have
+available is not wired that way.
+
+However, Mot/Compal's standard firmware on these phones includes a bootloader,
+a part that executes before any of the rest of the fw image is allowed to
+execute or is made use of in any way, and this Compal-specific bootloader has a
+provision for interrupting the boot process and diverting it to an externally-
+supplied piece of code loaded over the serial line.  Older fw versions have
+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 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 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
+====================
+
+If you have a C1xx phone which you are seeking to free, your first step should
+be to try breaking in with fc-loadtool, using the Compal bootloader method.
+With the phone powered off, but containing a charged battery (SIM present or
+absent, doesn't matter), proceed as follows:
+
+1. Connect the serial or USB-serial cable between your PC or other host and the
+   target phone's headset jack.
+
+2. On the host end, run fc-loadtool like this:
+
+C11x/123: fc-loadtool -h compal /dev/ttyXXX
+C139/140: fc-loadtool -h compal -c 1003 /dev/ttyXXX
+C155/156: fc-loadtool -h c155 /dev/ttyXXX
+
+3. Press the power button on the phone.  A momentary press is sufficient and
+   recommended: the hardware powers up and causes the boot code to run exactly
+   the same whether the power button is pressed momentarily or held down.
+
+   Normal phone power-up requires the button to be held down because the
+   standard firmware does a check fairly late in the boot process to see if the
+   power button is still held down, and commands the hardware (the ABB) to
+   power off if it is not - it is a standard feature to prevent phones from
+   turning themselves on inadvertently from accidental momentary presses of
+   that button.  But if the goal is to cause the boot code to run, but not to
+   boot the regular fw all the way, a momentary press is ideal.
+
+If your phone has a bootloader without the malicious lock in it, the above
+procedure should result in fc-loadtool gaining full access to the target and
+landing you at a loadtool> prompt.  You can dump the flash content and analyse
+it, etc.  If you would like to change to a different fw version (to remove the
+SIM lock / carrier branding or for any other reason), see the corresponding
+later section of this article.
+
+Alternative method
+==================
+
+If the above procedure fails to gain access to the Calypso because the boot
+code in the phone never offers a serial download opportunity, the alternate
+break-in method should be tried, going through the full running firmware
+instead of just the bootloader part thereof.  Proceed as follows:
+
+1. Remove the SIM (if there was one to begin with) and put the charged battery
+   back in.  Charge the battery if necessary, using the standard charging
+   function of the existing fw.
+
+2. Power the phone up for normal boot: hold the power button down like a
+   regular user would, without fc-loadtool or other serial break-in tools.
+   The fw will boot up, notice the lack of a SIM, and the display will read
+   "SIM card absent" or something to that effect, depending on the fw version.
+
+3. Key in this magic sequence: **16379#.  A hidden "Trace Switch" menu should
+   appear, with the choices being "Trace On" and "Earphone".  Select "Trace On".
+   The electrically controlled hardware switch mentioned earlier in this article
+   should now be set back to the UART, bringing the latter out to the headset
+   jack.  Because Mot/Compal's firmware is based on TI's reference architecture,
+   the interface presented by the running fw on this serial port is TI's RVTMUX,
+   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 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.  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 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
+success and direct you to run:
+
+fc-loadtool -h compal -c none /dev/ttyXXX
+
+Do as it says.  The -c none option tells fc-loadtool to skip compalstage and
+proceed directly to feeding loadagent to the Calypso boot ROM.  You should now
+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 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
+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
+===========================
+
+Once you break in with fc-loadtool (either through the bootloader or through
+tfc139), the first step you should do is make a dump (backup) of the flash:
+
+loadtool> flash dump2bin flashdump.bin
+
+Before you do any flash write (erase or program) operations, please realise
+that these phones are brickable.  Because the Calypso boot ROM is disabled at
+the board level (Calypso DBB's nIBOOT configuration input is tied high directly
+underneath the BGA package!), when the phone powers up, the ARM7 core starts
+executing instructions directly out of the flash, from address 0.  Therefore,
+flash sector 0 must contain good working boot code (one that allows serial code
+download access for recovery) at all times.  If you erase this sector or fill
+it with some garbage (anything other than good working boot code) and then power
+the phone off or otherwise lose control of it, the phone will be unrecoverably
+bricked!
+
+On most C1xx models there seems to be no way to access the Calypso's JTAG
+signals, hence no possibility of using JTAG to unbrick a bricked phone.  And
+because the flash chip is a micro-BGA, it is quite unlikely that one could
+successfully desolder it, program it in a standalone flash chip programmer,
+and then put it back on the board.  Thus if you brick your C1xx phone, then
+most likely it is truly toast.  You've been warned!
+
+That being said, if your phone came with a maliciously locked bootloader, such
+that you had to use tfc139 to break in, then replacing that bootloader with a
+non-malware version is pretty much a necessity, and taking the chance of
+bricking the phone becomes a necessary risk.  Even if the bootloader version in
+your C1xx is free of the locking malfeature, if you need to reflash the main fw
+to a different version, one still needs to erase and reprogram the dangerous
+sector: on C11x/123 and C139/140 the main fw image starts at 0x2000, but the
+erase block boundary doesn't come until 0x10000.
+
+The good news, however, is that fc-loadtool has special support for rewriting
+the boot sector on Compal phones with minimal risk of bricking.  The command is:
+
+flash erase-program-boot binfile [length]
+
+The first argument is the name of the file (in straight binary format)
+containing the new boot code; the second argument (always interpreted as hex)
+is the number of bytes to program, always starting at 0.  If only one argument
+is given, the length of the file is used instead, which must not exceed the
+length of flash sector 0: 64 KiB on C11x/123 and C139/140, or 8 KiB on C155/156.
+
+This special command minimizes the bricking vulnerability window by loading the
+entirety of the new boot code to be programmed into a scratchpad RAM buffer on
+the target first (no problem because it's 64 KiB max), then commanding loadagent
+(the code that actually runs on the Calypso when you use fc-loadtool) to perform
+the "atomic" operation of erasing flash sector 0, then immediately reprogramming
+it with the bits that are already in scratchpad RAM on the phone.
+
+With this approach the phone will only be bricked if the battery dies or is
+physically yanked out of the phone in the time window between the beginning of
+the erase operation and the last critical bit of the new boot code being
+programmed - on the order of a second or two, or if the flash operations fail
+for some reason.  However, the phone will *not* be bricked with this approach
+if the serial connection between fc-loadtool or the target gets broken during
+the window in question, or if the host machine running fc-loadtool crashes: no
+flash operations start until loadtool gives the go-ahead command to loadagent,
+and once loadagent receives the latter command, it will proceed till completion
+without caring if loadtool is still there or not.
+
+Of course the conventional flash erase and flash program-bin commands will be
+happy to operate on flash sector 0 just like any other sector, but doing so is
+NOT recommended, as the window of vulnerability for bricking would then be
+considerably greater.
+
+Unlocked firmware for C139
+==========================
+
+If your phone is a North American (1900+850 MHz) C139, and you are reading this
+article because it came with Cingular or TracFone branding, whereas you would
+like to use it with SIMs and networks of your own choosing instead, you've come
+to the right place.  We have an unlocked and non-carrier-branded (Mot branding
+only) version of the fw that runs on these phones, and you can use FreeCalypso
+loadtools to flash this version into your C139 whether it came with Cingular or
+TF branding originally.  Download this file:
+
+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
+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
+flash erase 10000 360000
+flash program-bin 2000 c139-unlocked-fw.bin 2000
+
+The 3 commands given above will reflash the phone as follows:
+
+* The first 0x2000 bytes of the firmware image in c139-unlocked-fw.bin comprise
+  the boot code.  This fw version features the "good" boot code *without* the
+  access locking malfeature.  The erase-program-boot command will erase flash
+  sector 0 (the entire 64 KiB sector, as the physics of the flash chip dictates)
+  and then immediately reprogram its first 8 KiB with the "good" boot code from
+  the unlocked fw image file.  The remaining 56 KiB of this sector will be blank
+  after this step.
+
+* The following "regular" flash erase command is to erase the following 54
+  sectors (also of 64 KiB each) in preparation for programming the main fw
+  image in there.
+
+* The last command programs the bulk of the fw image into blank flash that has
+  been erased by the first two commands.
+
+I also recommend erasing the old FFS that was maintained by the old fw version,
+so that the new fw will automatically format a "virgin" FFS the first time it
+boots:
+
+flash erase 370000 50000
+
+After this procedure the phone should retain its original IMEI and factory RF
+calibration values, as these are stored in the 8 KiB sector at 0x3FC000 which
+is not touched per the above procedure - not in the FFS.
+
+The same procedure should be followed for flashing all firmwares for C11x/123
+and C139/140 phones.  In the case of C11x/123, adjust the length for the "main"
+erase and program operations appropriately for the flash configuration in your
+phone.
+
+Flashing newer firmware versions
+================================
+
+The flashing procedure given above, where the first 0x2000 bytes of the new fw
+image (the bootloader part) are written with the flash erase-program-boot
+command and the regular flash program-bin command writes everything from 0x2000
+onward, is only correct for older firmware versions whose bootloader portion is
+completely free from the access locking malfeature: not only unlocked, but with
+no provision for locking at all.  In these older fw versions the boot code is
+fully contained in the first 0x2000 bytes and nothing from 0x2000 onward affects
+the ability to perform a new serial boot, hence the bricking vulnerability
+window ends at 0x2000.  However, this flashing procedure should NOT be used for
+newer fw versions that have the provision for locking the bootloader - it's the
+provision that matters in this case, even if the lock hasn't been activated -
+if you flash one of these newer fw versions as above, you will risk bricking
+your phone!
+
+If you need to flash one of the newer fw versions that includes the bootloader
+lock provision, you need to take some additional precautionary steps:
+
+1. Examine the fw image you wish to flash with a hex dump viewer.  Look starting
+   at offset 0x2000.  You should see 3 identifying ASCII strings: one right at
+   0x2000, another at 0x2020 and one more at 0x2040.  Then look at 4 bytes at
+   offset 0x2060.  If they contain 0xFFFFFFFF (blank flash) like the surrounding
+   unused bytes, then you have an older fw version without the bootloader lock
+   provision - you can safely flash it as in the previous section.  If it's a
+   newer fw version with the bootloader lock provision, the word at 0x2060 will
+   contain either 0x00000000 or 0xDDDDDDDD, corresponding to the activated
+   (access disabled) and non-activated (access enabled) states of the lock,
+   respectively.
+
+2. If the fw image you wish to flash has 0x00000000 at 0x2060, you must patch
+   it to 0xDDDDDDDD with a hex editor before flashing.  Just because our tfc139
+   utility can recover phones with maliciously locked bootloaders does NOT mean
+   that you should *ever* deliberately flash such a bootloader-locked fw image
+   into your phone!  Recovery of locked phones via tfc139 depends on the
+   complete fw image being present and working, not just the bootloader part,
+   hence if you were to flash an image that has a lockable bootloader with the
+   lock activated, the bricking vulnerability window will extend until the
+   *entire* fw image has been programmed - far too dangerous.
+
+3. When flashing the image with fc-loadtool, use a slightly different command
+   sequence compared to the previous section:
+
+   flash erase-program-boot new-fw-image.bin 10000
+   flash erase 10000 360000
+   flash program-bin 10000 new-fw-image.bin 10000 360000
+
+The difference is that the boundary between the part handled with flash
+erase-program-boot and the part handled with flash program-bin has been moved
+from 0x2000 to 0x10000.  Because the word at 0x2060 is part of the bricking
+vulnerability window with these newer fw versions, one should rewrite the
+entire boot sector of the flash (including the beginning of the main fw image)
+with flash erase-program-boot for safety.
+
+Unlocking while keeping the same fw version
+===========================================
+
+Suppose you have a phone with a locked bootloader such that you had to break in
+with tfc139, you would like to unlock it so you can use RAM-based (non-flash)
+tools such as c139explore or OsmocomBB with it, but you have no particular need
+to change the main fw from the original version to a different one.  If you
+need to perform such a cisversion unlock, you can do it as follows:
+
+1. Break in with tfc139;
+2. Use fc-loadtool's flash dump2bin command to save the first 64 KiB sector
+   of the flash to a file;
+3. Using a hex editor, patch the word at 0x2060 from 0x00000000 to 0xDDDDDDDD;
+4. Use fc-loadtool's flash erase-program-boot command to flash the patched
+   (unlocked) boot sector back into the phone.
+
+C155/156 differences
+====================
+
+C155/156 phones are nicer than the others in that they use a flash chip with a
+"bottom boot" configuration.  C11x/123 and C139/140 use "top boot" flash chips,
+which is why the boot code and the first 56 KiB of the main fw image live in
+the same erase block on those phones.  The boot code and the control hand-off
+interface between it and the main fw have also been revamped in C155/156 fw,
+and the new structure is:
+
+8 KiB sector at 0: contains the boot code
+7 more 8 KiB sectors starting at 0x2000: blank and unused
+64 KiB sector at 0x10000: also blank and unused
+64 KiB sector at 0x20000: beginning of main fw image
+
+With this new flash layout, it is now possible to erase and program the main fw
+region starting at 0x20000 without ever erasing the boot code sector or doing
+any writes to it, so there is no bricking vulnerability window at all.  (The
+phone can still be bricked though if one types the wrong command and erases the
+boot sector inadvertently, so be careful.)
+
+So far the only phones in this family that I laid my hacking hands on have been
+North American C156 units, all from the same seller and batch (hence identical),
+so I don't know if there exist any maliciously-locked boot code versions in
+this family - the boot code in my C156 is free of any malfeatures.  But if "bad"
+versions of C155/156 boot code do exist, and if you can break into the phone
+somehow, you can use the flash erase-program-boot command to rewrite the boot
+code with minimal risk of bricking just like on the other Compal families.