FreeCalypso > hg > fc-magnetite
view README @ 391:1da4c0cc9fc2
scripts/mkcomp-test.sh: default the new CHIPSET etc variables
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Wed, 17 Jan 2018 20:18:45 +0000 |
parents | 56ac93768594 |
children | 78e19122fa2b |
line wrap: on
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/