--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Mon Oct 03 04:26:16 2016 +0000
@@ -0,0 +1,153 @@
+FreeCalypso Magnetite firmware project
+======================================
+
+This source tree contains yet another firmware offering created under the
+FreeCalypso umbrella.  The key qualities of this firmware offering are:
+
+Negatives:
+
+  * Builds with TI's proprietary TMS470 compiler and thus requires Wine;
+  * Some of the fw components are still in the form of binary blobs -
+    but see below on the deblobbing progress.
+
+Positives:
+
+  * Can be built to run on Motorola C139, Openmoko GTA02 and Pirelli DP-L10
+    targets, as well as the to-be-built FCDEV3B, all from the same source tree;
+
+  * Works as solidly as the TCS211 "golden" reference from TI, on all of the
+    supported targets - deep sleep works, voice calls work in all codec modes
+    including AMR, the DSP dynamic download mechanism does its magic, the call
+    audio passes reliably in both directions.
+
+The present FC Magnetite firmware is built on the principle of starting with
+the known working TCS211 code base, without any major restructuring, and making
+small incremental evolutionary changes, testing at every step to ensure that
+nothing breaks.  It is the direct opposite of the "rebuild from the ground up"
+approach taken with our previous Citrine firmware (aka "gsm-fw"), the approach
+that produced very disappointing results.
+
+Functionality
+=============
+
+TI's GSM mobile station firmware architecture supports two ways in which the
+GSM device may be controlled: via AT commands from an external host and/or via
+a local UI on devices with LCD & keypad hardware.  (I said "and/or" because the
+two mechanisms can coexist.)  At the present time, however, only the AT command
+mode of operation is supported in FreeCalypso Magnetite.  The effect of this
+limitation is that if you run this fw on a Motorola C139 or a Pirelli DP-L10,
+the phone's LCD will stay dark, the buttons won't do anything, and the
+phone-turned-modem can only be operated via AT commands sent via FreeCalypso
+host utility fc-shell.
+
+The demo/prototype phone UI code in TI's reference fw delivery is written for
+a 176x220 pixel 16-bit color LCD (such an LCD was used on TI's official
+development platform called D-Sample), whereas our available Mot C139 and
+Pirelli targets have significantly smaller LCDs: 96x64 and 128x128 pixels,
+respectively.  Prior to the D-Sample, TI had used 84x48 pixel black&white
+(1 bit per pixel) LCDs, and this old C-Sample LCD code is still there, albeit
+bitrotten.  In late 2015 this author made a very dirty hack to resurrect TI's
+old C-Sample UI code and get it to display on the C139 phone LCD (84x48 is a
+proper subset of 96x64) - you can find this hack in the tcs211-c139 Hg tree.
+
+The upshot of this LCD situation is that porting TI's phone UI code to run on
+Mot C139 or Pirelli DP-L10 will require major rework of the affected parts of
+the firmware.  While I would like to do it eventually, I am not willing to do
+it right now - I would like to get this code running in its pristine state on
+its native 176x220 pix LCD *before* I hack the holy **** out of it for the
+C139/Pirelli port.  I do have a real TI-made D-Sample kit with the right LCD,
+but unfortunately the main board has an older version of the core chipset for
+which we lack the necessary fw support, hence it doesn't help.  Therefore, we
+will need to build our own Calypso board with a 176x220 pix 16-bit color LCD,
+get the UI-enabled GSM firmware running on that board, and only then proceed
+with C139 and/or Pirelli ports if such are still desired.
+
+For now, modem or pseudo-modem operation with control via AT commands is all
+we have.
+
+Build system
+============
+
+Even though FC Magnetite is essentially unchanged TCS211 code base and builds
+using TI's proprietary TMS470 compiler under Wine, the build system is entirely
+new.  TI's TCS211 build system, called BuSyB, works by way of a Java tool
+generating a customized makefile for each desired build configuration, based on
+lots of magic contained in a big repository of XML files.  There also a bunch
+of Perl scripts involved.  The Java tool that does the heavy lifting exists
+only as compiled Java bytecode sans source, and the surrounding Perl scripts
+aren't very understandable either.  And the whole thing thoroughly assumes a
+Windows environment (drive letters, backslashes, case-insensitive file system)
+throughout.  As a result, when working with TCS211 fw with its original build
+system, we had to treat these BuSyB-generated makefiles almost as being blobs in
+themselves: regenerating a makefile from XML magic required major effort, there
+were some bugs in the makefile generation which we couldn't fix and thus we had
+to edit the makefiles manually after each regeneration - it was an utter mess,
+and absolutely not an acceptable way to build a forward-looking, community-
+serving project.
+
+In FC Magnetite I have recreated the relevant parts of the TCS211 build system,
+using Bourne shell magic instead of Java and XML.  Just like TI's BuSyB, ours
+is a makefile generation system: in order to compile the firmware in a
+particular desired configuration, you run a shell script to select the config
+you would like.  This shell script will create a dedicated build directory tree
+to fully contain this build, and populate it with generated Makefiles and some
+other bits - then you go into the just-created build directory and run make
+there.  The source and build trees are thus cleanly separated.  See
+doc/Compiling for detailed instructions.
+
+Another key difference from our previous TCS211-based firmware offerings is that
+even though we still have to run TI's compiler binaries under Wine, the Wine
+invokation has been moved from the top (root) of the build process to the
+bottom leaves.  With our previous TCS211-based works you would run Wine at the
+top, and then the entire build process would proceed in the Windows environment,
+using Windows versions of make and other nonsense.  Not so in FC Magnetite:
+in this firmware project all shell scripts, Makefiles, Perl scripts and other
+build system accessories run at the native Unix level, and Wine is only invoked
+at the lowest level by individual tool wrappers: for example, TI's compiler
+binary cl470.exe is encapsulated in a Unix shell script called cl470 that
+invokes Wine to run the Windows binary, presenting the illusion of a native
+Unix tool to all upper levels.
+
+As yet another defenestration measure, all source files are checked into this
+tree with Unix line endings.
+
+Blob status
+===========
+
+A long-term FreeCalypso goal is to have our phone/modem firmware rebuild fully
+from source without any blobs, but this goal has not been achieved yet.  While
+we do have what *seems* to be a suitable replacement source (or feasible ability
+to reconstruct such) for every piece of TCS211 fw that came in binary-only form,
+actually making this replacement without breaking functionality is a very
+non-trivial endeavor.  Our previous attempt to rebuild the firmware from the
+ground up, using source pieces lifted from different available leaks and
+building with gcc so that no TMS470 COFF blobs could be used, produced very
+disappointing results.
+
+Instead the new FreeCalypso firmware approach implemented in FC Magnetite is to
+approach the blob-free goal incrementally.  The new Magnetite build system is
+specifically designed to enable the transition from the use of blobs to
+recompilation from source to be made with very fine granularity, down to the
+level of individual object modules within libs if necessary.  We tackle one
+binary-only component at a time, either reconstructing the missing source from
+disassembly or adapting the source from a different version as works best in
+each individual case, and we make a test build of the firmware using the
+reconstructed or fitted component instead of the original blob.  If the firmware
+still works (doesn't break), we make this deblobbing transition permanent and
+move on to the next component.
+
+As of this writing, most of Layer 1 and a few housekeeping parts of the fw have
+already been deblobbed, i.e., are now recompiled from source.  The G23M protocol
+stack is our next deblobbing target - we have a newer version of it in full
+source form, and we are hoping to be able to retrofit this newer G23M version
+into the TCS211 environment in order to replace the binary blob version we are
+using currently.
+
+Further reading
+===============
+
+For various instructions and notes specific to this FreeCalypso Magnetite
+firmware, look in the doc directory.  For more information about the overall
+FreeCalypso project and our hardware building aspirations, go to our website:
+
+https://www.freecalypso.org/