--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Roadmap	Mon Jun 23 20:39:36 2014 +0000
@@ -0,0 +1,131 @@
+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.