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 driver officially endorsed by TI for the TCS211 program (LCC
for "low cost" unregulated chargers) is not appropriate for phones that use
simple charging circuits and regulated +5 VDC charging power sources (USB or
Motorola's C1xx charging adapters), and TI's older PWR battery management
driver (TI totally removed it from TCS211, but we pulled it from the older
MV100 source fragments) is bitrotten and just generally broken.

In FreeCalypso we have developed our own battery charging and discharge
monitoring driver (FCHG) that works on Mot C1xx and Pirelli DP-L10 phones in
the "voice pseudo-modem" configuration (see doc/Voice-pseudo-modem), but we
still have the problem of the UI, namely, the lack of one that is practically
usable.

Because TI were in the business of making and selling chipsets rather than
complete phones, proper phone UI development was something they left to their
customers, and they provided only a very rough proof of concept implementation.
One difficulty which we face most immediately in our effort to turn this PoC UI
implementation into a practically usable one is the lack of support for our
desired target display sizes.  Because TI apparently did not want to become
significantly involved in phone UI development, they did not provide a selection
of UI layouts for different LCD sizes; instead at each given point in TI's
history they only supported one display size - whatever their current
development platform at each moment had on it.

At the time of TCS211, TI's primary development platform was called D-Sample;
it consisted of a development board with the Calypso+Iota chipset on it (as
well as a GSM RF section based on their older Clara RF transceiver chip) plus
an attached test handset.  Here are some pictures:

https://www.freecalypso.org/members/falcon/pictures/D-Sample/

The handset part of the D-Sample kit contains a 176x220 pixel color LCD, a
21-button main keypad just like on Mot C1xx and Pirelli DP-L10 phones, and 3
side buttons that almost match Pirelli's.  This D-Sample was the main
development platform for the entire TCS211 program (basically everything except
the small parts specific to Rita RF for which they had their other Leonardo
development boards), including the UI - the latter was made to target the
176x220 pix LCD size on the D-Sample.

I (Mychaela) have managed to obtain one of these historical D-Sample kits (the
one pictured) back in 2015, and I have a strong desire to get the TCS211 PoC UI
up and running in its native 176x220 pixel size.  However, the big difficulty
with getting our FC Magnetite firmware running on the original D-Sample board
(which, remember, is the original and most native hw target for TCS211!) is
that the D-Sample has Clara RF, not Rita, and we only got a stripped semi-src
version of TCS211 in which the *.c files for L1 were censored out and only
*.obj blobs were supplied instead.  The latter blobs target Rita RF and not
Clara.  We have now successfully reconstructed the lost C sources for the RF-
independent and Rita-specific L1 modules, and we have l1_rf10.c for Clara RF
from the MV100 source fragments, but we are still missing the tpudrv10.c module
which is also required for Clara RF.

Back in 2015 (when I first got this D-Sample kit) running our own firmware on
this historical board with an older version of the Calypso chip and with Clara
RF was absolutely out of the question, but since then we have made enormous
progress with our complete deblobbing of L1 and the init module and with our
FC Magnetite build system, and now that tpudrv10 module is literally the only
missing piece.  Given these new circumstances, I plan on making some serious
effort to locate the TPU driver code in the ancient 20020917 fw image that came
with our DS board, and attempt to reconstruct the needed tpudrv10 code from
that.

We also have a fallback plan: if we are not able to get our FC Magnetite
firmware running on the historical TI-made D-Sample board, there is another way
to get TI's TCS211 UI code running in its original 176x220 pixel size, albeit
one that will require a lot of time, effort and expense: design and build our
own UI development board to take the place of TI's D-Sample, combining the good
version of the Calypso+Iota+Rita chipset for which we have good fw support with
a 176x220 pix color LCD of our own - it is one of the industry standard sizes,
so it should only be a matter of getting a semi-custom one with the right
interface (16-bit parallel) and the right polarizer orientation (6 o'clock
viewing direction).  The proposed board would be a derivative of our current
FCDEV3B, keeping the core Calypso+RF block (originally from Openmoko) completely
unchanged, but adding the LCD, the keypad buttons and other handset peripherals,
resulting in a Handset Motherboard Prototype - HSMBP.

Once we get TI's TCS211 UI running in its original 176x220 pixel size like it
once ran in TI's own software development labs back in The Day, whether we do
it by way of TI's original DS board or our own HSMBP, the next step will be to
migrate it to the TCS2/TCS3 hybrid config, using the new versions of G23M PS
and ACI components.  It will also be worthwhile to see if the new version of
this BMI+MFW code in the LoCosto version is any better than the one we got from
Sotovik.  After these preliminary steps, the UI work can bifurcate:

* On the one hand, it will be worthwhile to produce a size-reduced version of
  the UI that targets a 96x64 pixel LCD instead of 176x220 pix, but still full
  color - thus fitting the LCD on Mot C139/140 phones on which we already run
  our fw very successfully in the "voice pseudo-modem" config.  We would then
  be able to see if a Mot C139 phone running FreeCalypso fw can be a practically
  usable end user phone, albeit a super-low-end one.

* On the other hand, it is my (Mychaela's) strong desire to have our own
  FreeCalypso Libre Dumbphone hardware product; running FC fw on Mot C139 just
  isn't enough to satisfy my ambition.  My choice of LCD size for our own FC
  Libre Dumbphone is 176x220 pix, matching TI's D-Sample, so that the rich UI
  targeting this large LCD size can see the light of day as a real end user
  product, and my planned HSMBP board is envisioned as not only an alternative
  to the D-Sample, but also as the prototype motherboard for our FC Libre
  Dumbphone.

Current state of the firmware
=============================

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 is currently one Magnetite configuration (in the ./configure.sh sense)
that includes the UI layers, called 2092.  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.  We previously had another config
called 2092-pwr that had TI's old PWR battery charging driver included, which
never worked because of severe bitrot - that config has now been dropped as the
regular 2092 config now includes our new and working FCHG battery charging
driver.

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 - but it is there in
anticipation of my idea of running our fw on the original D-Sample board as
described above.

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.

Going forward, the plan is as outlined above - I wish to see this UI code run
in the proper 176x220 pix color display config that once existed in TI's own
development environment before I do anything else to it.  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.

Deblobbing status
=================

The current 2092 config is based on the l1reconst modem config (see the
Modem-configs write-up), i.e., the entire chipsetsw division of the fw
including all of L1 and the init code in main.lib is 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.  My current plan is to work in this direction after we
either get our fw running on the historical D-Sample board or build our own
HSMBP.