--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/loadtools/README	Sat Jun 11 00:13:35 2016 +0000
@@ -0,0 +1,265 @@
+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.
+
+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.
+
+-c <compalstage flavor>
+
+	This option is common for all 3 utilities.  It directs the tools to
+	perform the Compal loading stage before proceeding with the Calypso
+	boot ROM serial protocol, and selects the "flavor" of compalstage to
+	use.  As you can see in the source, compalstage is built in 3 different
+	versions, for different C1xx models which exhibit different quirks.
+
+	This option overrides the compal-stage setting given in the hardware
+	parameter file selected with -h or -H; the -c or -C option must be given
+	after -h or -H in order to take effect.  -c none disables the Compal
+	stage and causes the tools to proceed directly to the Calypso boot ROM
+	phase, even on targets for which the hardware parameter file specifies
+	compal-stage.
+
+-C /path/to/compalstage-binary
+
+	This option is just like -c, except that the given argument is used
+	directly as the compalstage binary file pathname (absolute or relative)
+	without checking or alteration.
+
+-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
+	parameter file.
+
+	The hardware configurations known to the present release of FreeCalypso
+	loadtools are listed in the "Basic usage" section above.
+
+-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 (see the corresponding section below).  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	(fc-loadtool)
+
+	This option is specific to fc-loadtool.  It causes the tool to skip its
+	normal steps of feeding loadagent and possibly compalstage to the target
+	via special serial protocols, and instead assume that the target is
+	already running loadagent, communicating at the specified baud rate.
+	In other words, reattach to an already running loadagent.  Use this
+	option if your fc-loadtool session has been terminated ungracefully and
+	you would like to reattach and resume, rather than forcibly reset the
+	target by yanking and reinserting the battery and restart from the
+	beginning.
+
+-r baud	(fc-xram)
+
+	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.
+
+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.