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 (original intent)
===================================

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!

Supported targets (more recent additions)
=========================================

The discovery of Sony Ericsson K200/220 phones in late 2022 has created a novel,
not previously envisioned use case for the present FFS editor.  As of this
writing (2023 Winter Solstice), there are no active plans to run FreeCalypso
firmware on these SE K2x0 phones - hence by the principles of the previous
section, this target would not qualify to be supported by the present tool.
However, the FFS used by original/official fw on these phones is a variant of
TIFFS, and there are some corner use cases where it may be desirable to make
some surgical modifications to their FFS outside of the constraints imposed by
the official fw.  This type of use case is an area where the present FFS editor
is the best tool for the job, hence we decided to expand our scope a little
(beyond the original intent) and support a configuration where our ffs-editor
tool operates on an FFS instance that is not owned by FC.

The SE K2x0 version of our FFS editor (ffsagent-se_k2x0.srec) operates on the
original-manuf-defined FFS location on this SE K2x0 hardware target.  If anyone
ever decides to port full FC firmware (beyond the present ffs-editor tool) to
this se_k2x0 target, the Mother's recommendation would be to reuse the same FFS
location.  Unlike the situation on Pirelli DP-L10, the flash structure on SE
K2x0 (the layout of which flash area is used for what in the original/official
design) does not leave an obvious unused place where an aftermarket FFS can be
placed (not conflicting with any aspect of the official fw, FFS or otherwise),
and the different hw design (computer connection does not apply charger-plug
condition to Iota VRPC) eliminates the very peculiar set of issues we have to
deal with on the Pirelli target that led to our design decisions there.

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.