--- a/README	Sat Oct 15 19:30:58 2016 +0000
+++ b/README	Sat Oct 15 22:41:38 2016 +0000
@@ -150,8 +150,8 @@
 still works (doesn't break), we make this deblobbing transition permanent and
 move on to the next component.
 
-See doc/Deblobbing for the current status of the deblobbing effort and for the
-description of the currently available configurations.
+See doc/Modem-configs for the current status of the deblobbing effort and for
+the description of the currently available configurations.
 
 Further reading
 ===============

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Handset-configs	Sat Oct 15 22:41:38 2016 +0000
@@ -0,0 +1,105 @@
+Work toward end user libre phone firmware
+=========================================
+
+Phone handset firmware, i.e., fw that makes a phone device work as an untethered
+phone and not just a serial-cable-controlled pseudo-modem, requires a few
+additional layers of functionality beyond AT-command-controlled modem fw:
+
+* The hardware-specific LCD driver, called R2D in TI's TCS211 program;
+* The actual phone UI implementation, which the cellular industry calls by the
+  sexist term "MMI" - TI's implementation consists of two components called BMI
+  and MFW;
+* Battery management (monitoring and charging);
+* Fairly complex on/off logic to handle all possible combinations of turn-on,
+  turn-off, charging while "on", charging while "off", charging completed or
+  failed but charging power source not unplugged yet.
+
+The code we got from TI with the TCS211 delivery by Sotovik includes only a
+very rudimentary implementation of the above functions that basically amounts
+to nothing more than a proof of concept, and is absolutely not ready for driving
+a real end user phone: the UI code contains crashing and other killer bugs, the
+battery management code doesn't work (fails to even monitor the battery voltage
+in the discharging state, and I haven't even got to trying to charge), and the
+on/off logic is broken in several ways.
+
+If we desire a libre phone for our pockets and purses (I do desire one for my
+purse), we will have to bite the bullet and do the necessary work to transform
+the UI and associated handset code from its current sorry state into something
+usable, and I have started laying a little bit of the necessary foundation for
+doing this work in FC Magnetite.
+
+There are currently two Magnetite configurations (in the ./configure.sh sense)
+that include the UI layers: 2092 and 2092-pwr.  2092 is TI's bizarre "product"
+number for the configuration that is just like the one we got from Sotovik
+(called pdt_2091), but with BMI enabled.  The difference between the plain 2092
+config and 2092-pwr is that the latter includes TI's battery management code in
+the form of the old RiViera Software Entity (SWE) called PWR.  (I tested the
+latter on the C139 and found it to be broken.)
+
+If you request the 2092 configuration for a target other than c139, i.e., for
+fcdev3b, gtamodem or pirelli, you will get a successful build (to be pedantic,
+if you pick gtamodem, you'll get a link failure unless you tweak the linker
+script, but it's a minor nit), but if you then run that fw image on the
+hardware, it won't do anything good: it will try to display TI's D-Sample UI
+(176x220 pixels, color) on the D-Sample LCD attached to Calypso chip select
+nCS3, but of course neither Openmoko's modem nor the Pirelli has a D-Sample LCD
+on that chip select, thus the LCD output would fall into the aether.  (It would
+be even worse in the case of the Pirelli which has the 2nd flash bank on nCS3,
+thus the D-Sample LCD writes could clash with the FFS code operating on that
+flash - so don't do it.)  However, because BMI is enabled, the fw will still
+automatically bring up the GSM radio and register to the default network
+immediately upon boot like a typical UI-enabled phone does, even though the
+associated LCD output will be invisible.  Needless to say, this configuration
+is not something I would ever advise actually running.
+
+However, if you build the 2092 config for the c139 target, the Magnetite build
+system will enable the same hack which was originally implemented in the
+tcs211-c139 side project in late 2015.  Prior to the D-Sample with its fancy
+176x220 pix color LCD, TI's previous development platforms (C-Sample and
+earlier) had 84x48 pix black&white (1 bit per pixel) LCDs, and this old C-Sample
+LCD support is still there in TCS211, albeit in a bitrotten form that wouldn't
+even compile without a lot of fixing.  In our late-2015 tcs211-c139 side project
+we had resurrected this C-Sample UI configuration, and this work has now been
+integrated into Magnetite.  When you build Magnetite in the 2092 configuration
+for the c139, you will get our C139 LCD driver that pretends to be C-Sample to
+the upper layers, and you will get TI's old 84x48 pix B&W UI displayed on the
+phone's 96x64 pixel color LCD.  IOW, only 84x48 out of the available 96x64
+pixels are used, and only 2 out of the available 65536 colors.  Yes, pretty
+pathetic, I know.
+
+My (Mychaela's) plan going forward is to build our own more proper hardware
+before digging any deeper into TI's broken UI code.  I am not happy at all
+about having had to disable TI's D-Sample UI (the 176x220 pix color one) and
+resurrect the ancient pathetic C-Sample one instead, and given the long list of
+show-stopping bugs this UI code currently exhibits, I can never be sure which
+of these bugs were already there in the D-Sample config this code was made for,
+vs. which of these bugs could be a result of re-enabling the very bitrotten
+C-Sample UI config - remember, it wouldn't even compile at first.
+
+As much as I would love to have a libre phone in my purse, my desire to see
+TI's UI code running in its native 176x220 pix color form is even greater, hence
+I have decided that I shall abstain from doing any further UI work targeting
+the C139 or the Pirelli until *after* we have built my desired HSMBP: Handset
+Motherboard Prototype, a Calypso board with a 176x220 pix color LCD just like
+on TI's D-Sample.
+
+However, if anyone else in the community has a different view and sees the
+making of a libre phone based on Mot C1xx or Pirelli hardware as more important
+than building our own hw, please feel free to take a stab at the code yourself:
+the whole point of FLOSS projects is that anyone can do what s/he wants with
+the code and the project without being beholden to the leader's views.  At least
+some of the necessary foundation has already been laid for you.
+
+Deblobbing status
+=================
+
+The current 2092 and 2092-pwr configs are based on the l1reconst modem config
+(see the Modem-configs write-up), i.e., L1 is mostly rebuilt from source, but
+the versions of G23M PS and ACI are the original TCS211 ones, thus the G23M PS
+component is all blobs.  In order to build a G23M-deblobbed UI-enabled config,
+we would need to build the UI layers (MFW and BMI) on top of the new TCS3.2
+version of ACI used in the deblobbed hybrid config, and no such feat has been
+attempted yet.  I personally plan on tackling this direction only after we have
+built my desired D-Sample-like HSMBP and brought up the original TCS211 UI in
+its original form, but once again, anyone else whose priorities are different
+from mine should feel free to delve into the code themselves.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Modem-configs	Sat Oct 15 22:41:38 2016 +0000
@@ -0,0 +1,60 @@
+Modem configurations
+====================
+
+If you would like to build our Magnetite firmware in the AT-command-controlled
+modem configuration (not the C-Sample UI demo on the Mot C139), you have 3
+specific configurations to choose from, differing in the level of deblobbing:
+
+classic		This configuration replicates classic TCS211, just like
+		leo2moko from 2013.  Almost all of the original binary blob
+		libraries are used; the only components that are recompiled
+		from source are those which we got in source form with our copy
+		of TCS211 from Sotovik.  This config can only be built for the
+		fcdev3b and gtamodem targets, not for c139 or pirelli.
+
+l1reconst	In this configuration most of L1 (GSM Layer 1) is recompiled
+		from reconstructed source, although this deblobbing of L1 is
+		not 100% complete yet: for some pieces of L1 the original binary
+		object blobs are still used.  Some housekeeping pieces are also
+		recompiled from source that had to be reconstructed.  This
+		config can be built for all targets.
+
+hybrid		This configuration is a TCS2/TCS3 hybrid.  Instead of using the
+		TCS211 version of the G23M protocol stack which we got only as
+		binary blobs, this config uses the G23M PS version from the
+		TCS3.2/LoCosto source, backported to work with L1 and the fw
+		foundation layers from TCS211.  ACI also had to be replaced with
+		the TCS3 version, and a special hybrid version of the cdginc
+		headers had to be constructed.  L1 is also deblobbed to the
+		same extent as in l1reconst.  Like l1reconst, this config can
+		be built for all targets, and it is currently the most deblobbed
+		(closest to full source) Magnetite config.
+
+All 3 of the above configurations have CSD, fax and GPRS enabled, i.e., include
+functionality that will only become exercisable when we build our FCDEV3B and
+is dead weight until then, while we limp along with the currently available
+hardware.  We will need to deblob more of L1 (the l1audio and l1tm modules for
+which we currently still use the original object blobs) before we can try
+building a functionally reduced configuration that would be more appropriate
+for the feeble hardware targets.
+
+The deblobbing of L1 has been done in a very meticulous manner, ensuring that
+each individual reconstructed C module compiles into a strict functional
+equivalent of the original binary blob, sometimes even matching bit for bit -
+thus no regressions are expected with the classic->l1reconst transition, and no
+extensive testing is deemed necessary beyond the basic tests that have already
+been done.  However, the transition from l1reconst to hybrid involves wholesale
+replacement of two major firmware components (G23M PS and ACI) and some
+important associated support pieces with entirely different versions from a
+different TI program, hence extensive testing and debugging will be needed.
+
+So far the most-deblobbed hybrid config looks very promising: after fixing the
+hideous bug resulting from the addition of A5/3 support in TCS3.2 (hardware
+feature available on LoCosto but not on Calypso), voice calls work perfectly,
+both with the legacy codecs and with AMR!  (The same A5/3 bugfix has also been
+applied to our Citrine fw, hence the latter now has working voice calls too.)
+However, it is almost certain that there are a ton of minor bugs which need to
+be shaken out, hence this firmware build config should be treated as
+experimental for the time being, not production.  My plan is to work on shaking
+out the minor bugs and bringing this hybrid fw to production quality after we
+build the proper hardware platform for it, i.e., the FCDEV3B.