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's original version
  of the dev.c table with minor additions by OM and FC, appropriate for
  Tango/Caramel/Luna, for Openmoko GTA0x and for GTM900 modems converted to FC.

  Target name ti26 refers to 26 MHz CLKTCXO input to Calypso, i.e., *not*
  D-Sample - see below.  If we ever get our hands on a D-Sample C035 board or
  some other platform with similar needs, it will be easy to create a ti13
  counterpart.

* 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.  This 2015 aftermarket FFS config persists in FreeCalypso Magnetite
and Selenite firmwares.  However, our newer FC Tourmaline firmware (late 2020)
uses a different aftermarket FFS config on Compal phones with 4 MiB flash,
namely Mot C139, SE J100 and some rare C1xx specimen with 4 MiB flash: the new
aftermarket FFS config is 64x7 (7 sectors of 64 KiB each) at 0x300000.

ffsagent-compal-old.srec is for the old 2015/Magnetite/Selenite aftermarket FFS
config, ffsagent-compal-new.srec is for the new FC Tourmaline aftermarket FFS
config.

No Calypso C05 target support
=============================

The present FFS editor application is a stripped-down derivative of FC Selenite
firmware, still containing Nucleus RTOS, thus it uses interrupts.  Having a
run-from-RAM (or more precisely, independent of flashed fw) application use
interrupts requires having Calypso boot ROM version 0300, which is present only
in Calypso C035 silicon.  (We can still use this ROM for our purpose of
interrupt redirection even if it is disabled on boot like on Compal phones.)
Because of this interrupt handling issue, this FFS editor application is not
available on the Mother's D-Sample C05 board, or any other Calypso C05 target.