FreeCalypso > hg > freecalypso-reveng

annotate fluid-mnf/README @ 364:37d647dfb920

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fluid-mnf/README: coming further along
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 15 Mar 2020 03:52:23 +0000
parents 6cff3ee315e0
children f888ae294b1b
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
311
9cecc930d78f fluid-mnf: original source from TI,
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 In the summer of 2019 we (FreeCalypso) had recovered a copy of TI's original
9cecc930d78f fluid-mnf: original source from TI,
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 FLUID package including source, but this TI original FLUID source targets only
9cecc930d78f fluid-mnf: original source from TI,
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 Windows, no Unix or Linux support included. Back in 2007 or earlier Openmoko
9cecc930d78f fluid-mnf: original source from TI,
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 had made their own port of FLUID to Linux and we have their Linux/ARM binary,
9cecc930d78f fluid-mnf: original source from TI,
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 but the source for that Linux port appears to have been lost.
9cecc930d78f fluid-mnf: original source from TI,
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6
359
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
7 The present work is an independent (non-Openmoko) port of TI's FLUID to Linux
363
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
8 (can be further ported to other Unixes with some additional work, see below)
359
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
9 made by Mother Mychaela N. Falconia of FreeCalypso, named fluid-mnf in order to
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
10 distinguish it from any other Unix/Linux ports of FLUID that may have been made
363
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
11 by unknown other parties.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
12
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
13 Purpose and scope
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
14 =================
359
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
15
363
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
16 The present fluid-mnf port has been produced as an act of restorative justice,
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
17 righting the wrong of Closedmoko not releasing theirs when they made it in 2007
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
18 or earlier. The present fluid-mnf port is NOT intended to replace fc-loadtool,
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
19 thus a strict limit was put on the extent of work that was done on fluid-mnf:
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
20 just enough to right Moko's wrong, plus the minimum extra work that was needed
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
21 in order to satisfy my natural curiosity in the area of FLUID working with TI's
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
22 own D-Sample board, but no more.
359
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
23
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
24 As a result of these strict limits on the scope of the work, neither this
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
25 fluid-mnf nor any other known version of FLUID will work on FCDEV3B boards with
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
26 Spansion S71PL129N flash - instead our boards with this flash are supported only
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
27 by our own fc-loadtool, not FLUID. The ONLY Calypso targets that are expected
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
28 to be supported by fluid-mnf (same as TI's original FLUID for Windows) are:
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
29
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
30 * TI's own D-Sample and Leonardo boards;
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
31 * A certain non-TI development board nicknamed Caramel which has a Leonardo
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
32 clone as its core but has a D-Sample-like physical form factor;
83aed2355592 fluid-mnf/README: update for the present state
Mychaela Falconia <falcon@freecalypso.org>
parents: 311
diff changeset
33 * Openmoko GTA01 and GTA02 modems.
360
1f13f0e43e43 fluid-mnf: doc update after GTA02 tests
Mychaela Falconia <falcon@freecalypso.org>
parents: 359
diff changeset
34
363
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
35 The present fluid-mnf release has been tested and confirmed to work on the
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
36 Mother's D-Sample C05 and Caramel boards, as well as on Openmoko GTA02. It is
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
37 NOT expected to work on most other Calypso devices out in the wild.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
38
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
39 What is FLUID
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
40 =============
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
41
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
42 FLUID stands for Flash Loader Utility Independent of Device. It is not totally
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
43 clear to us (FreeCalypso) exactly what the "independent of device" part is
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
44 referring to; it can refer to any or all of the following:
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
45
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
46 * One can run FLUID, often with the exact same command line, against several
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
47 different TI-based GSM device targets, specifically against three different
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
48 DBB chip generations (ancient pre-Calypso chips, our familiar Calypso, and
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
49 Calypso+), using either the boot ROM protocol on Calypso and Calypso+ or
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
50 FLUID's own bootloader (either flash-resident or loaded via JTAG) with its
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
51 own protocol, and FLUID goes out of its way to try to autodetect and
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
52 automagically support all these target chip and boot entry method variations.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
53
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
54 * The flash chip type is autodetected and does not need to be manually selected
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
55 by the user. If multiple variations exist of a given product where the
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
56 factory has populated different flash chips for whatever part availability
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
57 and pricing reasons, but it is otherwise the same product running the same
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
58 firmware, one can use FLUID to flash fw updates without worrying about the
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
59 flash chip type. Our recent versions of fc-loadtool (since fc-host-tools-r11)
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
60 feature the same quality.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
61
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
62 * Whenever someone needs to add support for a new flash chip, this addition is
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
63 done by editing an ASCII text configuration file (devices.txt) that is read
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
64 by FLUID at run time, as opposed to needing to edit the source code and
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
65 recompile the program. This distinction was significant in the Windows world,
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
66 a culture of software in binary form, but makes absolutely no practical
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
67 difference for our fluid-mnf port for the Unix/Linux culture, a much healthier
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
68 culture where all software is distributed in source code form and where
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
69 compiling from source is a standard part of end user duties.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
70
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
71 TI's internal reference platforms on which FLUID was developed and which FLUID
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
72 supports as its most native targets are B-Sample through E-Sample:
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
73
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
74 B-Sample: seems to be Ulysse(s) chipset, very little known
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
75 C-Sample: seems to be early Calypso C05 rev A, little known
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
76 D-Sample: Calypso C05 rev B or Calypso C035, Iota ABB, Clara RF
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
77 E-Sample: Calypso+, apparently existed in both "secure" and "non-secure"
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
78 variants
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
79
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
80 FLUID supports Hercules/Ulysse(s), Calypso and Calypso+ chipsets as follows:
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
81
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
82 * Hercules and Ulysse(s) predate our familiar Calypso and have no boot ROM.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
83 The standard supported way to recover from blank or bricked flash was to use
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
84 JTAG: TI's original FLUID package (fluid-2.27.zip) contains an ulyboot.out
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
85 COFF image which you load via JTAG using TI's XDS510 or XDS560 hardware and
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
86 CCS software, then FLUID makes its entry via the protocol provided by this
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
87 bootloader. Standard firmwares included a flash-resident version of the same
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
88 bootloader; as long as you don't brick sector 0, you can then reload newer fw
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
89 versions without JTAG.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
90
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
91 * On our familiar Calypso, both the old way (JTAG for cold loading, flash-
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
92 resident bootloader for warm reloads) and the new way (Calypso boot ROM) are
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
93 supported. However, the old way (FLUID bootloader) is supported ONLY on
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
94 13 MHz platforms like D-Sample (Clara RF), and is NOT supported on the more
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
95 common Calypso+Iota+Rita platforms with 26 MHz clock input to the Calypso.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
96
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
97 * We know very little about Calypso+, but apparently it does not offer a
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
98 sensible boot ROM protocol like plain Calypso does: instead the choices are
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
99 either anti-user-freedom cryptographically restricted boot ("secure" E-Sample
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
100 boards) or no boot ROM at all, going back to brickable flash and needing JTAG
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
101 for cold loading on "non-secure" E-Sample boards. FLUID (the tool) supports
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
102 the old FLUID bootloader on those "non-secure" E-Sample boards, and that
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
103 Calypso+ version of the JTAG-loadable FLUID bootloader (calpboot.out) includes
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
104 the fix for 26 MHz clock input (E-Sample has Rita RF) - but the plain Calypso
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
105 version (calboot.out) does NOT support 26 MHz platforms.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
106
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
107 What we have done in fluid-mnf
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
108 ==============================
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
109
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
110 Almost no change in functionality has been made - the objective was to port TI's
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
111 tool from Windows to Linux with as little change as possible, changing only
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
112 those parts where the Unix/Linux way of life is strictly different from the
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
113 Windows way.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
114
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
115 The most principal change made in fluid-mnf is the way you specify the serial
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
116 port to use to connect to the target. The command line interface design in TI's
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
117 original version was thoroughly tied to the Windows model of numbered COM ports:
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
118 there was a -p option to select the serial port by number (defaulting to COM1),
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
119 but absolutely no provision to specify the serial port by name. Examining
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
120 Closedmoko's sans-source ARM/Linux fluid.exe version through a combination of
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
121 static analysis and running under strace, we see that they did two things:
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
122
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
123 1) They changed the numbered "COM" port name generation from "COM%d" to
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
124 "/dev/ttySAC%d" - but the command line parser still restricts -p numbers to
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
125 the range of [1,24], thus the correct modem tty port /dev/ttySAC0 still
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
126 cannot be specified in this manner. The default with no -p option and no
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
127 FLUID_PORT= environment variable is /dev/ttySAC1, which is garbage because
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
128 that port has the GPS receiver connected to it, not the GSM modem.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
129
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
130 2) They added a hack whereby if a FLUID_PORT= environment variable is defined,
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
131 its value overrides the sprintf-constructed numbered "COM" port name.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
132 Setting FLUID_PORT=/dev/ttySAC0 is the only way to select the correct modem
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
133 tty port with their stupid version.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
134
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
135 The following approach has been implemented in fluid-mnf, seeking to be both
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
136 forward-looking in the Unix/Linux culture way and backward-compatible with OM's
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
137 version:
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
138
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
139 * -p option in fluid-mnf takes a string argument instead of a number, and this
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
140 string argument is the tty port name.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
141
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
142 * If no -p option is given, the FLUID_PORT= environment variable is consulted.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
143
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
144 * If both -p and FLUID_PORT= are given, the -p option takes precedence.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
145
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
146 * If neither -p nor FLUID_PORT= is specified, it is a hard error - there is no
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
147 default tty port.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
148
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
149 The present port uses Linux-specific tty ioctl calls instead of generic termios
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
150 for serial port control, thus it won't compile or run under any other Unixes
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
151 without further porting. It was done this way because of non-standard baud
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
152 rates: FLUID supports Calypso high baud rates of 203125, 406250 and 812500 bps,
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
153 as well as D-Sample XXO (eXternal Xtal Oscillator) baud rates of 230400, 460800
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
154 and 921600 bps, and because of POSIX stupidity, supporting all of these baud
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
155 rates in a Unix application requires non-portable hacks.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
156
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
157 All original FLUID code that supports targets other than our familiar Calypso
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
158 (namely, Hercules/Ulysse(s) and Calypso+) has been left completely unchanged;
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
159 while none of this code exhibited any problems compiling for Linux, it is
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
160 completely untested: we have neither the hardware nor any real knowledge of
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
161 what it is and how it is supposed to work. For this reason, Calypso is the
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
162 only target platform which we can really vouch for as being supported by
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
163 fluid-mnf. See below regarding what works on D-Sample and what works on the
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
164 more common Calypso+Iota+Rita platforms.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
165
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
166 Target-side components of FLUID
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
167 ===============================
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
168
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
169 Like any other tool performing the same function, FLUID consists of not only
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
170 the PC or Unix/Linux application, but also target-side code pieces which are
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
171 fed either to the Calypso boot ROM or to FLUID's other bootloader
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
172 (flash-resident or loaded via JTAG) and which run on the target during the
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
173 flash programming or reading process. In the case of FLUID, these target-side
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
174 components are cmd.m0 and flash "method" drivers (amd.m0, intel.m0 etc),
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
175 performing essentially the same function as loadagent.srec does for our own
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
176 fc-loadtool.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
177
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
178 TI's original FLUID package fluid-2.27.zip contains both the sources for these
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
179 components and the deployable *.m0 target binaries. Openmoko left these *.m0
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
180 target components of FLUID completely unchanged in their port, and we are doing
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
181 likewise in fluid-mnf: aside from our cmd39.m0 concoction explained further
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
182 below, all *.m0 files in the target-bin subdirectory in this fluid-mnf release
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
183 are unchanged from TI's original delivery. I did not even bother with setting
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
184 up an environment to recompile them from source with TI's TMS470 toolchain.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
185
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
186 Search path for helper files
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
187 ============================
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
188
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
189 FLUID needs to find the just-mentioned *.m0 target binaries as well as the
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
190 devices.txt file as helper files. TI's original code looks in the current
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
191 directory, and also tries to look in the directory where the fluid.exe binary
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
192 is located by extracting the path from argv[0] - but the latter method works
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
193 only in the Windows culture, not Unix/Linux.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
194
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
195 Openmoko kept this helper file search logic completely unchanged in their
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
196 version, and they installed both their fluid.exe binary and the helper files in
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
197 /usr/sbin. But simply running OM's fluid.exe (never mind the non-sensical .exe
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
198 suffix on a Linux binary) from whatever current directory relying on the shell's
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
199 PATH search does not work: argv[0] will be equal to just "fluid.exe" without
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
200 any path, and TI's Windows-minded code unchanged by OM won't ever figure out
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
201 that it needs to look in /usr/sbin for the needed helper files. OM's official
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
202 instructions were to cd to /usr/sbin and run fluid.exe from there - unbelievable
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
203 bogosity.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
204
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
205 The present fluid-mnf port is made more Unix-proper in this regard: we put all
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
206 needed helper files in a designated installation directory
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
207 (/opt/freecalypso/fluid), and the code has been modified to look there instead
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
208 of the usually-null path extracted from argv[0]. The tool still looks in the
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
209 current directory first for every file: changes to TI's FLUID code architecture
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
210 have been kept to a minimum.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
211
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
212 Calypso C05 vs. C035
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
213 ====================
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
214
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
215 For all of its claims of device-independence and automagically supporting all
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
216 of various targets, TI's original FLUID as we got it in fluid-2.27.zip fails to
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
217 correctly support older Calypso boards with early Calypso C05 chips on them.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
218 First Calypso generations (C05 rev A and C05 rev B) have a maximum ARM7 clock
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
219 frequency of 39 MHz, while on the later Calypso C035 (found in most mass-
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
220 produced phones and modems) this maximum frequency has been lifted to 52 MHz.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
221
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
222 In TI's FLUID architecture, the target component 'cmd' (cmd.m0 built from cmd.c)
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
223 configures and enables the Calypso DPLL as soon as the host tool tells it that
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
224 the active target is Calypso rather than Ulysse(s). The responsible function
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
225 hardware_init_calypso() in target/cmd.c originally had code that configured
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
226 this DPLL at 39 MHz - then Calypso C035 came along, and someone at TI merrily
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
227 changed that DPLL setup constant from 39 MHz to 52 MHz. So what happens then
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
228 if someone runs TI's FLUID version 2.27 on an older C-Sample, D-Sample or
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
229 Leonardo board that has a Calypso C05 chip on it? Answer: it will produce an
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
230 overclocked chip with unknown consequences - I am not willing to try it on our
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
231 one and only D-Sample C05 board.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
232
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
233 Trying to improve the architecture of FLUID is strictly beyond the scope of what
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
234 I set out to do in this fluid-mnf port, instead I just needed a way to safely
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
235 run it on our D-Sample C05 board with minimal changes. So I went for the
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
236 minimally-invasive surgical approach:
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
237
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
238 * cmd39.m0 is a modified version of cmd.m0, produced by copying cmd.m0 and
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
239 manually patching the one offending DPLL setup constant, restoring the older
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
240 39 MHz config.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
241
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
242 * fluid-mnf has an added option -oC that causes it to use cmd39.m0 instead of
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
243 regular cmd.m0.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
244
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
245 FLUID operating on D-Sample
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
246 ===========================
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
247
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
248 For anyone lucky to have an original TI D-Sample board (either C05 or C035),
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
249 the way FLUID works on it is really awesome:
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
250
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
251 * Both boot entry methods work: fluid-mnf -oo goes through the Calypso boot ROM
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
252 (the older boot ROM version present in Calypso C05 is good enough), whereas
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
253 fluid-mnf -oO goes through the other FLUID bootloader, either flash-resident
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
254 or loaded via JTAG. (I haven't tried the JTAG way, but fluid-mnf -oO works
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
255 on the D-Sample when the flash contains a build of our FC Magnetite
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
256 l1reconst-bl configuration.) The extra -oC option is needed for D-Sample C05,
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
257 but won't be needed for D-Sample C035, if anyone has one.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
258
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
259 * FLUID (both TI's original and our fluid-mnf port) supports Calypso high baud
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
260 rates of 203125, 406250 and 812500 bps: just select the desired baud rate with
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
261 the -b option. The baud rate switch is effected when the command interpreter
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
262 ('cmd' target code piece) is running on the target, which is itself loaded at
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
263 115200 baud.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
264
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
265 * The D-Sample board has an extra 14.745600 MHz crystal oscillator and a special
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
266 circuit (controlled by bits in a register mapped into Calypso nCS3 address
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
267 space) that can switch the Calypso clock input from the regular 13 MHz coming
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
268 from the RF section to this special 14.745600 clock. Of course no GSM
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
269 functions can work in this state, but feeding this special clock to Calypso
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
270 allows its UARTs to produce "standard" baud rates of 230400, 460800 and 921600
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
271 bps! This feature is apparently called XXO for eXternal Xtal Oscillator, and
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
272 is supported by FLUID, including our fluid-mnf port: just select the desired
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
273 baud rate with the -b option, and if the target is D-Sample, it will just
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
274 magically work. (On more "mere mortal" Calypso targets the result will be a
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
275 spectacular failure instead.)
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
276
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
277 * The D-Sample board also has a block of 16 debug LEDs controlled by another
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
278 register mapped into Calypso nCS3 address space, and FLUID's target-side
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
279 component (which we haven't modified except for the 39 MHz fix) displays
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
280 pretty dancing patterns on these LEDs as it does its work.
6cff3ee315e0 fluid-mnf/README: work in progress
Mychaela Falconia <falcon@freecalypso.org>
parents: 360
diff changeset
281
364
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
282 FLUID operating on Openmoko devices
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
283 ===================================
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
284
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
285 While nowhere near as sexy as on TI's own D-Sample, our fluid-mnf port works
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
286 well on Openmoko modems:
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
287
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
288 * Only fluid-mnf -oo mode works on Openmoko devices, NOT fluid-mnf -oO, same as
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
289 with Leonardo or Caramel boards or any other Calypso 26 MHz platform. We have
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
290 incriminating evidence that Openmoko once made fluid -oO mode work on their
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
291 platform by witchcraft (bending the known laws of physics), but we were never
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
292 able to reproduce that paranormal feat - see this FreeCalypso community
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
293 mailing list thread:
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
294
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
295 https://www.freecalypso.org/pipermail/community/2020-March/000743.html
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
296
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
297 * Don't try D-Sample XXO baud rates of 230400, 460800 or 921600 bps - they
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
298 won't work. However, Calypso high baud rates of 203125, 406250 and 812500 bps
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
299 do work if you are going through the external headset jack and have one of
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
300 the better USB-serial cables, either FTDI or appropriately programmed CP2102.
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
301
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
302 Target boot control
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
303 ===================
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
304
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
305 The code we got from TI in fluid-2.27.zip includes a rather bizarre provision
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
306 for some ancient way of doing target boot control: right after opening the
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
307 target serial port but before sending periodic beacons seeking to interrupt and
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
308 divert the boot path either in the Calypso boot ROM or in a flash-resident
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
309 FLUID bootloader, FLUID does some manipulation of the host UART's DTR and RTS
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
310 outputs, as well as sending a break on the main data line. These manipulations
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
311 do absolutely nothing on any ordinary Calypso hardware: the DTR line goes only
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
312 to a GPIO if anywhere at all; the host's RTS output line will normally be
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
313 connected to Calypso CTS_MODEM input if it's the MODEM UART, but these flow
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
314 control lines are completely ignored by both the Calypso boot ROM and various
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
315 flash-resident bootloaders. But apparently there once existed some special
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
316 cable, interfaced to some unknown (probably very early and TI-internal) Calypso
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
317 or before-Calypso targets in some unknown way, and that arrangement produced a
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
318 target reset (probably a predecessor of Iota nTESTRESET on whatever before-Iota
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
319 ABB) when FLUID did this wiggle.
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
320
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
321 In any case, that hardware no longer exists and cannot be recreated because we
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
322 have no idea what it was like and how it is supposed to work. But the logic in
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
323 question is still there in this fluid-mnf port; running OM's fluid.exe under
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
324 strace reveals that they had retained this logic as well, although they broke
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
325 the code that generates a break on the serial data line - how ironic.
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
326
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
327 Aside from this non-understood UART control line wiggling, there is no effective
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
328 target boot control in FLUID: not in TI's original version, not in OM's port
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
329 and not in the present fluid-mnf. You just run FLUID against a serial port, it
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
330 sends beacons and waits forever for the selected bootloader (boot ROM or FLUID
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
331 bl) to respond, and you have to cause the Calypso target to go through its boot
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
332 path by your own external means. Most importantly, there is no provision for
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
333 automation, i.e., no provision for the process to exit with an error code
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
334 instead of hanging forever if you got some target boot control implemented, but
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
335 the bootloader fails to respond as expected - put another way, there is no
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
336 equivalent to loadtools -t option which we've added as of fc-host-tools-r13.
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
337
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
338 Performance
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
339 ===========
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
340
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
341 Even though it cannot be a replacement for fc-loadtool in most use cases, FLUID
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
342 is very aggressively optimized for speed in ways that would be hard to match in
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
343 our fc-loadtool architecture:
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
344
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
345 * FLUID's serial protocol between the host tool and the target-side component
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
346 includes compression (some form of LZ77) for blocks of data destined for
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
347 flash;
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
348
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
349 * The process of programming flash is parallelized: the bits to be programmed
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
350 are serially transferred into a large RAM buffer on the target in parallel
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
351 with the execution of flash erase and program operations on the target;
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
352 specifically, flash erase and program operation functions call the UART Rx
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
353 handler function (which handles the incoming serial stream) as they poll the
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
354 flash chip to complete its operation!
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
355
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
356 For these reasons, on those targets which are supported by both FLUID and
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
357 fc-loadtool, flash programming with FLUID is faster. Here are the performance
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
358 numbers obtained on the Mother's Slackware 14.2 host system, flashing an
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
359 Openmoko GTA02 modem with firmware version moko-new-fw-20190128, going through
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
360 the external headset jack, UberWaves CP2102 Professional cable:
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
361
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
362 fluid-mnf at 115200 baud: 2m28s
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
363 fc-loadtool at 115200 baud: 4m02s
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
364 fluid-mnf at 812500 baud: 0m40s
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
365 fc-loadtool at 812500 baud: 1m12s
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
366
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
367 With both tools the m0 version of the firmware image (fwimage.m0) was being
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
368 flashed; in the case of fc-loadtool the new flash e-program-m0 command was used.
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
369 The version of fc-loadtool used for this test is the one that is about to be
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
370 released with fc-host-tools-r13; previous versions would be even slower. In
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
371 the case of fluid-mnf the -C option was used to disable delta downloads, making
37d647dfb920 fluid-mnf/README: coming further along
Mychaela Falconia <falcon@freecalypso.org>
parents: 363
diff changeset
372 the test operation independent of previous flash state.