The loadtools subset of FreeCalypso host tools consists of:

fc-loadtool		The tool for operating on Calypso GSM devices at a low
			level.  After "breaking" into the target GSM device in
			its boot process and getting FreeCalypso loadagent
			running on the target (out of Calypso internal RAM, aka
			IRAM), loadtool presents an interactive command prompt
			with commands for peeking and poking registers and most
			importantly, reading and writing any part of the
			device's non-volatile flash memory.

fc-iram & fc-xram	These utilities are intended for FreeCalypso developers
			only.  They load an S-record code image into IRAM or
			XRAM, respectively, induce a transfer of control to the
			loaded code, and then drop into a serial line pass-thru
			mode for the operator to interact with the thus loaded
			target code.

The currently supported target devices are:

1) All Calypso devices (preferably with Iota ABB so we can cleanly power off
   after we are done) that have Calypso boot ROM (version 0200 or 0300) enabled
   by nIBOOT strapping on the board.  This category includes TI and FreeCalypso
   development boards, several modems (Openmoko GTA01/02, Huawei GTM900, Tango)
   and other devices.

2) Motorola C1xx and Sony Ericsson J100 phones made by Compal: these phones do
   NOT have Calypso boot ROM enabled, but they provide a different way of
   gaining serial code download access which is supported by our tools.

All tools in the FreeCalypso loadtools suite work by feeding pieces of code to
the target device as it boots, preventing the booting of its regular firmware
and diverting control to these externally-loaded code pieces.  These pieces of
ARM7 target code need to be installed on the host system running loadtools,
normally in /opt/freecalypso/target-bin:

loadagent	This is the "agent" code that runs on the target device when
		fc-loadtool is operating on it: loadtool carries out its
		operations by sending commands to loadagent.  There is only one
		version of loadagent for all currently supported Calypso
		targets: loadagent does not access any resources outside of the
		Calypso chip itself unless commanded to do so, and loadtool
		supports different target devices with different hardware
		configurations by sending different commands to loadagent as
		appropriate.

compalstage	For Compal phones only: a little piece of code that is fed to
		the original fw's bootloader via the serial download protocol
		provided by the latter; it re-enables the Calypso chip boot ROM
		and jumps to it, allowing our loadagent to be loaded in the
		same way as on freedom-enabled devices.

If you are working with a development snapshot of the freecalypso-tools source
tree, you will need to compile and install a GNU cross-compiler toolchain
targeting ARM7 (see ../toolchain) and then use that toolchain to compile
loadagent and compalstage (see ../target-utils) before you can successfully use
loadtools to operate on a target device.  End-user oriented releases of
FreeCalypso host tools include prebuilt loadagent and compalstage binaries.

Basic usage
===========

The steps for bringing up fc-loadtool to operate on a target Calypso device are
as follows:

1. If you are using a USB serial adapter, or operating on a Pirelli phone that
   has one built in, connect the USB side first so that the necessary
   /dev/ttyUSB* device node appears.  If you are working with a target such as
   FCDEV3B or D-Sample on which both Calypso UARTs are equally accessible with
   equal convenience, you can arbitrarily pick either one for fc-loadtool - it
   will work exactly the same through either port.

2. Run fc-loadtool like this:

   fc-loadtool $TARGETOPT /dev/ttyXXX

   Change /dev/ttyXXX to the actual serial port you are using, and change
   $TARGETOPT to:

   Device		Needed options
   -----------------------------------
   FreeCalypso FCDEV3B	-h fcfam
   Huawei GTM900	-h gen8
   Mot C11x/123		-h compal
   Mot C139/140		-h compal -c 1004
   Mot C155/156		-h c155
   Mot V17x		-h c155
   Mot W220		-h w220
   Openmoko GTA01/02	-h fic
   Pirelli DP-L10	-h pirelli
   Sony Ericsson J100	-h compal -c 1004
   TI D-Sample		-h dsample
   TI Leonardo		-h leonardo
   Tango modem		-h gen8

   Please refer to the Loadtool-targets article for more information about -h
   targets.

3. Cause the target device to execute its boot path.  TI/Openmoko/FreeCalypso
   and other sensible targets have the Calypso boot ROM enabled, and will
   interrupt and divert their normal boot path when they "hear" the beacons
   which fc-loadtool will be sending down the serial line.  Compal phones have
   this boot ROM disabled at the board level, but their standard firmware
   includes a flash-resident bootloader that offers a different way of
   interrupting the boot path and loading code over the serial line;
   fc-loadtool will be set up to speak the latter protocol when run with the
   corresponding options from the table above.

You will see messages showing fc-loadtool's progress with feeding first
compalstage (if needed), then loadagent (always needed) to the target device,
followed by some target-specific initialization done via loadagent commands.
If all of the above succeeds, you will land at a loadtool> prompt.  Type
'help', and it will guide you from there.  Alternatively, you can familiarize
yourself with loadtool commands and operations without actually running it by
reading the loadtool.help text file.

fc-loadtool batch mode
======================

In addition to the interactive mode described above, fc-loadtool can be used in
a scripted or batch mode where it makes contact with the target device as it
boots, interrupts and diverts the boot process to loadagent, executes a given
command or script, cleans up the target state as appropriate (usually powers
off) and exits.  This mode is used by the FreeCalypso factory for initial flash
programming on the device production line, but it can also be used by end users
to install firmware updates in a more automated manner.

To use the batch mode, specify an exec (command script), flash or flash2 command
on the fc-loadtool invokation command line after the target tty port name.  For
backward compatibility, if only one extra argument (in the UNIX process argument
list sense) is given after the target tty port name, it is interpreted as the
name of the command script to execute, as if it was preceded by 'exec'.  Only
flash and flash2 commands can be given directly without going through a script;
if you need to run other commands in batch mode, you will need to put them into
a script file.

Command line options
====================

The fc-loadtool command lines shown above will usually be sufficient.  However,
here is the complete command line description for all 3 tools:

fc-iram [options] ttyport iramimage.srec [2ndprog]
fc-xram [options] ttyport xramimage.srec [2ndprog]
fc-loadtool [options] ttyport [batch command]

The available options are common for all 3 utilities, with a few noted
exceptions:

-a /path/to/loadagent

	This option applies only to fc-loadtool and fc-xram.  It specifies the
	pathname at which the required loadagent.srec image should be sought,
	overriding the compiled-in default.

-b baud

	This option is common for all 3 utilities.  It selects the baud rate
	to be used when pushing the IRAM image to the Calypso boot ROM.  In the
	case of fc-iram, the selected baud rate will be in effect when the
	loaded IRAM image is jumped to and fc-iram drops into the serial tty
	pass-thru mode; in the case of fc-loadtool, it will be the initial baud
	rate for communicating with loadagent, which can be switched later with
	the baud command.  The default is 115200 baud.

-B baud (fc-loadtool)

	This option is specific to the batch mode of fc-loadtool, and has no
	effect when no batch mode command script is specified on the command
	line.  In the batch mode this option commands a baud rate switch to be
	performed before the command script is executed.

-B baud (fc-xram)

	This option is specific to fc-xram.  It selects the baud rate to be
	used when pushing the XRAM image to loadagent.  If no -B option is
	specified, fc-xram will communicate with loadagent at the same baud
	rate that was used to load loadagent itself via the Calypso boot ROM
	download protocol, i.e., the rate selected with -b, defaulting to
	115200 baud if no -b option was given either.  Neither -b nor -B
	affects the baud rate that will be in effect when the loaded XRAM image
	is jumped to and fc-xram drops into the serial tty pass-thru mode: that
	baud rate independently defaults to 115200 baud and can only be changed
	with the -r option.

-c <compalstage flavor>

	This option is common for all 3 utilities.  It directs the tools to
	perform the Compal loading stage before proceeding with the Calypso
	boot ROM serial protocol, and selects the "flavor" of compalstage to
	use.  As you can see in the source, compalstage is built in 3 different
	versions, for different C1xx models which exhibit different quirks.

	This option overrides the compal-stage setting given in the hardware
	parameter file selected with -h or -H; the -c or -C option must be given
	after -h or -H in order to take effect.  -c none disables the Compal
	stage and causes the tools to proceed directly to the Calypso boot ROM
	phase, even on targets for which the hardware parameter file specifies
	compal-stage.

-C /path/to/compalstage-binary

	This option is just like -c, except that the given argument is used
	directly as the compalstage binary file pathname (absolute or relative)
	without checking or alteration.

-h hwtype

	This option is common for all 3 utilities.  It selects the specific
	target device configuration to be used.  More precisely, it constructs
	a pathname of the form /opt/freecalypso/loadtools/%s.config, where %s
	is the argument given to this option, and uses that file as the hardware
	parameter file.

	The hardware configurations known to the present release of FreeCalypso
	loadtools are listed in the Loadtool-targets article.

-H /path/to/hwparam-file

	This option is just like -h, except that the given argument is used
	directly as the hardware parameter file pathname (absolute or relative)
	without alteration.

-i num

	This option is common for all 3 utilities.  It specifies the interval
	in milliseconds at which the tool will send "please interrupt the boot
	process" beacons out the serial port, hoping to catch the Calypso
	internal boot ROM.  The default is 13 ms.

-j

	This option is specific to fc-xram; it selects the special JTAG mode.
	In this mode the jump command to start executing the loaded image is
	skipped and the target is left in loadagent, allowing the developer to
	connect via JTAG, halt the ARM7 core, set whatever breakpoints or
	watchpoints are needed and resume at the image start address.

-P <boot control name>

	This option is common for all utilities in the loadtools suite; it
	tells the tools to perform target boot control as described in the
	Target-boot-control article.

-r baud	(fc-loadtool)

	This option is specific to fc-loadtool.  It causes the tool to skip its
	normal steps of feeding loadagent and possibly compalstage to the target
	via special serial protocols, and instead assume that the target is
	already running loadagent, communicating at the specified baud rate.
	In other words, reattach to an already running loadagent.  Use this
	option if your fc-loadtool session has been terminated ungracefully and
	you would like to reattach and resume, rather than forcibly reset the
	target by yanking and reinserting the battery and restart from the
	beginning.

-r baud	(fc-xram)

	This option is specific to fc-xram.  It selects the serial line baud
	rate which should be set just before the loaded XRAM image is jumped
	to; the default is 115200 baud.

-t num

	This option is common for all utilities in the loadtools suite; it sets
	the timeout to be applied to the wait for the Calypso boot ROM response.
	Normally the tools wait forever for the Calypso boot ROM to respond to
	the interrupt-boot beacons that are being sent continuously at the
	interval set with -i; this -t option sets a timeout in ms instead.
	This option is intended for automated (unattended) environments where
	it is used together with some kind of target boot control, either -P or
	external.

fc-iram & fc-xram 2nd program invokation
========================================

Our fc-iram and fc-xram utilities can take two possible actions after they have
loaded the specified S-record image into RAM:

* The default action, in the absence of additional command line arguments, is
  to drop into a serial tty pass-thru mode.

* The alternative action is to invoke a 2nd program and pass the serial
  communication channel to it.  This 2nd program invokation facility is intended
  primarily for passing the serial communication channel to rvinterf or rvtdump
  from the FreeCalypso host tools suite, not for launching any arbitrary
  3rd-party programs from fc-xram or fc-iram.

This feature was originally implemented in fc-xram only, and the intended usage
scenario is that one builds a version of one of our FreeCalypso GSM firmwares
(or some subset thereof, such as an "in vivo" FFS editing agent) in the ramImage
configuration, fc-xram is used to load that ramImage into the target device,
and then the serial communication channel (RVTMUX) is immediately taken over by
rvinterf or rvtdump.

This second program invokation capability was later extended to fc-iram for no
purpose other than to facilitate a boot hack that was only needed on one (1)
defective FCDEV3B board - see the Flash-boot-wa article.