--- a/loadtools/loadtool.help	Wed Jun 18 08:38:41 2014 +0000
+++ b/loadtools/loadtool.help	Thu Jun 19 00:23:28 2014 +0000
@@ -19,6 +19,8 @@
 help exit		Controlling the cleanup on exit
 
 === all
+abbr		Read an ABB register
+abbw		Write an ABB register
 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
@@ -39,6 +41,14 @@
 
 To get help on any command, type help and the command keyword.
 
+=== abbr
+=== abbw
+abbr pg reg		Read ABB register <reg> on page <pg>
+abbw pg reg val		Write <val> into register <reg> on page <pg>
+
+The <pg> and <reg> arguments default to decimal unless prefixed with 0x;
+the <val> argument to abbw is always hexadecimal.
+
 === baud
 baud		Display the current baud rate
 baud <rate>	Switch the baud rate to <rate> (number in bps)
@@ -109,13 +119,15 @@
 === quit
 exit		Clean up the target in the default manner and exit
 exit bare	Exit loadtool without doing anything to the target
+exit iota-off	Exit loadtool and command an ABB power-off on 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.
+mode, as the USB cable is connected and VBUS is present.  On Compal phones the
+default exit mode is iota-off.
 
 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
@@ -131,12 +143,12 @@
 === 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.
+memories of the supported GSM devices.  Compal phones and the GTA0x GSM modem
+have only one flash bank (as in chip select), and are 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:
+The following flash operations are available on all target devices:
 
 flash blankchk		Blank-check a region of flash
 flash dump2bin		Dump flash content to a file in binary format
@@ -147,11 +159,30 @@
 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 reset		Reset flash chip to read array mode
 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.
+get usage information, e.g., help flash program-bin.  See help compal for some
+additional info specific to Compal targets.
+
+=== compal
+=== compalflash
+=== flash:compal
+Compal phones have Intel or Intel-style flash chips; other Calypso targets for
+which loadtool was originally designed have AMD-style flash chips.  The author
+of the present software has a personal bias toward AMD-style flash, hence the
+support for Intel-style flash is not as clean.  Compal phones also have the
+Calypso boot ROM disabled, and depend on flash-resident boot code instead.
+This property makes them brickable.
+
+The following additional loadtool commands apply only to Compal targets with
+Intel-style flash:
+
+flash erase-program-boot	Erase and reprogram the boot sector
+flash status			Read Intel flash Status Register
+flash unlock			Unlock flash sectors
 
 === flash:blankchk
 flash[2] blankchk hex-start-offset hex-length
@@ -189,10 +220,28 @@
 
 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.
+knows the sector layout of the flash chip in your device from CFI or 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:erase-program-boot
+flash erase-program-boot binfile [length]
+
+This operation is applicable to Compal targets only.  This command erases and
+reprograms flash sector 0 (the boot sector) with minimized vulnerability to
+bricking by loading the new boot code into a scratchpad RAM area on the target,
+then commanding loadagent (running on the target) to erase and reprogram the
+dangerous flash sector without requiring further interaction with loadtool.
+(In contrast, loadtool's "regular" flash erase and program operations are
+driven primarily by loadtool, with loadagent providing only low-level
+functions.)
+
+The new bits to be programmed are taken from the specified binary file.  Byte 0
+of the file goes into byte 0 of the flash and so on, for the specified length.
+If no length argument is given, it defaults to the length of the file, which
+must not exceed the length of flash sector 0: 64 KiB on the "basic" Compal
+phones or 8 KiB on C155/156.
 
 === flash:info
 This command displays summary information about the flash memory configuration
@@ -232,7 +281,7 @@
 
 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 -
+the opposite byte order from that used by TI's *.m0 files -
 see help flash program-m0.  Images produced by flash[2] dump2srec are suitable
 for flash[2] program-srec.
 
@@ -246,10 +295,39 @@
 loadagent's basic flash write primitive.  Read the source code for more
 information.
 
+=== flash:reset
+Intel-style flash memory chips (found in Compal phones) have two "stable" or
+"quiescent" states: reading array data and reading the status register (SR).
+After an erase or program operation the flash chip is "parked" in the Read SR
+state; the flash reset command switches it back to reading array data.
+
+This command works for AMD-style flash as well (found in Openmoko and Pirelli
+phones), but it is normally not needed, as AMD-style flash chips automatically
+return to the read-array-data state after every erase or program operation.
+
 === 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.
 
+=== flash:status
+This command is only applicable to Intel-style flash as found in Compal phones.
+It reads the flash chip's Status Register, which can be used to diagnose errors
+incurred by previous erase or program operations.
+
+=== flash:unlock
+flash unlock hex-start-offset hex-length
+
+This command is only applicable to Intel-style flash as found in Compal phones.
+These flash chips power up with each sector (erase block) in the "locked" state;
+each sector needs to be unlocked before it can be erased or programmed.
+
+This command is normally not needed, as the flash erase command unlocks each
+sector before erasing it.  However, if you are going to perform program
+operations in some sectors without erasing them, you will need to unlock them
+explicitly first.
+
+This command operates only on sector boundaries just like flash erase.
+
 === r8
 === r16
 === r32