+
−What this project is about
+
−==========================
+
−
+
−You are looking at the software/firmware subproject of FreeCalypso.  The goal
+
−of this subproject is to produce a fully functional firmware version for the
+
−Calypso GSM baseband chipset from Texas Instruments that is fully controlled
+
−by We the People (recompilation with a free compiler from full source code
+
−which is freely published and maintained by us, as opposed to a frozen
+
−impenetrable binary blob from some long-defunct vendor) and which we can use in
+
−two ways:
+
−
+
−a) replace the original proprietary firmware of certain pre-existing phone
+
−   models based on this chipset, thereby turning these historical devices into
+
−   libre phones;
+
−
+
−b) use as the official firmware for new phones and modems which we design and
+
−   build ourselves, using the same Calypso chipset.
+
−
+
−Origin of the source
+
−====================
+
−
+
−We are *not* attempting to reimplement a fully functional and practically
+
−usable GSM protocol stack from scratch in this project - such a task would be
+
−far beyond the capabilities of our very small and woefully underfunded team,
+
−and in the opinion of project leader Space Falcon, such a from-scratch
+
−reimplementation would be an egregious and morally impermissible waste of human
+
−talent.  Instead, we are using the L1 and G23M protocol stack code for TI's
+
−LoCosto chipset that was included in the chipset.zip public release made by the
+
−CEO of Peek, Inc. (the Peek mobile email device company) as that company went
+
−under, and porting it from the LoCosto-based Peek platform to our Calypso target
+
−devices of interest.
+
−
+
−Where we came from
+
−==================
+
−
+
−Just because we are reusing most components from TI's original firmware releases
+
−does not mean that our project is trivial or devoid of our own original work.
+
−When we started the GSM firmware subproject in the fall of 2013 (that was when
+
−we obtained the last missing piece of required starting source material), the
+
−available TI firmware sources consisted of:
+
−
+
−* A TCS211 semi-src deliverable that could be compiled into a working fw image
+
−  for the GSM modem in the Neo Freerunner.  While this version includes
+
−  recompilable source for most of the supporting components, the actual GSM
+
−  protocol stack is 100% linkable binary libraries sans source.  These binary
+
−  object components necessitate the use of TI's proprietary compiler tools to
+
−  rebuild the fw.  The build environment is set up for Windows only.
+
−
+
−* The source from Peek (TCS3.2_N5.24_M18_V1.11_M23BTH_PSL1_src.zip) for TI's
+
−  I-Sample board with the LoCosto chipset.  Mostly real source (about 95%), but
+
−  still has a few required components which exist only as linkable binary
+
−  libraries sans source.  The use of TI's proprietary compiler tools is still
+
−  required for the same reason, and the build environment is set up to use a
+
−  bunch of other Windows-only tools.
+
−
+
−* The Peek Linux project (svn.peeklinux.com) replaced the Windows-based build
+
−  system with a Linux-based one, but the binary-only libraries are still there,
+
−  hence the compiler toolchain is still the same proprietary one from TI.
+
−
+
−The above sorry state of affairs (absolute dependency on binary object code
+
−sans source, on proprietary compiler toolchains and on Windows) was very far
+
−from what we sought to accomplish (compilation from full source with gcc under
+
−GNU/Linux or other free Unix), hence we set out on a firmware reintegration
+
−project that took a year and a half.
+
−
+
−What we've done
+
−===============
+
−
+
−By a process of painstaking reintegration piece by piece, we have put together
+
−our own firmware suite for the Calypso that builds into a flashable or
+
−RAM-loadable image and has the following essential features/qualities/
+
−attributes:
+
−
+
−* Targets Calypso rather than LoCosto.  This decision is somewhat controversial,
+
−  i.e., one could make a valid argument that we should have gone with LoCosto
+
−  instead.  But in our defense, we already have several pre-existing devices
+
−  with the Calypso chipset on which we would like to run libre firmware; as for
+
−  LoCosto, we don't have a hardware platform to use as a bring-up vehicle, and
+
−  when we started the project, we were missing a copy of some of TI's Windows
+
−  tools for LoCosto.
+
−
+
−* The overall architecture of our firmware (what components are included) mimics
+
−  that of TCS211 (TI's official fw for Calypso platforms for which we only have
+
−  a semi-src): e.g., we use real RiViera rather than RV emulation atop GPF.
+
−  In the case of RiViera, FFS and other components for which our copy of TCS211
+
−  has real source, we have used that TCS211 source.
+
−
+
−* L1 and all of G23M (including ACI, CCD and AIM/SAP definitions) are the
+
−  version from the LoCosto source - which has an unfortunate quality of being
+
−  completely untested.
+
−
+
−* Configured for a feature set matching TCS211, i.e., most of the newer features
+
−  appearing in TCS3.2 are *not* enabled.  The GSM protocol stack is also
+
−  configured for the minimal voice+SMS feature set, i.e., CSD, fax and GPRS
+
−  haven't been integrated or enabled yet.
+
−
+
−* Everything builds from full source with gcc, i.e., *nothing* is used in the
+
−  form of a precompiled binary object or library.  Some parts of GPF, L1 and
+
−  system initialization code had to be reconstructed from disassembly of TCS211
+
−  binary objects, as no original or suitable substitute source could be found.
+
−
+
−* The version of Nucleus we use comes from a non-TI source; all TI GSM fw
+
−  sources we found have their Nucleus in binary-only libs.
+
−
+
−* To reiterate: our compiler is gcc, *not* TI's proprietary TMS470!
+
−
+
−Current status (2015-06-30)
+
−===========================
+
−
+
−Our current firmware can be built for two targets: Openmoko's Calypso modem
+
−built into their GTA01 and GTA02 smartphones (target gtamodem) and the Pirelli
+
−DP-L10 feature phone.  The functionality is the same on both targets: a modem
+
−or pseudo-modem controlled by AT commands (no local UI on the Pirelli), and
+
−only the voice+SMS subset, i.e., no CSD, fax or GPRS yet.  The firmware is able
+
−to register successfully to a live commercial GSM network (using a legitimate
+
−SIM of course), and SMS sending and receiving both work; all SIM interface
+
−functions also work as far as we've tested them.  But voice calls don't work
+
−yet; making them work is our next task.
+
−
+
−We have also produced some host tools for loading firmware into Calypso GSM
+
−devices, for communicating with running firmwares over the RVTMUX interface,
+
−and for manipulating TI's flash file system.  See README.hosttools for the
+
−details.
+
−
+
−Source tree
+
−===========
+
−
+
−The subtrees of this source tree are as follows:
+
−
+
−gsm-fw		The main FreeCalypso GSM firmware work, see above.
+
−
+
−target-utils	This tree contains code that runs on Calypso targets, but is
+
−		not regular firmware (gsm-fw) or a part thereof.  The two key
+
−		components built in this tree are loadagent (needed for all
+
−		targets) and compalstage (for Compal phones only), which need
+
−		to be installed on the user's host system in order for
+
−		loadtools (see README.hosttools) to do their job.
+
−
+
−ffstools	Tools that run on a Unix or GNU/Linux host; see README.hosttools
+
−loadtools	for the details.
+
−miscutil
+
−rvinterf
+
−
+
−toolchain	Scripts and patches for building the gcc+binutils toolchain
+
−		targeting ARM7, the CPU core of the Calypso GSM/GPRS baseband
+
−		processor.  You'll need to build and install this toolchain
+
−		first before you can build gsm-fw or target-utils.
+
−
+
−Website and mailing list
+
−========================
+
−
+
−Please see our website at www.freecalypso.org for information on:
+
−
+
−* The overall FreeCalypso libre phone project, beyond this specific sw/fw
+
−  subproject;
+
−
+
−* Our community mailing list and how you can subscribe to it;
+
−
+
−* How you can help the human family behind the project with donations and how
+
−  you can accelerate the progress of our project by funding it.