The ultimate goal of the FreeCalypso project is to produce a GSM firmware
version that:

a) runs on the Calypso targets of interest to us: not only the FIC/Openmoko
   GTA0x GSM modem, but also some complete dumbphones like Mot C139 and/or
   Pirelli DP-L10;

b) operates each target device it runs on in a way that is practically usable:
   to me (lead developer Space Falcon) practical usability means providing a
   standard AT command interface on modems like GTA0x and operating as a self-
   contained standard cellphone with a UI on complete "dumbphone" targets;

c) is rebuildable from source in a way that would allow us to exercise the
   traditional Four Freedoms of free software as defined by the FSF.

Our starting point is TI's Leonardo reference firmware version from Sotovik, a
mixture of source and linkable binary object modules.  It can be built into a
complete and functional firmware image with TI's TMS470 compiler+linker+etc
toolchain, and can run on two hardware targets:

a) TI's Leonardo development board for the Calypso/Iota/Rita chipset -
   legendary unobtainium hardware;

b) FIC/Openmoko GTA0x GSM modem - while this device is *not* what I wish to use
   with the "end user" hat on, it is an available and working hw platform for
   development.

This Leonardo starting point does kinda-sorta satisfy the "rebuildable from
source" requirement, as I was able to port it from the Leonardo board to the
GTA0x modem, but it is still quite far from what the FreeCalypso project
ultimately seeks to achieve.

What I, the lead developer, ultimately seek is not an AT-controlled modem
embedded in a "Linux" smartphone, but a complete and standalone "dumbphone",
with the UI driven by the Calypso.  Transforming our starting and working
reference version from something that runs on the GTA0x modem and presents an
AT command interface into something that can run on a complete "dumbphone" and
present a self-contained UI can be done in several possible ways:

1. One could proceed further with the same approach that was used to produce
   leo2moko: keep making small incremental changes to the Leonardo semi-src,
   while keeping most of the binary object blobs intact at least initially, and
   sticking with the original proprietary TMS470 compiler toolchain (running
   under wine, as it's a bunch of M$ Windows binaries) throughout the journey.

   Advantage: no massive "forklift" step required at the very beginning of the
   journey, one can do small incremental steps instead.  One possible roadmap
   with this approach might be (just thinking out loud here) to start with
   finding a way to redirect the AT command channel to something wrapped inside
   RVTMUX, then port the fw to run on a target like Pirelli DP-L10, still
   controlled via AT commands but passed via RVTMUX, and then try to add the
   "dumbphone" UI layers.  Some of the binary object blobs would certainly need
   to be "cracked" and modified in this process, most sensibly by replacing
   each blob in need of modification with a reconstructed source piece, but
   this work would be done incrementally, rather than in a massive "forklift"
   step upfront.

   Disadvantage: this approach requires sticking with the original proprietary
   compiler toolchain throughout at least most of the journey, which means
   keeping the Weendoze poison that toolchain comes with.  This aspect was
   enough to turn me personally away from this approach.

2. One could move away from the proprietary compiler toolchain and replace it
   with gcc, while still retaining those parts of the Leonardo firmware for
   which we only have linkable binary objects but no C source, by teaching the
   GNU toolchain (gcc+binutils) to emulate the TMS470 compiler's ABI: COFF
   objects, a very different way of doing ARM/Thumb interworking, and a host of
   other differences from how the GNU toolchain for ARM normally does things.
   (I've done similar work on GCC and GNU Binutils in the past; let us not
   forget that GNU started out by emulating various inter-component interfaces,
   including ABIs, of various proprietary Unix versions.)

   The advantage of this approach should be obvious.  While in the long run we
   would certainly like to get rid of all binary object blobs and replace them
   with reconstructed source pieces, life would be much easier if we could do
   this work incrementally, one blob at a time in a regression-tested working
   fw version, rather than all upfront.

   Disadvantage: teaching gcc and binutils to emulate TI's TMS470 ABI well
   enough to where one could compile some sources with gcc, link the resulting
   .o's with TI's blobs and get a working fw image at the end would be no easy
   matter.  In fact, it would be a massive amount of work, and considering that
   this work would serve absolutely no purpose but to allow linking with some
   proprietary binary blobs, finding the justification for the effort would be
   difficult.

3. The approach I am currently following is the most ambitious one: start by
   deblobbing the firmware, i.e., replacing all binary object blobs with
   reconstructed source pieces, and then simply compile the all-C source with
   the GNU toolchain for ARM7 in its default ABI.

   Advantage: having the firmware in the form of full C source that builds with
   a free compiler (a compiler that is itself bona fide Free Software) is
   obviously the ultimate best.  No blobs means no need to waste creative energy
   on emulating proprietary compiler ABIs.

   Disadvantage: all the hardest work is upfront, and needs to be done in a
   "forklift" manner.

It should be obvious that incrementality, or division into manageable, bite-
sized pieces, is an essential requirement for successful execution of any large
scale project, and FreeCalypso is no different.  Because our chosen approach
unfortunately does not allow us to make small incremental modifications to a
fully functional fw version, I currently achieve the needed incrementality in a
different way: by starting out with a firmware "skeleton" that compiles into an
image and runs on the hardware, but does nothing useful yet, and then slowly
adding chunks of "meat" to this skeleton in incremental steps aiming in the
direction of the complete & working fw version that is our reference.  As I add
each "chunk of meat" to our gcc-built gsm-fw, I test it on the hardware and
compare its operation against the leo2moko reference version - that is our form
of pseudo-regression testing.

Where the missing source bits come from
=======================================

How can we replace a binary object blob with a corresponding source piece if we
lack the original source?  In two ways:

1. In many cases we can lift the corresponding source piece from another TI
   source leak, e.g., the LoCosto one.  Calypso and LoCosto chipsets are
   different, so code specific to LoCosto hardware won't run on Calypso targets,
   but much of the code is chipset-independent.  The LoCosto source leak is
   important because it contains real C source for many of the chipset-
   independent components for which our Leonardo reference version has only
   binary blobs.

2. When no original or suitable substitute source can be found anywhere, we
   have to bite the bullet, pass the blob through a suitable disassembler (I
   wrote one that is specifically taylored for reversing code built with the
   TMS470 compiler), and then write a piece of new C code that replicates the
   logic found in the disassembled blob.