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 (16 MiB flash chips 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.  As an implementation limit, both
the starting target memory address and the length of the area to dump need to
be aligned to 16 bytes.

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

The 128 byte alignment requirement of previous versions has been lifted; you
can now dump as little as one byte without any alignment restrictions.  In the
case of dump2srec the output file will be written with 32 bytes of payload per
S3 record, with the last record carrying from 1 to 32 bytes of payload as
needed.

=== exec
exec <script-file>

Read and execute commands from the named file.  If the execution of a script
command encounters an error, the following commands are not executed, i.e.,
stop on first error.

=== 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 most targets the default exit mode is
iota-off.

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.  Most Calypso phones and modems have
only one flash bank (as in chip select), and are manipulated with the flash
command.  FreeCalypso development boards and some complex phones (Pirelli
DP-L10, Sony Ericsson K2x0) have two flash banks (as in chip selects) of 8 MiB
each; they are manipulated with 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 geom		Display geometry details of detected flash chip
flash id		Perform flash chip autodetection sequence
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 e-program-bin	Combined erase and program-bin
flash e-program-m0	Combined erase and program-m0
flash e-program-srec	Combined erase and program-srec
flash prot-reg		Read Intel flash OTP protection register
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
flash status		Intel-style flash only: read Status Register
flash unlock		Intel-style flash only: unlock flash sectors

Additional operations for select Spansion and Samsung flash chips:

flash lock-state	Retrieve and display sector write-protection state
flash ppb-program	Program Persistent Protection Bit for one sector
flash ppb-program-all	Program all PPBs in the addressed flash bank
flash ppb-erase-all	Erase all PPBs in the flash chip, unlocking all sectors

Additional operations for Compal targets only:

flash compal-imei		Read IMEI from OTP protection register
flash erase-program-boot	Erase and reprogram the boot sector

Substitute flash2 instead of flash when operating on the 2nd flash chip select
of 16 MiB flash chips (FCDEV3B, Pirelli DP-L10 etc).  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:compal-imei
flash compal-imei		Display the Compal phone's IMEI
flash compal-imei <filename>	Display the Compal phone's IMEI, and also
				save it in the named file

Compal phones have their factory IMEI stored in the flash chip's OTP protection
register.  This command reads the Intel flash protection register, checks its
content for an IMEI formatted in Compal's particular way, and if a valid-looking
IMEI is found, it is displayed on the terminal.  The extracted IMEI can also be
saved into a text file.

=== 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 was originally nothing more than a user-friendly front-end to the
plain dump2bin command (see help dump2bin), but in the current version it first
performs the flash chip autodetection operation if it hasn't been done already
(needed in order to determine the size of the flash bank) and resets the flash
to read array mode.

=== 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 was originally nothing more than a user-friendly front-end to the
plain dump2srec command (see help dump2srec), but in the current version it
first performs the flash chip autodetection operation if it hasn't been done
already (needed in order to determine the size of the flash bank) and resets
the flash to read array mode.

=== 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 will
autodetect the flash chip in use and will only operate on those flash chip types
which it knows about; if a known chip is found, loadtool knows its sector layout
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:geom
This command displays information about the detected flash chip: device name,
geometry details and the command set style (AMD or Intel).  The displayed
geometry details include the total size of the flash bank, the total number of
sectors, the number of regions with different sector sizes and the sector size
and the number of sectors in each region.

=== flash:id
This command explicitly invokes the same flash chip autodetection operation
that is performed the first time each flash bank is accessed with any flash or
flash2 command.

=== flash:info
This command displays the global flash configuration settings that have been
selected at fc-loadtool invokation time (hardware parameters associated with
the target set via -h or -H): the global single-4M, single-8M or dual-8M
setting and flash bank base addresses.

In previous versions this command performed flash ID checks and displayed
geometry information; these functions have been moved to the new flash id and
flash geom commands.

=== flash:lock-state
This command is only implemented for certain specific Spansion and Samsung
flash chip types that have lockable sectors, i.e., an ability to write-protect
certain flash sectors in a persistent, non-volatile manner.  This command
retrieves and displays the lock state of every sector in the addressed flash
bank, as well as some chip-global lock status words.  (The details are highly
chip-dependent.)

In the case of 16 MiB flash chips, you need to execute flash lock-state to see
the lock state of sectors in the first flash bank and flash2 lock-state to see
the lock state of sectors in the second flash bank.

=== flash:ppb-program
flash[2] ppb-program sector-offset

This command (implemented only for certain specific Spansion and Samsung flash
chip types) programs the Persistent Protection Bit (PPB) for the specified
sector, causing that sector to become persistently write-protected.  Note that
on many flash chips sectors are aggregated into groups for the purpose of write
protection, with a group of up to 4 sectors sharing the same PPB - once that
per-group PPB is programmed, all sectors in that group become write-protected.

Use flash ppb-erase-all command to clear all write protection locks created by
this command.

=== flash:ppb-program-all
This command is implemented only for those flash chip types whose PPB program
and erase commands follow the model of Spansion PL-J, rather than that of
Spansion PL-N.  It programs all PPBs that reside in the addressed flash bank,
which will be the entire chip in the case of S71PL064J or half of the chip in
the case of S71PL129J or its Samsung equivalent.  There is no anticipated need
for this command to ever be invoked by end users of fc-loadtool - instead it is
best seen as a made-accessible internal function of the tool, the internal
function that is primarily needed as part of flash ppb-erase-all implementation.

=== flash:ppb-erase-all
This command erases the special-purpose non-volatile memory element inside the
flash chip that stores all Persistent Protection Bits (PPBs) for this chip.
Because the erased state of a PPB corresponds to the associated flash sector or
group of sectors being unlocked, the present operation clears all write
protection locks in the entire chip, making all flash unlocked.

Special note for 16 MiB flash chips: because there is only one dedicated NV
memory element in the entire flash chip for storing all PPBs, erasable only as
a unit, this command operates on the entire chip rather than per-bank.  There
is no flash2 ppb-erase-all command for this reason.

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

Calypso firmware images built with TI's TMS470 toolchain in TI's canonical
manner come out in a hex format that is a variant of Motorola's SREC, in files
ending with the .m0 suffix.  We have nicknamed this format "moko-style m0"
after its most famous user; this command programs the flash with an image in
this moko-style m0 format.

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.

This command does NOT include a built-in flash erase step - see
help flash e-program-m0 for the more complete version.

=== 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:e-program-bin
flash[2] e-program-bin flash-offset binfile [file-offset [length]]

This command is an extension of flash[2] program-bin: it first erases the range
of sectors that contains the range of flash words to be programmed, then
executes the program-bin operation.  All arguments are exactly the same as for
flash[2] program-bin - see help flash program-bin.  The range of sectors that
will be erased will be the minimal set that contains the area of flash to be
programmed.  This command is intended for automated (no thinking required)
flashing of firmware release images that are delivered in binary format; only
flash-offset and binfile arguments will be given in this case.

=== flash:e-program-m0
flash[2] e-program-m0 image.m0

This command reads in the specified S-record image in moko-style m0 format,
builds a map of potentially discontiguous flash regions into which the image
deposits bits, erases the set of flash sectors which need to be erased before
programming these regions, then programs the new image bits into flash.  This
command is intended for automated (no thinking required) flashing of firmware
release images that are delivered in moko-style m0 format.

=== flash:e-program-srec
flash[2] e-program-srec image.srec

This command works like flash[2] e-program-m0, but takes in an S-record image
in little-endian byte order, which is the opposite byte order from that used by
TI's *.m0 files.  This command is provided only for the sake of symmetry - no
practical use case is envisioned.

=== flash:prot-reg
This command is only applicable to Intel-style flash chips.  These flash chips
have an OTP (one time programmable, then physically immutable afterward) area
called "protection register"; this command reads the flash chip's protection
register and displays its content as in lock word, factory words and user words.

=== 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 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, 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 detected
flash chip.  This command is deprecated except for debugging of loadtool
internals; the new flash geom command displays the same information in a much
more compact form.

=== flash:status
This command is only applicable to Intel-style flash chips.  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 chips.  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.