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.

Having the headset jack do double duty as a programming port is actually a
standard practice in the world of basic (non-smart) cellular phones, and
furthermore, the pinout used by FIC on the GTA0x phones just happens to be
exactly the same as that used by Compal/Motorola - hence the same headset jack
serial cables that are used by OsmocomBB with the latter phones (the famous
"T191 unlock cable") will also work for connecting from an external host
directly to the Calypso part of GTA0x phones.

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

The usb2serial chip inside the phone is bus-powered and will be visible as
/dev/ttyUSBx whether the phone battery is present or not.  There are two ways
to break into the bootloader:

1. Run the fc-loadtool command given above with the USB cable connected, but no
   battery present.  Once loadtool says "Sending beacons to <port>", insert the
   battery.

2. Connect the USB cable to a powered-on phone running its original factory
   firmware.  (If the phone was off, it will power up and boot in the "charging
   only" mode - it is not possible for a Calypso/Iota phone to be completely
   off when both the battery and the charging voltage are present.)  Run
   fc-loadtool as above - it will start sending its beacons, which will be
   ignored by the running fw.  Then execute the "power off" operation from the
   UI (unlock the keypad, then press and hold the red button).  The presence of
   USB VBUS (used as the charging power source on this phone) will turn the
   power-off into a reboot, and you'll break into the bootloader.

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

Run the above command first, then power on the GSM modem from the AP - or power
it off, then on if it was on already.  The "download" path needs to be enabled
(controlled from the AP) and fc-loadtool needs to be running on the external
host when the modem is powered on.

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

In this last scenario the specially built version of fc-loadtool running on the
AP takes care of manipulating the modem power to induce entry into the
bootloader, thus no extra manual steps are needed.

See loadtool.help for a detailed description of the functionality and commands
that are available once loadtool is running and communicating with loadagent on
the target device.

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
fc-xram [options] ttyport xramimage.srec [2ndprog]
fc-loadtool [options] ttyport

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

	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.

-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 /usr/local/share/freecalypso/%s.config, where %s
	is the argument given to this option, and uses that file as the hardware
	parameters file.

	The hardware configurations known to the present release of FreeCalypso
	loadtools are gta02 and pirelli.

-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.

-n

	This option does anything only when loadtools have been compiled to run
	on GTA0x AP.  If you've compiled loadtools with the -DGTA0x_AP_BUILD
	option, it has an effect of making each tool automatically toggle the
	modem power control upon startup, removing the need for manual
	sequencing of the Calypso boot process.  This -n option suppresses that
	action, making the AP build behave like the standard build in this
	regard.

-r baud

	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.

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

The fc-xram utility can take two possible actions after it has loaded the
specified S-record image into XRAM:

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

* 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 software suite, not for launching any arbitrary 3rd-party
  programs from fc-xram.

The intended usage scenario is that one builds a version of the FreeCalypso GSM
firmware (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.

More detailed usage instructions will be written when the rvinterf tools reach
a point of being usable by more than just the original developer; until then,
read the source code.