FreeCalypso Citrine firmware on Mot C11x/12x and C139/140 families
==================================================================

NOTE: this write-up refers specifically to our work-in-progress Citrine fw.
The tcs211-c139 hack which we have produced in late 2015 is an entirely
different animal.

Unlike tcs211-c139, Citrine can run equally "well" on both our preferred
C139/140 platform and the more primitive C11x/12x, but this fw is currently
much more limited:

* tcs211-c139 includes TI's demo/prototype UI code and an LCD driver that works
  with C139/140 LCD hardware; Citrine currently has no UI code at all,
  expecting control via AT commands via the same serial cable you use for
  flashing it.

* TCS211 is TI's official production-quality firmware for the Calypso, whereas
  our Citrine fw is only beginning to catch up to it - see the Current_Status
  article for more information.

The phones in this family have very little RAM: 256 KiB of Calypso on-chip RAM
(IRAM) on all variants, plus another 256 KiB of board-level RAM (XRAM) on
C11x/12x or 512 KiB of XRAM on C139/140.  The tcs211-c139 port uses almost all
available IRAM and XRAM on the C139, hence porting it to C11x with even less
RAM was completely out of the question.  Citrine currently has a lot less
functionality integrated, which naturally translates to lower memory
requirements - hence it is possible to build for the C11x.

Because RAM is so precious on these feeble targets, running our own fw on them
absolutely requires flashing - fc-xram is not an option.  Furthermore, we cannot
use an FFS-in-RAM configuration like we do on large-XRAM targets, and Motorola's
original FFS (flash file system) on these phones is not suitable for our needs -
unlike the situation on Openmoko modems.  Therefore, we need to create and
maintain our own aftermarket FFS in a region of the device's flash memory which
we arbitrarily choose ourselves.

If you are going to play with FreeCalypso firmwares on Mot C1xx targets, we
recommend that you devote a phone specifically for FreeCalypso and have another
phone to charge batteries.  The process of flashing our firmware and creating
and maintaining the necessary aftermarket FFS on these targets is quite
involved, hence flashing a given phone back and forth between FreeCalypso and
Mot/Compal's official firmwares would be a total pita.  However, none of our
firmwares (neither this one nor tcs211-c139) currently has working battery
charging code, hence you will need to use another phone running one of the
official fw versions to charge batteries.

Compiling
=========

The starting configuration file for building Citrine for targets in this family
is configs/c139-gsm-flash.  If your phone is a C139 or C140, this default
config can be used as-is, although you are always welcome to edit it to taste.
If your phone is C11x or C12x, change the target setting from c139 to c11x.

The two numbers on the 'feature aftermarket-ffs' line select the region of
flash where our aftermarket FFS will be placed.  The default configuration
places our FFS in the region from 0x3C0000 through 0x3EFFFF.  This configuration
is recommended because:

* it does not conflict with the FFS maintained by Mot/Compal's fw (the two
  locations are different), eliminating the possibility of one firmware trying
  to use the FFS created by the other;

* it is placed at the very end of the flash (or rather at the end of the main
  flash zone with 64 KiB sectors), maximizing the room available for the
  firmware code image.

NOTE 1: our aftermarket FFS code cannot use 8 KiB flash sectors at the chip's
highest addresses.  Therefore, the sectors with factory data (which we don't
know how to grok) are safely left untouched by our fw.

NOTE 2: if your phone is a C11x/12x variant with 2 MiB of flash (some have
2 MiB, others have 4 MiB), directing the firmware to put its FFS at 0x3C0000
will result in it being at 0x1C0000 in reality - the highest address bit does
nothing when the flash chip only has 2 MiB.

NOTE 3: if your phone is C139/140, keeping the aftermarket FFS at 0x3C0000 is
doubly recommended as that is the location used by our tcs211-c139 build.

Flashing
========

The flashing procedures can be divided into two parts: the steps which you need
to perform only once when you first convert a given phone from Mot/Compal's fw
to FreeCalypso vs. the steps which you need to perform each time you wish to
flash another image you just compiled.

If you are starting with a "virgin" phone that never ran FreeCalypso before,
you will need to start by breaking in with fc-loadtool and possibly tfc139 -
see the Compal-unlock article in the FreeCalypso host tools package for more
details.  Once you are in with loadtool and have made a backup of your original
flash content, your first step will be to reflash sector 0 (the dangerous one)
with a version of the bootloader code that has been patched to transfer control
to the main fw image in the way we need:

loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin

The compal-flash-boot-for-fc.bin code image can be downloaded here:

ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/compal-flash-boot-for-fc.bin

It was made from one of Mot/Compal's original versions by applying a binary
patch to it; the source for this patch can be found in the retired
freecalypso-sw source repository on Bitbucket.

This step of replacing the bootloader needs to be done only once - you don't
need to reflash this dangerous sector again when you reflash the main fw image.
The patched FreeCalypso bootloader is also the same for both the present Citrine
fw and tcs211-c139.

The next step is to flash the main firmware image which you have just compiled:

loadtool> flash erase 0x10000 0x160000
loadtool> flash program-bin 0x10000 finlink/flashImage.bin

Note that the main fw image is flashed at 0x10000 on these targets.  It is
flashed at 0 on sane targets with the Calypso boot ROM enabled in the hardware,
but Compal phones have malicious wiring in their PCBs that makes them brickable
and imposes the requirement of having working boot code in sector 0 at all
times, with the main fw image pushed down to 0x10000.

Finally, you should erase the flash region which you have allocated for the
aftermarket FFS:

loadtool> flash erase 0x3C0000 0x30000

or if your phone only has 2 MiB of flash:

loadtool> flash erase 0x1C0000 0x30000

Now you can close your loadtool session with an exit command, and the phone
will be cleanly powered off.

The next time you need to reflash another FreeCalypso image, get in with
loadtool like this:

fc-loadtool -h compal /dev/ttyXXX

There is no more need for tfc139 or for the inefficient -c 1003 option to
fc-loadtool once you've replaced the bootloader with compal-flash-boot-for-fc.
Once you are in loadtool, just reflash the main fw image, and leave the
bootloader and FFS sectors alone.

First boot of the firmware
==========================

Connect the serial cable, but instead of running fc-loadtool, run rvinterf.
Press the red power button on the phone briefly just like you would for
fc-loadtool entry.  Because there is no fc-loadtool running on the host end of
the serial cable, the boot path will *not* be diverted in the bootloader, and
the main fw image will run - and this time it will be the FreeCalypso firmware
you have compiled and flashed.  The phone's LCD will remain dark as there is no
LCD driver code in this firmware, but you will see trace output in the rvinterf
window, telling you that the fw is running.

Before you do anything else, you will need to run fc-fsio and initialize the
aftermarket FFS for our firmware.  When running on Openmoko GTA0x and Pirelli
DP-L10 targets, our fw can use the original factory-programmed IMEISV and RF
calibration values (partial in the case of the Pirelli), but on Mot/Compal
phones these factory data are stored in a format which we haven't been able to
grok, hence we cannot make use of them.  Therefore, you will have to set your
own IMEISV manually, and the radio will run uncalibrated.

Initialize your aftermarket FFS as follows:

fsio> format /
fsio> mk-std-dirs
fsio> set-imeisv fc XXXXXXXX-YYYYYY-ZZ (punctuation optional, place anywhere)
fsio> set-rfcap dual-eu (if you have 900+1800 MHz hardware)
or
fsio> set-rfcap dual-us (if you have 850+1900 MHz hardware)

After you've initialized your FFS as above, you can exit fc-fsio, run fc-shell
and try some AT commands:

AT+CMEE=2	-- enable verbose error responses
AT+CFUN=1	-- enable radio and SIM interfaces
AT+COPS=0	-- register to the default GSM network

When you are done, you can power the phone off by sending a 'poweroff' command
through fc-shell.  The only other way is to yank the battery, and doing the
latter is recommended anyway: when a phone with the present hack-firmware
flashed into it is powered off but still has the battery inserted, even a
momentary accidental press of the power button will cause it to power on and
boot, but there will be absolutely no visual indication, as the LCD stays dark.

FreeCalypso GSM firmware on Mot C155/156
========================================

One major difference between Mot C155/156 and the other two subfamilies is that
C155 and C156 have 2 MiB of XRAM, which is large enough to allow our small-ish
experimental firmware to run entirely from RAM, without flashing, just like on
the Pirelli DP-L10.

If you are ready to play with our experimental GSM pseudo-modem fw on your
C155/156, the steps are as follows:

1. Build the firmware in the c155-gsm-ramonly configuration - see the
   Compiling document for more details.

2. Connect your serial or USB-serial cable as usual; the phone needs to be
   powered off at this point.

3. Run a command like the following:

   fc-xram -h c155 /dev/ttyUSB0 finlink/ramImage.srec rvinterf

   If you are using an official FreeCalypso USB-serial cable from UberWaves,
   you can speed up the code download by switching the serial line to 812500
   baud:

   fc-xram -h c155 -B 812500 /dev/ttyUSB0 finlink/ramImage.srec rvinterf

   Adjust the paths to your /dev/ttyUSBx or other serial device and your
   ramImage.srec as appropriate, and add rvinterf logging or other options as
   desired.  Specifying rvinterf on the fc-xram command line directs fc-xram to
   exec rvinterf and pass the serial channel to it immediately as soon as the
   code image has been loaded into target RAM and jumped to; this direct
   passing of the serial channel from fc-xram to rvinterf is appropriate
   because the loaded fw will immediately start emitting binary trace packets
   in TI's RVTMUX format.

4. Momentarily press the red power button on the phone.

Once the phone executes its boot code with fc-xram running, the boot path will
be diverted and our experimental firmware will be loaded into target device RAM
and jumped to.  Our fw will now run, and the rvinterf process on the host will
maintain communication with it.

Just like on the lower Mot/Compal subfamilies, we don't know how to extract the
factory-programmed IMEI and RF calibration data from Mot/Compal's proprietary
flash data structures, therefore, when our RAM-based firmware boots, it has no
IMEI and no RF calibration.  Because this RAM-only configuration leaves the
flash completely alone and does not create a non-volatile FFS there, you will
need to set the IMEISV and RFCAP with fc-fsio on each boot.  See the fc-fsio
commands given earlier, but skip the format command as the RAM-based FFS is
automatically formatted - but not otherwise initialized - upon firmware boot.