FreeCalypso Magnetite firmware project======================================This source tree contains yet another firmware offering created under theFreeCalypso 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: * Officially supports our own FCDEV3B and Openmoko GTA01/02 modem targets, as well as "hack-only" support for Motorola C139 and Pirelli DP-L10, 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 (on non-broken hardware), 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 withthe known working TCS211 code base, without any major restructuring, and makingsmall incremental evolutionary changes, testing at every step to ensure thatnothing 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 theGSM device may be controlled: via AT commands from an external host and/or viaa local UI on devices with LCD & keypad hardware. (I said "and/or" because thetwo mechanisms can coexist.) The code we got from TI (TCS211) is very solidand mature in the modem configuration (control via AT commands only, no UI, nobattery management, no traditional handset on/off control), but the additionalcode layers that are needed for handset products but not for modems are in avery rough "proof of concept" condition, nowhere close to a usable product.The same situation currently exists in FreeCalypso Magnetite. As explainedbelow in the Build system section, a key feature of FC Magnetite is that manydifferent firmware configurations can be built from the same source tree. Oneof the configuration choices is that you can build the fw either with or withoutthe phone UI layers. The work we have done earlier in the tcs211-c139 sideproject (late 2015) has been integrated into Magnetite, properly conditionalizedso that TI's original configuration is fully preserved when the target != c139.However, if you build the UI-enabled configuration for any target other thanMot C139, it will compile, but it won't do anything useful: it will try todisplay TI's 176x220 pixel color UI on the D-Sample LCD on Calypso chip selectnCS3, but this hardware doesn't exist on any of our supported targets. (ThePirelli in particular has flash on that chip select instead, so it may interferewith FFS operation.)Further work on the handset firmware configuration (UI, battery management andother currently missing functionality required for a usable phone) will have towait until we build our own Handset Motherboard Prototype (HSMBP) with a 176x220pixel 16-bit color LCD, replicating TI's D-Sample - I personally am not toointerested in doing this handset fw work on the very crippled Mot C139 or onthe Pirelli with its own host of issues, although others in the community aremore than welcome to take a shot at it if someone is interested.Until then, the primary current focus of the FC Magnetite project is theAT-command-controlled modem configuration. Both TI's original modem fw (TCS211)and our recreation thereof in this Magnetite project support not only voicecalls and SMS, but also CSD, fax and GPRS. This advanced functionality isfully supported on our own GSM MS development board (FCDEV3B), where bothCalypso UARTs are presented directly to the developer, as well as on theembedded Calypso modem in Openmoko GTA01/02 smartphones, where the AT commandchannel with CSD, fax and GPRS capabilities is connected to the phone'sapplication processor.Build system============Even though FC Magnetite is essentially unchanged TCS211 code base and buildsusing TI's proprietary TMS470 compiler under Wine, the build system is entirelynew. TI's TCS211 build system, called BuSyB, works by way of a Java toolgenerating a customized makefile for each desired build configuration, based onlots of magic contained in a big repository of XML files. There are a bunch ofPerl scripts involved as well. The Java tool that does the heavy lifting existsonly as compiled Java bytecode sans source, and the surrounding Perl scriptsaren't very understandable either. And the whole thing thoroughly assumes aWindows environment (drive letters, backslashes, case-insensitive file system)throughout. As a result, when working with TCS211 fw with its original buildsystem, we had to treat these BuSyB-generated makefiles almost as being blobs inthemselves: regenerating a makefile from XML magic required major effort, therewere some bugs in the makefile generation which we couldn't fix and thus we hadto 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, oursis a makefile generation system: in order to compile the firmware in aparticular desired configuration, you run a shell script to select the configyou would like. This shell script will create a dedicated build directory treeto fully contain this build, and populate it with generated Makefiles and someother bits - then you go into the just-created build directory and run makethere. The source and build trees are thus cleanly separated. Seedoc/Compiling for detailed instructions.Another key difference from our previous TCS211-based firmware offerings is thateven though we still have to run TI's compiler binaries under Wine, the Wineinvokation has been moved from the top (root) of the build process to thebottom leaves. With our previous TCS211-based works you would run Wine at thetop, 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 otherbuild system accessories run at the native Unix level, and Wine is only invokedat the lowest level by individual tool wrappers: for example, TI's compilerbinary cl470.exe is encapsulated in a Unix shell script called cl470 thatinvokes Wine to run the Windows binary, presenting the illusion of a nativeUnix tool to all upper levels.As yet another defenestration measure, all source files are checked into thistree with Unix line endings.Blob status===========A long-term FreeCalypso goal is to have our phone/modem firmware rebuild fullyfrom source without any blobs, but this goal has not been achieved yet. Whilewe do have what *seems* to be a suitable replacement source (or feasible abilityto reconstruct such) for every piece of TCS211 fw that came in binary-only form,actually making this replacement without breaking functionality is a verynon-trivial endeavor. Our previous attempt to rebuild the firmware from theground up, using source pieces lifted from different available leaks andbuilding with gcc so that no TMS470 COFF blobs could be used - see FreeCalypsoCitrine - 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 workreliably.Instead the new FreeCalypso firmware approach implemented in FC Magnetite is toapproach the blob-free goal incrementally. The new Magnetite build system isspecifically designed to enable the transition from the use of blobs torecompilation from source to be made with very fine granularity, down to thelevel of individual object modules within libs if necessary. We tackle onebinary-only component at a time, either reconstructing the missing source fromdisassembly or adapting the source from a different version as works best ineach individual case, and we make a test build of the firmware using thereconstructed or fitted component instead of the original blob. If the firmwarestill works (doesn't break), we make this deblobbing transition permanent andmove on to the next component.See doc/Modem-configs for the current status of the deblobbing effort and forthe description of the currently available configurations.Further reading===============For various instructions and notes specific to this FreeCalypso Magnetitefirmware, look in the doc directory. For more information about the overallFreeCalypso project and our hardware building aspirations, go to our website:https://www.freecalypso.org/