FreeCalypso > hg > freecalypso-reveng

comparison fluid-mnf/README @ 363:6cff3ee315e0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fluid-mnf/README: work in progress
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 15 Mar 2020 03:02:13 +0000
parents 1f13f0e43e43
children 37d647dfb920
comparison
equal deleted inserted replaced
362:b4fb0c7dfdf4 363:6cff3ee315e0
3 Windows, no Unix or Linux support included. Back in 2007 or earlier Openmoko 3 Windows, no Unix or Linux support included. Back in 2007 or earlier Openmoko
4 had made their own port of FLUID to Linux and we have their Linux/ARM binary, 4 had made their own port of FLUID to Linux and we have their Linux/ARM binary,
5 but the source for that Linux port appears to have been lost. 5 but the source for that Linux port appears to have been lost.
6 6
7 The present work is an independent (non-Openmoko) port of TI's FLUID to Linux 7 The present work is an independent (non-Openmoko) port of TI's FLUID to Linux
8 (can be further ported to other Unixes with some additional work, see below)
8 made by Mother Mychaela N. Falconia of FreeCalypso, named fluid-mnf in order to 9 made by Mother Mychaela N. Falconia of FreeCalypso, named fluid-mnf in order to
9 distinguish it from any other Unix/Linux ports of FLUID that may have been made 10 distinguish it from any other Unix/Linux ports of FLUID that may have been made
10 by unknown other parties. The present port uses Linux-specific tty ioctl calls 11 by unknown other parties.
11 instead of generic termios for serial port control, thus it won't compile or 12
12 run under any other Unixes without further porting. It was done this way 13 Purpose and scope
13 because of non-standard baud rates: FLUID supports Calypso high baud rates of 14 =================
14 203125, 406250 and 812500 bps, as well as D-Sample XXO (eXternal Xtal 15
15 Oscillator) baud rates of 230400, 460800 and 921600 bps, and because of POSIX 16 The present fluid-mnf port has been produced as an act of restorative justice,
16 stupidity, supporting all of these baud rates in a Unix application requires 17 righting the wrong of Closedmoko not releasing theirs when they made it in 2007
17 non-portable hacks. 18 or earlier. The present fluid-mnf port is NOT intended to replace fc-loadtool,
18 19 thus a strict limit was put on the extent of work that was done on fluid-mnf:
19 Please note that the target-side binaries in the target-bin directory are 20 just enough to right Moko's wrong, plus the minimum extra work that was needed
20 unchanged from TI's original delivery, just like Openmoko left them unchanged 21 in order to satisfy my natural curiosity in the area of FLUID working with TI's
21 in their version. I am not even bothering with setting up an environment to 22 own D-Sample board, but no more.
22 recompile them from source with TI's TMS470 toolchain: I am going to do the 23
23 same thing Openmoko did, just use them unchanged.
24
25 Please also note that the present fluid-mnf port is being made as an act of
26 restorative justice, righting the wrong of Closedmoko not releasing theirs when
27 they made it in 2007 or earlier. The present fluid-mnf port is NOT intended to
28 replace fc-loadtool, thus a strict limit is being put on the extent of work
29 that will be done on fluid-mnf: just enough to right Moko's wrong and maybe a
30 little extra to allow for satisfaction of some natural curiosities, but no more.
31 As a result of these strict limits on the scope of the work, neither this 24 As a result of these strict limits on the scope of the work, neither this
32 fluid-mnf nor any other known version of FLUID will work on FCDEV3B boards with 25 fluid-mnf nor any other known version of FLUID will work on FCDEV3B boards with
33 Spansion S71PL129N flash - instead our boards with this flash are supported only 26 Spansion S71PL129N flash - instead our boards with this flash are supported only
34 by our own fc-loadtool, not FLUID. The ONLY Calypso targets that are expected 27 by our own fc-loadtool, not FLUID. The ONLY Calypso targets that are expected
35 to be supported by fluid-mnf (same as TI's original FLUID for Windows) are: 28 to be supported by fluid-mnf (same as TI's original FLUID for Windows) are:
37 * TI's own D-Sample and Leonardo boards; 30 * TI's own D-Sample and Leonardo boards;
38 * A certain non-TI development board nicknamed Caramel which has a Leonardo 31 * A certain non-TI development board nicknamed Caramel which has a Leonardo
39 clone as its core but has a D-Sample-like physical form factor; 32 clone as its core but has a D-Sample-like physical form factor;
40 * Openmoko GTA01 and GTA02 modems. 33 * Openmoko GTA01 and GTA02 modems.
41 34
42 Openmoko GTA02 has just been tested and confirmed to work with fluid-mnf; 35 The present fluid-mnf release has been tested and confirmed to work on the
43 D-Sample and Caramel boards remain to be tested. 36 Mother's D-Sample C05 and Caramel boards, as well as on Openmoko GTA02. It is
37 NOT expected to work on most other Calypso devices out in the wild.
38
39 What is FLUID
40 =============
41
42 FLUID stands for Flash Loader Utility Independent of Device. It is not totally
43 clear to us (FreeCalypso) exactly what the "independent of device" part is
44 referring to; it can refer to any or all of the following:
45
46 * One can run FLUID, often with the exact same command line, against several
47 different TI-based GSM device targets, specifically against three different
48 DBB chip generations (ancient pre-Calypso chips, our familiar Calypso, and
49 Calypso+), using either the boot ROM protocol on Calypso and Calypso+ or
50 FLUID's own bootloader (either flash-resident or loaded via JTAG) with its
51 own protocol, and FLUID goes out of its way to try to autodetect and
52 automagically support all these target chip and boot entry method variations.
53
54 * The flash chip type is autodetected and does not need to be manually selected
55 by the user. If multiple variations exist of a given product where the
56 factory has populated different flash chips for whatever part availability
57 and pricing reasons, but it is otherwise the same product running the same
58 firmware, one can use FLUID to flash fw updates without worrying about the
59 flash chip type. Our recent versions of fc-loadtool (since fc-host-tools-r11)
60 feature the same quality.
61
62 * Whenever someone needs to add support for a new flash chip, this addition is
63 done by editing an ASCII text configuration file (devices.txt) that is read
64 by FLUID at run time, as opposed to needing to edit the source code and
65 recompile the program. This distinction was significant in the Windows world,
66 a culture of software in binary form, but makes absolutely no practical
67 difference for our fluid-mnf port for the Unix/Linux culture, a much healthier
68 culture where all software is distributed in source code form and where
69 compiling from source is a standard part of end user duties.
70
71 TI's internal reference platforms on which FLUID was developed and which FLUID
72 supports as its most native targets are B-Sample through E-Sample:
73
74 B-Sample: seems to be Ulysse(s) chipset, very little known
75 C-Sample: seems to be early Calypso C05 rev A, little known
76 D-Sample: Calypso C05 rev B or Calypso C035, Iota ABB, Clara RF
77 E-Sample: Calypso+, apparently existed in both "secure" and "non-secure"
78 variants
79
80 FLUID supports Hercules/Ulysse(s), Calypso and Calypso+ chipsets as follows:
81
82 * Hercules and Ulysse(s) predate our familiar Calypso and have no boot ROM.
83 The standard supported way to recover from blank or bricked flash was to use
84 JTAG: TI's original FLUID package (fluid-2.27.zip) contains an ulyboot.out
85 COFF image which you load via JTAG using TI's XDS510 or XDS560 hardware and
86 CCS software, then FLUID makes its entry via the protocol provided by this
87 bootloader. Standard firmwares included a flash-resident version of the same
88 bootloader; as long as you don't brick sector 0, you can then reload newer fw
89 versions without JTAG.
90
91 * On our familiar Calypso, both the old way (JTAG for cold loading, flash-
92 resident bootloader for warm reloads) and the new way (Calypso boot ROM) are
93 supported. However, the old way (FLUID bootloader) is supported ONLY on
94 13 MHz platforms like D-Sample (Clara RF), and is NOT supported on the more
95 common Calypso+Iota+Rita platforms with 26 MHz clock input to the Calypso.
96
97 * We know very little about Calypso+, but apparently it does not offer a
98 sensible boot ROM protocol like plain Calypso does: instead the choices are
99 either anti-user-freedom cryptographically restricted boot ("secure" E-Sample
100 boards) or no boot ROM at all, going back to brickable flash and needing JTAG
101 for cold loading on "non-secure" E-Sample boards. FLUID (the tool) supports
102 the old FLUID bootloader on those "non-secure" E-Sample boards, and that
103 Calypso+ version of the JTAG-loadable FLUID bootloader (calpboot.out) includes
104 the fix for 26 MHz clock input (E-Sample has Rita RF) - but the plain Calypso
105 version (calboot.out) does NOT support 26 MHz platforms.
106
107 What we have done in fluid-mnf
108 ==============================
109
110 Almost no change in functionality has been made - the objective was to port TI's
111 tool from Windows to Linux with as little change as possible, changing only
112 those parts where the Unix/Linux way of life is strictly different from the
113 Windows way.
114
115 The most principal change made in fluid-mnf is the way you specify the serial
116 port to use to connect to the target. The command line interface design in TI's
117 original version was thoroughly tied to the Windows model of numbered COM ports:
118 there was a -p option to select the serial port by number (defaulting to COM1),
119 but absolutely no provision to specify the serial port by name. Examining
120 Closedmoko's sans-source ARM/Linux fluid.exe version through a combination of
121 static analysis and running under strace, we see that they did two things:
122
123 1) They changed the numbered "COM" port name generation from "COM%d" to
124 "/dev/ttySAC%d" - but the command line parser still restricts -p numbers to
125 the range of [1,24], thus the correct modem tty port /dev/ttySAC0 still
126 cannot be specified in this manner. The default with no -p option and no
127 FLUID_PORT= environment variable is /dev/ttySAC1, which is garbage because
128 that port has the GPS receiver connected to it, not the GSM modem.
129
130 2) They added a hack whereby if a FLUID_PORT= environment variable is defined,
131 its value overrides the sprintf-constructed numbered "COM" port name.
132 Setting FLUID_PORT=/dev/ttySAC0 is the only way to select the correct modem
133 tty port with their stupid version.
134
135 The following approach has been implemented in fluid-mnf, seeking to be both
136 forward-looking in the Unix/Linux culture way and backward-compatible with OM's
137 version:
138
139 * -p option in fluid-mnf takes a string argument instead of a number, and this
140 string argument is the tty port name.
141
142 * If no -p option is given, the FLUID_PORT= environment variable is consulted.
143
144 * If both -p and FLUID_PORT= are given, the -p option takes precedence.
145
146 * If neither -p nor FLUID_PORT= is specified, it is a hard error - there is no
147 default tty port.
148
149 The present port uses Linux-specific tty ioctl calls instead of generic termios
150 for serial port control, thus it won't compile or run under any other Unixes
151 without further porting. It was done this way because of non-standard baud
152 rates: FLUID supports Calypso high baud rates of 203125, 406250 and 812500 bps,
153 as well as D-Sample XXO (eXternal Xtal Oscillator) baud rates of 230400, 460800
154 and 921600 bps, and because of POSIX stupidity, supporting all of these baud
155 rates in a Unix application requires non-portable hacks.
156
157 All original FLUID code that supports targets other than our familiar Calypso
158 (namely, Hercules/Ulysse(s) and Calypso+) has been left completely unchanged;
159 while none of this code exhibited any problems compiling for Linux, it is
160 completely untested: we have neither the hardware nor any real knowledge of
161 what it is and how it is supposed to work. For this reason, Calypso is the
162 only target platform which we can really vouch for as being supported by
163 fluid-mnf. See below regarding what works on D-Sample and what works on the
164 more common Calypso+Iota+Rita platforms.
165
166 Target-side components of FLUID
167 ===============================
168
169 Like any other tool performing the same function, FLUID consists of not only
170 the PC or Unix/Linux application, but also target-side code pieces which are
171 fed either to the Calypso boot ROM or to FLUID's other bootloader
172 (flash-resident or loaded via JTAG) and which run on the target during the
173 flash programming or reading process. In the case of FLUID, these target-side
174 components are cmd.m0 and flash "method" drivers (amd.m0, intel.m0 etc),
175 performing essentially the same function as loadagent.srec does for our own
176 fc-loadtool.
177
178 TI's original FLUID package fluid-2.27.zip contains both the sources for these
179 components and the deployable *.m0 target binaries. Openmoko left these *.m0
180 target components of FLUID completely unchanged in their port, and we are doing
181 likewise in fluid-mnf: aside from our cmd39.m0 concoction explained further
182 below, all *.m0 files in the target-bin subdirectory in this fluid-mnf release
183 are unchanged from TI's original delivery. I did not even bother with setting
184 up an environment to recompile them from source with TI's TMS470 toolchain.
185
186 Search path for helper files
187 ============================
188
189 FLUID needs to find the just-mentioned *.m0 target binaries as well as the
190 devices.txt file as helper files. TI's original code looks in the current
191 directory, and also tries to look in the directory where the fluid.exe binary
192 is located by extracting the path from argv[0] - but the latter method works
193 only in the Windows culture, not Unix/Linux.
194
195 Openmoko kept this helper file search logic completely unchanged in their
196 version, and they installed both their fluid.exe binary and the helper files in
197 /usr/sbin. But simply running OM's fluid.exe (never mind the non-sensical .exe
198 suffix on a Linux binary) from whatever current directory relying on the shell's
199 PATH search does not work: argv[0] will be equal to just "fluid.exe" without
200 any path, and TI's Windows-minded code unchanged by OM won't ever figure out
201 that it needs to look in /usr/sbin for the needed helper files. OM's official
202 instructions were to cd to /usr/sbin and run fluid.exe from there - unbelievable
203 bogosity.
204
205 The present fluid-mnf port is made more Unix-proper in this regard: we put all
206 needed helper files in a designated installation directory
207 (/opt/freecalypso/fluid), and the code has been modified to look there instead
208 of the usually-null path extracted from argv[0]. The tool still looks in the
209 current directory first for every file: changes to TI's FLUID code architecture
210 have been kept to a minimum.
211
212 Calypso C05 vs. C035
213 ====================
214
215 For all of its claims of device-independence and automagically supporting all
216 of various targets, TI's original FLUID as we got it in fluid-2.27.zip fails to
217 correctly support older Calypso boards with early Calypso C05 chips on them.
218 First Calypso generations (C05 rev A and C05 rev B) have a maximum ARM7 clock
219 frequency of 39 MHz, while on the later Calypso C035 (found in most mass-
220 produced phones and modems) this maximum frequency has been lifted to 52 MHz.
221
222 In TI's FLUID architecture, the target component 'cmd' (cmd.m0 built from cmd.c)
223 configures and enables the Calypso DPLL as soon as the host tool tells it that
224 the active target is Calypso rather than Ulysse(s). The responsible function
225 hardware_init_calypso() in target/cmd.c originally had code that configured
226 this DPLL at 39 MHz - then Calypso C035 came along, and someone at TI merrily
227 changed that DPLL setup constant from 39 MHz to 52 MHz. So what happens then
228 if someone runs TI's FLUID version 2.27 on an older C-Sample, D-Sample or
229 Leonardo board that has a Calypso C05 chip on it? Answer: it will produce an
230 overclocked chip with unknown consequences - I am not willing to try it on our
231 one and only D-Sample C05 board.
232
233 Trying to improve the architecture of FLUID is strictly beyond the scope of what
234 I set out to do in this fluid-mnf port, instead I just needed a way to safely
235 run it on our D-Sample C05 board with minimal changes. So I went for the
236 minimally-invasive surgical approach:
237
238 * cmd39.m0 is a modified version of cmd.m0, produced by copying cmd.m0 and
239 manually patching the one offending DPLL setup constant, restoring the older
240 39 MHz config.
241
242 * fluid-mnf has an added option -oC that causes it to use cmd39.m0 instead of
243 regular cmd.m0.
244
245 FLUID operating on D-Sample
246 ===========================
247
248 For anyone lucky to have an original TI D-Sample board (either C05 or C035),
249 the way FLUID works on it is really awesome:
250
251 * Both boot entry methods work: fluid-mnf -oo goes through the Calypso boot ROM
252 (the older boot ROM version present in Calypso C05 is good enough), whereas
253 fluid-mnf -oO goes through the other FLUID bootloader, either flash-resident
254 or loaded via JTAG. (I haven't tried the JTAG way, but fluid-mnf -oO works
255 on the D-Sample when the flash contains a build of our FC Magnetite
256 l1reconst-bl configuration.) The extra -oC option is needed for D-Sample C05,
257 but won't be needed for D-Sample C035, if anyone has one.
258
259 * FLUID (both TI's original and our fluid-mnf port) supports Calypso high baud
260 rates of 203125, 406250 and 812500 bps: just select the desired baud rate with
261 the -b option. The baud rate switch is effected when the command interpreter
262 ('cmd' target code piece) is running on the target, which is itself loaded at
263 115200 baud.
264
265 * The D-Sample board has an extra 14.745600 MHz crystal oscillator and a special
266 circuit (controlled by bits in a register mapped into Calypso nCS3 address
267 space) that can switch the Calypso clock input from the regular 13 MHz coming
268 from the RF section to this special 14.745600 clock. Of course no GSM
269 functions can work in this state, but feeding this special clock to Calypso
270 allows its UARTs to produce "standard" baud rates of 230400, 460800 and 921600
271 bps! This feature is apparently called XXO for eXternal Xtal Oscillator, and
272 is supported by FLUID, including our fluid-mnf port: just select the desired
273 baud rate with the -b option, and if the target is D-Sample, it will just
274 magically work. (On more "mere mortal" Calypso targets the result will be a
275 spectacular failure instead.)
276
277 * The D-Sample board also has a block of 16 debug LEDs controlled by another
278 register mapped into Calypso nCS3 address space, and FLUID's target-side
279 component (which we haven't modified except for the 39 MHz fix) displays
280 pretty dancing patterns on these LEDs as it does its work.
281