This semi-source tree contains a hacked version of TI's TCS211 firmware that
has been made to run on the Motorola C139.  Once the remaining bugs get shaken
out (there are still some crippling ones, so don't break out the champagne yet),
one will be able to replace Motorola's firmware in flash with this one and
*still be able to use the phone as an end user* - but now running firmware that
we build from source ourselves, one whose internals we know and understand and
which we can use a baseline for further functional improvements.

Compiling
=========

Building the present firmware from semi-source requires using a Wine environment
to run TI's proprietary compiler toolchain and other build tools which exist
only as M$ Windows binaries.  The necessary environment can be downloaded here:

ftp://ftp.freecalypso.org/pub/GSM/TI_src/wine/

You will also need the mokosrec2bin utility, which is needed for one of the
finishing steps in generating an image that can be usefully flashed into a C139:

ftp://ftp.freecalypso.org/pub/GSM/GTA02/gsm-fw/mokosrec2bin.c

Once you have the necessary build tools installed, you should be able to
compile the present fw as follows:

cd g23m
./winebuild.sh
./copyout.sh

The build products will be in the g23m/mfw-build directory.  mfw-build.progbin
is the flashable image, and the other files should be saved as documentation:
you should retain the COFF, map and str2ind.tab files that correspond exactly
to what you have flashed, so you can debug it later.

Flashing: what goes where
=========================

WARNING: C139 phones are brickable!  If you type the wrong command in
fc-loadtool, you can brick your phone *unrecoverably*!  Flash sector 0 MUST at
all times contain working boot code that can successfully perform the following
functions:

1. Check the headset jack UART for a possible serial download - if an external
   host is requesting a serial code download, accept the serially loaded code
   and jump to it.

2. If no serial download is taking place, jump to the main fw image in the rest
   of the flash for normal boot.

Function (2) may differ depending on what main fw is to be used, but function
(1) is absolutely essential: if flash sector 0 is erased and not immediately
reprogrammed with working boot code, or if it gets programmed with some code
version that does not perform function (1), then all ability to take control of
the phone will be lost, and it will be forever stuck in one of two states:

(a) If the boot code still performs function (2) and there happens to be a
    working main fw image in the flash, the phone will be stuck with that fw
    version forever, with no ability to reflash it or to load and execute any
    code in RAM.

(b) If the conditions of (a) above aren't met, the phone will be reduced to a
    paperweight.  There is no JTAG access on these phones, and the flash chip
    is not only a micro-BGA, but also combined with SRAM in the same package.
    Desoldering the flash+SRAM chip and replacing it with an externally
    programmed one is not likely to be feasible, hence bricked really means
    bricked.  You've been warned!

For FreeCalypso we've adopted our own version of the bootloader that performs
function (1) exactly like Mot/Compal's original (actually slightly better, as
we've removed the "1003" check, thus the inefficient -c 1003 fc-loadtool option
becomes unnecessary), but we've modified function (2): in Compal's original
design the main fw image starts at 0x2000 with the entry point at 0x20F8,
whereas in our arrangement the main fw image starts at 0x10000 with the entry
point at 0x10058.

We've changed the starting address for the main fw image to coincide with the
physical flash erase block boundary and thereby reduce the bricking risk.  If
we put our main fw image starting at 0x2000 like Mot/Compal did, we would have
to erase and reprogram flash sector 0 every time we would like to change the
main fw, incurring the risk of bricking the phone.  But with our modified boot
code we only have to do it once, when a given phone is first transitioned from
Mot/Compal's original fw to one of ours.  With subsequent reflashings from one
FreeCalypso fw version to another, we only need to reflash the main fw starting
at 0x10000, and leave flash sector 0 alone.

Besides the main fw and the critical boot code, the flash houses two more
entities: the factory data block and the flash file system (FFS).

Factory data block
==================

The 8 KiB flash sector at 0x3FC000 contains per-unit factory programming from
Motorola/Compal: RF calibration values, the unit's official IMEI and Cthulhu
knows what else.  Unfortunately we haven't been able to parse this info beyond
a superficial level, hence we have no way to make use of any of this data.
But of course we should not erase or overwrite it, so we just leave this flash
sector alone.

Flash file system
=================

Because Mot/Compal had moved their IMEI and RF calibration values into their
own proprietary format, these juicy items are NOT found in the FFS maintained
by the original firmware.  Instead the original fw's FFS contains only dynamic
state and user data, hence it is of no use to us.  We have adopted a different
flash location for our FFS from that used by Mot/Compal's fw in order to prevent
any possible cross-contamination, and you will need to manually initialize this
aftermarket FFS the first time you install FreeCalypso firmware on your C139.

Flashing procedure
==================

If you are not scared off by all of the above and you still wish to try this
experimental fw on your C139, you can install it as follows:

1. Connect to the phone with fc-loadtool, preceded by tfc139 if necessary -
   see loadtools documentation.

2. If the C139 in question does not already have some other FreeCalypso fw
   version in its flash, replace the bootloader:

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

(compal-flash-boot-for-fc.bin is our modified bootloader version, and it is
 built from one of Compal's versions via binary patching in the freecalypso-sw
 source tree.)

Optional step: If your serial cable setup supports the special GSM high baud
rates, you can speed the process up by issuing a baud 406250 or baud 812500
command at this point.

3. Flash the main fw image:

loadtool> flash erase 10000 290000
loadtool> flash program-bin 10000 mfw-build.progbin

Or you can use the supplied nifty loadtool command script:

loadtool> exec ./flash-mfw

The current directory must be g23m for the script method to work.

4. Erase the sectors where our firmware's non-volatile flash file system
   (aftermarket FFS configuration) will reside:

loadtool> flash erase 3C0000 30000

5. Cleanly end your fc-loadtool session, which will power the phone off:

loadtool> exit

FFS initialization
==================

The first time you boot your C139 after the above flashing procedure, the phone
should have no SIM in it.  Firmwares built with UI enabled (like the present)
automatically fire up GSM functionality and try to connect to a network
immediately upon boot if a SIM is present, and you don't want to do that on
your first boot: at this point your phone has *no* IMEI and no working FFS at
all.  When the fw boots up without a SIM, it still enables the part of the GSM
radio protocol stack that looks for usable cells, in anticipation of the
possibility that the user may need to make an emergency call, but it never
transmits anything in this state (Tx fully off) unless you do dial that
emergency call.

So take the SIM out before you start the reflashing procedure, and then boot
the SIM-less phone afterward.  You should see a message on the LCD that reads
"Insert SIM".  But instead of inserting a SIM, you should run the fc-fsio
utility from FreeCalypso host tools at this point.  Plug the serial cable back
in if you unplugged it, and run fc-fsio:

fc-fsio -p /dev/ttyXXX

(Omit the -p argument if you already have rvinterf running for fc-fsio to
 connect to.)

Then issue the following commands:

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)

Yes, you need to set your own IMEISV.  The official one is stored in the factory
data block, but we don't know how to parse it, so it effectively does not exist
for us.  It is entirely up to you whether you set the same IMEI as the official
one or a different one: our fw has no psychic powers to compare.  Unless you
have reason to do otherwise though, the default should be to keep the original
IMEI.  It is not clear what Mot/Compal's fw puts in the SV digits, so just put
00 in there if you don't feel like inventing version numbers.

The set-rfcap command is necessary because our fw does not know otherwise
whether your C139 is the 900+1800 MHz version or 1900+850 MHz.  If you don't
write a /gsm/com/rfcap file with this command, the fw defaults to quadband
(the part of the fw where this default is effected is a binary blob in the
present version) and will waste time scanning frequencies which it can't
receive because the corresponding RF transceiver input is unconnected
(unsupported high band) or because they are blocked by a SAW filter
(unsupported low band).

After you have initialized your new aftermarket FFS with fc-fsio per the above,
exit fc-fsio and power your phone off: hold the power button down until a TI
logo appears on the LCD, then release the button; the phone will power off
shortly, and you'll know it's off when the LCD turns off.  Now you can insert
a SIM and boot again - this time the phone should be live!

Limitations
===========

* The present fw has been built from a semi-src (half source, half binary
  objects) TI firmware release which was made for some manufacturer that made
  GSM/GPRS modems, rather than voice handsets, hence the present configuration
  is unfortunately highly suboptimal for our use case.  The entire mass of code
  supporting CSD, fax and GPRS data services is included and cannot be removed
  because that part of the fw is in binary blobs, but all this code is pure dead
  weight in the present configuration: the phone UI layer won't make any use of
  data functionality (nowhere near enough resources on this hw to implement a
  WAP browser or MMS), and because we had to give up the standard AT command
  channel (see next point), the option of having the phone dual-function as a
  laptop-tethered modem is not available either.

* TI's full-featured phone firmwares allow the phone to dual-function as a
  modem, so one could connect the phone to a laptop and make a CSD call or use
  GPRS.  But they were designed to make use of two UARTs, one for the classic
  AT command interface and the other for their RVTMUX debug/calibration/etc
  interface.  Unfortunately though, our present target hw has only one UART
  practically accessible (Calypso's MODEM UART brought out on the headset jack),
  and we absolutely need the debug interface, thus the classic AT command
  interface had to be sacrificed.  One can still issue AT commands over RVTMUX
  with FreeCalypso host utility fc-shell, but this mechanism works only for
  voice and SMS commands, not CSD or GPRS.  Hence the data functions of the fw
  remain unusable dead weight. :(

* The headset functionality of the headset jack is also unavailable: because we
  need to be able to use the debug interface at all times, we always keep the
  electrically-controlled switch in the state that connects the headset jack to
  the UART (presenting RVTMUX) instead of the audio circuits.

* Because we don't know how to grok Mot/Compal's factory data block, our fw
  currently runs UNCALIBRATED.  It may have difficulty connecting to networks
  if it can't acquire the frequency burst lacking VCXO calibration, and the Tx
  power levels are almost certainly wrong (out of spec) - BEWARE!

* The only 3 display configurations for which TI produced demo/prototype UI in
  their chipset reference firmware are 84x48 pix monochrome, 176x220 pix
  monochrome and 176x220 pix full color.  We have a 96x64 pix LCD on the C139,
  hence we are using TI's 84x48 UI design until we can create one that makes
  use of the slightly larger 96x64 screen.  However, TI had that 84x48 LCD on
  their C-Sample and earlier platforms (*very* old), and as we discovered
  empirically, the support for this 84x48 display config is already bitrotten
  in the source tree we got, which officially targets TI's D-Sample and Leonardo
  boards.

  At first the C-Sample UI configuration did not even compile.  We got it to
  compile by fixing it in a way that *seemed* right, but when we run this
  resurrected C-Sample UI on our C139 hardware, one can plainly see that the UI
  is still defective, as the expected output on the LCD is mixed with garbage.
  We will need to delve into the UI code in more depth in order to really fix it
  to where the display will be readable without garbage.

* Battery charging has not been tried yet.  It most likely won't work without
  additional fixes.