# HG changeset patch # User Mychaela Falconia # Date 1584241333 0 # Node ID 6cff3ee315e0f8a87d0bc48f124a114fc622cb55 # Parent b4fb0c7dfdf4cece7b49e7f0eabd21b75fa0b773 fluid-mnf/README: work in progress diff -r b4fb0c7dfdf4 -r 6cff3ee315e0 fluid-mnf/README --- 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. +