FreeCalypso > hg > ffs-editor

comparison README @ 20:49bd6136f4a9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
README added
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 16 May 2020 07:27:31 +0000
parents
children 5dd2fa1d3da1
comparison
equal deleted inserted replaced
19:399779c700da 20:49bd6136f4a9
1 FFS editor operated via fc-xram
2 ===============================
3
4 The software article presented in this repository is a tool for operating on
5 the flash file system (FFS) of Calypso devices running FreeCalypso firmware.
6 Before explaining the tool itself, I need to explain why it is needed.
7
8 Every FC firmware version includes our TI-based FFS implementation and maintains
9 an FFS instance in device flash memory; the standard way to operate on this FFS
10 is by way of our fc-fsio utility communicating with the running firmware over
11 its RVT/ETM interface. With our AT-command-controlled modem firmwares, most of
12 the time the modem fw itself is the only agent that actually operates on the
13 FFS: if you need to perform low-level FFS operations such as formatting, simply
14 boot the firmware normally, but don't give it any AT commands, and instead poke
15 at it with fc-fsio. But when we start building firmware versions with handset
16 UI layers included, relying on the firmware itself as the sole FFS operating
17 agent becomes problematic: these UI-enabled firmwares launch into complex
18 high-level operations immediately upon boot, and it can be very desirable to be
19 able to get the FFS into a certain shape *before* the main firmware is allowed
20 to boot with it.
21
22 The tool presented in this repository is intended to be a solution to this
23 problem. The present FFS editor is a very heavily stripped-down derivative of
24 our FC Selenite firmware, stripped heavily enough to fit entirely into RAM on
25 all of our targets, even the smallest Mot C11x. This FFS editor "firmware"
26 does not include any GSM functionality - no L1, no G23M PS and no ACI - and GPF
27 has been removed as well. The only fw components left are Nucleus, Riviera
28 (which is totally indepedent of GPF in our TCS211-based architecture), RVT (the
29 component which manages the RVTMUX UART interface to which we interface via
30 rvinterf), ETM (the component to which fc-tmsh and fc-fsio talk) and FFS, the
31 primary component of interest to us here. This FFS editor "firmware" is
32 compiled with gcc (Selenite-based), and is built only into a RAM-loadable image
33 to be run via fc-xram, no flashable images.
34
35 The intended usage model is that you run this FFS editor like this:
36
37 fc-xram -h mytarget /dev/ttyXXX ffsagent-XXX.srec rvinterf
38
39 Cause the Calypso device to execute its boot path, fc-xram will load and run
40 the ffsagent image, and pass the serial channel to rvinterf - then you will
41 have rvinterf running on your host, talking to ffsagent running on the Calypso.
42 The FFS editor "firmware" does nothing other than emit a few RV traces and
43 listen for ETM command packets, and at this point you run fc-fsio to talk to
44 this FFS agent and perform whatever FFS manipulations are needed. fc-tmsh can
45 also be used to read and write both Calypso and ABB registers.
46
47 When you are done with the needed fc-fsio manipulations, you can command a Iota
48 power-off on the target with fc-shell poweroff (sends an ETM ABB register write
49 command hitting VRPCDEV), or you can kill rvinterf or unplug the serial cable
50 and let ffsagent on the target power off in 15 to 20 s upon keepalive timeout.
51 Or you can press the RESET button on the board (FCDEV3B or Caramel) and cause
52 the flashed firmware to boot. (Powering off by pressing and holding PWON won't
53 work because the heavily stripped FFS editor "firmware" does not include the
54 regular firmware's ABB interrupt handling code path.) In any case, when the
55 flashed fw does boot, it will boot with the FFS content in whatever state you
56 brought it to with ffsagent and fc-fsio, which is the whole point of the
57 exercise.
58
59 Supported targets
60 =================
61
62 The present FFS editor is intended to run only on those Calypso targets which
63 run one of our full FreeCalypso GSM firmwares of the Magnetite/Selenite family.
64 More specifically, it is intended to operate on FFS instances that are "owned"
65 by flashed FreeCalypso firmwares, *not* on FFS instances that are owned by
66 someone else's firmware. There is no mechanism for explicitly specifying FFS
67 location and geometry at a user level, as would be needed for operating on
68 arbitrary alien FFS instances, instead the FFS editor includes exactly the same
69 dev.c table of FFS configurations as our production firmwares. The few
70 different ffsagent build variants that are provided (run ./make-all.sh to
71 compile all of them) differ in which dev.c table is included, exactly the same
72 as in our production firmwares:
73
74 * ffsagent-fcfam-{irda,modem}.srec version is built with the CONFIG_TARGET_FCFAM
75 version of the dev.c table, appropriate for FCDEV3B.
76
77 * ffsagent-ti26-{irda,modem}.srec version is built with TI/OM's original version
78 of the dev.c table, appropriate for Tango/Caramel/Luna and for Openmoko GTA0x.
79
80 * compal and pirelli versions correspond to FreeCalypso aftermarket FFS configs
81 on those targets, *NOT* Compal's or Pirelli's original FFS!
82
83 compal-new vs. compal-old configs
84 =================================
85
86 Back in 2015 I (Mother Mychaela) made the decision to define FC aftermarket FFS
87 on Mot C139 phones as 64x3 (meaning 3 sectors of 64 KiB each), located at
88 0x3C0000. Right now I am thinking that we should change to a larger FFS config,
89 but I have not yet committed on any specific new config. When and if I make
90 the big switch, compal-new will be the new config, while compal-old will remain
91 the original 2015 config. At the present moment the two ffsagent-compal-*
92 images are identical.