--- a/fluid-mnf/README	Sat Mar 14 19:44:44 2020 +0000
+++ b/fluid-mnf/README	Sun Mar 15 03:02:13 2020 +0000
@@ -5,29 +5,22 @@
 but the source for that Linux port appears to have been lost.
 
 The present work is an independent (non-Openmoko) port of TI's FLUID to Linux
+(can be further ported to other Unixes with some additional work, see below)
 made by Mother Mychaela N. Falconia of FreeCalypso, named fluid-mnf in order to
 distinguish it from any other Unix/Linux ports of FLUID that may have been made
-by unknown other parties.  The present port uses Linux-specific tty ioctl calls
-instead of generic termios for serial port control, thus it won't compile or
-run under any other Unixes without further porting.  It was done this way
-because of non-standard baud rates: FLUID supports Calypso high baud rates of
-203125, 406250 and 812500 bps, as well as D-Sample XXO (eXternal Xtal
-Oscillator) baud rates of 230400, 460800 and 921600 bps, and because of POSIX
-stupidity, supporting all of these baud rates in a Unix application requires
-non-portable hacks.
+by unknown other parties.
+
+Purpose and scope
+=================
 
-Please note that the target-side binaries in the target-bin directory are
-unchanged from TI's original delivery, just like Openmoko left them unchanged
-in their version.  I am not even bothering with setting up an environment to
-recompile them from source with TI's TMS470 toolchain: I am going to do the
-same thing Openmoko did, just use them unchanged.
+The present fluid-mnf port has been produced as an act of restorative justice,
+righting the wrong of Closedmoko not releasing theirs when they made it in 2007
+or earlier.  The present fluid-mnf port is NOT intended to replace fc-loadtool,
+thus a strict limit was put on the extent of work that was done on fluid-mnf:
+just enough to right Moko's wrong, plus the minimum extra work that was needed
+in order to satisfy my natural curiosity in the area of FLUID working with TI's
+own D-Sample board, but no more.
 
-Please also note that the present fluid-mnf port is being made as an act of
-restorative justice, righting the wrong of Closedmoko not releasing theirs when
-they made it in 2007 or earlier.  The present fluid-mnf port is NOT intended to
-replace fc-loadtool, thus a strict limit is being put on the extent of work
-that will be done on fluid-mnf: just enough to right Moko's wrong and maybe a
-little extra to allow for satisfaction of some natural curiosities, but no more.
 As a result of these strict limits on the scope of the work, neither this
 fluid-mnf nor any other known version of FLUID will work on FCDEV3B boards with
 Spansion S71PL129N flash - instead our boards with this flash are supported only
@@ -39,5 +32,250 @@
   clone as its core but has a D-Sample-like physical form factor;
 * Openmoko GTA01 and GTA02 modems.
 
-Openmoko GTA02 has just been tested and confirmed to work with fluid-mnf;
-D-Sample and Caramel boards remain to be tested.
+The present fluid-mnf release has been tested and confirmed to work on the
+Mother's D-Sample C05 and Caramel boards, as well as on Openmoko GTA02.  It is
+NOT expected to work on most other Calypso devices out in the wild.
+
+What is FLUID
+=============
+
+FLUID stands for Flash Loader Utility Independent of Device.  It is not totally
+clear to us (FreeCalypso) exactly what the "independent of device" part is
+referring to; it can refer to any or all of the following:
+
+* One can run FLUID, often with the exact same command line, against several
+  different TI-based GSM device targets, specifically against three different
+  DBB chip generations (ancient pre-Calypso chips, our familiar Calypso, and
+  Calypso+), using either the boot ROM protocol on Calypso and Calypso+ or
+  FLUID's own bootloader (either flash-resident or loaded via JTAG) with its
+  own protocol, and FLUID goes out of its way to try to autodetect and
+  automagically support all these target chip and boot entry method variations.
+
+* The flash chip type is autodetected and does not need to be manually selected
+  by the user.  If multiple variations exist of a given product where the
+  factory has populated different flash chips for whatever part availability
+  and pricing reasons, but it is otherwise the same product running the same
+  firmware, one can use FLUID to flash fw updates without worrying about the
+  flash chip type.  Our recent versions of fc-loadtool (since fc-host-tools-r11)
+  feature the same quality.
+
+* Whenever someone needs to add support for a new flash chip, this addition is
+  done by editing an ASCII text configuration file (devices.txt) that is read
+  by FLUID at run time, as opposed to needing to edit the source code and
+  recompile the program.  This distinction was significant in the Windows world,
+  a culture of software in binary form, but makes absolutely no practical
+  difference for our fluid-mnf port for the Unix/Linux culture, a much healthier
+  culture where all software is distributed in source code form and where
+  compiling from source is a standard part of end user duties.
+
+TI's internal reference platforms on which FLUID was developed and which FLUID
+supports as its most native targets are B-Sample through E-Sample:
+
+B-Sample: seems to be Ulysse(s) chipset, very little known
+C-Sample: seems to be early Calypso C05 rev A, little known
+D-Sample: Calypso C05 rev B or Calypso C035, Iota ABB, Clara RF
+E-Sample: Calypso+, apparently existed in both "secure" and "non-secure"
+variants
+
+FLUID supports Hercules/Ulysse(s), Calypso and Calypso+ chipsets as follows:
+
+* Hercules and Ulysse(s) predate our familiar Calypso and have no boot ROM.
+  The standard supported way to recover from blank or bricked flash was to use
+  JTAG: TI's original FLUID package (fluid-2.27.zip) contains an ulyboot.out
+  COFF image which you load via JTAG using TI's XDS510 or XDS560 hardware and
+  CCS software, then FLUID makes its entry via the protocol provided by this
+  bootloader.  Standard firmwares included a flash-resident version of the same
+  bootloader; as long as you don't brick sector 0, you can then reload newer fw
+  versions without JTAG.
+
+* On our familiar Calypso, both the old way (JTAG for cold loading, flash-
+  resident bootloader for warm reloads) and the new way (Calypso boot ROM) are
+  supported.  However, the old way (FLUID bootloader) is supported ONLY on
+  13 MHz platforms like D-Sample (Clara RF), and is NOT supported on the more
+  common Calypso+Iota+Rita platforms with 26 MHz clock input to the Calypso.
+
+* We know very little about Calypso+, but apparently it does not offer a
+  sensible boot ROM protocol like plain Calypso does: instead the choices are
+  either anti-user-freedom cryptographically restricted boot ("secure" E-Sample
+  boards) or no boot ROM at all, going back to brickable flash and needing JTAG
+  for cold loading on "non-secure" E-Sample boards.  FLUID (the tool) supports
+  the old FLUID bootloader on those "non-secure" E-Sample boards, and that
+  Calypso+ version of the JTAG-loadable FLUID bootloader (calpboot.out) includes
+  the fix for 26 MHz clock input (E-Sample has Rita RF) - but the plain Calypso
+  version (calboot.out) does NOT support 26 MHz platforms.
+
+What we have done in fluid-mnf
+==============================
+
+Almost no change in functionality has been made - the objective was to port TI's
+tool from Windows to Linux with as little change as possible, changing only
+those parts where the Unix/Linux way of life is strictly different from the
+Windows way.
+
+The most principal change made in fluid-mnf is the way you specify the serial
+port to use to connect to the target.  The command line interface design in TI's
+original version was thoroughly tied to the Windows model of numbered COM ports:
+there was a -p option to select the serial port by number (defaulting to COM1),
+but absolutely no provision to specify the serial port by name.  Examining
+Closedmoko's sans-source ARM/Linux fluid.exe version through a combination of
+static analysis and running under strace, we see that they did two things:
+
+1) They changed the numbered "COM" port name generation from "COM%d" to
+   "/dev/ttySAC%d" - but the command line parser still restricts -p numbers to
+   the range of [1,24], thus the correct modem tty port /dev/ttySAC0 still
+   cannot be specified in this manner.  The default with no -p option and no
+   FLUID_PORT= environment variable is /dev/ttySAC1, which is garbage because
+   that port has the GPS receiver connected to it, not the GSM modem.
+
+2) They added a hack whereby if a FLUID_PORT= environment variable is defined,
+   its value overrides the sprintf-constructed numbered "COM" port name.
+   Setting FLUID_PORT=/dev/ttySAC0 is the only way to select the correct modem
+   tty port with their stupid version.
+
+The following approach has been implemented in fluid-mnf, seeking to be both
+forward-looking in the Unix/Linux culture way and backward-compatible with OM's
+version:
+
+* -p option in fluid-mnf takes a string argument instead of a number, and this
+  string argument is the tty port name.
+
+* If no -p option is given, the FLUID_PORT= environment variable is consulted.
+
+* If both -p and FLUID_PORT= are given, the -p option takes precedence.
+
+* If neither -p nor FLUID_PORT= is specified, it is a hard error - there is no
+  default tty port.
+
+The present port uses Linux-specific tty ioctl calls instead of generic termios
+for serial port control, thus it won't compile or run under any other Unixes
+without further porting.  It was done this way because of non-standard baud
+rates: FLUID supports Calypso high baud rates of 203125, 406250 and 812500 bps,
+as well as D-Sample XXO (eXternal Xtal Oscillator) baud rates of 230400, 460800
+and 921600 bps, and because of POSIX stupidity, supporting all of these baud
+rates in a Unix application requires non-portable hacks.
+
+All original FLUID code that supports targets other than our familiar Calypso
+(namely, Hercules/Ulysse(s) and Calypso+) has been left completely unchanged;
+while none of this code exhibited any problems compiling for Linux, it is
+completely untested: we have neither the hardware nor any real knowledge of
+what it is and how it is supposed to work.  For this reason, Calypso is the
+only target platform which we can really vouch for as being supported by
+fluid-mnf.  See below regarding what works on D-Sample and what works on the
+more common Calypso+Iota+Rita platforms.
+
+Target-side components of FLUID
+===============================
+
+Like any other tool performing the same function, FLUID consists of not only
+the PC or Unix/Linux application, but also target-side code pieces which are
+fed either to the Calypso boot ROM or to FLUID's other bootloader
+(flash-resident or loaded via JTAG) and which run on the target during the
+flash programming or reading process.  In the case of FLUID, these target-side
+components are cmd.m0 and flash "method" drivers (amd.m0, intel.m0 etc),
+performing essentially the same function as loadagent.srec does for our own
+fc-loadtool.
+
+TI's original FLUID package fluid-2.27.zip contains both the sources for these
+components and the deployable *.m0 target binaries.  Openmoko left these *.m0
+target components of FLUID completely unchanged in their port, and we are doing
+likewise in fluid-mnf: aside from our cmd39.m0 concoction explained further
+below, all *.m0 files in the target-bin subdirectory in this fluid-mnf release
+are unchanged from TI's original delivery.  I did not even bother with setting
+up an environment to recompile them from source with TI's TMS470 toolchain.
+
+Search path for helper files
+============================
+
+FLUID needs to find the just-mentioned *.m0 target binaries as well as the
+devices.txt file as helper files.  TI's original code looks in the current
+directory, and also tries to look in the directory where the fluid.exe binary
+is located by extracting the path from argv[0] - but the latter method works
+only in the Windows culture, not Unix/Linux.
+
+Openmoko kept this helper file search logic completely unchanged in their
+version, and they installed both their fluid.exe binary and the helper files in
+/usr/sbin.  But simply running OM's fluid.exe (never mind the non-sensical .exe
+suffix on a Linux binary) from whatever current directory relying on the shell's
+PATH search does not work: argv[0] will be equal to just "fluid.exe" without
+any path, and TI's Windows-minded code unchanged by OM won't ever figure out
+that it needs to look in /usr/sbin for the needed helper files.  OM's official
+instructions were to cd to /usr/sbin and run fluid.exe from there - unbelievable
+bogosity.
+
+The present fluid-mnf port is made more Unix-proper in this regard: we put all
+needed helper files in a designated installation directory
+(/opt/freecalypso/fluid), and the code has been modified to look there instead
+of the usually-null path extracted from argv[0].  The tool still looks in the
+current directory first for every file: changes to TI's FLUID code architecture
+have been kept to a minimum.
+
+Calypso C05 vs. C035
+====================
+
+For all of its claims of device-independence and automagically supporting all
+of various targets, TI's original FLUID as we got it in fluid-2.27.zip fails to
+correctly support older Calypso boards with early Calypso C05 chips on them.
+First Calypso generations (C05 rev A and C05 rev B) have a maximum ARM7 clock
+frequency of 39 MHz, while on the later Calypso C035 (found in most mass-
+produced phones and modems) this maximum frequency has been lifted to 52 MHz.
+
+In TI's FLUID architecture, the target component 'cmd' (cmd.m0 built from cmd.c)
+configures and enables the Calypso DPLL as soon as the host tool tells it that
+the active target is Calypso rather than Ulysse(s).  The responsible function
+hardware_init_calypso() in target/cmd.c originally had code that configured
+this DPLL at 39 MHz - then Calypso C035 came along, and someone at TI merrily
+changed that DPLL setup constant from 39 MHz to 52 MHz.  So what happens then
+if someone runs TI's FLUID version 2.27 on an older C-Sample, D-Sample or
+Leonardo board that has a Calypso C05 chip on it?  Answer: it will produce an
+overclocked chip with unknown consequences - I am not willing to try it on our
+one and only D-Sample C05 board.
+
+Trying to improve the architecture of FLUID is strictly beyond the scope of what
+I set out to do in this fluid-mnf port, instead I just needed a way to safely
+run it on our D-Sample C05 board with minimal changes.  So I went for the
+minimally-invasive surgical approach:
+
+* cmd39.m0 is a modified version of cmd.m0, produced by copying cmd.m0 and
+  manually patching the one offending DPLL setup constant, restoring the older
+  39 MHz config.
+
+* fluid-mnf has an added option -oC that causes it to use cmd39.m0 instead of
+  regular cmd.m0.
+
+FLUID operating on D-Sample
+===========================
+
+For anyone lucky to have an original TI D-Sample board (either C05 or C035),
+the way FLUID works on it is really awesome:
+
+* Both boot entry methods work: fluid-mnf -oo goes through the Calypso boot ROM
+  (the older boot ROM version present in Calypso C05 is good enough), whereas
+  fluid-mnf -oO goes through the other FLUID bootloader, either flash-resident
+  or loaded via JTAG.  (I haven't tried the JTAG way, but fluid-mnf -oO works
+  on the D-Sample when the flash contains a build of our FC Magnetite
+  l1reconst-bl configuration.)  The extra -oC option is needed for D-Sample C05,
+  but won't be needed for D-Sample C035, if anyone has one.
+
+* FLUID (both TI's original and our fluid-mnf port) supports Calypso high baud
+  rates of 203125, 406250 and 812500 bps: just select the desired baud rate with
+  the -b option.  The baud rate switch is effected when the command interpreter
+  ('cmd' target code piece) is running on the target, which is itself loaded at
+  115200 baud.
+
+* The D-Sample board has an extra 14.745600 MHz crystal oscillator and a special
+  circuit (controlled by bits in a register mapped into Calypso nCS3 address
+  space) that can switch the Calypso clock input from the regular 13 MHz coming
+  from the RF section to this special 14.745600 clock.  Of course no GSM
+  functions can work in this state, but feeding this special clock to Calypso
+  allows its UARTs to produce "standard" baud rates of 230400, 460800 and 921600
+  bps!  This feature is apparently called XXO for eXternal Xtal Oscillator, and
+  is supported by FLUID, including our fluid-mnf port: just select the desired
+  baud rate with the -b option, and if the target is D-Sample, it will just
+  magically work.  (On more "mere mortal" Calypso targets the result will be a
+  spectacular failure instead.)
+
+* The D-Sample board also has a block of 16 debug LEDs controlled by another
+  register mapped into Calypso nCS3 address space, and FLUID's target-side
+  component (which we haven't modified except for the 39 MHz fix) displays
+  pretty dancing patterns on these LEDs as it does its work.
+