--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Handset-goal	Fri Jan 12 01:39:11 2018 +0000
@@ -0,0 +1,194 @@
+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.