The present article is a companion to the TCS211 firmware architecture document
(TCS211-fw-arch).  Those who are interested in the FreeCalypso phone handset
goal (which is currently a very distant goal) should read the TCS211-fw-arch
document first and then this article, whereas those who are more interested in
the rock solid FreeCalypso modem (as opposed to handset) solution which is
already available today and would like to understand our modem fw better only
need to read the TCS211-fw-arch document and can safely skip this handset UI
addendum.

TI's offerings for handset UI
=============================

Unlike their rock solid, full commercial product offering for AT-command-
controlled modems, TI never produced a reference phone handset firmware
implementation that could be used as-is with minimal or no changes: instead
they provided a very rough proof-of-concept implementation which is nowhere
close to usable, and left it up to their customers (handset manufacturers) to
whip it into even a minimally decent shape.  Furthermore, they had several
different approaches over the years to what the GSM industry calls by the
sexist term "MMI":

* They once had something called SMI, for "simple MMI" or "slim MMI".  We have
  what appears to be the complete source for this SMI component as part of the
  MV100-0.1.rar and 94140216gsm.rar finds, but both of those finds are just
  broken fragments, not a complete firmware for any target.  It might be
  possible to integrate this unknown-origin SMI source into Magnetite and get
  it to work with the TCS2 version of ACI, but no such feat has been attempted
  yet - it would be a mere curiosity, not something for practical use.

* SMI later gave way to a successor called BMI for "basic MMI", which is much
  bigger in terms of code size and complexity and consists of two layers: there
  is a layer called MFW (mobile framework) that sits on top of ACI, and then
  BMI proper sits on top of MFW.  This incarnation of TI's demo/prototype phone
  UI is the one which they officially supported in the TCS211 program, and our
  copy of TCS211 from OM miraculously has these BMI+MFW sources included, even
  though OM obviously didn't use this code and could not even compile it without
  doing some surgery on the build system.  Our other TCS3.2/LoCosto source also
  has BMI and MFW matching that newer version of G23M ACI and PS components,
  and we use this new TCS3 version of BMI+MFW in our TCS2/TCS3 hybrid config.

* It appears that TI once had or were trying to develop some kind of Riviera-
  based "MMI" code as an alternative to the Condat-based SMI and BMI.  SMI and
  BMI+MFW execute in the same "MMI" GPF task as ACI and communicate with it
  through direct function calls; in contrast, the alternative Riviera MMI would
  run somewhere in Riviera land and communicate with ACI through ATP and some
  kind of ACI adapter.  We never got any of this code, and it is not clear if
  it was ever a reality beyond just the idea.

In any case, it is clear from the code that TI's SSA group in France who
developed the drivers for various Calypso chipset peripherals including LCDs,
keypads and ringing buzzers on their development boards and the Condat UK group
who did SMI and BMI had very different visions and ideas.  Some examples:

* The Calypso DSP has a built-in mechanism for playing quite pleasant-sounding
  ringtone melodies through a loudspeaker driven by the chipset's ABB, and the
  SSA group developed their RiViera Audio Service front-end to these L1+DSP
  audio services, but Condat's code makes absolutely minimal use of this RV
  Audio Service, just enough to be compatible with it, and does not use any of
  the melody functions, neither E1 nor E2.

* In the original TCS211 architecture before LoCosto changes, the driver for
  the physical LCD was/is R2D in the Riviera/SSA land.  R2D provides a very rich
  set of text and graphics drawing primitives, but Condat's display layer does
  not use any of them: instead they obtain the raw framebuffer address from R2D
  and do all drawing operations themselves.

* The TCS211 code we got had a jaw-dropping bug in the code path for ringing
  the piezoelectric buzzer: due to a miscommunication between the French folks
  in charge of the actual buzzer driver in chipsetsw and the German or UK folks
  in charge of Condat's audio layer, the buzzer always rang at some 99 Hz (its
  lowest possible frequency, horrible on ears) no matter what tone frequency
  was intended.  Given that our copy of TCS211 dates from 2007 and considering
  how old the buzzer function must be, it hurts to think for how many years
  that bug sat there without anyone wondering why ringing sounds so horrible.

In terms of the code architecture, none of Condat's UI code ever calls any of
the actual drivers in the SSA realm directly: instead everything goes through
the Condat drivers layer in condat/com/src/driver, and that layer provides a
very poor adaptation as highlighted above.

LCD support
===========

TI's demo/prototype UI code never supported a wide variety of different display
sizes or keypad layouts - instead they only supported whatever existed on their
in-house development boards at each given point in their history.  TI's C-Sample
and earlier development boards had 84x48 pixel B&W displays, whereas from
D-Sample onward they made the big jump to a 176x220 pixel color LCD.  Both
versions of the UI we got (TCS211 targeting D-Sample and TCS3.2 targeting
I-Sample, TI's LoCosto board) were developed on 176x220 pixel color LCD
platforms, and that is the only display size which they intended to support.
There also exists a remnant of support for their earlier 84x48 pixel C-Sample
LCD, which we resurrected in FreeCalypso to see it run on Mot C139 hardware,
but that support was broken: it would not even compile without our fixes.  In
our current FC Magnetite firmware we can build this C-Sample UI version for the
C139 target and it works in the demo / proof-of-concept sense, but it is likely
to be even more broken than the official 176x220 pixel version.

Anyone interested in adding support for a different LCD will need to start with
the R2D driver under src/cs/drivers/drv_app/r2d.  The principal LCD type
selection is done in r2d_config.h (C-Sample and D-Sample are the only options
supported by the version we got with TCS211), and this selection affects all of
R2D and all of its clients.  Our change to this r2d_config.h LCD type selection
logic consists of selecting C-Sample instead of D-Sample when the build target
is C139.  A secondary selection is made in r2d_inits.c and r2d_refresh.c where
the code snippets for the actual hardware initialization and output are
included: the way we currently support the C139 hw target is a very thorough
emulation of the C-Sample including its vertical B&W framebuffer format, all of
the code in R2D and in Condat's display driver sees a real C-Sample LCD, and
only the hardware-poking code is substituted.

The direct implication of our C-Sample emulation approach for the C139 LCD is
that the full 96x64 pixel size of Motorola's LCD becomes completely
inaccessible, and all software sees a 84x48 pixel subset.  The same happens
with color: because TI's C-Sample LCD was B&W, the color capabilities of the
real C139 LCD become inaccessible.  Anyone who wishes to fix this shortcoming
would need to implement a new bona fide LCD type in R2D, and then adapt
Condat's display driver accordingly.

Condat's display driver (condat/com/src/driver/display.c) is very messy and
very difficult to understand.  The only change we have made to it in FreeCalypso
was fixing the support for the C-Sample LCD which was bitrotten: the bitrot and
our fix for it is not specific to the C139, it would affect a real C-Sample
board just as well.  Understanding this code well enough to extend it to other
LCD geometries and framebuffer formats would be a much greater challenge.

Above Condat's display driver lies the actual UI implementation in BMI and MFW.
This UI code supports only 3 possible configurations:

* Both COLOURDISPLAY and LSCREEN defined: the display is 176x220 color;

* LSCREEN is defined but not COLOURDISPLAY: the display is 176x220 B&W - TI
  used this config when building "GSM Lite" fw for the D-Sample;

* Neither LSCREEN nor COLOURDISPLAY defined: the old 84x48 pixel B&W UI from
  the days of C-Sample and earlier.

Note the lack of support for small color displays like the one on the C139.

Text fonts
----------

The SSA group's R2D driver provides text display functions and contains its own
fonts, but Condat's stuff does not use those display functions or fonts -
instead BMI and MFW (and presumably SMI too) use a different font/text
implementation contained in the Condat drivers layer.

Keypad support
==============
 
The hardware keypad driver is KPD in Riviera/SSA land, residing in
chipsetsw/drivers/drv_app/kpd in TCS211 or in src/cs/drivers/drv_app/kpd in
Magnetite and Selenite.  Unlike the display driver R2D, KPD is always included
even in modem firmware builds - but if there is no keypad connected to the
Calypso, it does nothing.  TI's firmware architecture and UI code support only
traditional numeric keypads - there is no provision for supporting a full QWERTY
keyboard.  However, if the keypad layout on a given phone handset is close
enough to what TI had on their development boards, modifying KPD for the
specific wiring is very easy: we have already added proper support for Mot C1xx
and Pirelli DP-L10 keypads.

Battery monitoring and charging
===============================

TI had two incarnations of their battery charging and monitoring driver: first
PWR, then LCC.  Both were implemented in Riviera/SSA land.  LCC was not a good
fit for our targets of interest (Mot C1xx, Pirelli DP-L10 and our desired
FreeCalypso Libre Dumbphone hardware) while PWR had other problems, so we
retired both of them and wrote our own replacement called FCHG.

There is a quirk, however: there is no connection in the TCS211 code as
delivered by TI between their demo/prototype UI (or rather between Condat's
power driver stub) and either of their battery driver implementations.  At the
time of TCS211-2007 the original PWR driver had already been retired and only
LCC was supported, but even that LCC driver had no connection to the UI: one
could remove it from the fw build configuration and the UI code would still
compile and link just fine, which would not be possible if there were any calls
to LCC's API functions.  The practical effect of this quirk is that there is no
need to resurrect PWR or LCC in order to run TI's UI code in its pristine
original form - using our own FCHG or no battery management driver at all is
just as fine.

FreeCalypso Luna handset UI development platform
================================================

As of 2020 we have a new hardware platform for running UI-enabled firmware
configurations; this development platform is codenamed FC Luna.  Our FC Luna
platform consists of a 176x220 pixel LCD (TFT color) and a 5x5 keypad connected
to a Calypso core; the key feature is that the LCD size (176x220 pix), color
depth (16 bits) and interface to Calypso (16-bit parallel with memory-mapped
registers) are exactly the same as on TI's D-Sample.  This FC Luna platform is
supported in FC Magnetite, and it finally allows us to run TI's handset UI code
in its native form.  We can run all of the same configurations which existed in
TI's original TCS211 fw on TI's original D-Sample platform:

* The default configuration is 176x220 pixel UI with full color - this is the
  config which TI actually supported in TCS211 days.

* Setting UI_CONFIG=bigbw (switching UI code config) and optionally
  DSAMPLE_FULL_COLOR=0 (switching R2D driver config) produces TI's 176x220 pixel
  black&white configuration.  This config is not particularly interesting: any
  practical phone LCD of this large size is also going to be color, thus it is
  better to use the full color config for this large size instead.  For this
  reason whatever bugs are specific to this 176x220 pix B&W config (and there
  definitely are some) will be ignored, as there is no point in investigating
  and fixing them.

* Setting UI_CONFIG=84x48 and DSAMPLE_FULL_COLOR=0 produces the same C-Sample
  UI config which we've been running on Mot C139 phones, but without the
  ugliness of emulating C-Sample LCD hw at the driver level - instead in this
  config the small 84x48 pixel UI code runs on top of TI's D-Sample B&W R2D
  driver, with the small UI displayed in the upper left corner of the large
  physical Luna LCD.

Running the UI_CONFIG=84x48 DSAMPLE_FULL_COLOR=0 config on Luna has already
helped shed light on one UI issue that was more elusive when running on C139 hw:
the disappearing time display.  When running this config on Luna, we can see
that the UI code displays a text line with date and time outside of the 84x48
pixel area, i.e., it is a bug in the !LSCREEN configuration - but when we run
with driver-level C-Sample emulation on C139, this misplaced text line is
invisible.

The proper way to get proper support for Mot C139
=================================================

For many years the handset firmware project direction in FreeCalypso had been
blocked by the lack of a D-Sample-like development platform with a 176x220 pixel
LCD.  This blockage has finally been lifted in 2020 with the arrival of our Luna
UI development platform, and now the only lacking factor is developer time and
motivation.  As of this writing (2020-09) I (Mother Mychaela) am not able to
devote any significant time to handset firmware work because I need to focus on
bringing FC Tango and Caramel2 hardware products to market, but once I get past
this current work, I may be able to refocus on handset fw.

When and if I start working again in the handset fw direction, my plan of action
is as follows:

1) Fix the most obvious bugs like the misplaced text line in the small UI config
   while staying in the Magnetite source tree, but working only in the hybrid UI
   code base - the old TCS2 version of BMI+MFW that sits on top of a blobs-only
   old version of G23M PS will not be carried forward.

2) Create a new firmware source tree based on Magnetite that keeps only the
   hybrid config with old clutter removed, allowing bolder changes going
   forward.

3) Drop the driver-level C-Sample LCD emulation approach, and instead implement
   a 96x64 pixel B&W logical framebuffer config in R2D.  Display this logical
   96x64 pix B&W framebuffer on both Luna and C139 physical LCDs.  In both cases
   the physical LCD color capability will remain unutilized, with all display
   images being black&white, but so be it.

4) Immediately after the previous step the 84x48 pixel UI will appear in the
   upper left corner of the 96x64 pixel B&W display, with the rightmost 12 and
   bottommost 16 pixels remaining unused.

5) Drop the 176x220 pixel B&W UI config, leaving only large (176x220 pix) color
   and "small B&W".  Remove code stanzas specific to the
   (LSCREEN && !COLOURDISPLAY) combination, and outside of that eliminated
   combination, make all conditionals based on LSCREEN and not COLOURDISPLAY.

6) Extend the "small B&W" UI config from 84x48 to 96x64 pixels, i.e., from 6
   rows of 14 characters to 8 rows of 16 characters with TI's existing font.

7) With the above gymnastics out of the way, work on whipping the actual phone
   UI into shape, supporting two configurations: large color and small B&W,
   with Luna hw platform supporting both configs, whereas the small B&W config
   will also run on C139 hw.

It should be noted that this approach does NOT include any implementation of
color UI for the small LCD size on Mot C139 and similar low-end platforms.  As
the plan stands currently, this omission is intentional and is part of effort
minimization: I need to put some limits on the amount of time and effort I
invest into project directions that are specific to low-end phones, i.e.,
project directions that are intrinsically less worthy than my desired
FreeCalypso Libre Dumbphone as in FreeCalypso handset hardware.

Why Mot C139?
=============

Out of the known repertoire of pre-existing Calypso-based phones whose existence
has been discovered by OsmocomBB and for which we already have some foundations
of support in FreeCalypso, Mot C139 is the most suitable one for the purpose of
turning it into a Libre Dumbphone by way of aftermarket firmware.  Here are the
problems with the other ones:

* Pirelli DP-L10 is my absolute favourite with an end user hat on, but the
  unwanted extra chips for the unwanted-for-us WLAN and camera functionality
  are a killer.  There are no schematics for the phone and no documentation for
  any of these chips, and we don't know how to power them down.  In a fully
  quiescent state with all Calypso sleep modes enabled and with both LCD and
  keypad backlights off, the board still draws about 87 mA from the battery,
  which will kill a fully charged battery in about 10 hours of complete idle.
  Furthermore, it is not possible to turn on the loudspeaker without going
  through the W56940 ringtone chip, and the reset line for this chip comes from
  a GPIO on the completely undocumented camera chip - thus without a way to
  control this reset line we may not be able to program the W56940, and without
  that programming we may not be able to turn on the loudspeaker, ruining all
  usefulness of this phone.

* Mot C11x/12x family is good in terms of not having any undocumented hardware,
  but the tiny RAM capacity is a bummer.  These lowest-end phones have only
  256 KiB of IRAM (Calypso internal RAM) and 256 KiB of XRAM (board-level RAM),
  whereas the next-step-up C139/140 has 512 KiB of XRAM.  It is a significant
  difference for us: while we fit into C139's 512 KiB with no sweat, it would
  require some very unpleasant and unrewarding work to trim the fat and
  reshuffle our memory usage to fit into the 256+256 arrangement on C11x.
  Furthermore, most C11x/12x phones have only 2 MiB of flash, which would again
  require major contortions to fit into, whereas all C139/140 phones have 4 MiB.

* Mot C155/156 seem nice, but there is a problem: these phones ring with a
  loudspeaker driven by a ringtone generator chip instead of a piezo buzzer
  driven by the Calypso, and their ringtone generator chip is Sunplus SPMA100B.
  No documentation could be found for that chip, and if we can't program it, we
  won't be able to make the phone ring or operate its loudspeaker in any other
  way.  Furthermore, the LCD controller in these phones is much less obvious
  than the one in the C139/140.