Whether you are interested in FreeCalypso VPM firmware (the main use case for
FC aftermarket fw that has actual utility value for GSM network testing etc) or
the UI-enabled FC firmware for Mot C139 that is currently just a preview (and
is not expected to advance to actual usability any time soon), either way these
firmwares need to be flashed.  All FC firmware offerings for Mot C1xx have
always required flashing, and various instructions have been published in the
past.  However, old FC-on-C1xx flashing instructions should not be used with
current firmware versions, because of these new developments:

* Our current fw relies even more than it did before on having certain files in
  FFS, hence populating the flash with not only the fw image, but also the FFS
  content it needs has become more important than ever before.

* For FC-on-C1xx configurations with 4 MiB flash, including the most important
  case of C139, the FFS location changed from the old one in Magnetite and
  Selenite to a new one in Tourmaline.  Therefore, old FFS instructions have to
  be invalidated.

The present fc-am-toolkit package provides a new way to flash FC firmware images
and initialize their associated FFS in one go, and this document provides
instructions.

Step 1: install software on your host machine
=============================================

The host machine (PC or laptop) which you are going to use to drive the phone
flashing process will need to have the following FreeCalypso software packages
installed on it:

1) FC host tools base package:

   ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-latest.tar.bz2

2) FFS data bundle add-on:

   ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/ffs-data-bundle-latest.tar.bz2

3) The present fc-am-toolkit package.

All 3 packages install all of their files under the /opt/freecalypso directory
tree defined by the Mother, and you only need to do this host software
installation once (or when updates come out), irrespective of how many phones
of various kinds you are going to flash or otherwise work with.

Step 2: read and save your phone's current flash
================================================

You will need to create a dedicated project directory for each individual phone
you are going to reflash to FreeCalypso, or on which you may contemplate the
possibility of such reflashing.  This per-phone project directory will contain
a record of the phone's IMEI, a dump (backup) of the original flash content,
bits of data extracted from that flash dump with tools in the present package,
generated command scripts for flashing FC firmware and for restoring the
original flash, and some other script-generated files - read the shell script
code if you want to know the full details.

In previous instructions I advised users to name this per-phone project
directory after the IMEI, i.e., to use the IMEI as the directory name.  I no
longer recommend that approach, and it no longer makes sense with the current
fc-am-toolkit design as the IMEI will be stored in a text file inside the
per-phone project directory, rather than in the directory name.  So please name
your project directories in whatever way makes sense for your situation.

Once you have created your per-phone project directory, please cd into it, and
with that directory as current, run fc-loadtool as appropriate for your C1xx
phone model:

fc-loadtool -h compal /dev/ttyXXX		-- for C11x/12x
fc-loadtool -h compal -c 1004 /dev/ttyXXX	-- for C139/140
fc-loadtool -h c155 /dev/ttyXXX			-- for C155/156

These simple instructions are valid for C1xx phones with unlocked bootloaders.
If your bootloader is locked, you will need to break in with tfc139 instead.
There are other documentation articles in FreeCalypso that describe tfc139
break-in method.

These instructions also assume that you already know how to operate fc-loadtool
on a basic level.  If not, here is a basic summary: to make an entry with
fc-loadtool, you need to start with the phone turned off - but the battery
needs to be inserted, and preferably have a full charge.  You need to run the
fc-loadtool command shown above (change /dev/ttyXXX to the correct serial or
USB-serial device in your setup) with the cable connected between your PC/laptop
and your phone's headset jack _and with the phone turned off_.  When you run
fc-loadtool in this state, it will sit there, waiting for PROMPT1 from the
phone's bootloader.  Once fc-loadtool is running in that state and the cable is
correctly inserted on the phone end, press the red power button on the phone -
a momentary press is sufficient and recommended.

Once you have landed at the loadtool> prompt, make a dump of your flash as
follows:

loadtool> flash dump2bin flashdump.bin

The dump file needs to be named flashdump.bin - at least in the case of C11x/12x
subfamily, there is one script in the fc-am-toolkit shell script hierarchy that
looks for this original flash image under this specific name.

Once the flash dump operation finishes, issue this additional command:

loadtool> flash compal-imei IMEI

This command tells fc-loadtool to retrieve the phone's factory IMEI from OTP
cells (the flash chip's OTP protection register) and save it into a text file
named "IMEI".  The file name is important - scripts that follow will look for
the IMEI in the file with this name.

IMEI retrieval needs to be done with this extra command because of the location
where this factory datum is stored.  On Compal phones the factory IMEI is not
stored anywhere at all in the flash image (in the main byte array held by the
flash memory chip), instead it is stored in an out-of-band location (OTP cells,
meaning physically immutable once written) in the flash chip's protection
register.  Therefore, this factory IMEI cannot be extracted from a captured
flash image - instead it needs to be read in a separate explicit step and saved
alongside the flash image.

Once you have captured both flashdump.bin and IMEI, close your fc-loadtool
session by issuing an "exit" command at the loadtool> prompt.  The phone will
return to its powered-off state.

Step 3: analyze the flash image you just captured
=================================================

Run this command:

c1xx-analyze-image flashdump.bin

This command runs a shell script, which then invokes several different programs
that analyze various aspects of the flash image.  Your current directory when
running the above script command needs to be the per-phone project directory,
and the script will create the following items:

* A subdirectory named rfasc will contain extracted RF calibration values in
  FreeCalypso RF table ASCII format, which is both human- and machine-readable.
  This directory is not used by any subsequent fc-am-toolkit scripts, but if
  you have the mind of an engineer, you may find its content interesting.

* Another subdirectory named rfbin will contain the same data as rfasc, but in
  the firmware's internal binary format.  This subdir will be used by subsequent
  scripts.

* A text file named restore-flash will contain a generated command script for
  fc-loadtool - executing this script will restore the flash image in
  flashdump.bin back into your phone's flash, i.e., restore your phone back to
  its original state after playing with FreeCalypso.

Step 4: prepare FC firmware flashing command script
===================================================

This step is the first one where you need the FC firmware image you seek to
flash - previous steps didn't need one.  You can flash a firmware image which
you compiled yourself from source, or an official build you downloaded as part
of a tarball release - either way, you need the fwimage.bin file that
corresponds to your hardware model (c11x, c139 or c155) and your desired
functional configuration as in VPM or UI preview firmware.

VERY IMPORTANT: You need to be very certain of which C1xx subfamily your phone
belongs to; the 3 subfamilies known to us are C11x/12x, C139/140 and C155/156.
Firmware images are NOT interchangeable between these 3 hw subfamilies!  C11x
and C139 are distinguished by their LCD type (monochrome on C11x, color on
C139); C155/156 have a distinct visual appearance, but they also have 8 MiB
flash which no other subfamily in this set uses, and our c1xx-analyze-image
script looks at the image size.  Verbose notes printed by that script should
agree with your own knowledge of which phone subfamily you are working with -
if there is a discrepancy, STOP RIGHT HERE and ask for expert help.

Once you have confirmed your phone model/subfamily and selected the firmware
image you are going to flash, execute one of the following shell scripts:

c11x-gen-fc-script path/to/fwimage.bin
c139-gen-fc-script path/to/fwimage.bin
c155-gen-fc-script path/to/fwimage.bin

Each script variant works the same way for its respective C1xx subfamily, and
all have the same invokation rules: the current directory needs to be your
per-phone project directory containing flashdump.bin and IMEI files and the
rfbin subdirectory produced in steps 2 and 3, and the script adds to this
project directory.

The main result of executing the script command above will be a text file named
fc-flash-script; this text file is a command script for fc-loadtool that
reflashes your phone to the FreeCalypso fw image you have selected.  The fw
image pathname you gave to {c11x,c139,c155}-gen-fc-script will be contained
inside the generated fc-flash-script - but in addition to referencing that fw
image, the generated loadtool command script also contains instructions for
programming fc-ffs.bin into the phone along with the firmware.  This fc-ffs.bin
image is also generated by the shell script you just ran, and it is specific to
your individual phone: your IMEI and extracted RF calibration values go into it.

Step 5: actually flash your phone
=================================

This step is the actual surgery - all previous steps merely manipulated data in
files in your project directory on your host machine.  To perform the flashing
surgery, do the following:

* Using the phone's original firmware as the charging agent (the thing you plug
  in is not the charger, it is the charging power source; the charger circuit
  is inside the phone, and the firmware is the entity that controls the flow of
  current from the charging power source into the battery), make sure that your
  battery is fully charged.  The flashing process does not require a ton of
  battery power, but the last thing you want is to have your battery run out
  while you are in the middle of the flashing operation.

* Make entry with fc-loadtool just like you did in step 2, when you made a dump
  of the original flash content.

* Once you are at the loadtool> prompt, issue this command:

  exec fc-flash-script

In this step you are basically telling fc-loadtool to execute the command script
that was prepared in step 4.  This script performs all necessary flash erasure
and programming operations - having a previously prepared script do everything
in one go greatly reduces the chances of leaving your phone in an invalid
partially flashed state due to operator distraction or other human errors.
Once the flashing script finishes executing, exit loadtool and your phone will
power off.  Next time this reflashed phone executes hardware switch-on (power
button press or charging power plug-in while off), your firmware will boot!

Restoring the original firmware and full flash content
======================================================

To restore the flash to its original state, do the same procedure as above, but
run 'exec restore-flash' instead of 'exec fc-flash-script' - just execute a
different flashing command script.

IMPORTANT NOTE: Do NOT attempt to transplant complete flash images (not just
the firmware portion, but the whole thing) from one phone to another!  For
maximal restorative power, the loadtool command script generated by
c1xx-analyze-image (named restore-flash) restores the entire flash image, every
bit without exceptions - but this property also makes the {flashdump.bin +
restore-flash script} combo non-transplantable, i.e., it should NOT be
programmed into a different phone.  Each individual phone has its own unique RF
calibration values and other factory tunings, stored in small sectors at the end
of the flash (after the firmware), and these bits should never be mindlessly
transplanted from one phone to another.

The firmware portion (part of the flash up to a certain model-dependent offset)
CAN be transplanted from one phone to another, and such copying of certain
"good" official Motorola fw versions is often quite useful - but such procedures
are a different topic from what the present document is addressing, which is
providing less expert users with a fool-proof way to play with FreeCalypso fw
and then restore their phones to the original state.

Flash process interruptions and recovery
========================================

All C1xx phones are brickable: if you give wrong flash write commands to
fc-loadtool, it is quite easy to brick the phone's boot sector beyond recovery.
As a departure from previous FreeCalypso flashing instructions, in the present
flow you never enter any flash commands manually in loadtool - instead you
execute a loadtool command script that was generated by official shell scripts
in the present package.

Because the boot sector still needs to be rewritten (the command that does so
is part of the generated fc-flash-script and restore-flash scripts), a very
small bricking vulnerability window still exists - but this window is on the
order of some milliseconds to a few seconds at most.  (The bricking-vulnerable
operation completes in an imperceptible time in my actual experience, but Intel
flash datasheet says it can take up to 5 s.)  Furthermore, in order for the
phone to get bricked, the unfortunate event happening in that short
vulnerability window would have to be someone physically yanking the battery
out of the phone, or the battery running down or falling out - simply
disconnecting the serial cable or killing fc-loadtool process on the driving
host during this window will NOT cause bricking, as the entire sequence of
operations that fall into the bricking vulnerability window happens entirely
inside loadagent without needing further host communication once started.

However, if the flashing process as a whole (on the order of a few minutes if
you are using "slow" 115200 baud rate) gets interrupted for whatever reason,
you will get a partially flashed phone, which may at first glance appear to be
bricked.  But as long as the boot sector is good - and it will be good if you
haven't hit the worst-case scenario as above - you can still recover.  To
recover from a flashing process that got interrupted in the middle, follow this
sequence:

* Return the phone to its powered-off state by removing and reinserting the
  battery.  Very important: do NOT press the power button or plug in charging
  power after reinserting the battery until instructed to do so below; if you
  mess up, remove the battery again, reinsert it, and be careful this time to
  NOT press the power button prematurely.

* With the phone off and the battery freshly removed and reinserted, connect
  the headset jack serial cable and run fc-loadtool with the right arguments.

* Momentarily press the power button.

fc-loadtool should now make its entry and land you at the loadtool> prompt.
At this point you re-issue the 'exec fc-flash-script' or 'exec restore-flash'
command as per the direction of desired transition, and hopefully complete this
time.

Battery charging
================

If your phone happens to be in the messed-up state caused by interrupted
flashing, charging will not work in this state: you can only use whatever power
is left in the battery, or swap in another battery, perhaps charged in another
phone.  This consideration is the main reason why you should fully charge your
battery before starting a firmware flashing operation.  Don't ever plug the
charging power source into a phone with (temporarily) messed-up firmware: it
won't do any actual charging (which requires charging control managed by fw),
but it will mess up your ability to make fc-loadtool entry for recovery.

One of the benefits of the current flashing procedure, with the firmware and a
fully prepared FFS image flashed in one go, is that once converted to
FreeCalypso, the phone regains its charging ability right away.  With previous
instructions that called for flashing just the firmware and then formatting and
initializing FFS with fc-fsio, there was a longer window in which the phone is
not capable of charging its battery.

When the phone is in flashed FC firmware state, flashed correctly by following
the present instructions, it _is_ capable of charging: simply plug in charging
power, and charging will proceed much like it does in standard phones.  This
aspect holds for VPM firmwares too, not just the UI-enabled version - although
the only way to see the progress state of the charging process is by watching
the debug trace output or querying the firmware with AT%CBC (a private AT
command) and knowing how to interpret the cryptic result it returns.

A warning is needed, however: FC-fw-driven battery charging on C1xx phones is
not carefully tuned, and what our fw aims for as "full charge" may actually be
either an undercharge or an overcharge.  Significant overcharge appears to be
unlikely - the available evidence suggests that undercharge is a little more
likely - but the possibility of overcharge (which is very bad for battery
health) cannot be ruled out.  You've been warned!