line source
+ − FreeCalypso Magnetite firmware project
+ − ======================================
+ −
+ − As of A.D. 2018, FC Magnetite is the primary official Calypso firmware source
+ − tree for the FreeCalypso family of projects. This maintained and evolving
+ − source can be built in many different configurations for several different
+ − hardware targets, and is currently used in the following ways:
+ −
+ − * The official production firmwares for our fully supported GSM+GPRS modem
+ − products (FCDEV3B and the modem part of Openmoko devices) are built from
+ − this source tree. See doc/Modem-configs for this mode of usage.
+ −
+ − * The work in progress toward a future complete FreeCalypso phone handset
+ − (also known as a Libre Dumbphone) is being done in this source tree.
+ − See doc/Handset-goal for more info about this project direction.
+ −
+ − * One can play with FreeCalypso and get a taste for it using certain hardware
+ − that used to be readily available and which most people in the phone hacking
+ − scene already have: Motorola C1xx and Pirelli DP-L10. Firmware images of the
+ − "hacking toy" sort can be built for these devices from the present source
+ − tree, and one can exercise most of the functions and capabilities of
+ − FreeCalypso (with the notable exception of CSD and GPRS) on this historical
+ − but available-to-most-people hardware. See doc/C1xx-Howto, doc/Pirelli-Howto
+ − and doc/Voice-pseudo-modem for more information.
+ −
+ − 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 came in a
+ − very rough "proof of concept" condition, nowhere close to a usable product.
+ −
+ − In FC Magnetite we further maintain and support the solid code base we got for
+ − the modem functionality, and we are also working to improve the support for
+ − handset products and bring it into a practically usable state. We have already
+ − implemented an entirely new battery charging and discharge monitoring driver
+ − that actually works on our target hw (of the two we got from TI, one was
+ − bitrotten and the other was designed for charging hardware that is quite
+ − different from what we are working with), and we shall hopefully start working
+ − on the UI soon - see doc/Handset-goal for more info.
+ −
+ − 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. This advanced functionality is fully supported on our own GSM MS
+ − development board (FCDEV3B), where both Calypso UARTs are presented directly to
+ − the developer, as well as on the embedded Calypso modem in Openmoko GTA01/02
+ − smartphones, where the AT command channel with CSD, fax and GPRS capabilities
+ − is connected to the phone's application processor.
+ −
+ − 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.
+ −
+ − Two versions of the G23M protocol stack
+ − =======================================
+ −
+ − A major component of all functional firmware configurations is the mass of code
+ − that implements layers 2 and 3 of the GSM+GPRS protocol stack, called G23M. In
+ − FC Magnetite we have the option of using one of two different versions of this
+ − key firmware component:
+ −
+ − * The original G23M version from Openmoko: this version is believed to be very
+ − stable because it has been used (successfully to the best of our knowledge)
+ − by Openmoko, and it came from TI's TCS211 program that officially targeted
+ − the Calypso chipset - but it exists only as binary object libraries with no
+ − corresponding source. The lack of source means no ability to change the
+ − feature configuration (what is enabled and what is disabled), very difficult
+ − to debug if something does go wrong - all of the usual problems of software
+ − without source.
+ −
+ − * A newer version from TI's TCS3/LoCosto program. This version came to us in
+ − the form of full C source, and because this fw component is chipset-
+ − independent (unlike L1), we have successfully produced a TCS2/TCS3 hybrid in
+ − which the new G23M code from TCS3.2 is grafted onto the chipsetsw foundation
+ − from TCS211, which we have reconstructed into full C source form as well.
+ −
+ − Each of the two G23M PS versions also has its own version of the Application
+ − Control Interface (ACI) layer to go with it, which we call aci2 and aci3 -
+ − except that in the case of ACI, we have the full source for both versions.
+ −
+ − The new TCS2/TCS3 hybrid config is the way forward, as our goal is to have no
+ − blobs in our firmware - having the full source is a prerequisite for maintaining
+ − a software product. FC Magnetite supports building both configurations in order
+ − to facilitate the transition, and as of this writing, we still need to add a few
+ − bits to the new version of ACI in order to achieve 100% feature parity with
+ − Openmoko.
+ −
+ − Other blobs
+ − ===========
+ −
+ − The TCS2/TCS3 hybrid firmware is built almost entirely from source; the only
+ − components which are linked in the form of prebuilt libraries are GPF, Nucleus
+ − and the TMS470 compiler's equivalent of libc/libgcc. It needs to be noted that
+ − these components are so stable and configuration-independent that they were
+ − used mostly in prebuilt library form even inside TI. In the case of GPF we've
+ − got the corresponding source for most of the modules within those libs; for the
+ − few modules for which the original source has been lost, we've already done a
+ − rough first-draft reconstruction as part of our previous gcc-built GSM fw
+ − efforts, and we only need to polish this reconstruction in order to have
+ − deblobbed GPF in our mainline production fw. In the case of Nucleus we likewise
+ − have another version of it in full source form which has been proven good in
+ − other FreeCalypso firmware projects.
+ −
+ − The planned successor to FC Magnetite (tentative planned name Selenite) will
+ − use the hybrid config for the G23M PS, deblobbed GPF and the source-enabled
+ − version of Nucleus, resulting in blob-free firmware except for the proprietary
+ − TMS470 compiler and its equivalent of libc/libgcc. Transition to building with
+ − gcc (like in FreeCalypso Citrine) will follow afterward, completely exiting the
+ − land of blobs and proprietary build tools.
+ −
+ − 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/