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 real tpudrv10.c driver code for Clara RF, we are
  running with a disassembly-based reconstruction attempt which is unfortunately
  still broken and non-functional.  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 seconds of 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.

* One can also use a Pirelli DP-L10 phone instead of FCDEV3B.  The long-time
  bug that caused GSM radio functionality to break if it was brought up without
  getting some deep sleep first was fixed in 2019-03, and all GSM radio
  functionality now works just as well on this Pirelli target as it does on our
  native FCDEV3B.  The native 128x128 pixel LCD on this phone remains dark and
  unused for now because it is too small to display TI's 176x220 pixel UI, but
  the present fc-lcdpoll|fc-lcdemu mechanism works just as well on the Pirelli
  as it does on FCDEV3B.  However, the Pirelli phone has a physical keypad that
  has the same repertoire of buttons as D-Sample, and our fw knows and supports
  Pirelli's keypad wiring.  Thus if you run a UI-enabled Magnetite build on the
  Pirelli, you can use the phone's native keypad to drive this UI, but you have
  to use the fc-lcdpoll|fc-lcdemu mechanism to see the display output.

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.  Back in 2018-03 I was thinking about
fixing rvinterf at some point to make its output less voluminous by default,
keeping the human-readable traces, but omitting the rarely-useful hex dumps
from the default output - but now I am thinking of different approaches as
outlined below.

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.

New thoughts as of 2019-12
==========================

While the fc-lcdpoll approach implemented in 2018-03 is much cleaner and much
more workable than the original 2015-09 approach, the update rate of the virtual
LCD is painfully slow, which is why no actual UI development work has been done
yet via this approach.  It needs to be remembered that a 176x220 pixel
framebuffer image with 16 bits per pixel weighs 77440 bytes, while the
theoretical maximum throughput of a Calypso UART at the maximum 812500 baud rate
is 81250 bytes per second - thus even under ideal conditions it will still take
almost a full second to push out a single frame update.  The original 2015-09
approach tried to get close to this theoretical maximum update rate by having
the firmware stream out framebuffer updates continuously, but embedding this
stream within RVTMUX resulted in overwhelming the trace mechanism beyond what
it was meant to handle.

The newer 2018-03 approach avoids overstressing the trace mechanism, but the new
drawback is that the update rate of the virtual LCD got even slower: it now
takes about 4 s to update the virtual LCD window by reading out the firmware's
framebuffer via ETM, thus any UI features (animations, temporary message
pop-ups) that last less than 4 s become lost.  This unacceptable lag in visible
display updates is the main reason why I did not pursue further UI development
work back in 2018 using this mechanism.

If we were to continue down the virtual LCD route as opposed to looking for a
new Calypso platform with a suitable hardware LCD, one possible approach would
be to make use of two fully accessible UARTs on our FCDEV3B as opposed to just
one UART accessible on our previous OM GTA02 and Pirelli DP-L10 platforms.  One
idea would be to keep the IrDA UART for RVTMUX and keep it free from virtual LCD
blit traffic, remove the ASCII AT command channel from the MODEM UART (not
needed for basic handset UI work) and repurpose the MODEM UART for a new ad hoc
interface that would carry just virtual LCD blits and nothing else.  It would be
similar to going back to the original 2015-09 approach, but using a dedicated
UART and thus not loading the RiViera Trace mechanism at all.

However, as of right now (final days of 2019) I (Mother Mychaela) am not looking
at any more virtual LCD approaches because as explained above, even under ideal
conditions we would still have a lag of almost a full second per frame update -
and no real LCD on any real phone or proper development board is that slow.

Instead my view is that the proper solution is to acquire or create a UI
development platform whose LCD subsystem would be no worse than D-Sample.  The
exact arrangement implemented on the DS board is unknown because we have no
schematics or any other hw docs, but the R2D driver in TI's firmware implements
both LCD module configuration writes and actual pixel output by writing 16-bit
words into certain magic addresses in the nCS3 address space, meaning that a
16-bit parallel microprocessor bus write interface is implemented in some
manner.  The 128x128 pixel LCD (also 16-bit color) on the Pirelli DP-L10 is
similarly memory-mapped, with both commands and pixel data written as 16-bit
words into magic addresses on another chip select (nCS4 in Pirelli's case) -
although they have the additional complication of going through that SPCA552E
camera chip which we would much rather not have.

Smaller LCDs on lower-end phones are attached serially, using either uWire or
I2C, but note that the largest serial LCD we have ever seen on a real-life
Calypso phone is the 96x64 pixel 16-bit color LCD on the C139.  Pirelli's
128x128 pixel LCD is already 2.6 times larger in terms of bits per frame, and
it is parallel memory-mapped, not serially interfaced any more.  TI's 176x220
pixel LCD on the D-Sample (also 16-bit color) is another 2.3 times larger than
Pirelli's 128x128, and it is also parallel memory-mapped.  I desire a 176x220
pixel LCD for UI development so I can see TI's original UI in its full glory,
and I feel that interfacing it to the Calypso in any other way than 16-bit
parallel memory-mapped would be substandard: the update rate would be slower
than it was on the original D-Sample, and the user experience with the UI would
no longer be the same as what TI's original developers experienced when they
implemented this UI.

The current situation as of the last days of 2019 is that we are looking to put
together our own FC Luna UI development platform with a memory-mapped parallel-
interfaced 176x220 pixel LCD using a certain historical development board as our
starting point.  Our current hope is to be able to work on this project in the
first half of 2020 once the starting-point hw arrives at the Mother's shop in
California.