--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Handset-UI-fw	Mon Oct 08 19:52:50 2018 +0000
@@ -0,0 +1,287 @@
+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.