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.