--- a/loadtools/README	Wed Sep 11 17:58:55 2013 +0000
+++ b/loadtools/README	Fri Sep 13 16:47:09 2013 +0000
@@ -26,6 +26,7 @@
 			(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
@@ -44,6 +45,7 @@
 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
@@ -75,6 +77,14 @@
    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
@@ -84,6 +94,7 @@
    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:
@@ -101,6 +112,7 @@
 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:
@@ -109,13 +121,124 @@
 
 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 [runbaud]
+fc-loadtool [options] ttyport
+
+The last optional argument to fc-xram selects the serial line baud rate which
+should be set just before the loaded XRAM image is jumped to; the default is
+115200 baud.
+
+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
+	by the last optional argument on the fc-xram command line.
+
+-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 knows 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.