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
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
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.

=== 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)

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 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.  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
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.  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 on all target devices:

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 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.  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

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 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
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 *.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: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
=== 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.