# HG changeset patch # User Mychaela Falconia # Date 1589614051 0 # Node ID 49bd6136f4a923dd0b5db12d078627010988cd2c # Parent 399779c700da472145365344c81be4238f9c7420 README added diff -r 399779c700da -r 49bd6136f4a9 README --- /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.