--- /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.

--- a/doc/Freerunner-Howto	Sat Mar 05 05:10:49 2016 +0000
+++ b/doc/Freerunner-Howto	Sat Mar 05 20:50:37 2016 +0000
@@ -1,14 +1,45 @@
 How to play with FreeCalypso GSM firmware on a Neo Freerunner
 =============================================================
 
-Aside from the half-source leo2moko fw we produced back in 2013-10 (you can
-read all about that one at www.freecalypso.org/leo2moko/), we don't have a
-working free GSM firmware version for the Freerunner yet.  What we do have
-currently is experimental code that can be built into an image that can be
-flashed into a GTA02 modem - but it doesn't really work yet.
+We have two entirely different firmware offerings for the Freerunner:
+
+1. Leo2moko fw produced back in 2013-10: this is the only one suitable for
+   end users.  We also have leo2moko-debug which is a slightly hacked-up
+   version of leo2moko with some additional debug features for developers;
+   this version is for developers only; end users should stick with the
+   original leo2moko-r1 aka moko12 from 2013-10.
+
+2. The work-in-progress full-source gcc-built FC GSM fw can be built for
+   multiple targets, and the gtamodem target is one of them - the original
+   one, in fact.
 
-If you would like to play with our experimental code on your Neo FR and maybe
-help us make it work, here are the instructions:
+The flash+SRAM chip which FIC/Openmoko populated in their modems provides
+plenty enough RAM for the firmware's data space requirements, but not enough
+to run a complete firmware code image entirely from RAM, hence whichever fw
+version you would like to exercise, you need to flash it.  There are two ways
+to flash modem firmware images in these smartphones: from inside the phone
+(from the application processor) or externally through a special serial cable
+inserted into the analog headset jack.  The internal method is intended only
+for end users flashing released production-quality images; developers and
+tinkerers are expected to use the serial cable method.
+
+The serial cable wiring requirements for the GTA02 are the same as for Mot C1xx
+phones, thus the same cable can be used for both.  The FreeCalypso project has
+endorsed UberWaves as our official vendor for serial cables; George at
+UberWaves now makes serial cables that are specifically certified for use with
+FreeCalypso.  If you would like to order one, email uberwaves@gmail.com.
+
+Please see the Firmware_Status write-up for the current status of our full-
+source gcc-built firmware.  As you can read there, this fw is currently nowhere
+near being able to replace leo2moko.  Therefore, if you are going to flash our
+gcc-built gsm-fw into your FR's modem, we expect that you are using your FR as
+a poor man's substitute for the not-yet-built FCDEV3B (a board we seek to build
+specifically for developers and not for end users), and are NOT expecting this
+experimental work-in-progress modem fw to work together with user-oriented
+application processor software like QtMoko.
+
+If you would like to play with our experimental gcc-built gsm-fw using a GTA02
+modem as the hw platform, here are the instructions:
 
 1. Build the firmware in the gtamodem-gsm configuration - see the Compiling
    document for more details;
@@ -38,11 +69,41 @@
 the modem and see the new fw boot.  You should have the serial cable connected,
 the serial channel enabled from the Freerunner's AP side and either rvtdump or
 rvinterf running on your PC or other development machine when you first power
-your modem up with the experimental fw in it: this way you will see whether the
-fw boots successfully or crashes.  If it does boot without crashing (whether or
-not it does seems to depend on some factors which we have yet to understand),
-you will get an AT command interface on the other UART going to the Freerunner's
-AP - now go ahead and play from there. :)
+your modem up with the experimental fw in it: this way you will see the debug
+output as the firmware boots up.
+
+Once the firmware has booted, it needs to be controlled via AT commands.  The
+present fw presents its AT command interface on two channels on this target: on
+the MODEM UART going to the Freerunner's application processor and via RVTMUX.
+At the present stage of development, we highly recommend that you avoid running
+any GSM-driving software on the AP and exercise our work-in-progress fw solely
+through the external serial interface on the headset jack, using rvinterf and
+fc-shell.  The standard AT command interface on the dedicated MODEM UART is a
+feature which we plan to address properly only when we build our planned FCDEV3B
+hardware, which will bring both UARTs out to the external host.
+
+Assuming that you already have rvinterf running in a terminal window (you should
+have started it before you gave the modem power-on command from the AP side),
+to exercise our firmware further, you will need to open another terminal window
+on your driving PC/laptop and run fc-shell.  This program will connect to the
+already running rvinterf process via a local socket, and it will enable you to
+send various commands to the running fw on the target, the most important ones
+being standard AT commands.  Send the following sequence of AT commands to
+bring up GSM functionality:
+
+AT%SLEEP=2	-- disable deep sleep (doesn't work yet)
+AT+CMEE=2	-- enable verbose error responses
+AT+CFUN=1	-- enable radio and SIM interfaces
+AT+COPS=0	-- register to the default GSM network
+
+Our fw is currently able to exercise all SIM interface functions (at least the
+obvious ones which I've tested), register with a live commercial GSM network
+using a legitimate SIM, and send and receive SMS using standard GSM 07.05 AT
+commands.  Voice calls don't work yet: you can dial a MO call with the ATD
+command and you can place a MT call to the device under test from the network
+side and then answer it with ATA, these calls connect successfully, but the
+voice audio fails to pass through: nothing but noise is heard in the earpiece
+speaker.  See the Firmware_Status write-up for more information.
 
 To reflash your modem back to stable and working leo2moko aka moko12, execute
 the following fc-loadtool commands:

--- a/doc/Pirelli-Howto	Sat Mar 05 05:10:49 2016 +0000
+++ b/doc/Pirelli-Howto	Sat Mar 05 20:50:37 2016 +0000
@@ -4,9 +4,9 @@
 Our experimental FC GSM fw can now run on the Pirelli DP-L10 target.  Our fw
 cannot yet operate this phone in a useful manner, i.e., it is not currently
 possible to replace Pirelli's proprietary fw with ours and use the phone as an
-end user.  Our gsm-fw is close to having working voice call functionality when
-controlled by an external host via AT commands, but we haven't even started
-working on the on-board user interface part yet.
+end user.  Our current gsm-fw has working SMS functionality (voice calls are
+still broken) when controlled by an external host via AT commands, but we
+haven't even started working on the on-board user interface part yet.
 
 One very useful special feature of the Pirelli DP-L10 is its very large RAM:
 8 MiB.  Having such large RAM allows us to run our experimental fw on this
@@ -23,8 +23,8 @@
 If you are ready to play with our experimental GSM pseudo-modem fw on your
 Pirelli, the steps are as follows:
 
-1. Build the firmware in the pirelli-gsm configuration - see the Compiling
-   document for more details.
+1. Build the firmware in the pirelli-gsm-rvtat configuration - see the
+   Compiling document for more details.
 
 2. Connect a USB cable from your GNU/Linux PC/laptop to the phone.  If the
    phone was off but the battery is present, it will go through a charger-plug
@@ -71,10 +71,11 @@
 Our fw is currently able to exercise all SIM interface functions (at least the
 obvious ones which I've tested), register with a live commercial GSM network
 using a legitimate SIM, and send and receive SMS using standard GSM 07.05 AT
-commands.  Voice calls don't work yet; dialing a MO call with the ATD command
-or placing a MT call to the device under test from the network side results in
-the firmware going haywire.  The latter misbehaviour is next to be investigated
-and (hopefully) fixed.
+commands.  Voice calls don't work yet: you can dial a MO call with the ATD
+command and you can place a MT call to the device under test from the network
+side and then answer it with ATA, these calls connect successfully, but the
+voice audio fails to pass through: nothing but noise is heard in the earpiece
+speaker.  See the Firmware_Status write-up for more information.
 
 When you are done playing with our experimental fw, you can either yank the
 battery and kill the host side rvinterf and fc-shell processes, or you can