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 1004 /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.