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.

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

I (Mother Mychaela) feel very strongly that the best way to produce practically
usable end user FreeCalypso firmware for the C139 target would be to do it
together with our own FreeCalypso Libre Dumbphone development, as opposed to
trying to support the C139 to the exclusion of our own FreeCalypso hardware.
Specifically, I propose the following order of steps:

1) First build our own FreeCalypso UI development board, a derivative of the
   FCDEV3B adding a 176x220 pixel color LCD and other miscellany to serve as a
   replacement for TI's D-Sample.

2) Retire the C-Sample UI configuration and our currently implemented C-Sample
   emulation hack on the C139, and start running TI's UI code the way TI's own
   developers ran it on the D-Sample.

3) Change the "small screen" UI layout from 84x48 to 96x64 pixels (from 6 rows
   of 14 characters to 8 rows of 16 characters with TI's existing font), and
   fix the bugs related to displaying this "small screen" (!LSCREEN) UI on a
   physically larger LCD - we would like to display it on our 176x220 pixel UI
   development board.

4) Extend the UI code to allow the possibility of COLOURDISPLAY && !LSCREEN,
   i.e., a small (96x64 pixels) color display like on the C139.  Have this
   96x64 pixel color UI displayed on our 176x220 pixel UI development board.

5) Work on getting the actual UI into shape, keeping the two configurations of
   176x220 pixel color (future FreeCalypso Libre Dumbphone) and 96x64 pixel
   color (Mot C139) as actively supported ones.  Do all development on our
   176x220 pixel UI development board.

6) Once the UI-enabled firmware works decently on our development board in both
   176x220 and 96x64 configurations, add native C139 LCD support (not C-Sample
   emulation) to R2D, adapt Condat's display driver as necessary if we are still
   using it (if we don't find a way to get rid of it by this point), and run
   our 96x64 pixel color UI config on real C139 hardware.  At this point we
   should have practically usable end user FreeCalypso fw on the C139.

7) While the less demanding and more casual phone users will be happy with the
   feeble C139 if it runs our FreeCalypso fw, those of us who desire the
   Ultimate Awesome Libre Dumbphone will be able to take our 176x220 pixel UI
   development board and start turning it into an actual FreeCalypso Libre
   Dumbphone handset.  This will be the point when we can move the ringtone
   output from the piezo buzzer to the loudspeaker (Melody E1) and start making
   other changes for better-than-C139 hardware.

Of course the biggest difficulty with the above plan is that it requires
designing and building a new piece of hardware as its very first critical step.
My personal plan is to kill two birds with one stone: design the board in such
a way that it can be used both as a development board for the above plan and as
a close-to-final prototype for my desired FC Libre Dumbphone handset - although
not completely final, as this board would absolutely need to be usable in its
bare form on a lab bench without plastics, which calls for a somewhat different
design than a final handset product.

Anyone who disagrees with my approach, anyone who is against designing and
building new custom hardware at high cost and who is instead interested first
and foremost in pre-existing hardware targets like Mot C139 is more than welcome
to delve into the code themselves and try their own hand at fixing the code to
make it practically usable on the C139.  However, I have to warn you: if you
spend a significant amount of time working with TI's code and develop an
affection for it, it is quite possible that you will start to feel the way I do
in terms of desiring a D-Sample-like platform for development.

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.