--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Firmware_Status	Sat Mar 05 20:50:37 2016 +0000
@@ -0,0 +1,83 @@
+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
+are unfortunately nowhere near the goal of actually being able to replace TCS211
+for practical use.  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
+  and send and receive SMS.
+
+* Voice calls are broken: using appropriate AT commands, one can dial outgoing
+  calls and answer incoming ones, and they connect as they should.  However,
+  the voice audio path is broken: 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.
+
+* Deep sleep is broken and needs to be disabled with AT%SLEEP=2; the breakage
+  is likewise assumed to be somewhere in L1.
+
+The two current points of breakage in L1 (broken deep sleep and broken voice
+calls) are deemed to be show-stoppers, i.e., we are not going to progress this
+work in any other direction until these two are fixed.  And we currently see
+only two possible ways to fix these L1 issues:
+
+Option 1: find and obtain another copy of TCS211 that has its L1 component in
+source form, or a separate L1-by-itself source that would be compatible with
+Calypso DSP ROM 3606 and with the TCS211 fw architecture.
+
+Option 2: painstakingly reconstruct a TCS211-fitting version of L1 from the
+disassembly of the available binary objects, by taking LoCosto L1 sources and
+massaging them until they compile into object code that matches our TCS211
+reference.
+
+Option 1 involves more prayer than actionable work, while Option 2 is currently
+being worked on in another subproject of FreeCalypso - see tcs211-l1-reconst.