You are looking at the source for the FreeCalypso loadtools package.  You may
have downloaded it either as a separate package or as part of the larger
freecalypso-sw suite.

The tools in this package are written to run on some Unix/Linux machine
(normally a PC/Linux desktop or laptop) that acts as a host for operating on
Calypso target devices.  All of these tools communicate with the Calypso target
through a serial port; each tool begins its operation by sending special byte
sequences to this serial port which are designed to interrupt the Calypso
device boot process in the ROM bootloader.

Three utilities are currently built as part of FreeCalypso loadtools:

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.

fc-loadtool		This utility is intended for both developers and end
			users.  After establishing communication with the
			target, fc-loadtool drops into interactive operation.
			Once at the loadtool> prompt, you can peek and poke
			registers, and most importantly, dump (read) and load
			(program) the flash memory of the target device.

Loadagent

Both fc-loadtool and fc-xram work by first feeding a FreeCalypso-developed
program called loadagent to the Calypso ROM bootloader; all further operations
(loading code into XRAM or flash) are done via this loadagent.  An S-record
image of the loadagent program is required for fc-loadtool and fc-xram to work.
That program is in turn built with the ARM7 toolchain.

If you are working with the full freecalypso-sw suite, you presumably already
have the proper ARM7 toolchain built and installed.  To build loadagent, simply
run 'make' in the ../target-utils tree.

If you have downloaded a separately-packaged version of FreeCalypso loadtools,
the package should have a prebuilt loadagent.srec image included, sparing
non-developer users the nontrivial hurdle of having to build and install a
special cross-compilation toolchain.  The same loadagent binary is designed to
work on all supported Calypso targets.

Building and installing loadtools

Normally the machine on which you build and install fc-loadtools would be your
PC/Linux desktop or laptop, the system you would use to program or otherwise
interact with Calypso phones by way of appropriate USB-to-phone cables.  Just
like loadagent, the host utilities you are going to build and install aren't
specific to a particular target device; instead you will select the target
device at run time via a command line option.  Hence you can build and install
the host utilities (usual 'make' and 'make install') without limiting your
setup to just one target phone type.

However, if your intended target device is an Openmoko GTA02 (or GTA01)
smartphone, there is one additional complication: one cannot directly access
the Calypso part of these phones from the outside without going through the
phone's application processor first.  If you would like to use fc-loadtool to
read or write the GSM flash memory of your GTA0x (load a different firmware
image, dump the flash file system for backup or examination, restore a previous
backup etc), there are two ways to do it:

1. The recommended way for FreeCalypso developers is to get a special serial
   cable (low voltage, as in 3.3V or lower - *NOT* RS-232 levels - please don't
   fry your precious phone!) that would plug into the 2.5mm jack on the left
   side of the phone that is normally intended for a wired headset.  This way
   you can use your regular build of fc-loadtool (and fc-iram & fc-xram) on
   your PC/Linux (or other) development host, no need to build anything for
   GTA0x AP, and all communication happens directly between your development
   host and the Calypso part of your target phone - not going through the AP
   at all.  You still need working software on the GTA0x AP to do battery
   management, to power the Calypso block on and off, and to enable the headset
   jack "download" path, but it is much less burdensome than having to do the
   actual FreeCalypso work from the AP.

2. If you are an end user who simply wishes to reflash a different GSM firmware
   image, it can be done from inside the phone (from the AP) without having to
   acquire special hardware (as in the cable described above).  However, the
   trade-off is that in return for saving on the special hardware, you have to
   do more work on the software.  You will have to use a cross-compiler
   targeting the ARM/Linux AP environment (*not* the ARM7 cross-compiler used
   for the GSM firmware itself!) to build fc-loadtools to run on the GTA0x AP.

Building loadtools for GTA0x AP

If you've decided 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= to EXTRA_OBJ=gtapower.o, i.e., add gtapower.c (compiling
  into gtapower.o) to the build.

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

Running fc-loadtool

Once you've got loadtools built and installed, you can run fc-loadtool
as follows:

To operate on a Pirelli DP-L10 that appears as /dev/ttyUSB0:

fc-loadtool -h pirelli /dev/ttyUSB0

To operate on the Calypso block of a GTA02, accessing it from an external
PC/Linux host via a USB-to-headset-jack serial cable that appears as
/dev/ttyUSB0:

fc-loadtool -h gta02 /dev/ttyUSB0

To operate on the Calypso block of a GTA02, running fc-loadtool from inside the
phone, i.e., from the AP of the same GTA02:

fc-loadtool -h gta02 /dev/ttySAC0