The set of host tools built in this directory 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 the Compal family of basic
dumbphones, the Openmoko GTA0x GSM modem and the Pirelli DP-L10 feature phone.

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 /usr/local/share/freecalypso:

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-sw 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 will include prebuilt loadagent and compalstage binaries
in the target-binaries subdirectory.

Installing
==========

Just run 'make' and 'make install' as usual.  If the target-binaries directory
is present, your installation will be complete and ready to use.  If you are
building these pieces yourself from source, do a 'make' and 'make install' in
../target-utils, after you have the ARM7 gcc toolchain installed and working.

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.

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
   -----------------------------------
   Mot C11x/123		-h compal
   Mot C139/140		-h compal -c 1003
   Mot C155/156		-h c155
   Openmoko GTA02	-h gta02
   Pirelli DP-L10	-h pirelli

3. Cause the target device to execute its boot path.  Openmoko GTA0x and
   Pirelli DP-L10 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.

For other fc-loadtool options and fc-[ix]ram usage details, see the slightly
outdated README.old file.  For newer options added since that file was written,
see the source code.  I hope to write some real man pages eventually.

Openmoko GTA0x
==============

All of the above instructions assume that you are running these loadtools on a
general-purpose host system such as a GNU/Linux PC or laptop, and will
potentially use them to operate on multiple Calypso targets of different kinds.
If instead you are building loadtools to run on the application processor of a
smartphone such as Openmoko GTA0x, then it makes no sense for that special build
of loadtools to support any target other than the specific modem in that
smartphone.  Loadtools can be built with compalstage support excluded and with
GTA0x-specific modem power control included instead.  This build will still
include a bunch of functions of no relevance to GTA0x, but oh well..

To build loadtools for the GTA0x AP, you'll need to make the following
modifications to the Makefile:

* Change the CC= line to point to the appropriate cross-compiler (which you'll
  need to provide yourself);

* Change the CFLAGS= line: add the right options to target the ARM920T core in
  the GTA0x AP (e.g., -march=armv4t -mtune=arm920t), and add -DGTA0x_AP_BUILD
  to enable some code that makes sense only when running on the GTA0x AP.

* Change EXTRA_OBJ= from listing compalload.o to listing compaldummy.o and
  gtapower.o instead.

See gta-ap-build.sed for an example.