+@deffn {Flash Driver} str9xpec
+Only use this driver for locking/unlocking the device or configuring the option bytes.
+Use the standard str9 driver for programming.
+Before using the flash commands the turbo mode must be enabled using the
+@command{str9xpec enable_turbo} command.
+
+Several str9xpec-specific commands are defined:
+
+@deffn Command {str9xpec disable_turbo} num
+Restore the str9 into JTAG chain.
+@end deffn
+
+@deffn Command {str9xpec enable_turbo} num
+Enable turbo mode, will simply remove the str9 from the chain and talk
+directly to the embedded flash controller.
+@end deffn
+
+@deffn Command {str9xpec lock} num
+Lock str9 device. The str9 will only respond to an unlock command that will
+erase the device.
+@end deffn
+
+@deffn Command {str9xpec part_id} num
+Prints the part identifier for bank @var{num}.
+@end deffn
+
+@deffn Command {str9xpec options_cmap} num (@option{bank0}|@option{bank1})
+Configure str9 boot bank.
+@end deffn
+
+@deffn Command {str9xpec options_lvdsel} num (@option{vdd}|@option{vdd_vddq})
+Configure str9 lvd source.
+@end deffn
+
+@deffn Command {str9xpec options_lvdthd} num (@option{2.4v}|@option{2.7v})
+Configure str9 lvd threshold.
+@end deffn
+
+@deffn Command {str9xpec options_lvdwarn} bank (@option{vdd}|@option{vdd_vddq})
+Configure str9 lvd reset warning source.
+@end deffn
+
+@deffn Command {str9xpec options_read} num
+Read str9 option bytes.
+@end deffn
+
+@deffn Command {str9xpec options_write} num
+Write str9 option bytes.
+@end deffn
+
+@deffn Command {str9xpec unlock} num
+unlock str9 device.
+@end deffn
+
+@end deffn
+
+
+@section mFlash
+
+@subsection mFlash Configuration
+@cindex mFlash Configuration
+
+@deffn {Config Command} {mflash bank} soc base RST_pin target
+Configures a mflash for @var{soc} host bank at
+address @var{base}.
+The pin number format depends on the host GPIO naming convention.
+Currently, the mflash driver supports s3c2440 and pxa270.
+
+Example for s3c2440 mflash where @var{RST pin} is GPIO B1:
+
+@example
+mflash bank s3c2440 0x10000000 1b 0
+@end example
+
+Example for pxa270 mflash where @var{RST pin} is GPIO 43:
+
+@example
+mflash bank pxa270 0x08000000 43 0
+@end example
+@end deffn
+
+@subsection mFlash commands
+@cindex mFlash commands
+
+@deffn Command {mflash config pll} frequency
+Configure mflash PLL.
+The @var{frequency} is the mflash input frequency, in Hz.
+Issuing this command will erase mflash's whole internal nand and write new pll.
+After this command, mflash needs power-on-reset for normal operation.
+If pll was newly configured, storage and boot(optional) info also need to be update.
+@end deffn
+
+@deffn Command {mflash config boot}
+Configure bootable option.
+If bootable option is set, mflash offer the first 8 sectors
+(4kB) for boot.
+@end deffn
+
+@deffn Command {mflash config storage}
+Configure storage information.
+For the normal storage operation, this information must be
+written.
+@end deffn
+
+@deffn Command {mflash dump} num filename offset size
+Dump @var{size} bytes, starting at @var{offset} bytes from the
+beginning of the bank @var{num}, to the file named @var{filename}.
+@end deffn
+
+@deffn Command {mflash probe}
+Probe mflash.
+@end deffn
+
+@deffn Command {mflash write} num filename offset
+Write the binary file @var{filename} to mflash bank @var{num}, starting at
+@var{offset} bytes from the beginning of the bank.
+@end deffn
+
+@node NAND Flash Commands
+@chapter NAND Flash Commands
+@cindex NAND
+
+Compared to NOR or SPI flash, NAND devices are inexpensive
+and high density. Today's NAND chips, and multi-chip modules,
+commonly hold multiple GigaBytes of data.
+
+NAND chips consist of a number of ``erase blocks'' of a given
+size (such as 128 KBytes), each of which is divided into a
+number of pages (of perhaps 512 or 2048 bytes each). Each
+page of a NAND flash has an ``out of band'' (OOB) area to hold
+Error Correcting Code (ECC) and other metadata, usually 16 bytes
+of OOB for every 512 bytes of page data.
+
+One key characteristic of NAND flash is that its error rate
+is higher than that of NOR flash. In normal operation, that
+ECC is used to correct and detect errors. However, NAND
+blocks can also wear out and become unusable; those blocks
+are then marked "bad". NAND chips are even shipped from the
+manufacturer with a few bad blocks. The highest density chips
+use a technology (MLC) that wears out more quickly, so ECC
+support is increasingly important as a way to detect blocks
+that have begun to fail, and help to preserve data integrity
+with techniques such as wear leveling.
+
+Software is used to manage the ECC. Some controllers don't
+support ECC directly; in those cases, software ECC is used.
+Other controllers speed up the ECC calculations with hardware.
+Single-bit error correction hardware is routine. Controllers
+geared for newer MLC chips may correct 4 or more errors for
+every 512 bytes of data.
+
+You will need to make sure that any data you write using
+OpenOCD includes the apppropriate kind of ECC. For example,
+that may mean passing the @code{oob_softecc} flag when
+writing NAND data, or ensuring that the correct hardware
+ECC mode is used.
+
+The basic steps for using NAND devices include:
+@enumerate
+@item Declare via the command @command{nand device}
+@* Do this in a board-specific configuration file,
+passing parameters as needed by the controller.
+@item Configure each device using @command{nand probe}.
+@* Do this only after the associated target is set up,
+such as in its reset-init script or in procures defined
+to access that device.
+@item Operate on the flash via @command{nand subcommand}
+@* Often commands to manipulate the flash are typed by a human, or run
+via a script in some automated way. Common task include writing a
+boot loader, operating system, or other data needed to initialize or
+de-brick a board.
+@end enumerate
+
+@b{NOTE:} At the time this text was written, the largest NAND
+flash fully supported by OpenOCD is 2 GiBytes (16 GiBits).
+This is because the variables used to hold offsets and lengths
+are only 32 bits wide.
+(Larger chips may work in some cases, unless an offset or length
+is larger than 0xffffffff, the largest 32-bit unsigned integer.)
+Some larger devices will work, since they are actually multi-chip
+modules with two smaller chips and individual chipselect lines.
+
+@anchor{NAND Configuration}
+@section NAND Configuration Commands
+@cindex NAND configuration
+
+NAND chips must be declared in configuration scripts,
+plus some additional configuration that's done after
+OpenOCD has initialized.
+
+@deffn {Config Command} {nand device} name driver target [configparams...]
+Declares a NAND device, which can be read and written to
+after it has been configured through @command{nand probe}.
+In OpenOCD, devices are single chips; this is unlike some
+operating systems, which may manage multiple chips as if
+they were a single (larger) device.
+In some cases, configuring a device will activate extra
+commands; see the controller-specific documentation.
+
+@b{NOTE:} This command is not available after OpenOCD
+initialization has completed. Use it in board specific
+configuration files, not interactively.
+
+@itemize @bullet
+@item @var{name} ... may be used to reference the NAND bank
+in most other NAND commands. A number is also available.
+@item @var{driver} ... identifies the NAND controller driver
+associated with the NAND device being declared.
+@xref{NAND Driver List}.
+@item @var{target} ... names the target used when issuing
+commands to the NAND controller.
+@comment Actually, it's currently a controller-specific parameter...
+@item @var{configparams} ... controllers may support, or require,
+additional parameters. See the controller-specific documentation
+for more information.
+@end itemize
+@end deffn
+
+@deffn Command {nand list}
+Prints a summary of each device declared
+using @command{nand device}, numbered from zero.
+Note that un-probed devices show no details.
+@example
+> nand list
+#0: NAND 1GiB 3,3V 8-bit (Micron) pagesize: 2048, buswidth: 8,
+ blocksize: 131072, blocks: 8192
+#1: NAND 1GiB 3,3V 8-bit (Micron) pagesize: 2048, buswidth: 8,
+ blocksize: 131072, blocks: 8192
+>
+@end example
+@end deffn
+
+@deffn Command {nand probe} num
+Probes the specified device to determine key characteristics
+like its page and block sizes, and how many blocks it has.
+The @var{num} parameter is the value shown by @command{nand list}.
+You must (successfully) probe a device before you can use
+it with most other NAND commands.
+@end deffn
+
+@section Erasing, Reading, Writing to NAND Flash
+
+@deffn Command {nand dump} num filename offset length [oob_option]
+@cindex NAND reading
+Reads binary data from the NAND device and writes it to the file,
+starting at the specified offset.
+The @var{num} parameter is the value shown by @command{nand list}.
+
+Use a complete path name for @var{filename}, so you don't depend
+on the directory used to start the OpenOCD server.
+
+The @var{offset} and @var{length} must be exact multiples of the
+device's page size. They describe a data region; the OOB data
+associated with each such page may also be accessed.
+
+@b{NOTE:} At the time this text was written, no error correction
+was done on the data that's read, unless raw access was disabled
+and the underlying NAND controller driver had a @code{read_page}
+method which handled that error correction.
+
+By default, only page data is saved to the specified file.
+Use an @var{oob_option} parameter to save OOB data:
+@itemize @bullet
+@item no oob_* parameter
+@*Output file holds only page data; OOB is discarded.
+@item @code{oob_raw}
+@*Output file interleaves page data and OOB data;
+the file will be longer than "length" by the size of the
+spare areas associated with each data page.
+Note that this kind of "raw" access is different from
+what's implied by @command{nand raw_access}, which just
+controls whether a hardware-aware access method is used.
+@item @code{oob_only}
+@*Output file has only raw OOB data, and will
+be smaller than "length" since it will contain only the
+spare areas associated with each data page.
+@end itemize
+@end deffn
+
+@deffn Command {nand erase} num [offset length]
+@cindex NAND erasing
+@cindex NAND programming
+Erases blocks on the specified NAND device, starting at the
+specified @var{offset} and continuing for @var{length} bytes.
+Both of those values must be exact multiples of the device's
+block size, and the region they specify must fit entirely in the chip.
+If those parameters are not specified,
+the whole NAND chip will be erased.
+The @var{num} parameter is the value shown by @command{nand list}.
+
+@b{NOTE:} This command will try to erase bad blocks, when told
+to do so, which will probably invalidate the manufacturer's bad
+block marker.
+For the remainder of the current server session, @command{nand info}
+will still report that the block ``is'' bad.
+@end deffn
+
+@deffn Command {nand write} num filename offset [option...]
+@cindex NAND writing
+@cindex NAND programming
+Writes binary data from the file into the specified NAND device,
+starting at the specified offset. Those pages should already
+have been erased; you can't change zero bits to one bits.
+The @var{num} parameter is the value shown by @command{nand list}.
+
+Use a complete path name for @var{filename}, so you don't depend
+on the directory used to start the OpenOCD server.
+
+The @var{offset} must be an exact multiple of the device's page size.
+All data in the file will be written, assuming it doesn't run
+past the end of the device.
+Only full pages are written, and any extra space in the last
+page will be filled with 0xff bytes. (That includes OOB data,
+if that's being written.)
+
+@b{NOTE:} At the time this text was written, bad blocks are
+ignored. That is, this routine will not skip bad blocks,
+but will instead try to write them. This can cause problems.
+
+Provide at most one @var{option} parameter. With some
+NAND drivers, the meanings of these parameters may change
+if @command{nand raw_access} was used to disable hardware ECC.
+@itemize @bullet
+@item no oob_* parameter
+@*File has only page data, which is written.
+If raw acccess is in use, the OOB area will not be written.
+Otherwise, if the underlying NAND controller driver has
+a @code{write_page} routine, that routine may write the OOB
+with hardware-computed ECC data.
+@item @code{oob_only}
+@*File has only raw OOB data, which is written to the OOB area.
+Each page's data area stays untouched. @i{This can be a dangerous
+option}, since it can invalidate the ECC data.
+You may need to force raw access to use this mode.
+@item @code{oob_raw}
+@*File interleaves data and OOB data, both of which are written
+If raw access is enabled, the data is written first, then the
+un-altered OOB.
+Otherwise, if the underlying NAND controller driver has
+a @code{write_page} routine, that routine may modify the OOB
+before it's written, to include hardware-computed ECC data.
+@item @code{oob_softecc}
+@*File has only page data, which is written.
+The OOB area is filled with 0xff, except for a standard 1-bit
+software ECC code stored in conventional locations.
+You might need to force raw access to use this mode, to prevent
+the underlying driver from applying hardware ECC.
+@item @code{oob_softecc_kw}
+@*File has only page data, which is written.
+The OOB area is filled with 0xff, except for a 4-bit software ECC
+specific to the boot ROM in Marvell Kirkwood SoCs.
+You might need to force raw access to use this mode, to prevent
+the underlying driver from applying hardware ECC.
+@end itemize
+@end deffn
+
+@deffn Command {nand verify} num filename offset [option...]
+@cindex NAND verification
+@cindex NAND programming
+Verify the binary data in the file has been programmed to the
+specified NAND device, starting at the specified offset.
+The @var{num} parameter is the value shown by @command{nand list}.
+
+Use a complete path name for @var{filename}, so you don't depend
+on the directory used to start the OpenOCD server.
+
+The @var{offset} must be an exact multiple of the device's page size.
+All data in the file will be read and compared to the contents of the
+flash, assuming it doesn't run past the end of the device.
+As with @command{nand write}, only full pages are verified, so any extra
+space in the last page will be filled with 0xff bytes.
+
+The same @var{options} accepted by @command{nand write},
+and the file will be processed similarly to produce the buffers that
+can be compared against the contents produced from @command{nand dump}.
+
+@b{NOTE:} This will not work when the underlying NAND controller
+driver's @code{write_page} routine must update the OOB with a
+hardward-computed ECC before the data is written. This limitation may
+be removed in a future release.
+@end deffn
+
+@section Other NAND commands
+@cindex NAND other commands
+
+@deffn Command {nand check_bad_blocks} [offset length]
+Checks for manufacturer bad block markers on the specified NAND
+device. If no parameters are provided, checks the whole
+device; otherwise, starts at the specified @var{offset} and
+continues for @var{length} bytes.
+Both of those values must be exact multiples of the device's
+block size, and the region they specify must fit entirely in the chip.
+The @var{num} parameter is the value shown by @command{nand list}.
+
+@b{NOTE:} Before using this command you should force raw access
+with @command{nand raw_access enable} to ensure that the underlying
+driver will not try to apply hardware ECC.
+@end deffn
+
+@deffn Command {nand info} num
+The @var{num} parameter is the value shown by @command{nand list}.
+This prints the one-line summary from "nand list", plus for
+devices which have been probed this also prints any known
+status for each block.
+@end deffn
+
+@deffn Command {nand raw_access} num (@option{enable}|@option{disable})
+Sets or clears an flag affecting how page I/O is done.
+The @var{num} parameter is the value shown by @command{nand list}.
+
+This flag is cleared (disabled) by default, but changing that
+value won't affect all NAND devices. The key factor is whether
+the underlying driver provides @code{read_page} or @code{write_page}
+methods. If it doesn't provide those methods, the setting of
+this flag is irrelevant; all access is effectively ``raw''.
+
+When those methods exist, they are normally used when reading
+data (@command{nand dump} or reading bad block markers) or
+writing it (@command{nand write}). However, enabling
+raw access (setting the flag) prevents use of those methods,
+bypassing hardware ECC logic.
+@i{This can be a dangerous option}, since writing blocks
+with the wrong ECC data can cause them to be marked as bad.
+@end deffn
+
+@anchor{NAND Driver List}
+@section NAND Driver List
+As noted above, the @command{nand device} command allows
+driver-specific options and behaviors.
+Some controllers also activate controller-specific commands.
+
+@deffn {NAND Driver} at91sam9
+This driver handles the NAND controllers found on AT91SAM9 family chips from
+Atmel. It takes two extra parameters: address of the NAND chip;
+address of the ECC controller.
+@example
+nand device $NANDFLASH at91sam9 $CHIPNAME 0x40000000 0xfffffe800
+@end example
+AT91SAM9 chips support single-bit ECC hardware. The @code{write_page} and
+@code{read_page} methods are used to utilize the ECC hardware unless they are
+disabled by using the @command{nand raw_access} command. There are four
+additional commands that are needed to fully configure the AT91SAM9 NAND
+controller. Two are optional; most boards use the same wiring for ALE/CLE:
+@deffn Command {at91sam9 cle} num addr_line
+Configure the address line used for latching commands. The @var{num}
+parameter is the value shown by @command{nand list}.
+@end deffn
+@deffn Command {at91sam9 ale} num addr_line
+Configure the address line used for latching addresses. The @var{num}
+parameter is the value shown by @command{nand list}.
+@end deffn
+
+For the next two commands, it is assumed that the pins have already been
+properly configured for input or output.
+@deffn Command {at91sam9 rdy_busy} num pio_base_addr pin
+Configure the RDY/nBUSY input from the NAND device. The @var{num}
+parameter is the value shown by @command{nand list}. @var{pio_base_addr}
+is the base address of the PIO controller and @var{pin} is the pin number.
+@end deffn
+@deffn Command {at91sam9 ce} num pio_base_addr pin
+Configure the chip enable input to the NAND device. The @var{num}
+parameter is the value shown by @command{nand list}. @var{pio_base_addr}
+is the base address of the PIO controller and @var{pin} is the pin number.
+@end deffn
+@end deffn
+
+@deffn {NAND Driver} davinci
+This driver handles the NAND controllers found on DaVinci family
+chips from Texas Instruments.
+It takes three extra parameters:
+address of the NAND chip;
+hardware ECC mode to use (@option{hwecc1},
+@option{hwecc4}, @option{hwecc4_infix});
+address of the AEMIF controller on this processor.
+@example
+nand device davinci dm355.arm 0x02000000 hwecc4 0x01e10000
+@end example
+All DaVinci processors support the single-bit ECC hardware,
+and newer ones also support the four-bit ECC hardware.
+The @code{write_page} and @code{read_page} methods are used
+to implement those ECC modes, unless they are disabled using
+the @command{nand raw_access} command.
+@end deffn
+
+@deffn {NAND Driver} lpc3180
+These controllers require an extra @command{nand device}
+parameter: the clock rate used by the controller.
+@deffn Command {lpc3180 select} num [mlc|slc]
+Configures use of the MLC or SLC controller mode.
+MLC implies use of hardware ECC.
+The @var{num} parameter is the value shown by @command{nand list}.
+@end deffn
+
+At this writing, this driver includes @code{write_page}
+and @code{read_page} methods. Using @command{nand raw_access}
+to disable those methods will prevent use of hardware ECC
+in the MLC controller mode, but won't change SLC behavior.
+@end deffn
+@comment current lpc3180 code won't issue 5-byte address cycles
+
+@deffn {NAND Driver} orion
+These controllers require an extra @command{nand device}
+parameter: the address of the controller.
+@example
+nand device orion 0xd8000000
+@end example
+These controllers don't define any specialized commands.
+At this writing, their drivers don't include @code{write_page}
+or @code{read_page} methods, so @command{nand raw_access} won't
+change any behavior.
+@end deffn
+
+@deffn {NAND Driver} s3c2410
+@deffnx {NAND Driver} s3c2412
+@deffnx {NAND Driver} s3c2440
+@deffnx {NAND Driver} s3c2443
+These S3C24xx family controllers don't have any special
+@command{nand device} options, and don't define any
+specialized commands.
+At this writing, their drivers don't include @code{write_page}
+or @code{read_page} methods, so @command{nand raw_access} won't
+change any behavior.
+@end deffn
+
+@node PLD/FPGA Commands
+@chapter PLD/FPGA Commands
+@cindex PLD
+@cindex FPGA
+
+Programmable Logic Devices (PLDs) and the more flexible
+Field Programmable Gate Arrays (FPGAs) are both types of programmable hardware.
+OpenOCD can support programming them.
+Although PLDs are generally restrictive (cells are less functional, and
+there are no special purpose cells for memory or computational tasks),
+they share the same OpenOCD infrastructure.
+Accordingly, both are called PLDs here.
+
+@section PLD/FPGA Configuration and Commands
+
+As it does for JTAG TAPs, debug targets, and flash chips (both NOR and NAND),
+OpenOCD maintains a list of PLDs available for use in various commands.
+Also, each such PLD requires a driver.
+
+They are referenced by the number shown by the @command{pld devices} command,
+and new PLDs are defined by @command{pld device driver_name}.
+
+@deffn {Config Command} {pld device} driver_name tap_name [driver_options]
+Defines a new PLD device, supported by driver @var{driver_name},
+using the TAP named @var{tap_name}.
+The driver may make use of any @var{driver_options} to configure its
+behavior.
+@end deffn
+
+@deffn {Command} {pld devices}
+Lists the PLDs and their numbers.
+@end deffn
+
+@deffn {Command} {pld load} num filename
+Loads the file @file{filename} into the PLD identified by @var{num}.
+The file format must be inferred by the driver.
+@end deffn
+
+@section PLD/FPGA Drivers, Options, and Commands
+
+Drivers may support PLD-specific options to the @command{pld device}
+definition command, and may also define commands usable only with
+that particular type of PLD.
+
+@deffn {FPGA Driver} virtex2
+Virtex-II is a family of FPGAs sold by Xilinx.
+It supports the IEEE 1532 standard for In-System Configuration (ISC).
+No driver-specific PLD definition options are used,
+and one driver-specific command is defined.
+
+@deffn {Command} {virtex2 read_stat} num
+Reads and displays the Virtex-II status register (STAT)
+for FPGA @var{num}.
+@end deffn
+@end deffn
+
+@node General Commands
+@chapter General Commands
+@cindex commands
+
+The commands documented in this chapter here are common commands that
+you, as a human, may want to type and see the output of. Configuration type
+commands are documented elsewhere.
+
+Intent:
+@itemize @bullet
+@item @b{Source Of Commands}
+@* OpenOCD commands can occur in a configuration script (discussed
+elsewhere) or typed manually by a human or supplied programatically,
+or via one of several TCP/IP Ports.
+
+@item @b{From the human}
+@* A human should interact with the telnet interface (default port: 4444)
+or via GDB (default port 3333).
+
+To issue commands from within a GDB session, use the @option{monitor}
+command, e.g. use @option{monitor poll} to issue the @option{poll}
+command. All output is relayed through the GDB session.
+
+@item @b{Machine Interface}
+The Tcl interface's intent is to be a machine interface. The default Tcl
+port is 5555.
+@end itemize
+
+
+@section Daemon Commands
+
+@deffn {Command} exit
+Exits the current telnet session.
+@end deffn
+
+@deffn {Command} help [string]
+With no parameters, prints help text for all commands.
+Otherwise, prints each helptext containing @var{string}.
+Not every command provides helptext.
+
+Configuration commands, and commands valid at any time, are
+explicitly noted in parenthesis.
+In most cases, no such restriction is listed; this indicates commands
+which are only available after the configuration stage has completed.
+@end deffn
+
+@deffn Command sleep msec [@option{busy}]
+Wait for at least @var{msec} milliseconds before resuming.
+If @option{busy} is passed, busy-wait instead of sleeping.
+(This option is strongly discouraged.)
+Useful in connection with script files
+(@command{script} command and @command{target_name} configuration).
+@end deffn
+
+@deffn Command shutdown
+Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).
+@end deffn
+
+@anchor{debug_level}
+@deffn Command debug_level [n]
+@cindex message level
+Display debug level.
+If @var{n} (from 0..3) is provided, then set it to that level.
+This affects the kind of messages sent to the server log.
+Level 0 is error messages only;
+level 1 adds warnings;
+level 2 adds informational messages;
+and level 3 adds debugging messages.
+The default is level 2, but that can be overridden on
+the command line along with the location of that log
+file (which is normally the server's standard output).
+@xref{Running}.
+@end deffn
+
+@deffn Command fast (@option{enable}|@option{disable})
+Default disabled.
+Set default behaviour of OpenOCD to be "fast and dangerous".
+
+At this writing, this only affects the defaults for two ARM7/ARM9 parameters:
+fast memory access, and DCC downloads. Those parameters may still be
+individually overridden.
+
+The target specific "dangerous" optimisation tweaking options may come and go
+as more robust and user friendly ways are found to ensure maximum throughput
+and robustness with a minimum of configuration.
+
+Typically the "fast enable" is specified first on the command line:
+
+@example
+openocd -c "fast enable" -c "interface dummy" -f target/str710.cfg
+@end example
+@end deffn
+
+@deffn Command echo message
+Logs a message at "user" priority.
+Output @var{message} to stdout.
+@example
+echo "Downloading kernel -- please wait"
+@end example
+@end deffn
+
+@deffn Command log_output [filename]
+Redirect logging to @var{filename};
+the initial log output channel is stderr.
+@end deffn
+
+@anchor{Target State handling}
+@section Target State handling
+@cindex reset
+@cindex halt
+@cindex target initialization
+
+In this section ``target'' refers to a CPU configured as
+shown earlier (@pxref{CPU Configuration}).
+These commands, like many, implicitly refer to
+a current target which is used to perform the
+various operations. The current target may be changed
+by using @command{targets} command with the name of the
+target which should become current.
+
+@deffn Command reg [(number|name) [value]]
+Access a single register by @var{number} or by its @var{name}.
+The target must generally be halted before access to CPU core
+registers is allowed. Depending on the hardware, some other
+registers may be accessible while the target is running.
+
+@emph{With no arguments}:
+list all available registers for the current target,
+showing number, name, size, value, and cache status.
+For valid entries, a value is shown; valid entries
+which are also dirty (and will be written back later)
+are flagged as such.
+
+@emph{With number/name}: display that register's value.
+
+@emph{With both number/name and value}: set register's value.
+Writes may be held in a writeback cache internal to OpenOCD,
+so that setting the value marks the register as dirty instead
+of immediately flushing that value. Resuming CPU execution
+(including by single stepping) or otherwise activating the
+relevant module will flush such values.
+
+Cores may have surprisingly many registers in their
+Debug and trace infrastructure:
+
+@example
+> reg
+===== ARM registers
+(0) r0 (/32): 0x0000D3C2 (dirty)
+(1) r1 (/32): 0xFD61F31C
+(2) r2 (/32)
+...
+(164) ETM_contextid_comparator_mask (/32)
+>
+@end example
+@end deffn
+
+@deffn Command halt [ms]
+@deffnx Command wait_halt [ms]
+The @command{halt} command first sends a halt request to the target,
+which @command{wait_halt} doesn't.
+Otherwise these behave the same: wait up to @var{ms} milliseconds,
+or 5 seconds if there is no parameter, for the target to halt
+(and enter debug mode).
+Using 0 as the @var{ms} parameter prevents OpenOCD from waiting.
+
+@quotation Warning
+On ARM cores, software using the @emph{wait for interrupt} operation
+often blocks the JTAG access needed by a @command{halt} command.
+This is because that operation also puts the core into a low
+power mode by gating the core clock;
+but the core clock is needed to detect JTAG clock transitions.
+
+One partial workaround uses adaptive clocking: when the core is
+interrupted the operation completes, then JTAG clocks are accepted
+at least until the interrupt handler completes.
+However, this workaround is often unusable since the processor, board,
+and JTAG adapter must all support adaptive JTAG clocking.
+Also, it can't work until an interrupt is issued.
+
+A more complete workaround is to not use that operation while you
+work with a JTAG debugger.
+Tasking environments generaly have idle loops where the body is the
+@emph{wait for interrupt} operation.
+(On older cores, it is a coprocessor action;
+newer cores have a @option{wfi} instruction.)
+Such loops can just remove that operation, at the cost of higher
+power consumption (because the CPU is needlessly clocked).
+@end quotation
+
+@end deffn
+
+@deffn Command resume [address]
+Resume the target at its current code position,
+or the optional @var{address} if it is provided.
+OpenOCD will wait 5 seconds for the target to resume.
+@end deffn
+
+@deffn Command step [address]
+Single-step the target at its current code position,
+or the optional @var{address} if it is provided.
+@end deffn
+
+@anchor{Reset Command}
+@deffn Command reset
+@deffnx Command {reset run}
+@deffnx Command {reset halt}
+@deffnx Command {reset init}
+Perform as hard a reset as possible, using SRST if possible.
+@emph{All defined targets will be reset, and target
+events will fire during the reset sequence.}
+
+The optional parameter specifies what should
+happen after the reset.
+If there is no parameter, a @command{reset run} is executed.
+The other options will not work on all systems.
+@xref{Reset Configuration}.
+
+@itemize @minus
+@item @b{run} Let the target run
+@item @b{halt} Immediately halt the target
+@item @b{init} Immediately halt the target, and execute the reset-init script
+@end itemize
+@end deffn
+
+@deffn Command soft_reset_halt
+Requesting target halt and executing a soft reset. This is often used
+when a target cannot be reset and halted. The target, after reset is
+released begins to execute code. OpenOCD attempts to stop the CPU and
+then sets the program counter back to the reset vector. Unfortunately
+the code that was executed may have left the hardware in an unknown
+state.
+@end deffn
+
+@section I/O Utilities
+
+These commands are available when
+OpenOCD is built with @option{--enable-ioutil}.
+They are mainly useful on embedded targets,
+notably the ZY1000.
+Hosts with operating systems have complementary tools.
+
+@emph{Note:} there are several more such commands.
+
+@deffn Command append_file filename [string]*
+Appends the @var{string} parameters to
+the text file @file{filename}.
+Each string except the last one is followed by one space.
+The last string is followed by a newline.
+@end deffn
+
+@deffn Command cat filename
+Reads and displays the text file @file{filename}.
+@end deffn
+
+@deffn Command cp src_filename dest_filename
+Copies contents from the file @file{src_filename}
+into @file{dest_filename}.
+@end deffn
+
+@deffn Command ip
+@emph{No description provided.}
+@end deffn
+
+@deffn Command ls
+@emph{No description provided.}
+@end deffn
+
+@deffn Command mac
+@emph{No description provided.}
+@end deffn
+
+@deffn Command meminfo
+Display available RAM memory on OpenOCD host.
+Used in OpenOCD regression testing scripts.
+@end deffn
+
+@deffn Command peek
+@emph{No description provided.}
+@end deffn
+
+@deffn Command poke
+@emph{No description provided.}
+@end deffn
+
+@deffn Command rm filename
+@c "rm" has both normal and Jim-level versions??
+Unlinks the file @file{filename}.
+@end deffn
+
+@deffn Command trunc filename
+Removes all data in the file @file{filename}.
+@end deffn
+
+@anchor{Memory access}
+@section Memory access commands
+@cindex memory access
+
+These commands allow accesses of a specific size to the memory
+system. Often these are used to configure the current target in some
+special way. For example - one may need to write certain values to the
+SDRAM controller to enable SDRAM.
+
+@enumerate
+@item Use the @command{targets} (plural) command
+to change the current target.
+@item In system level scripts these commands are deprecated.
+Please use their TARGET object siblings to avoid making assumptions
+about what TAP is the current target, or about MMU configuration.
+@end enumerate
+
+@deffn Command mdw [phys] addr [count]
+@deffnx Command mdh [phys] addr [count]
+@deffnx Command mdb [phys] addr [count]
+Display contents of address @var{addr}, as
+32-bit words (@command{mdw}), 16-bit halfwords (@command{mdh}),
+or 8-bit bytes (@command{mdb}).
+When the current target has an MMU which is present and active,
+@var{addr} is interpreted as a virtual address.
+Otherwise, or if the optional @var{phys} flag is specified,
+@var{addr} is interpreted as a physical address.
+If @var{count} is specified, displays that many units.
+(If you want to manipulate the data instead of displaying it,
+see the @code{mem2array} primitives.)
+@end deffn
+
+@deffn Command mww [phys] addr word
+@deffnx Command mwh [phys] addr halfword
+@deffnx Command mwb [phys] addr byte
+Writes the specified @var{word} (32 bits),
+@var{halfword} (16 bits), or @var{byte} (8-bit) value,
+at the specified address @var{addr}.
+When the current target has an MMU which is present and active,
+@var{addr} is interpreted as a virtual address.
+Otherwise, or if the optional @var{phys} flag is specified,
+@var{addr} is interpreted as a physical address.
+@end deffn
+
+
+@anchor{Image access}
+@section Image loading commands
+@cindex image loading
+@cindex image dumping
+
+@anchor{dump_image}
+@deffn Command {dump_image} filename address size
+Dump @var{size} bytes of target memory starting at @var{address} to the
+binary file named @var{filename}.
+@end deffn
+
+@deffn Command {fast_load}
+Loads an image stored in memory by @command{fast_load_image} to the
+current target. Must be preceeded by fast_load_image.
+@end deffn
+
+@deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
+Normally you should be using @command{load_image} or GDB load. However, for
+testing purposes or when I/O overhead is significant(OpenOCD running on an embedded
+host), storing the image in memory and uploading the image to the target
+can be a way to upload e.g. multiple debug sessions when the binary does not change.
+Arguments are the same as @command{load_image}, but the image is stored in OpenOCD host
+memory, i.e. does not affect target. This approach is also useful when profiling
+target programming performance as I/O and target programming can easily be profiled
+separately.
+@end deffn
+
+@anchor{load_image}
+@deffn Command {load_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
+Load image from file @var{filename} to target memory at @var{address}.
+The file format may optionally be specified
+(@option{bin}, @option{ihex}, or @option{elf})
+@end deffn
+
+@deffn Command {test_image} filename [address [@option{bin}|@option{ihex}|@option{elf}]]
+Displays image section sizes and addresses
+as if @var{filename} were loaded into target memory
+starting at @var{address} (defaults to zero).
+The file format may optionally be specified
+(@option{bin}, @option{ihex}, or @option{elf})
+@end deffn
+
+@deffn Command {verify_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
+Verify @var{filename} against target memory starting at @var{address}.
+The file format may optionally be specified
+(@option{bin}, @option{ihex}, or @option{elf})
+This will first attempt a comparison using a CRC checksum, if this fails it will try a binary compare.
+@end deffn
+
+
+@section Breakpoint and Watchpoint commands
+@cindex breakpoint
+@cindex watchpoint
+
+CPUs often make debug modules accessible through JTAG, with
+hardware support for a handful of code breakpoints and data
+watchpoints.
+In addition, CPUs almost always support software breakpoints.
+
+@deffn Command {bp} [address len [@option{hw}]]
+With no parameters, lists all active breakpoints.
+Else sets a breakpoint on code execution starting
+at @var{address} for @var{length} bytes.
+This is a software breakpoint, unless @option{hw} is specified
+in which case it will be a hardware breakpoint.
+
+(@xref{arm9 vector_catch}, or @pxref{xscale vector_catch},
+for similar mechanisms that do not consume hardware breakpoints.)
+@end deffn
+
+@deffn Command {rbp} address
+Remove the breakpoint at @var{address}.
+@end deffn
+
+@deffn Command {rwp} address
+Remove data watchpoint on @var{address}
+@end deffn
+
+@deffn Command {wp} [address len [(@option{r}|@option{w}|@option{a}) [value [mask]]]]
+With no parameters, lists all active watchpoints.
+Else sets a data watchpoint on data from @var{address} for @var{length} bytes.
+The watch point is an "access" watchpoint unless
+the @option{r} or @option{w} parameter is provided,
+defining it as respectively a read or write watchpoint.
+If a @var{value} is provided, that value is used when determining if
+the watchpoint should trigger. The value may be first be masked
+using @var{mask} to mark ``don't care'' fields.
+@end deffn
+
+@section Misc Commands
+
+@cindex profiling
+@deffn Command {profile} seconds filename
+Profiling samples the CPU's program counter as quickly as possible,
+which is useful for non-intrusive stochastic profiling.
+Saves up to 10000 sampines in @file{filename} using ``gmon.out'' format.
+@end deffn
+
+@deffn Command {version}
+Displays a string identifying the version of this OpenOCD server.
+@end deffn
+
+@deffn Command {virt2phys} virtual_address
+Requests the current target to map the specified @var{virtual_address}
+to its corresponding physical address, and displays the result.
+@end deffn
+
+@node Architecture and Core Commands
+@chapter Architecture and Core Commands
+@cindex Architecture Specific Commands
+@cindex Core Specific Commands
+
+Most CPUs have specialized JTAG operations to support debugging.
+OpenOCD packages most such operations in its standard command framework.
+Some of those operations don't fit well in that framework, so they are
+exposed here as architecture or implementation (core) specific commands.
+
+@anchor{ARM Hardware Tracing}
+@section ARM Hardware Tracing
+@cindex tracing
+@cindex ETM
+@cindex ETB
+
+CPUs based on ARM cores may include standard tracing interfaces,
+based on an ``Embedded Trace Module'' (ETM) which sends voluminous
+address and data bus trace records to a ``Trace Port''.
+
+@itemize
+@item
+Development-oriented boards will sometimes provide a high speed
+trace connector for collecting that data, when the particular CPU
+supports such an interface.
+(The standard connector is a 38-pin Mictor, with both JTAG
+and trace port support.)
+Those trace connectors are supported by higher end JTAG adapters
+and some logic analyzer modules; frequently those modules can
+buffer several megabytes of trace data.
+Configuring an ETM coupled to such an external trace port belongs
+in the board-specific configuration file.
+@item
+If the CPU doesn't provide an external interface, it probably
+has an ``Embedded Trace Buffer'' (ETB) on the chip, which is a
+dedicated SRAM. 4KBytes is one common ETB size.
+Configuring an ETM coupled only to an ETB belongs in the CPU-specific
+(target) configuration file, since it works the same on all boards.
+@end itemize
+
+ETM support in OpenOCD doesn't seem to be widely used yet.
+
+@quotation Issues
+ETM support may be buggy, and at least some @command{etm config}
+parameters should be detected by asking the ETM for them.
+
+ETM trigger events could also implement a kind of complex
+hardware breakpoint, much more powerful than the simple
+watchpoint hardware exported by EmbeddedICE modules.
+@emph{Such breakpoints can be triggered even when using the
+dummy trace port driver}.
+
+It seems like a GDB hookup should be possible,
+as well as tracing only during specific states
+(perhaps @emph{handling IRQ 23} or @emph{calls foo()}).
+
+There should be GUI tools to manipulate saved trace data and help
+analyse it in conjunction with the source code.
+It's unclear how much of a common interface is shared
+with the current XScale trace support, or should be
+shared with eventual Nexus-style trace module support.
+
+At this writing (November 2009) only ARM7, ARM9, and ARM11 support
+for ETM modules is available. The code should be able to
+work with some newer cores; but not all of them support
+this original style of JTAG access.
+@end quotation
+
+@subsection ETM Configuration
+ETM setup is coupled with the trace port driver configuration.
+
+@deffn {Config Command} {etm config} target width mode clocking driver
+Declares the ETM associated with @var{target}, and associates it
+with a given trace port @var{driver}. @xref{Trace Port Drivers}.
+
+Several of the parameters must reflect the trace port capabilities,
+which are a function of silicon capabilties (exposed later
+using @command{etm info}) and of what hardware is connected to
+that port (such as an external pod, or ETB).
+The @var{width} must be either 4, 8, or 16,
+except with ETMv3.0 and newer modules which may also
+support 1, 2, 24, 32, 48, and 64 bit widths.
+(With those versions, @command{etm info} also shows whether
+the selected port width and mode are supported.)
+
+The @var{mode} must be @option{normal}, @option{multiplexed},
+or @option{demultiplexed}.
+The @var{clocking} must be @option{half} or @option{full}.
+
+@quotation Warning
+With ETMv3.0 and newer, the bits set with the @var{mode} and
+@var{clocking} parameters both control the mode.
+This modified mode does not map to the values supported by
+previous ETM modules, so this syntax is subject to change.
+@end quotation
+
+@quotation Note
+You can see the ETM registers using the @command{reg} command.
+Not all possible registers are present in every ETM.
+Most of the registers are write-only, and are used to configure
+what CPU activities are traced.
+@end quotation
+@end deffn
+
+@deffn Command {etm info}
+Displays information about the current target's ETM.
+This includes resource counts from the @code{ETM_CONFIG} register,
+as well as silicon capabilities (except on rather old modules).
+from the @code{ETM_SYS_CONFIG} register.
+@end deffn
+
+@deffn Command {etm status}
+Displays status of the current target's ETM and trace port driver:
+is the ETM idle, or is it collecting data?
+Did trace data overflow?
+Was it triggered?
+@end deffn