--- a/loadtools/Makefile	Mon Sep 02 03:07:07 2013 +0000
+++ b/loadtools/Makefile	Tue Sep 03 07:31:26 2013 +0000
@@ -3,7 +3,7 @@
 PROGS=	fc-iram fc-loadtool fc-xram
 LASRC=	../target-utils/loadagent
 SCRIPTS=scripts/gta02.config scripts/k5a3281.init scripts/pirelli.config \
-	scripts/pirelli.init
+	scripts/pirelli.init loadtool.help
 INSTBIN=/usr/local/bin
 INSTSCR=/usr/local/share/freecalypso
 EXTRA_OBJ=
@@ -13,9 +13,9 @@
 
 LOADTOOL_OBJS=	crc32tab.o defpath.o flerase.o flprogbin.o flprogsrec.o \
 		flutil.o hexdecode.o hwparam.o labaud.o ltdispatch.o ltdump.o \
-		ltexit.o ltflash.o ltmain.o ltmisc.o ltpassthru.o ltscript.o \
-		romload.o sercomm.o srecreader.o tpinterf.o tpinterf2.o \
-		tpinterf3.o ${EXTRA_OBJ}
+		ltexit.o ltflash.o lthelp.o ltmain.o ltmisc.o ltpassthru.o \
+		ltscript.o romload.o sercomm.o srecreader.o tpinterf.o \
+		tpinterf2.o tpinterf3.o ${EXTRA_OBJ}
 
 XRAM_OBJS=	chainload.o clmain.o defpath.o hexdecode.o hwparam.o \
 		hwparamstubs.o initscript.o labaud.o romload.o sercomm.o \

--- a/loadtools/defpath.c	Mon Sep 02 03:07:07 2013 +0000
+++ b/loadtools/defpath.c	Tue Sep 03 07:31:26 2013 +0000
@@ -6,3 +6,4 @@
 
 char default_helpers_dir[] = "/usr/local/share/freecalypso";
 char default_loadagent_image[] = "/usr/local/share/freecalypso/loadagent.srec";
+char loadtool_help_file[] = "/usr/local/share/freecalypso/loadtool.help";

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/loadtools/loadtool.help	Tue Sep 03 07:31:26 2013 +0000
@@ -0,0 +1,270 @@
+This is the help file for fc-loadtool.  See lthelp.c for the code
+that parses and displays it.  The parsing code is the only
+documentation for the format of this help file - if you are going to
+edit this help text, read the parsing code first.
+
+=== main
+This utility allows you to perform the following operations
+on your Calypso GSM device:
+
+* Peek and poke registers
+* Dump any part of memory
+* Read and program flash
+
+See the following help topics for more information:
+
+help peekpoke		Register peek and poke commands
+help flash		Flash operation commands
+help all		List of all implemented commands
+help exit		Controlling the cleanup on exit
+
+=== all
+baud		Switch the serial comm with loadagent to a different baud rate
+crc32		Get CRC-32 of a memory area on the target
+dieid		Read the Calypso die ID
+dump		Dump a target memory region in hex and ASCII
+dump2bin	Dump a target memory region to a file in binary format
+dump2srec	Dump a target memory region to a file in S-record format
+exec		Execute a command script
+exit		Exit from loadtool and clean up the target device state
+flash		Flash operations
+flash2		Operations on the 2nd flash bank (Pirelli phone only)
+quit		Alias for exit
+r8		Read an 8-bit register or memory location
+r16		Read a 16-bit register or memory location
+r32		Read a 32-bit register or memory location
+w8		Write an 8-bit register or memory location
+w16		Write a 16-bit register or memory location
+w32		Write a 32-bit register or memory location
+
+To get help on any command, type help and the command keyword.
+
+=== baud
+baud		Display the current baud rate
+baud <rate>	Switch the baud rate to <rate> (number in bps)
+
+The supported baud rates are:
+
+Standard: 19200, 38400, 57600, 115200
+Calypso special: 203125, 406250, 812500
+
+The baud command coordinates the necessary simultaneous switching of the
+baud rate on both the host and the target (loadagent).  Loadagent always
+supports all of the listed rates and will switch happily, but in the case
+of the higher non-standard baud rates fc-loadtool has no way of knowing
+ahead of time whether or not the requested baud rate is supported by your
+usb2serial adapter or whatever other serial port hardware and driver
+you are using.  If the baud rate switch fails, the communication link with
+the target will be broken and fc-loadtool will exit ungracefully.
+
+=== crc32
+crc32 hex-start hex-len
+
+The first argument is the starting target memory address in hex; the second
+argument is the length of the area to CRC, also in hex.  The command will be
+sent to loadagent; CRC-32 of the requested range will be computed on the target
+and displayed in hex.
+
+=== dieid
+dieid			Display the Calypso die ID
+dieid <filename>	Display the Calypso die ID, and also save it in the
+			named file
+
+The Calypso die ID resides in 4 16-bit registers at target addresses
+0xFFFEF010 through 0xFFFEF016.  It is displayed on the terminal and optionally
+saved to a file in this simple form:
+
+FFFEF010: xxxx
+FFFEF012: xxxx
+FFFEF014: xxxx
+FFFEF016: xxxx
+
+=== dump
+dump hex-start hex-len
+
+The first argument is the starting target memory address in hex; the second
+argument is the length of the area to dump, also in hex.  The dump will be
+displayed on the terminal in hex and ASCII.
+
+=== dump2bin
+=== dump2srec
+dump2bin hex-start hex-len outfile
+dump2srec hex-start hex-len outfile
+
+The first argument is the starting target memory address in hex; the second
+argument is the length of the area to dump, also in hex; the third argument
+is the name of the output file to be created/written.  The dump will be saved
+in binary or S-records as per the chosen command, always in the native byte
+order of the Calypso ARM7 target (little-endian).
+
+=== exec
+exec <script-file>
+
+Read and execute commands from the named file.  If the given file name contains
+no slashes, the script file is sought in the default directory (normally
+/usr/local/share/freecalypso unless changed in the code); otherwise the given
+name is used directly as the pathname.
+
+=== exit
+=== quit
+exit		Clean up the target in the default manner and exit
+exit bare	Exit loadtool without doing anything to the target
+exit jump0	Exit loadtool and command the target to reboot via jump to 0
+
+The default method of cleaning up the target device state upon exit is set
+in the hardware parameters file selected with the -h or -H command line
+option; it is the exit-mode setting.  On the Pirelli phone the default exit
+mode is jump0: it causes the phone to reboot and enter the "charging boot"
+mode, as the USB cable is connected and VBUS is present.
+
+If your device is a GTA02 and you are running fc-loadtool from inside the phone
+(from the AP), the exit command will power off the modem from the AP.  If you
+are talking to GTA02 Calypso from an external host via the headset jack, there
+is nothing that fc-loadtool can currently do to power the modem off (exit is
+the same as exit bare in this case) - power it off yourself from the AP.
+
+If you do an exit bare without powering the target device off in some other
+way, the device will still be running loadagent, which is probably not what you
+want.  However, it is the proper exit mode if you have powered off or reset the
+target device by brute force (yanking the battery).
+
+=== flash
+=== flash2
+The primary end use of fc-loadtool is for reading and writing the NOR flash
+memories of the supported GSM devices.  The GTA0x GSM modem has only one 4 MiB
+flash bank (as in chip select), and is manipulated with the flash command.
+The Pirelli phone has two flash banks (as in chip selects) of 8 MiB each; they
+are manipulated with the flash and flash2 commands.
+
+The following flash operations are available:
+
+flash blankchk		Blank-check a region of flash
+flash dump2bin		Dump flash content to a file in binary format
+flash dump2srec		Dump flash content to a file in S-record format
+flash erase		Erase a region of flash
+flash info		Display flash configuration info
+flash program-bin	Program flash with a binary file
+flash program-m0	Program flash with an image in TI's *.m0 format
+flash program-srec	Program flash with an image in standard S-record format
+flash quickprog		Program a few flash words from the command line
+flash sectors		Display the list of flash sector addresses and sizes
+
+Substitute flash2 instead of flash when operating on the 2nd flash chip select
+of Pirelli-style flash memory configurations.  Prepend help before a command to
+get usage information, e.g., help flash program-bin.
+
+=== flash:blankchk
+flash[2] blankchk hex-start-offset hex-length
+
+Blank-checks an area of flash starting at the specified hex offset (from the
+base address of the flash bank) and extending for the specified hex length.
+Reports whether the checked region is blank or not.  Flash must be blank (FF in
+all bytes) before it can be programmed.
+
+=== flash:dump2bin
+flash[2] dump2bin outfile [offset [length]]
+
+Read device flash content and save it to a file.  If only a filename is
+specified, the full flash bank is dumped; one can optionally specify a starting
+offset and an explicit length, both in hex.
+
+This command is merely a user-friendly front-end to the plain dump2bin command;
+see help dump2bin.
+
+=== flash:dump2srec
+flash[2] dump2srec outfile [offset [length]]
+
+Read device flash content and save it to a file.  If only a filename is
+specified, the full flash bank is dumped; one can optionally specify a starting
+offset and an explicit length, both in hex.
+
+This command is merely a user-friendly front-end to the plain dump2srec command;
+see help dump2srec.
+
+=== flash:erase
+flash[2] erase hex-start-offset hex-length
+
+Erases an area of flash starting at the specified hex offset (from the base
+address of the flash bank) and extending for the specified hex length.
+
+Flash memory can only be erased (turning 0 bits back to 1s) in units of
+sectors, as set in stone by the design of the flash chip in use.  Loadtool
+knows the sector layout of the flash chip in your device from the hardware
+parameters file (you can display it with the flash[2] sectors command), and
+enforces that both arguments to the flash[2] erase command lie on sector
+boundaries.
+
+=== flash:info
+This command displays summary information about the flash memory configuration
+of the Calypso target device loadtool thinks it's talking to.
+
+=== flash:program-bin
+flash[2] program-bin flash-offset binfile [file-offset [length]]
+
+This command programs flash, using a binary file as the data source.  One must
+always specify the starting flash offset (from the base address of the flash
+bank), but the starting file offset and length are optional, defaulting to the
+whole file.
+
+The binary file must be in the native byte order of the Calypso ARM7 processor,
+which is little-endian.  Images produced by flash[2] dump2bin are suitable.
+
+=== flash:program-m0
+flash[2] program-m0 image.m0
+
+*.m0 is the format that has been used by companies like TI and Closedmoko for
+their proprietary firmware images.  It is emitted by TI's hex470 tool, and in
+the proprietary environment it is fed as an input to FLUID.  (The latter is
+TI's Flash Loader Utility Independent of Device, and fc-loadtool can be seen as
+an independent reimplementation thereof - although it doesn't have the same
+level of device-independence.)  The *.m0 format is actually a variant of
+Motorola's SREC, but with a different byte order: each 16-bit word is
+byte-reversed relative to the native byte order of the ARM7 processor.
+(This strange byte order actually makes some sense if one views the image as a
+long array of 16-bit hex values; 16 bits is the width of the flash memory on
+Calypso GSM devices and thus the natural unit size for flash programming.)
+
+Because each S-record contains an address, no addresses or offsets need to be
+specified in the flash[2] program-m0 command, only the image file.
+
+=== flash:program-srec
+flash[2] program-srec image.srec
+
+This command programs the flash with an image in the standard S-record format,
+in the native little-endian byte order of the Calypso ARM7 processor.  It is
+the opposite byte order from that used by TI's and Closedmoko's *.m0 files -
+see help flash program-m0.  Images produced by flash[2] dump2srec are suitable
+for flash[2] program-srec.
+
+Because each S-record contains an address, no addresses or offsets need to be
+specified in the flash[2] program-srec command, only the image file.
+
+=== flash:quickprog
+flash[2] quickprog hex-offset hex-data-string
+
+This command is intended only for developers; it provides raw access to
+loadagent's basic flash write primitive.  Read the source code for more
+information.
+
+=== flash:sectors
+This command displays the list of sector offsets and sizes for the flash chip
+in the Calypso target device loadtool thinks it's talking to.
+
+=== r8
+=== r16
+=== r32
+=== w8
+=== w16
+=== w32
+=== peekpoke
+The register peek and poke commands are:
+
+r8 addr		Read an 8-bit register or memory location
+r16 addr	Read a 16-bit register or memory location
+r32 addr	Read a 32-bit register or memory location
+w8 addr data	Write an 8-bit register or memory location
+w16 addr data	Write a 16-bit register or memory location
+w32 addr data	Write a 32-bit register or memory location
+
+All addresses and data values are in hex.
+

--- a/loadtools/ltdispatch.c	Mon Sep 02 03:07:07 2013 +0000
+++ b/loadtools/ltdispatch.c	Tue Sep 03 07:31:26 2013 +0000
@@ -16,6 +16,7 @@
 extern int cmd_exec();
 extern int cmd_exit();
 extern int cmd_flash();
+extern int cmd_help();
 extern int loadtool_cmd_passthru();
 
 static struct cmdtab {
@@ -34,6 +35,7 @@
 	{"exit", 0, 1, cmd_exit},
 	{"flash", 1, 5, cmd_flash},
 	{"flash2", 1, 5, cmd_flash},
+	{"help", 0, 2, cmd_help},
 	{"quit", 0, 1, cmd_exit},
 	{"r8", 1, 1, loadtool_cmd_passthru},
 	{"r16", 1, 1, loadtool_cmd_passthru},

--- a/loadtools/ltflash.c	Mon Sep 02 03:07:07 2013 +0000
+++ b/loadtools/ltflash.c	Tue Sep 03 07:31:26 2013 +0000
@@ -242,6 +242,11 @@
 				format);
 }
 
+flashcmd_help()
+{
+	return loadtool_help("flash");
+}
+
 flashcmd_info(argc, argv, bank)
 	char **argv;
 {
@@ -309,6 +314,7 @@
 	{"dump2bin", flashcmd_dump2file},
 	{"dump2srec", flashcmd_dump2file},
 	{"erase", flashcmd_erase},
+	{"help", flashcmd_help},
 	{"info", flashcmd_info},
 	{"program-bin", flashcmd_progbin},
 	{"program-m0", flashcmd_program_m0},

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/loadtools/lthelp.c	Tue Sep 03 07:31:26 2013 +0000
@@ -0,0 +1,80 @@
+/*
+ * This module implements the loadtool help facility.
+ */
+
+#include <stdio.h>
+#include <ctype.h>
+#include <string.h>
+#include <strings.h>
+#include <stdlib.h>
+
+extern char loadtool_help_file[];
+
+loadtool_help(topic)
+	char *topic;
+{
+	FILE *f;
+	char linebuf[256];
+	char *cp, *np;
+	int flag;
+
+	f = fopen(loadtool_help_file, "r");
+	if (!f) {
+		perror(loadtool_help_file);
+		return(-1);
+	}
+	for (;;) {
+		if (!fgets(linebuf, sizeof linebuf, f)) {
+			fprintf(stderr, "Help topic \"%s\" not found\n", topic);
+			fclose(f);
+			return(-1);
+		}
+		if (linebuf[0] != '=' || linebuf[1] != '=' || linebuf[2] != '=')
+			continue;
+		for (cp = linebuf + 3; isspace(*cp); cp++)
+			;
+		for (np = cp; *cp && !isspace(*cp); cp++)
+			;
+		if (*cp)
+			*cp++ = '\0';
+		if (!strcmp(np, topic))
+			break;
+	}
+	for (flag = 0; fgets(linebuf, sizeof linebuf, f); ) {
+		if (linebuf[0] == '=' && linebuf[1] == '=' &&
+		    linebuf[2] == '=') {
+			if (flag)
+				break;
+			else
+				continue;
+		}
+		fputs(linebuf, stdout);
+		flag = 1;
+	}
+	fclose(f);
+	return(0);
+}
+
+cmd_help(argc, argv)
+	char **argv;
+{
+	char flashtopic[32];
+
+	switch (argc) {
+	case 1:
+		return loadtool_help("main");
+	case 2:
+		return loadtool_help(argv[1]);
+	case 3:
+		if ((!strcmp(argv[1], "flash") || !strcmp(argv[1], "flash2"))
+		    && strlen(argv[2]) <= 20) {
+			sprintf(flashtopic, "flash:%s", argv[2]);
+			return loadtool_help(flashtopic);
+		}
+		fprintf(stderr, "No such help topic\n");
+		return(-1);
+	default:
+		fprintf(stderr, "internal error in cmd_help(): bad argc\n");
+		abort();
+	}
+}