--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Fri Mar 16 03:50:38 2018 +0000
@@ -0,0 +1,145 @@
+This repository contains a couple of hack-utilities that have been developed as
+attempts at displaying TI's 176x220 pixel demo/prototype phone UI on an external
+development host in the absence of a suitable Calypso target device with an LCD
+of the needed large size.  Two approaches have been tried, separated in time by
+about 2.5 y:
+
+2015-09 approach
+================
+
+A year before FreeCalypso Magnetite, when all we had was the TCS211 semi-src
+from Sotovik with its original all-Windows build system, with all of the blobs
+intact and no apparent hope of deblobbing, plus our first attempt at bottom-up
+GSM fw with completely broken L1, we had built two hacked-up versions of TI's
+TCS211 fw with TI's 176x220 pixel UI enabled: one running on the GTA02 modem,
+the other running on the Pirelli DP-L10.  Both were hacked up to emit raster
+blits of the big 176x220 pix, 16 bits per pixel color UI on the RVTMUX serial
+channel, running at Calypso's maximum baud rate of 812500 bps.  These hacks
+have not been touched since 2015-09, but they can still be found in the
+historical leo2moko-debug and tcs211-pirelli Hg repositories on Bitbucket.
+
+A host utility named fc-lcdemu had been written to display these LCD blits
+emitted by those hacked-up firmwares.  It receives these blits via a pipe from
+rvinterf and displays them in an X11 window; it thus naturally requires libX11
+to compile and an X11 display to run.  X11 programming is a black art which
+this author (Mychaela Falconia) once knew but now largely forgot, hence
+fc-lcdemu was based on the HECterm project (an xterm-like terminal application
+for X11) by the same author, but from a much earlier life phase.
+
+If you wish to resurrect and play with one of these external LCD output hacks
+from 2015-09, you will need to invoke rvinterf with special arguments to tell
+it to launch fc-lcdemu and to pass the LCD blits to it; the synopsis is as
+follows:
+
+rvinterf -B812500 -X fc-lcdemu /dev/ttyXXX
+
+The -B812500 argument is needed to tell rvinterf to use this high baud rate,
+and the -X option tells rvinterf to invoke the following named program (can be
+a more complex shell command) with popen(3) and then feed it LCD blits received
+from the target.  If you use the new version of rvinterf that is about to be
+released with fc-host-tools-r8, the old -v option is no longer needed and no
+longer accepted.
+
+This 2015-09 approach was putting a huge load on the RiViera Trace mechanism,
+hacks were required in the firmware to massively super-size the memory space
+allotted to RVT and to run the RVTMUX serial channel at 812500 baud, and even
+with the supersized memory allocation and the maximum serial baud rate there
+were still some 'Lost Message' traces.  The hacks on the firmware side which
+implement this 2015-09 approach have NOT been included in our current Magnetite
+firmware.
+
+2018-03 approach
+================
+
+Rivisiting the phone UI subproject of FreeCalypso in 2018, I got another idea
+for how to get the LCD framebuffer bits out of a Calypso device: instead of
+having the firmware push them out to the trace buffer every time r2d_refresh()
+is called, have the fw do nothing, and have the external host read the
+framebuffer memory out at its own pace via ETM memory read commands.  The new
+fc-lcdpoll utility implements this approach; in order to avoid having to reopen
+the X11 can of worms, I made fc-lcdpoll output the blits in the form which the
+already-existing fc-lcdemu code from 2015 takes as input, so you run a pipeline
+like this:
+
+fc-lcdpoll framebuffer_base_addr | fc-lcdemu
+
+fc-lcdpoll connects to rvinterf as a regular client, thus you would typically
+have rvinterf running already when you run the above pipeline in another window.
+fc-lcdpoll needs to know the address of the in-RAM framebuffer maintained by
+the R2D firmware component, and this address needs to be given on the command
+line.  You can find it by grepping the linker-generated map file (fwimage.map
+or ramimage.map as appropriate) for the _r2d_lcd_memory_words symbol.
+
+This new approach works with current FC Magnetite firmware, and has been tested
+in a few different ways:
+
+* We have a real TI-made D-Sample board and we can run our Magnetite firmware
+  on it, but lacking the tpudrv10 driver code for Clara RF, we are running with
+  a non-functional placeholder stub for the TPU driver.  The D-Sample board thus
+  has no GSM radio functionality when running our fw, and the firmware can only
+  do what any regular phone would do in an area with zero coverage: limited to
+  stepping through menus and examining SIM phonebook entries and stored
+  messages.  The physical LCD output works, but is often garbled due to what
+  appears to be a hardware problem.  Running fc-lcdpoll|fc-lcdemu against this
+  setup results in the virtual LCD mirroring the physical one, albeit with some
+  lag, and the virtual LCD shows what the physical one *should* display if it
+  weren't garbled.
+
+* One can run a UI-enabled Magnetite build on our FCDEV3B modem board and use
+  the fc-lcdpoll|fc-lcdemu pipe to display what the fw puts in the framebuffer.
+  Unlike the D-Sample, our FCDEV3B has perfectly working GSM radio, thus this
+  setup allows us to see the behaviour of the UI firmware with a working radio
+  and thus a working GSM network connection underneath.  By calling the number
+  of the SIM inserted into this setup, one can see the incoming call screen
+  followed by the missed call indication.  Because there is no physical keypad
+  on the FCDEV3B, it appears at first that the show stops here with no way to
+  feed keypresses to the firmware, but TI's firmware does have a mechanism for
+  sending simulated keystrokes via RVTMUX encoded in GPF system primitives, and
+  we have recently figured out how to use it.  Our fc-shell utility now offers
+  the new key command for sending such simulated keypresses to the target, and
+  by combining this key entry mechanism with the present fc-lcdpoll|fc-lcdemu
+  display viewing mechanism, we've been able to exercise the UI a little
+  further.  This approach definitely shows some promise.
+
+* The Pirelli DP-L10 target has also been tried.  I was hoping that it would
+  make a good platform by virtue of having a working GSM radio (unlike the
+  D-Sample sans tpudrv10 code) and a physical keypad that is just like the
+  one on the D-Sample, but no joy.  When running FreeCalypso on Pirelli's alien
+  hardware, among many other issues that kill any possibility of turning this
+  alien hw into a libre phone, we get this one highly bizarre misbehaviour for
+  which we have absolutely no explanation: the radio works OK *only if* the
+  firmware is built with deep sleep enabled in CST (i.e., enabled by default on
+  boot), and the Calypso gets to do some deep sleeps prior to the operator
+  manually bringing it up with AT commands.  If deep sleep is disabled, as soon
+  as you try to bring the radio up, the Calypso DSP falls over with errors
+  which we naturally have no way of debugging.  The most recent experiment has
+  revealed that this same DSP death behaviour (resulting in no working GSM
+  radio) occurs even when deep sleep is enabled if the firmware is built in the
+  MFW configuration (UI layers included) - as the UI layers command the radio
+  bring-up immediately on boot, the DSP falls over.  Thus we are rudely reminded
+  once more than the Pirelli target is a dead end.
+
+Baud rate considerations
+========================
+
+The ETM memory read approach implemented in fc-lcdpoll is a lock-step, one read
+transaction at a time mechanism, not a continuous unstoppable stream of data
+like the original 2015-09 approach - therefore, it does not impose any load on
+the firmware's trace buffers, and it can work with RVTMUX running at any baud
+rate, even plain 115200.  However, the slower the RVTMUX serial channel runs,
+the slower will the virtual LCD update, hence running the serial line at 812500
+baud is still preferable.  To change the RVTMUX serial baud rate from 115200 bps
+to 812500 bps in your Magnetite firmware build, follow these steps:
+
+* Run ./configure.sh like you normally would, selecting the UI-enabled config
+  of interest for your target.
+
+* Go into the build directory, and before running 'make', edit
+  config/swconfig.cfg - it is one of the config headers generated by the
+  configure.sh process.  In that configuration header file, change the
+  TR_BAUD_CONFIG setting from TR_BAUD_115200 to TR_BAUD_812500.
+
+* Run 'make' or 'make ram' as desired after editing the swconfig.cfg header.
+
+And of course remember to pass the -B812500 option to rvinterf when talking to
+such trace-speed-increased firmware.