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.