--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/loadtools/README	Sun Sep 01 12:54:42 2013 +0000
@@ -0,0 +1,121 @@
+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