In the summer of 2019 we (FreeCalypso) had recovered a copy of TI's original
FLUID package including source, but this TI original FLUID source targets only
Windows, no Unix or Linux support included.  Back in 2007 or earlier Openmoko
had made their own port of FLUID to Linux and we have their Linux/ARM binary,
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.

Purpose and scope
=================

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.

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
by our own fc-loadtool, not FLUID.  The ONLY Calypso targets that are expected
to be supported by fluid-mnf (same as TI's original FLUID for Windows) are:

* TI's own D-Sample and Leonardo boards;
* A certain non-TI development board nicknamed Caramel which has a Leonardo
  clone as its core but has a D-Sample-like physical form factor;
* Openmoko GTA01 and GTA02 modems.

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.