FreeCalypso > hg > ffs-editor
annotate README @ 27:cb3f6fe694e1 default tip
README: document SE K2x0 addition
| author | Mychaela Falconia <falcon@freecalypso.org> |
|---|---|
| date | Thu, 21 Dec 2023 21:44:43 +0000 |
| parents | d7740787396c |
| children |
| rev | line source |
|---|---|
| 20 | 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 | |
|
27
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
59 Supported targets (original intent) |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
60 =================================== |
| 20 | 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 | |
|
21
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
77 * ffsagent-ti26-{irda,modem}.srec version is built with TI's original version |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
78 of the dev.c table with minor additions by OM and FC, appropriate for |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
79 Tango/Caramel/Luna, for Openmoko GTA0x and for GTM900 modems converted to FC. |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
80 |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
81 Target name ti26 refers to 26 MHz CLKTCXO input to Calypso, i.e., *not* |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
82 D-Sample - see below. If we ever get our hands on a D-Sample C035 board or |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
83 some other platform with similar needs, it will be easy to create a ti13 |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
84 counterpart. |
| 20 | 85 |
| 86 * compal and pirelli versions correspond to FreeCalypso aftermarket FFS configs | |
| 87 on those targets, *NOT* Compal's or Pirelli's original FFS! | |
| 88 | |
|
27
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
89 Supported targets (more recent additions) |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
90 ========================================= |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
91 |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
92 The discovery of Sony Ericsson K200/220 phones in late 2022 has created a novel, |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
93 not previously envisioned use case for the present FFS editor. As of this |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
94 writing (2023 Winter Solstice), there are no active plans to run FreeCalypso |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
95 firmware on these SE K2x0 phones - hence by the principles of the previous |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
96 section, this target would not qualify to be supported by the present tool. |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
97 However, the FFS used by original/official fw on these phones is a variant of |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
98 TIFFS, and there are some corner use cases where it may be desirable to make |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
99 some surgical modifications to their FFS outside of the constraints imposed by |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
100 the official fw. This type of use case is an area where the present FFS editor |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
101 is the best tool for the job, hence we decided to expand our scope a little |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
102 (beyond the original intent) and support a configuration where our ffs-editor |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
103 tool operates on an FFS instance that is not owned by FC. |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
104 |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
105 The SE K2x0 version of our FFS editor (ffsagent-se_k2x0.srec) operates on the |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
106 original-manuf-defined FFS location on this SE K2x0 hardware target. If anyone |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
107 ever decides to port full FC firmware (beyond the present ffs-editor tool) to |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
108 this se_k2x0 target, the Mother's recommendation would be to reuse the same FFS |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
109 location. Unlike the situation on Pirelli DP-L10, the flash structure on SE |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
110 K2x0 (the layout of which flash area is used for what in the original/official |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
111 design) does not leave an obvious unused place where an aftermarket FFS can be |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
112 placed (not conflicting with any aspect of the official fw, FFS or otherwise), |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
113 and the different hw design (computer connection does not apply charger-plug |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
114 condition to Iota VRPC) eliminates the very peculiar set of issues we have to |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
115 deal with on the Pirelli target that led to our design decisions there. |
|
cb3f6fe694e1
README: document SE K2x0 addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
24
diff
changeset
|
116 |
| 20 | 117 compal-new vs. compal-old configs |
| 118 ================================= | |
| 119 | |
| 120 Back in 2015 I (Mother Mychaela) made the decision to define FC aftermarket FFS | |
| 121 on Mot C139 phones as 64x3 (meaning 3 sectors of 64 KiB each), located at | |
|
24
d7740787396c
README: compal-old vs. compal-new distinction is here
Mychaela Falconia <falcon@freecalypso.org>
parents:
21
diff
changeset
|
122 0x3C0000. This 2015 aftermarket FFS config persists in FreeCalypso Magnetite |
|
d7740787396c
README: compal-old vs. compal-new distinction is here
Mychaela Falconia <falcon@freecalypso.org>
parents:
21
diff
changeset
|
123 and Selenite firmwares. However, our newer FC Tourmaline firmware (late 2020) |
|
d7740787396c
README: compal-old vs. compal-new distinction is here
Mychaela Falconia <falcon@freecalypso.org>
parents:
21
diff
changeset
|
124 uses a different aftermarket FFS config on Compal phones with 4 MiB flash, |
|
d7740787396c
README: compal-old vs. compal-new distinction is here
Mychaela Falconia <falcon@freecalypso.org>
parents:
21
diff
changeset
|
125 namely Mot C139, SE J100 and some rare C1xx specimen with 4 MiB flash: the new |
|
d7740787396c
README: compal-old vs. compal-new distinction is here
Mychaela Falconia <falcon@freecalypso.org>
parents:
21
diff
changeset
|
126 aftermarket FFS config is 64x7 (7 sectors of 64 KiB each) at 0x300000. |
|
d7740787396c
README: compal-old vs. compal-new distinction is here
Mychaela Falconia <falcon@freecalypso.org>
parents:
21
diff
changeset
|
127 |
|
d7740787396c
README: compal-old vs. compal-new distinction is here
Mychaela Falconia <falcon@freecalypso.org>
parents:
21
diff
changeset
|
128 ffsagent-compal-old.srec is for the old 2015/Magnetite/Selenite aftermarket FFS |
|
d7740787396c
README: compal-old vs. compal-new distinction is here
Mychaela Falconia <falcon@freecalypso.org>
parents:
21
diff
changeset
|
129 config, ffsagent-compal-new.srec is for the new FC Tourmaline aftermarket FFS |
|
d7740787396c
README: compal-old vs. compal-new distinction is here
Mychaela Falconia <falcon@freecalypso.org>
parents:
21
diff
changeset
|
130 config. |
|
21
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
131 |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
132 No Calypso C05 target support |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
133 ============================= |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
134 |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
135 The present FFS editor application is a stripped-down derivative of FC Selenite |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
136 firmware, still containing Nucleus RTOS, thus it uses interrupts. Having a |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
137 run-from-RAM (or more precisely, independent of flashed fw) application use |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
138 interrupts requires having Calypso boot ROM version 0300, which is present only |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
139 in Calypso C035 silicon. (We can still use this ROM for our purpose of |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
140 interrupt redirection even if it is disabled on boot like on Compal phones.) |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
141 Because of this interrupt handling issue, this FFS editor application is not |
|
5dd2fa1d3da1
README: minor fixes
Mychaela Falconia <falcon@freecalypso.org>
parents:
20
diff
changeset
|
142 available on the Mother's D-Sample C05 board, or any other Calypso C05 target. |