FFS editor operated via fc-xram
===============================

The software article presented in this repository is a tool for operating on
the flash file system (FFS) of Calypso devices running FreeCalypso firmware.
Before explaining the tool itself, I need to explain why it is needed.

Every FC firmware version includes our TI-based FFS implementation and maintains
an FFS instance in device flash memory; the standard way to operate on this FFS
is by way of our fc-fsio utility communicating with the running firmware over
its RVT/ETM interface.  With our AT-command-controlled modem firmwares, most of
the time the modem fw itself is the only agent that actually operates on the
FFS: if you need to perform low-level FFS operations such as formatting, simply
boot the firmware normally, but don't give it any AT commands, and instead poke
at it with fc-fsio.  But when we start building firmware versions with handset
UI layers included, relying on the firmware itself as the sole FFS operating
agent becomes problematic: these UI-enabled firmwares launch into complex
high-level operations immediately upon boot, and it can be very desirable to be
able to get the FFS into a certain shape *before* the main firmware is allowed
to boot with it.

The tool presented in this repository is intended to be a solution to this
problem.  The present FFS editor is a very heavily stripped-down derivative of
our FC Selenite firmware, stripped heavily enough to fit entirely into RAM on
all of our targets, even the smallest Mot C11x.  This FFS editor "firmware"
does not include any GSM functionality - no L1, no G23M PS and no ACI - and GPF
has been removed as well.  The only fw components left are Nucleus, Riviera
(which is totally indepedent of GPF in our TCS211-based architecture), RVT (the
component which manages the RVTMUX UART interface to which we interface via
rvinterf), ETM (the component to which fc-tmsh and fc-fsio talk) and FFS, the
primary component of interest to us here.  This FFS editor "firmware" is
compiled with gcc (Selenite-based), and is built only into a RAM-loadable image
to be run via fc-xram, no flashable images.

The intended usage model is that you run this FFS editor like this:

fc-xram -h mytarget /dev/ttyXXX ffsagent-XXX.srec rvinterf

Cause the Calypso device to execute its boot path, fc-xram will load and run
the ffsagent image, and pass the serial channel to rvinterf - then you will
have rvinterf running on your host, talking to ffsagent running on the Calypso.
The FFS editor "firmware" does nothing other than emit a few RV traces and
listen for ETM command packets, and at this point you run fc-fsio to talk to
this FFS agent and perform whatever FFS manipulations are needed.  fc-tmsh can
also be used to read and write both Calypso and ABB registers.

When you are done with the needed fc-fsio manipulations, you can command a Iota
power-off on the target with fc-shell poweroff (sends an ETM ABB register write
command hitting VRPCDEV), or you can kill rvinterf or unplug the serial cable
and let ffsagent on the target power off in 15 to 20 s upon keepalive timeout.
Or you can press the RESET button on the board (FCDEV3B or Caramel) and cause
the flashed firmware to boot.  (Powering off by pressing and holding PWON won't
work because the heavily stripped FFS editor "firmware" does not include the
regular firmware's ABB interrupt handling code path.)  In any case, when the
flashed fw does boot, it will boot with the FFS content in whatever state you
brought it to with ffsagent and fc-fsio, which is the whole point of the
exercise.

Supported targets
=================

The present FFS editor is intended to run only on those Calypso targets which
run one of our full FreeCalypso GSM firmwares of the Magnetite/Selenite family.
More specifically, it is intended to operate on FFS instances that are "owned"
by flashed FreeCalypso firmwares, *not* on FFS instances that are owned by
someone else's firmware.  There is no mechanism for explicitly specifying FFS
location and geometry at a user level, as would be needed for operating on
arbitrary alien FFS instances, instead the FFS editor includes exactly the same
dev.c table of FFS configurations as our production firmwares.  The few
different ffsagent build variants that are provided (run ./make-all.sh to
compile all of them) differ in which dev.c table is included, exactly the same
as in our production firmwares:

* ffsagent-fcfam-{irda,modem}.srec version is built with the CONFIG_TARGET_FCFAM
  version of the dev.c table, appropriate for FCDEV3B.

* ffsagent-ti26-{irda,modem}.srec version is built with TI/OM's original version
  of the dev.c table, appropriate for Tango/Caramel/Luna and for Openmoko GTA0x.

* compal and pirelli versions correspond to FreeCalypso aftermarket FFS configs
  on those targets, *NOT* Compal's or Pirelli's original FFS!

compal-new vs. compal-old configs
=================================

Back in 2015 I (Mother Mychaela) made the decision to define FC aftermarket FFS
on Mot C139 phones as 64x3 (meaning 3 sectors of 64 KiB each), located at
0x3C0000.  Right now I am thinking that we should change to a larger FFS config,
but I have not yet committed on any specific new config.  When and if I make
the big switch, compal-new will be the new config, while compal-old will remain
the original 2015 config.  At the present moment the two ffsagent-compal-*
images are identical.