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 image (but
doesn't work properly yet - see below) 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-05)
========================

We are currently using the Calypso GSM modem in the Openmoko GTA02 smartphone
as our bring-up vehicle.  This target has been chosen as the BUV because it is
very close to TI's reference hardware platform (Leonardo) on which TI's TCS211
reference firmware was designed to run.  Because our own firmware, despite
having been reintegrated and rebuilt by us, is still based on TI's reference
design and is only slowly diverging from that origin, it makes the most sense
to bring our fw up on the most "vanilla" hw platform first, and only then port
to other hw targets of interest (Motorola and Pirelli phones) that exhibit
noticeable differences from TI's "canon".

Our current gcc-built GSM firmware image runs on this gtamodem target.  But it
doesn't work properly yet: getting this firmware *built* was the first half of
the project (took a year and a half), and now we enter the second stage:
debugging problems one by one until we make it work.  Right now one can flash
our firmware image into a GTA02 modem and boot it; the modem running our fw
will then present a working AT command interface: one can exercise trivial
functions like version queries and even bring up SIM communication; one can
successfully query the SIM for its IMSI and phone numbers, for example.  But
attempting to bring the radio interface up fails.  There is also some weird
interaction with a hardware power cycling issue which we still need to
characterize further.

We are confident that we can fix whatever issues currently prevent our gcc-built
firmware from working, and get it to work no worse than the original half-src,
half-binary TCS211 - at least in the voice+SMS functional subset, without CSD,
fax or GPRS.  Once we reach that point, we will then port our FreeCalypso fw to
our non-Openmoko targets of interest (Motorola C1xx and Pirelli DP-L10), and
start reintegrating TI's reference UI code - our current fw is controlled by AT
commands only.  Then later re-add CSD, fax and GPRS.

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.