--- a/README	Sun May 03 21:23:34 2015 +0000
+++ b/README	Sun May 10 05:28:05 2015 +0000
@@ -1,96 +1,141 @@
 What this project is about
 ==========================
 
-Welcome to FreeCalypso.  The goal is this project is to produce a Free Dumb
-Phone - not yet another smartphone (free or otherwise), but a "dumbphone",
-i.e., a traditional cellular telephone handset just like we all had and enjoyed
-back in the 1990s - a device with just enough hardware resources to make and
-receive traditional phone calls on a standard GSM network, and not one iota
-more.  No power-hungry application processors, just have one baseband processor
-that does everything from running the GSM protocol stack to responding to the
-user pressing buttons on the traditional numeric dialpad.  No big screens with
-power-hungry backlights, just a little LCD to display who is calling and the
-current date and time - I use my cellphone as a pocketwatch too, so my wrists
-stay free.
+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
+====================
 
-But we seek to build a "dumbphone" with one VERY SPECIAL twist: namely,
-operational firmware for the phone (which includes everything from the UI down
-to GSM Layer 1, as there is no separate baseband processor) available to every
-end user in the form of full source code.  Hence it will be a Free Dumb Phone.
-We seek to achieve this "special twist" by doing the following:
+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
+==================
 
-* We'll use the ancient TI Calypso chipset for our Free Dumb Phone instead of
-  whatever is the current offering from MTK or other cellular chipset company
-  du jour.  TI stopped making these chips ages ago, and got out of the cellular
-  baseband chipset business altogether, but we can still source these chips in
-  5-digit quantities on the Chinese surplus market.
+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:
 
-* Because we'll be using a baseband chipset from the surplus market made by a
-  company that long bit the dust, we will not be getting any official firmware
-  releases from any vendor.  Therefore, there is no one to sign any NDAs with,
-  and there is no one to tell us what we can or cannot do with the firmware as
-  we won't be getting any official firmware in the first place.
+* 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.
 
-* Our Free Dumb Phone will run free firmware which we put together ourselves.
-  When TI completely exited the cellular baseband chipset business, closed all
-  their offices involved with that work and laid off all of the responsible
-  employees, they broke their firmware into pieces and threw the pieces in the
-  trash.  We have picked these shattered pieces out of the trash dumpster, and
-  like anything else found in a dumpster, these abandonware pieces are
-  effectively in the public domain, and any person in the world is free to do
-  with them as she pleases.
+* 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
+===============
 
-The "shattered pieces" aspect of the firmware needs to be re-emphasized.  TI's
-complete firmware suite for their Calypso chipset, also known as TCS2.1.1 or
-TCS211, has *not* survived the disbanding of its maker company in an intact
-form.  Shattered bits and pieces are all we've been able to gather through our
-dumpster diving efforts.
+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.
 
-Reconstructing fully-functional firmware for the Calypso from the available
-broken pieces is where the bulk of the hard work in our project is.  There is
-another project (bb.osmocom.org) seeking to produce similarly-functional fw by
-rewriting it completely from scratch with a totally different architecture, but
-the lead developer of the present FreeCalypso project has chosen the
-reconstruction approach as more reliable and more likely to produce the desired
-result.
+* 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.
 
-Hardware vs. software
-=====================
+* 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.
 
-Our goal is to produce a complete and usable cellphone product.  Such a product
-requires both hardware and software (firmware).  We need to produce both.  We
-could do the hw and fw subprojects in either order, but we have chosen to work
-on the firmware first.  By doing the fw first, we will get to exercise it on
-some existing phones that use the same Calypso chipset; doing the hw ahead of
-the fw would give us a fancy paperweight.
+* 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.
 
-Current status
-==============
+* 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.  We have our own firmware suite, compiled 100% from
-source with gcc (no blobs or proprietary compiler toolchains!), but we have not
-yet reintegrated the full GSM protocol stack in this project.  (The leo2moko
-side project doesn't count.)  But we are getting close: we've got the
-FreeNucleus RTOS by XVilka as a working replacement for the binary-only version
-of Nucleus used by TI, and we've got the following parts of TI's original
-firmware suite integrated and working:
-
-* RiViera framework and everything that runs under it, including TI's original
-  FFS (flash file system), RVTMUX serial channel and ETM (Enhanced Test Mode).
-  This part has been found in a TCS211 semi-src package.
+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".
 
-* GPF (Condat's protocol stack framework) - TI used it mostly as binary libs,
-  even internally, and we had to reconstruct it from pieces.  Some parts of GPF
-  had to be reconstructed from disassembly.  But it works beautifully now.
+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.
 
-* GSM Layer 1 code - we took the version from the LoCosto source (no official
-  Calypso L1 source could be found) and backported it from LoCosto to Calypso.
-
-We are now working on reintegrating the rest of the GSM protocol stack code,
-also taking it from the LoCosto source (the only available full source) and
-reintegrating it to build in our FreeCalypso environment, targeting Calypso
-instead of LoCosto.
+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,
@@ -121,7 +166,15 @@
 		processor.  You'll need to build and install this toolchain
 		first before you can build gsm-fw or target-utils.
 
-If you like this project and would like to see it continue to fruition, please
-consider making a Bitcoin donation to the human family behind it:
+Website and mailing list
+========================
+
+Please see our website at www.freecalypso.org for information on:
 
-https://blockchain.info/address/159Yx6JRJ4oMLPTYrh1jW7fQ5D5tPHdnoM
+* 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.