FLUID source found

[Mychaela Falconia]

Hello FreeCalypso community,

Six years after having implemented our own replacement for it, a few
days ago I was finally able to get a hold of TI's official GSM board
flashing tool called FLUID:

ftp://ftp.freecalypso.org/pub/GSM/TI_tools/fluid-2.27.zip

The package contains the official Windows binary, the source from which
it was built (yay!), and both binaries and sources for the target-side
components.

This original TI software is being archived solely for historical
lorekeeping purposes - for all practical use our own fc-loadtool is
the tool that actually works.  If someone feels like giving FLUID a
try just for the heck of it, here are the issues you will encounter:

1) Although it is a historical fact that some people in the past have
ported FLUID (the PC-side program) from Windows to Unix/Linux (OM is
one company known to have done it internally), we don't have any
sources for any such non-TI ports - the source we have only supports
Win32 APIs for serial port access and timers and whatnot, and there is
no code to do it the Unix/Linux way with termios - thus anyone who
desires such a port would have to redo the porting work themselves.

2) If you get past the OS porting issue or run the existing Windows
fluid.exe binary as-is (maybe it will work under Wine, or using a real
Windows machine), it won't work with the S71PL129N flash chip on the
FCDEV3B unless you change some of the flash poking code that goes into
cmd.m0, i.e., modify cmd.c and recompile the cmd.m0 payload piece.

Regarding the flash chip issue: I have worked with AMD and later
Spansion flashes since year 2000, and every AMD flash datasheet I ever
had to scrutinize says quite clearly that the "magic" command write
addresses are 0x555 and 0x2AA on byte-wide devices, or the same
shifted left one bit on 16 bit wide devices, thus in the Calypso ARM7
address space the correct "magic" command write addresses for AMD
flash are 0xAAA and 0x554 from the beginning of the flash bank.  Yet
TI's code, both in FLUID and in the FFS firmware component, uses
0xAAAA and 0x5555 instead.  Aside from doing a 16-bit write at an odd
address (there is no effect as the low bit gets ignored by the
hardware, but seriously Mads, you could have done better), there is an
extra address nibble added, i.e., address bits [15:12] are driven as
1010/0101 instead of 0000.  I don't know why TI did it this way -
perhaps their way is needed for SST flash, which is apparently AMD-like
but not quite the same.  I don't have any SST flashes laying around
to check (neither hardware nor datasheets), so I really don't know.

Despite being officially incorrect per every AMD flash datasheet I have
seen, TI's way apparently worked with all of the old AMD flash chips
before the AMD->Spansion transition, with early Spansion flash chips
and with the Samsung K5A3281CTM flash+RAM chip used by Openmoko, but
it does NOT work with Spansion PL-N flash, or at least with the
S71PL129NC0HFW4B part that is seen in most Pirelli DP-L10 specimen and
used on our own FCDEV3B.  This newer Spansion flash chip is more
strict about what command sequences it accepts, and it requires AMD's
proper way, not TI's slightly-off way.

Our FreeCalypso flashing tools (fc-loadtool and its loadagent back end)
were never affected because I used AMD's proper way from the beginning
(might not work with SST flashes, but we don't have any such flashes
among our supported repertoire of real-life Calypso targets), but on
the firmware side (FFS component) I had to modify TI's autodetection
code and their AMD multibank driver to issue proper AMD flash command
sequences - the same change which Foxconn/Pirelli had to make to their
fw, as they used the same chip.  If anyone feels like making the same
fix in FLUID just for fun, change the setting of bss->hexAAAA and
bss->hex5555 in the hardware_init() function in target/cmd.c to 0xAAA
and 0x554, respectively, then recompile cmd.m0 with TI's compiler.

But aside from the lack of support for Unix/Linux hosts and for newer
flash chips, how does FLUID compare against our fc-loadtool?  What we
have here are two independently implemented solutions to the same
problem, developed by different people (FLUID was written by Mads
Meisner-Jensen, FC tools by yours truly) at different times (about 12 y
apart, 2001 vs. 2013) facing different requirements (Mads needed to
support TI's in-house development boards and provide a starting point
for TI's customers, whereas I needed to support OM GTA02 and Pirelli
DP-L10 in 2013), thus the two designs are quite different.

As required by the nature of the problem to be solved (flashing Calypso
GSM devices), both FLUID and fc-loadtool consist of a host component
(the program you run on the host) and target-side components: cmd.m0
and amd.m0/intel.m0/etc in the case of FLUID and loadagent.srec for
fc-loadtool.  But that is where the similarity ends and implementation
differences begin.  Both tools support gaining access to the target
via the boot ROM on nIBOOT-enabled Calypso devices, but the other
supported methods are different: FLUID supports entry by way of the
bootloader stage embedded in TI's firmwares and by way of JTAG
(halting the Calypso via TI's XDS510 or XDS560 hardware and CCS
software and then loading a COFF image built in the FLUID suite),
whereas our fc-loadtool supports Compal's non-TI bootloader protocol.

The ad hoc serial protocol between the host tool and the target-side
component appears to be more efficient (optimized for speed) in TI's
version: it is binary (no ASCII overhead), and even includes some kind
of compression.  In contrast, the interface between fc-loadtool and
loadagent is ASCII-based, because instead of optimizing for speed, I
optimized for ease of development and modular testing: loadagent can
be loaded via fc-iram and exercised manually without fc-loadtool.
Like all FC target-utils programs, loadagent has a "terminal" interface
that allows a human operator to type commands manually with echo and
minimal editing, and fc-loadtool talking to loadagent simulates human
command typing: it sends command strings ending with a carriage return
and collects the echo from the target, then parses further target output.
When binary images are transferred, they are transferred in lines
corresponding to S-records, and each byte is transmitted as two hex
characters, i.e., a 2x+ increase in the number of bytes transferred.
(It is a little more than 2x because of line breaks and headers on
each line.)  The binary protocol used by FLUID is clearly more
efficient, but when I wrote fc-loadtool and loadagent in 2013, I was
not in any position to care about maximizing efficiency, instead my
goal was to develop a non-OBB tool that could be used by people like
me who took a vow to not use OBB software.

As for OBB's flashing tools, those are not in any position to compete
with either FLUID or fc-loadtool: they only support Intel flash on
Compal phones, no AMD flash support at all (meaning no flash writing
support for FCDEV3B, Openmoko or GTM900 targets), and when it comes to
the very brickable Compal phones, OBB's flashing tools don't have any
of the provisions for minimizing the bricking vulnerability window
that are implemented in our tools.

In any case, our fc-loadtool is now production software in the most
literal sense of the word (it is used to program FreeCalypso boards on
the device production line) and also an end user tool that is useful
beyond the scope of FreeCalypso proper (works great for removing
carrier branding from Mot C139 phones and reflashing them with
Motorola's non-carrier-branded, non-SIM-locked "vanilla" firmware),
thus we are sticking with it.  Implementing a more efficient serial
protocol inspired by TI's FLUID is an idea to be potentially tackled
at a later time - too many higher-priority tasks right now.

Hasta la Victoria, Siempre,
Mychaela aka The Mother