annotate README @ 21:5dd2fa1d3da1

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