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 and the init code in main.lib are
fully 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.