--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Sat May 16 07:27:31 2020 +0000
@@ -0,0 +1,92 @@
+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.