The goal of the gcc-built Calypso GSM firmware project contained in the gsm-fw
directory of this source tree is to replace the Windows-built firmwares which
have been produced in other subprojects under the FreeCalypso umbrella - see
leo2moko and tcs211-c139.  Our leo2moko project has produced a production
quality modem fw image for the Openmoko GTA02, while a C139 reflashed with
tcs211-c139 is the first dumbphone in history that can still function as an
untethered phone after having had its fw replaced with an indie one that bears
no relation to the manufacturer's original - but those TCS211-based
Windows-built projects have severe limitations.  Much of the firmware code base
in those versions is in the form of unmodifiable binary object libraries, and
the Windows-based configuration and build system is incompatible with the
long-term needs of FreeCalypso development.

The present FreeCalypso GSM fw project seeks to rectify the situation by
replacing the blob-laden, Windows-built firmware with a version that is built
from full source (no binary blobs) with gcc, with an entirely different
configuration mechanism that actually suits our needs.  Because one of the key
goals of this project is to build the firmware from *full source*, the binary
object versions of L1 (GSM Layer 1) and G23M (layers 2&3 of the protocol stack)
featured in our reference TCS211 fw could not be reused.  Instead this project
uses versions of L1 and G23M (and some other pieces) that have been lifted from
the firmware for TI's other chipset (LoCosto) and backported to Calypso.

The current state of the project is that we have made remarkable progress, but
what we have right now is still not a satisfactory replacement for TCS211.
Specifically:

* Only the bare minimal modem functionality for the voice+SMS subset has been
  integrated so far.  "Modem" means our fw can only be controlled via AT
  commands; no UI code (as in LCD+keypad) has been integrated at all.  But it
  is not a true modem either as none of the data functions have been integrated
  yet: no CSD, no fax, no GPRS.  Thus it is an AT-command-controlled voice+SMS
  pseudo-modem.

* The firmware can be built for the following targets:

  Mot C11x/12x
  Mot C139/140
  Mot C155/156
  Openmoko GTA01/02
  Pirelli DP-L10

  All configurations are built from the same source tree.  The firmware
  functions identically on all supported targets.  Because there is no UI code
  integrated yet, the LCD stays dark and the buttons do nothing on those target
  devices that have such hardware.

* Most of our supported target devices have only one practically accessible
  serial port (UART).  Our firmware presents TI's RVTMUX interface on this
  UART; the operator is expected to interface to it by running our rvinterf
  tools on the host PC/laptop.  One of the utilities in the rvinterf suite is
  fc-shell; this tool is used to send AT commands to the running firmware,
  which is the only way to control its operation.

* With a valid SIM card inserted and a valid IMEISV configured, a GSM device
  running our firmware can successfully connect to live commercial GSM networks,
  make and receive voice calls, and send and receive SMS.

* Voice calls work correctly only when the original FR codec is used; EFR and
  AMR are broken.  Our current workaround is that we advertise to the network
  that we only support the original FR codec; if we tell the network that we
  support EFR and/or AMR and the network selects one of these codecs, the
  result will be either a total DSP failure (the Calypso DSP blows up with
  errors, the call fails, and the phone is messed up until reboot) or a
  seemingly successful call with broken audio: nothing but noise is heard in
  the earpiece speaker.

  We reason that the problem must be somewhere in L1, which has been backported
  from LoCosto to Calypso in a rather Frankensteinian manner.

* When voice calls do work successfully (when the FR codec is used), the call
  downlink audio is routed to the phone's earpiece speaker and the phone's
  microphone serves as the source for the uplink audio, i.e., even though the
  LCD and keypad are dead with our firmware, the earpiece and mic continue to
  function as in a conventional phone.

  There is also a highly experimental and minimally tested alternative mode
  of operation in which the traffic channel carrying FR codec bits (260 bits
  every 20 ms) is rerouted away from the internal vocoder to the external host,
  such that you can receive the downlink voice bits digitally instead of
  listening to them in the earpiece speaker, and you can substitute your own
  uplink bits instead of the microphone-fed internal vocoder output.  See the
  TCH-special-feature write-up for more information.

* Deep sleep is broken and needs to be disabled with AT%SLEEP=2; the breakage
  is likewise assumed to be somewhere in L1.

The plan for further development is as follows:

* Our current problems with deep sleep and with the more advanced voice codecs
  are indicative of breakage in L1.  Furthermore, these are merely visible
  symptoms, and there may be other, more subtle breakage which we haven't
  noticed yet.  Because one of the key goals of this project is to produce a
  full-source, gcc-built firmware version that is no worse than TCS211, we need
  an L1 that functions no worse than in TCS211.

  In order to obtain this TCS211-matching L1, we are taking a little detour
  from the present gcc-built gsm-fw line of development and temporarily going
  back into the Windows build environment of TCS211 in order to reconstruct a
  recompilable TCS211 L1 source in its native environment.  You can follow the
  progress of that project in the tcs211-l1-reconst Hg repository on Bitbucket.
  When we get the TCS211 version of L1 fully reconstructed in its native
  environment, we are going to make a wholesale replacement of L1 in our
  gcc-built gsm-fw: completely remove the current version and replace it with
  the reconstructed TCS211 one.  This step should fix the deep sleep and
  advanced voice codec breakage, and give us a more solid foundation that will
  be no worse than our TCS211 golden reference.

* Once we have an L1 which we feel happy with, we will need to fix a few minor
  issues and implement two major missing features for the AT-command-controlled
  voice+SMS pseudo-modem configuration: battery charging (the ability to charge
  the battery while our pseudo-modem fw is running) and a keepalive mechanism
  that detects when the external host (connected via the serial port) has been
  disconnected and powers off the phone-turned-pseudo-modem in this case.  Once
  these two features are implemented, we will have a robust voice+SMS pseudo-
  modem solution with external AT command control.

* Once we reach the robust AT-command-controlled voice+SMS pseudo-modem
  milestone, we will have several different directions in which we can develop
  the project further.  It is too early and premature right now to plan that
  far ahead, though.

Target-specific usage instructions
==================================

If you would like to play with our work-in-progress firmware and check it out
for yourself, see the following target-specific instructions:

Mot C1xx (Compal)	FC-on-Compal
Openmoko GTA01/02	Freerunner-Howto
Pirelli DP-L10		Pirelli-Howto