+
−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".
+
−
+
−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.)  The code we got from TI (TCS211) is very solid
+
−and mature in the modem configuration (control via AT commands only, no UI, no
+
−battery management, no traditional handset on/off control), but the additional
+
−code layers that are needed for handset products but not for modems are in a
+
−very rough "proof of concept" condition, nowhere close to a usable product.
+
−
+
−The same situation currently exists in FreeCalypso Magnetite.  As explained
+
−below in the Build system section, a key feature of FC Magnetite is that many
+
−different firmware configurations can be built from the same source tree.  One
+
−of the configuration choices is that you can build the fw either with or without
+
−the phone UI layers.  The work we have done earlier in the tcs211-c139 side
+
−project (late 2015) has been integrated into Magnetite, properly conditionalized
+
−so that TI's original configuration is fully preserved when the target != c139.
+
−However, if you build the UI-enabled configuration for any target other than
+
−Mot C139, it will compile, but it won't do anything useful: it will try to
+
−display TI's 176x220 pixel color UI on the D-Sample LCD on Calypso chip select
+
−nCS3, but this hardware doesn't exist on any of our supported targets.  (The
+
−Pirelli in particular has flash on that chip select instead, so it may interfere
+
−with FFS operation.)
+
−
+
−Further work on the handset firmware configuration (UI, battery management and
+
−other currently missing functionality required for a usable phone) will have to
+
−wait until we build our own Handset Motherboard Prototype (HSMBP) with a 176x220
+
−pixel 16-bit color LCD, replicating TI's D-Sample - I personally am not too
+
−interested in doing this handset fw work on the very crippled Mot C139 or on
+
−the Pirelli with its own host of issues, although others in the community are
+
−more than welcome to take a shot at it if someone is interested.
+
−
+
−Until then, the primary current focus of the FC Magnetite project is the
+
−AT-command-controlled modem configuration.  Both TI's original modem fw (TCS211)
+
−and our recreation thereof in this Magnetite project support not only voice
+
−calls and SMS, but also CSD, fax and GPRS.  However, before we can really
+
−exercise this functionality, we need to first build our long-overdue FCDEV3B
+
−hardware.  TI's standard fw architecture (kept unchanged in FC Magnetite)
+
−assumes the availability of two UARTs: the modem UART presents a classic AT
+
−command interface which includes the CSD, fax and GPRS functionality, whereas
+
−the 2nd IrDA UART carries the debug trace channel (RVTMUX) essential for
+
−developers.  However, only one UART is practically accessible on Mot C139 and
+
−Pirelli DP-L10 targets; because we could not give up RVTMUX, we gave up the
+
−classic AT command UART channel instead.  We have implemented a mechanism for
+
−passing AT commands over RVTMUX, but this mechanism works only for the voice
+
−and SMS AT commands, not CSD, fax or GPRS.  Therefore, the latter functionality
+
−remains inaccessible until we build our own proper Calypso board with both
+
−UARTs brought out.
+
−
+
−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 are a bunch of
+
−Perl scripts involved as well.  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 - see FreeCalypso
+
−Citrine - has produced only a very limited subset of the original functionality,
+
−and until very recently even the most basic function of voice calls did not work
+
−reliably.
+
−
+
−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.
+
−
+
−See doc/Modem-configs for the current status of the deblobbing effort and for
+
−the description of the currently available configurations.
+
−
+
−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/