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 in fc-host-tools-r8 or
later, 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.

One currently outstanding defect with this fc-lcdpoll mechanism is that rvinterf
currently prints all ETM packets as full hex dumps, and the flood of all that
hex in the rvinterf window makes that window unusable for its original intended
purpose of seeing other debug output from the fw.  This voluminous rvinterf
output also slows down the rate at which the LCD framebuffer is polled.  One
can run rvinterf with the -n option to suppress its output, but then all other
debug trace output will be lost too.  I plan on fixing rvinterf at some point
in the future to make its output less voluminous by default: keep the human-
readable traces, but omit the rarely-useful hex dumps from the default output.

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, simply add a
TR_BAUD_CONFIG=TR_BAUD_812500 argument to your ./configure.sh line,
and remember to pass the -B812500 option to rvinterf when talking to such
trace-speed-increased firmware.