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