+Examples:
+@itemize @bullet
+@item at91sam7x256 - has 256K flash YES enable it.
+@item str912 - has flash internal YES enable it.
+@item imx27 - uses boot flash on CS0 - it goes in the board file.
+@item pxa270 - again - CS0 flash - it goes in the board file.
+@end itemize
+
+@anchor{Translating Configuration Files}
+@section Translating Configuration Files
+@cindex translation
+If you have a configuration file for another hardware debugger
+or toolset (Abatron, BDI2000, BDI3000, CCS,
+Lauterbach, Segger, Macraigor, etc.), translating
+it into OpenOCD syntax is often quite straightforward. The most tricky
+part of creating a configuration script is oftentimes the reset init
+sequence where e.g. PLLs, DRAM and the like is set up.
+
+One trick that you can use when translating is to write small
+Tcl procedures to translate the syntax into OpenOCD syntax. This
+can avoid manual translation errors and make it easier to
+convert other scripts later on.
+
+Example of transforming quirky arguments to a simple search and
+replace job:
+
+@example
+# Lauterbach syntax(?)
+#
+# Data.Set c15:0x042f %long 0x40000015
+#
+# OpenOCD syntax when using procedure below.
+#
+# setc15 0x01 0x00050078
+
+proc setc15 @{regs value@} @{
+ global TARGETNAME
+
+ echo [format "set p15 0x%04x, 0x%08x" $regs $value]
+
+ mcr 15 [expr ($regs>>12)&0x7] \
+ [expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] \
+ [expr ($regs>>8)&0x7] $value
+@}
+@end example
+
+
+
+@node Daemon Configuration
+@chapter Daemon Configuration
+@cindex initialization
+The commands here are commonly found in the openocd.cfg file and are
+used to specify what TCP/IP ports are used, and how GDB should be
+supported.
+
+@anchor{Configuration Stage}
+@section Configuration Stage
+@cindex configuration stage
+@cindex config command
+
+When the OpenOCD server process starts up, it enters a
+@emph{configuration stage} which is the only time that
+certain commands, @emph{configuration commands}, may be issued.
+In this manual, the definition of a configuration command is
+presented as a @emph{Config Command}, not as a @emph{Command}
+which may be issued interactively.
+
+Those configuration commands include declaration of TAPs,
+flash banks,
+the interface used for JTAG communication,
+and other basic setup.
+The server must leave the configuration stage before it
+may access or activate TAPs.
+After it leaves this stage, configuration commands may no
+longer be issued.
+
+@section Entering the Run Stage
+
+The first thing OpenOCD does after leaving the configuration
+stage is to verify that it can talk to the scan chain
+(list of TAPs) which has been configured.
+It will warn if it doesn't find TAPs it expects to find,
+or finds TAPs that aren't supposed to be there.
+You should see no errors at this point.
+If you see errors, resolve them by correcting the
+commands you used to configure the server.
+Common errors include using an initial JTAG speed that's too
+fast, and not providing the right IDCODE values for the TAPs
+on the scan chain.
+
+Once OpenOCD has entered the run stage, a number of commands
+become available.
+A number of these relate to the debug targets you may have declared.
+For example, the @command{mww} command will not be available until
+a target has been successfuly instantiated.
+If you want to use those commands, you may need to force
+entry to the run stage.
+
+@deffn {Config Command} init
+This command terminates the configuration stage and
+enters the run stage. This helps when you need to have
+the startup scripts manage tasks such as resetting the target,
+programming flash, etc. To reset the CPU upon startup, add "init" and
+"reset" at the end of the config script or at the end of the OpenOCD
+command line using the @option{-c} command line switch.
+
+If this command does not appear in any startup/configuration file
+OpenOCD executes the command for you after processing all
+configuration files and/or command line options.
+
+@b{NOTE:} This command normally occurs at or near the end of your
+openocd.cfg file to force OpenOCD to ``initialize'' and make the
+targets ready. For example: If your openocd.cfg file needs to
+read/write memory on your target, @command{init} must occur before
+the memory read/write commands. This includes @command{nand probe}.
+@end deffn
+
+@deffn {Overridable Procedure} jtag_init
+This is invoked at server startup to verify that it can talk
+to the scan chain (list of TAPs) which has been configured.
+
+The default implementation first tries @command{jtag arp_init},
+which uses only a lightweight JTAG reset before examining the
+scan chain.
+If that fails, it tries again, using a harder reset
+from the overridable procedure @command{init_reset}.
+
+Implementations must have verified the JTAG scan chain before
+they return.
+This is done by calling @command{jtag arp_init}
+(or @command{jtag arp_init-reset}).
+@end deffn
+
+@anchor{TCP/IP Ports}
+@section TCP/IP Ports
+@cindex TCP port
+@cindex server
+@cindex port
+@cindex security
+The OpenOCD server accepts remote commands in several syntaxes.
+Each syntax uses a different TCP/IP port, which you may specify
+only during configuration (before those ports are opened).
+
+For reasons including security, you may wish to prevent remote
+access using one or more of these ports.
+In such cases, just specify the relevant port number as zero.
+If you disable all access through TCP/IP, you will need to
+use the command line @option{-pipe} option.
+
+@deffn {Command} gdb_port (number)
+@cindex GDB server
+Specify or query the first port used for incoming GDB connections.
+The GDB port for the
+first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
+When not specified during the configuration stage,
+the port @var{number} defaults to 3333.
+When specified as zero, this port is not activated.
+@end deffn
+
+@deffn {Command} tcl_port (number)
+Specify or query the port used for a simplified RPC
+connection that can be used by clients to issue TCL commands and get the
+output from the Tcl engine.
+Intended as a machine interface.
+When not specified during the configuration stage,
+the port @var{number} defaults to 6666.
+When specified as zero, this port is not activated.
+@end deffn
+
+@deffn {Command} telnet_port (number)
+Specify or query the
+port on which to listen for incoming telnet connections.
+This port is intended for interaction with one human through TCL commands.
+When not specified during the configuration stage,
+the port @var{number} defaults to 4444.
+When specified as zero, this port is not activated.
+@end deffn
+
+@anchor{GDB Configuration}
+@section GDB Configuration
+@cindex GDB
+@cindex GDB configuration
+You can reconfigure some GDB behaviors if needed.
+The ones listed here are static and global.
+@xref{Target Configuration}, about configuring individual targets.
+@xref{Target Events}, about configuring target-specific event handling.
+
+@anchor{gdb_breakpoint_override}
+@deffn {Command} gdb_breakpoint_override [@option{hard}|@option{soft}|@option{disable}]
+Force breakpoint type for gdb @command{break} commands.
+This option supports GDB GUIs which don't
+distinguish hard versus soft breakpoints, if the default OpenOCD and
+GDB behaviour is not sufficient. GDB normally uses hardware
+breakpoints if the memory map has been set up for flash regions.
+@end deffn
+
+@anchor{gdb_flash_program}
+@deffn {Config Command} gdb_flash_program (@option{enable}|@option{disable})
+Set to @option{enable} to cause OpenOCD to program the flash memory when a
+vFlash packet is received.
+The default behaviour is @option{enable}.
+@end deffn
+
+@deffn {Config Command} gdb_memory_map (@option{enable}|@option{disable})
+Set to @option{enable} to cause OpenOCD to send the memory configuration to GDB when
+requested. GDB will then know when to set hardware breakpoints, and program flash
+using the GDB load command. @command{gdb_flash_program enable} must also be enabled
+for flash programming to work.
+Default behaviour is @option{enable}.
+@xref{gdb_flash_program}.
+@end deffn
+
+@deffn {Config Command} gdb_report_data_abort (@option{enable}|@option{disable})
+Specifies whether data aborts cause an error to be reported
+by GDB memory read packets.
+The default behaviour is @option{disable};
+use @option{enable} see these errors reported.
+@end deffn
+
+@anchor{Event Polling}
+@section Event Polling
+
+Hardware debuggers are parts of asynchronous systems,
+where significant events can happen at any time.
+The OpenOCD server needs to detect some of these events,
+so it can report them to through TCL command line
+or to GDB.
+
+Examples of such events include:
+
+@itemize
+@item One of the targets can stop running ... maybe it triggers
+a code breakpoint or data watchpoint, or halts itself.
+@item Messages may be sent over ``debug message'' channels ... many
+targets support such messages sent over JTAG,
+for receipt by the person debugging or tools.
+@item Loss of power ... some adapters can detect these events.
+@item Resets not issued through JTAG ... such reset sources
+can include button presses or other system hardware, sometimes
+including the target itself (perhaps through a watchdog).
+@item Debug instrumentation sometimes supports event triggering
+such as ``trace buffer full'' (so it can quickly be emptied)
+or other signals (to correlate with code behavior).
+@end itemize
+
+None of those events are signaled through standard JTAG signals.
+However, most conventions for JTAG connectors include voltage
+level and system reset (SRST) signal detection.
+Some connectors also include instrumentation signals, which
+can imply events when those signals are inputs.
+
+In general, OpenOCD needs to periodically check for those events,
+either by looking at the status of signals on the JTAG connector
+or by sending synchronous ``tell me your status'' JTAG requests
+to the various active targets.
+There is a command to manage and monitor that polling,
+which is normally done in the background.
+
+@deffn Command poll [@option{on}|@option{off}]
+Poll the current target for its current state.
+(Also, @pxref{target curstate}.)
+If that target is in debug mode, architecture
+specific information about the current state is printed.
+An optional parameter
+allows background polling to be enabled and disabled.
+
+You could use this from the TCL command shell, or
+from GDB using @command{monitor poll} command.
+@example
+> poll
+background polling: on
+target state: halted
+target halted in ARM state due to debug-request, \
+ current mode: Supervisor
+cpsr: 0x800000d3 pc: 0x11081bfc
+MMU: disabled, D-Cache: disabled, I-Cache: enabled
+>
+@end example
+@end deffn
+
+@node Interface - Dongle Configuration
+@chapter Interface - Dongle Configuration
+@cindex config file, interface
+@cindex interface config file
+
+JTAG Adapters/Interfaces/Dongles are normally configured
+through commands in an interface configuration
+file which is sourced by your @file{openocd.cfg} file, or
+through a command line @option{-f interface/....cfg} option.
+
+@example
+source [find interface/olimex-jtag-tiny.cfg]
+@end example
+
+These commands tell
+OpenOCD what type of JTAG adapter you have, and how to talk to it.
+A few cases are so simple that you only need to say what driver to use:
+
+@example
+# jlink interface
+interface jlink
+@end example
+
+Most adapters need a bit more configuration than that.
+
+
+@section Interface Configuration
+
+The interface command tells OpenOCD what type of JTAG dongle you are
+using. Depending on the type of dongle, you may need to have one or
+more additional commands.
+
+@deffn {Config Command} {interface} name
+Use the interface driver @var{name} to connect to the
+target.
+@end deffn
+
+@deffn Command {interface_list}
+List the interface drivers that have been built into
+the running copy of OpenOCD.
+@end deffn
+
+@deffn Command {jtag interface}
+Returns the name of the interface driver being used.
+@end deffn
+
+@section Interface Drivers
+
+Each of the interface drivers listed here must be explicitly
+enabled when OpenOCD is configured, in order to be made
+available at run time.
+
+@deffn {Interface Driver} {amt_jtagaccel}
+Amontec Chameleon in its JTAG Accelerator configuration,
+connected to a PC's EPP mode parallel port.
+This defines some driver-specific commands:
+
+@deffn {Config Command} {parport_port} number
+Specifies either the address of the I/O port (default: 0x378 for LPT1) or
+the number of the @file{/dev/parport} device.
+@end deffn
+
+@deffn {Config Command} rtck [@option{enable}|@option{disable}]
+Displays status of RTCK option.
+Optionally sets that option first.
+@end deffn
+@end deffn
+
+@deffn {Interface Driver} {arm-jtag-ew}
+Olimex ARM-JTAG-EW USB adapter
+This has one driver-specific command:
+
+@deffn Command {armjtagew_info}
+Logs some status
+@end deffn
+@end deffn
+
+@deffn {Interface Driver} {at91rm9200}
+Supports bitbanged JTAG from the local system,
+presuming that system is an Atmel AT91rm9200
+and a specific set of GPIOs is used.
+@c command: at91rm9200_device NAME
+@c chooses among list of bit configs ... only one option
+@end deffn
+
+@deffn {Interface Driver} {dummy}
+A dummy software-only driver for debugging.
+@end deffn
+
+@deffn {Interface Driver} {ep93xx}
+Cirrus Logic EP93xx based single-board computer bit-banging (in development)
+@end deffn
+
+@deffn {Interface Driver} {ft2232}
+FTDI FT2232 (USB) based devices over one of the userspace libraries.
+These interfaces have several commands, used to configure the driver
+before initializing the JTAG scan chain:
+
+@deffn {Config Command} {ft2232_device_desc} description
+Provides the USB device description (the @emph{iProduct string})
+of the FTDI FT2232 device. If not
+specified, the FTDI default value is used. This setting is only valid
+if compiled with FTD2XX support.
+@end deffn
+
+@deffn {Config Command} {ft2232_serial} serial-number
+Specifies the @var{serial-number} of the FTDI FT2232 device to use,
+in case the vendor provides unique IDs and more than one FT2232 device
+is connected to the host.
+If not specified, serial numbers are not considered.
+(Note that USB serial numbers can be arbitrary Unicode strings,
+and are not restricted to containing only decimal digits.)
+@end deffn
+
+@deffn {Config Command} {ft2232_layout} name
+Each vendor's FT2232 device can use different GPIO signals
+to control output-enables, reset signals, and LEDs.
+Currently valid layout @var{name} values include:
+@itemize @minus
+@item @b{axm0432_jtag} Axiom AXM-0432
+@item @b{comstick} Hitex STR9 comstick
+@item @b{cortino} Hitex Cortino JTAG interface
+@item @b{evb_lm3s811} Luminary Micro EVB_LM3S811 as a JTAG interface,
+either for the local Cortex-M3 (SRST only)
+or in a passthrough mode (neither SRST nor TRST)
+@item @b{luminary_icdi} Luminary In-Circuit Debug Interface (ICDI) Board
+@item @b{flyswatter} Tin Can Tools Flyswatter
+@item @b{icebear} ICEbear JTAG adapter from Section 5
+@item @b{jtagkey} Amontec JTAGkey and JTAGkey-Tiny (and compatibles)
+@item @b{jtagkey2} Amontec JTAGkey2 (and compatibles)
+@item @b{m5960} American Microsystems M5960
+@item @b{olimex-jtag} Olimex ARM-USB-OCD and ARM-USB-Tiny
+@item @b{oocdlink} OOCDLink
+@c oocdlink ~= jtagkey_prototype_v1
+@item @b{sheevaplug} Marvell Sheevaplug development kit
+@item @b{signalyzer} Xverve Signalyzer
+@item @b{stm32stick} Hitex STM32 Performance Stick
+@item @b{turtelizer2} egnite Software turtelizer2
+@item @b{usbjtag} "USBJTAG-1" layout described in the OpenOCD diploma thesis
+@end itemize
+@end deffn
+
+@deffn {Config Command} {ft2232_vid_pid} [vid pid]+
+The vendor ID and product ID of the FTDI FT2232 device. If not specified, the FTDI
+default values are used.
+Currently, up to eight [@var{vid}, @var{pid}] pairs may be given, e.g.
+@example
+ft2232_vid_pid 0x0403 0xcff8 0x15ba 0x0003
+@end example
+@end deffn
+
+@deffn {Config Command} {ft2232_latency} ms
+On some systems using FT2232 based JTAG interfaces the FT_Read function call in
+ft2232_read() fails to return the expected number of bytes. This can be caused by
+USB communication delays and has proved hard to reproduce and debug. Setting the
+FT2232 latency timer to a larger value increases delays for short USB packets but it
+also reduces the risk of timeouts before receiving the expected number of bytes.
+The OpenOCD default value is 2 and for some systems a value of 10 has proved useful.
+@end deffn
+
+For example, the interface config file for a
+Turtelizer JTAG Adapter looks something like this:
+
+@example
+interface ft2232
+ft2232_device_desc "Turtelizer JTAG/RS232 Adapter"
+ft2232_layout turtelizer2
+ft2232_vid_pid 0x0403 0xbdc8
+@end example
+@end deffn
+
+@deffn {Interface Driver} {gw16012}
+Gateworks GW16012 JTAG programmer.
+This has one driver-specific command:
+
+@deffn {Config Command} {parport_port} number
+Specifies either the address of the I/O port (default: 0x378 for LPT1) or
+the number of the @file{/dev/parport} device.
+@end deffn
+@end deffn
+
+@deffn {Interface Driver} {jlink}
+Segger jlink USB adapter
+@c command: jlink_info
+@c dumps status
+@c command: jlink_hw_jtag (2|3)
+@c sets version 2 or 3
+@end deffn
+
+@deffn {Interface Driver} {parport}
+Supports PC parallel port bit-banging cables:
+Wigglers, PLD download cable, and more.
+These interfaces have several commands, used to configure the driver
+before initializing the JTAG scan chain:
+
+@deffn {Config Command} {parport_cable} name
+The layout of the parallel port cable used to connect to the target.
+Currently valid cable @var{name} values include:
+
+@itemize @minus
+@item @b{altium} Altium Universal JTAG cable.
+@item @b{arm-jtag} Same as original wiggler except SRST and
+TRST connections reversed and TRST is also inverted.
+@item @b{chameleon} The Amontec Chameleon's CPLD when operated
+in configuration mode. This is only used to
+program the Chameleon itself, not a connected target.
+@item @b{dlc5} The Xilinx Parallel cable III.
+@item @b{flashlink} The ST Parallel cable.
+@item @b{lattice} Lattice ispDOWNLOAD Cable
+@item @b{old_amt_wiggler} The Wiggler configuration that comes with
+some versions of
+Amontec's Chameleon Programmer. The new version available from
+the website uses the original Wiggler layout ('@var{wiggler}')
+@item @b{triton} The parallel port adapter found on the
+``Karo Triton 1 Development Board''.
+This is also the layout used by the HollyGates design
+(see @uref{http://www.lartmaker.nl/projects/jtag/}).
+@item @b{wiggler} The original Wiggler layout, also supported by
+several clones, such as the Olimex ARM-JTAG
+@item @b{wiggler2} Same as original wiggler except an led is fitted on D5.
+@item @b{wiggler_ntrst_inverted} Same as original wiggler except TRST is inverted.
+@end itemize
+@end deffn
+
+@deffn {Config Command} {parport_port} number
+Either the address of the I/O port (default: 0x378 for LPT1) or the number of
+the @file{/dev/parport} device
+
+When using PPDEV to access the parallel port, use the number of the parallel port:
+@option{parport_port 0} (the default). If @option{parport_port 0x378} is specified
+you may encounter a problem.
+@end deffn
+
+@deffn Command {parport_toggling_time} [nanoseconds]
+Displays how many nanoseconds the hardware needs to toggle TCK;
+the parport driver uses this value to obey the
+@command{jtag_khz} configuration.
+When the optional @var{nanoseconds} parameter is given,
+that setting is changed before displaying the current value.
+
+The default setting should work reasonably well on commodity PC hardware.
+However, you may want to calibrate for your specific hardware.
+@quotation Tip
+To measure the toggling time with a logic analyzer or a digital storage
+oscilloscope, follow the procedure below:
+@example
+> parport_toggling_time 1000
+> jtag_khz 500
+@end example
+This sets the maximum JTAG clock speed of the hardware, but
+the actual speed probably deviates from the requested 500 kHz.
+Now, measure the time between the two closest spaced TCK transitions.
+You can use @command{runtest 1000} or something similar to generate a
+large set of samples.
+Update the setting to match your measurement:
+@example
+> parport_toggling_time <measured nanoseconds>
+@end example
+Now the clock speed will be a better match for @command{jtag_khz rate}
+commands given in OpenOCD scripts and event handlers.
+
+You can do something similar with many digital multimeters, but note
+that you'll probably need to run the clock continuously for several
+seconds before it decides what clock rate to show. Adjust the
+toggling time up or down until the measured clock rate is a good
+match for the jtag_khz rate you specified; be conservative.
+@end quotation
+@end deffn
+
+@deffn {Config Command} {parport_write_on_exit} (on|off)
+This will configure the parallel driver to write a known
+cable-specific value to the parallel interface on exiting OpenOCD
+@end deffn
+
+For example, the interface configuration file for a
+classic ``Wiggler'' cable might look something like this:
+
+@example
+interface parport
+parport_port 0xc8b8
+parport_cable wiggler
+@end example
+@end deffn
+
+@deffn {Interface Driver} {presto}
+ASIX PRESTO USB JTAG programmer.
+@c command: presto_serial str
+@c sets serial number
+@end deffn
+
+@deffn {Interface Driver} {rlink}
+Raisonance RLink USB adapter
+@end deffn
+
+@deffn {Interface Driver} {usbprog}
+usbprog is a freely programmable USB adapter.
+@end deffn
+
+@deffn {Interface Driver} {vsllink}
+vsllink is part of Versaloon which is a versatile USB programmer.
+
+@quotation Note
+This defines quite a few driver-specific commands,
+which are not currently documented here.
+@end quotation
+@end deffn
+
+@deffn {Interface Driver} {ZY1000}
+This is the Zylin ZY1000 JTAG debugger.
+
+@quotation Note
+This defines some driver-specific commands,
+which are not currently documented here.
+@end quotation
+
+@deffn Command power [@option{on}|@option{off}]
+Turn power switch to target on/off.
+No arguments: print status.
+@end deffn
+
+@end deffn
+
+@anchor{JTAG Speed}
+@section JTAG Speed
+JTAG clock setup is part of system setup.
+It @emph{does not belong with interface setup} since any interface
+only knows a few of the constraints for the JTAG clock speed.
+Sometimes the JTAG speed is
+changed during the target initialization process: (1) slow at
+reset, (2) program the CPU clocks, (3) run fast.
+Both the "slow" and "fast" clock rates are functions of the
+oscillators used, the chip, the board design, and sometimes
+power management software that may be active.
+
+The speed used during reset, and the scan chain verification which
+follows reset, can be adjusted using a @code{reset-start}
+target event handler.
+It can then be reconfigured to a faster speed by a
+@code{reset-init} target event handler after it reprograms those
+CPU clocks, or manually (if something else, such as a boot loader,
+sets up those clocks).
+@xref{Target Events}.
+When the initial low JTAG speed is a chip characteristic, perhaps
+because of a required oscillator speed, provide such a handler
+in the target config file.
+When that speed is a function of a board-specific characteristic
+such as which speed oscillator is used, it belongs in the board
+config file instead.
+In both cases it's safest to also set the initial JTAG clock rate
+to that same slow speed, so that OpenOCD never starts up using a
+clock speed that's faster than the scan chain can support.
+
+@example
+jtag_rclk 3000
+$_TARGET.cpu configure -event reset-start @{ jtag_rclk 3000 @}
+@end example
+
+If your system supports adaptive clocking (RTCK), configuring
+JTAG to use that is probably the most robust approach.
+However, it introduces delays to synchronize clocks; so it
+may not be the fastest solution.
+
+@b{NOTE:} Script writers should consider using @command{jtag_rclk}
+instead of @command{jtag_khz}.
+
+@deffn {Command} jtag_khz max_speed_kHz
+A non-zero speed is in KHZ. Hence: 3000 is 3mhz.
+JTAG interfaces usually support a limited number of
+speeds. The speed actually used won't be faster
+than the speed specified.
+
+Chip data sheets generally include a top JTAG clock rate.
+The actual rate is often a function of a CPU core clock,
+and is normally less than that peak rate.
+For example, most ARM cores accept at most one sixth of the CPU clock.
+
+Speed 0 (khz) selects RTCK method.
+@xref{FAQ RTCK}.
+If your system uses RTCK, you won't need to change the
+JTAG clocking after setup.
+Not all interfaces, boards, or targets support ``rtck''.
+If the interface device can not
+support it, an error is returned when you try to use RTCK.
+@end deffn
+
+@defun jtag_rclk fallback_speed_kHz
+@cindex adaptive clocking
+@cindex RTCK
+This Tcl proc (defined in @file{startup.tcl}) attempts to enable RTCK/RCLK.
+If that fails (maybe the interface, board, or target doesn't
+support it), falls back to the specified frequency.
+@example
+# Fall back to 3mhz if RTCK is not supported
+jtag_rclk 3000
+@end example
+@end defun
+
+@node Reset Configuration
+@chapter Reset Configuration
+@cindex Reset Configuration
+
+Every system configuration may require a different reset
+configuration. This can also be quite confusing.
+Resets also interact with @var{reset-init} event handlers,
+which do things like setting up clocks and DRAM, and
+JTAG clock rates. (@xref{JTAG Speed}.)
+They can also interact with JTAG routers.
+Please see the various board files for examples.
+
+@quotation Note
+To maintainers and integrators:
+Reset configuration touches several things at once.
+Normally the board configuration file
+should define it and assume that the JTAG adapter supports
+everything that's wired up to the board's JTAG connector.
+
+However, the target configuration file could also make note
+of something the silicon vendor has done inside the chip,
+which will be true for most (or all) boards using that chip.
+And when the JTAG adapter doesn't support everything, the
+user configuration file will need to override parts of
+the reset configuration provided by other files.
+@end quotation
+
+@section Types of Reset
+
+There are many kinds of reset possible through JTAG, but
+they may not all work with a given board and adapter.
+That's part of why reset configuration can be error prone.
+
+@itemize @bullet
+@item
+@emph{System Reset} ... the @emph{SRST} hardware signal
+resets all chips connected to the JTAG adapter, such as processors,
+power management chips, and I/O controllers. Normally resets triggered
+with this signal behave exactly like pressing a RESET button.
+@item
+@emph{JTAG TAP Reset} ... the @emph{TRST} hardware signal resets
+just the TAP controllers connected to the JTAG adapter.
+Such resets should not be visible to the rest of the system; resetting a
+device's the TAP controller just puts that controller into a known state.
+@item
+@emph{Emulation Reset} ... many devices can be reset through JTAG
+commands. These resets are often distinguishable from system
+resets, either explicitly (a "reset reason" register says so)
+or implicitly (not all parts of the chip get reset).
+@item
+@emph{Other Resets} ... system-on-chip devices often support
+several other types of reset.
+You may need to arrange that a watchdog timer stops
+while debugging, preventing a watchdog reset.
+There may be individual module resets.
+@end itemize
+
+In the best case, OpenOCD can hold SRST, then reset
+the TAPs via TRST and send commands through JTAG to halt the
+CPU at the reset vector before the 1st instruction is executed.
+Then when it finally releases the SRST signal, the system is
+halted under debugger control before any code has executed.
+This is the behavior required to support the @command{reset halt}
+and @command{reset init} commands; after @command{reset init} a
+board-specific script might do things like setting up DRAM.
+(@xref{Reset Command}.)
+
+@anchor{SRST and TRST Issues}
+@section SRST and TRST Issues
+
+Because SRST and TRST are hardware signals, they can have a
+variety of system-specific constraints. Some of the most
+common issues are:
+
+@itemize @bullet
+
+@item @emph{Signal not available} ... Some boards don't wire
+SRST or TRST to the JTAG connector. Some JTAG adapters don't
+support such signals even if they are wired up.
+Use the @command{reset_config} @var{signals} options to say
+when either of those signals is not connected.
+When SRST is not available, your code might not be able to rely
+on controllers having been fully reset during code startup.
+Missing TRST is not a problem, since JTAG level resets can
+be triggered using with TMS signaling.
+
+@item @emph{Signals shorted} ... Sometimes a chip, board, or
+adapter will connect SRST to TRST, instead of keeping them separate.
+Use the @command{reset_config} @var{combination} options to say
+when those signals aren't properly independent.
+
+@item @emph{Timing} ... Reset circuitry like a resistor/capacitor
+delay circuit, reset supervisor, or on-chip features can extend
+the effect of a JTAG adapter's reset for some time after the adapter
+stops issuing the reset. For example, there may be chip or board
+requirements that all reset pulses last for at least a
+certain amount of time; and reset buttons commonly have
+hardware debouncing.
+Use the @command{jtag_nsrst_delay} and @command{jtag_ntrst_delay}
+commands to say when extra delays are needed.
+
+@item @emph{Drive type} ... Reset lines often have a pullup
+resistor, letting the JTAG interface treat them as open-drain
+signals. But that's not a requirement, so the adapter may need
+to use push/pull output drivers.
+Also, with weak pullups it may be advisable to drive
+signals to both levels (push/pull) to minimize rise times.
+Use the @command{reset_config} @var{trst_type} and
+@var{srst_type} parameters to say how to drive reset signals.
+
+@item @emph{Special initialization} ... Targets sometimes need
+special JTAG initialization sequences to handle chip-specific
+issues (not limited to errata).
+For example, certain JTAG commands might need to be issued while
+the system as a whole is in a reset state (SRST active)
+but the JTAG scan chain is usable (TRST inactive).
+Many systems treat combined assertion of SRST and TRST as a
+trigger for a harder reset than SRST alone.
+Such custom reset handling is discussed later in this chapter.
+@end itemize
+
+There can also be other issues.
+Some devices don't fully conform to the JTAG specifications.
+Trivial system-specific differences are common, such as
+SRST and TRST using slightly different names.
+There are also vendors who distribute key JTAG documentation for
+their chips only to developers who have signed a Non-Disclosure
+Agreement (NDA).
+
+Sometimes there are chip-specific extensions like a requirement to use
+the normally-optional TRST signal (precluding use of JTAG adapters which
+don't pass TRST through), or needing extra steps to complete a TAP reset.
+
+In short, SRST and especially TRST handling may be very finicky,
+needing to cope with both architecture and board specific constraints.
+
+@section Commands for Handling Resets
+
+@deffn {Command} jtag_nsrst_assert_width milliseconds
+Minimum amount of time (in milliseconds) OpenOCD should wait
+after asserting nSRST (active-low system reset) before
+allowing it to be deasserted.
+@end deffn
+
+@deffn {Command} jtag_nsrst_delay milliseconds
+How long (in milliseconds) OpenOCD should wait after deasserting
+nSRST (active-low system reset) before starting new JTAG operations.
+When a board has a reset button connected to SRST line it will
+probably have hardware debouncing, implying you should use this.
+@end deffn
+
+@deffn {Command} jtag_ntrst_assert_width milliseconds
+Minimum amount of time (in milliseconds) OpenOCD should wait
+after asserting nTRST (active-low JTAG TAP reset) before
+allowing it to be deasserted.
+@end deffn
+
+@deffn {Command} jtag_ntrst_delay milliseconds
+How long (in milliseconds) OpenOCD should wait after deasserting
+nTRST (active-low JTAG TAP reset) before starting new JTAG operations.
+@end deffn
+
+@deffn {Command} reset_config mode_flag ...
+This command displays or modifies the reset configuration
+of your combination of JTAG board and target in target
+configuration scripts.
+
+Information earlier in this section describes the kind of problems
+the command is intended to address (@pxref{SRST and TRST Issues}).
+As a rule this command belongs only in board config files,
+describing issues like @emph{board doesn't connect TRST};
+or in user config files, addressing limitations derived
+from a particular combination of interface and board.
+(An unlikely example would be using a TRST-only adapter
+with a board that only wires up SRST.)
+
+The @var{mode_flag} options can be specified in any order, but only one
+of each type -- @var{signals}, @var{combination},
+@var{gates},
+@var{trst_type},
+and @var{srst_type} -- may be specified at a time.
+If you don't provide a new value for a given type, its previous
+value (perhaps the default) is unchanged.
+For example, this means that you don't need to say anything at all about
+TRST just to declare that if the JTAG adapter should want to drive SRST,
+it must explicitly be driven high (@option{srst_push_pull}).
+
+@itemize
+@item
+@var{signals} can specify which of the reset signals are connected.
+For example, If the JTAG interface provides SRST, but the board doesn't
+connect that signal properly, then OpenOCD can't use it.
+Possible values are @option{none} (the default), @option{trst_only},
+@option{srst_only} and @option{trst_and_srst}.
+
+@quotation Tip
+If your board provides SRST and/or TRST through the JTAG connector,
+you must declare that so those signals can be used.
+@end quotation
+
+@item
+The @var{combination} is an optional value specifying broken reset
+signal implementations.
+The default behaviour if no option given is @option{separate},
+indicating everything behaves normally.
+@option{srst_pulls_trst} states that the
+test logic is reset together with the reset of the system (e.g. Philips
+LPC2000, "broken" board layout), @option{trst_pulls_srst} says that
+the system is reset together with the test logic (only hypothetical, I
+haven't seen hardware with such a bug, and can be worked around).
+@option{combined} implies both @option{srst_pulls_trst} and
+@option{trst_pulls_srst}.
+
+@item
+The @var{gates} tokens control flags that describe some cases where
+JTAG may be unvailable during reset.
+@option{srst_gates_jtag} (default)
+indicates that asserting SRST gates the
+JTAG clock. This means that no communication can happen on JTAG
+while SRST is asserted.
+Its converse is @option{srst_nogate}, indicating that JTAG commands
+can safely be issued while SRST is active.
+@end itemize
+
+The optional @var{trst_type} and @var{srst_type} parameters allow the
+driver mode of each reset line to be specified. These values only affect
+JTAG interfaces with support for different driver modes, like the Amontec
+JTAGkey and JTAG Accelerator. Also, they are necessarily ignored if the
+relevant signal (TRST or SRST) is not connected.
+
+@itemize
+@item
+Possible @var{trst_type} driver modes for the test reset signal (TRST)
+are the default @option{trst_push_pull}, and @option{trst_open_drain}.
+Most boards connect this signal to a pulldown, so the JTAG TAPs
+never leave reset unless they are hooked up to a JTAG adapter.
+
+@item
+Possible @var{srst_type} driver modes for the system reset signal (SRST)
+are the default @option{srst_open_drain}, and @option{srst_push_pull}.
+Most boards connect this signal to a pullup, and allow the
+signal to be pulled low by various events including system
+powerup and pressing a reset button.
+@end itemize
+@end deffn
+
+@section Custom Reset Handling
+@cindex events
+
+OpenOCD has several ways to help support the various reset
+mechanisms provided by chip and board vendors.
+The commands shown in the previous section give standard parameters.
+There are also @emph{event handlers} associated with TAPs or Targets.
+Those handlers are Tcl procedures you can provide, which are invoked
+at particular points in the reset sequence.
+
+After configuring those mechanisms, you might still
+find your board doesn't start up or reset correctly.
+For example, maybe it needs a slightly different sequence
+of SRST and/or TRST manipulations, because of quirks that
+the @command{reset_config} mechanism doesn't address;
+or asserting both might trigger a stronger reset, which
+needs special attention.
+
+Experiment with lower level operations, such as @command{jtag_reset}
+and the @command{jtag arp_*} operations shown here,
+to find a sequence of operations that works.
+@xref{JTAG Commands}.
+When you find a working sequence, it can be used to override
+@command{jtag_init}, which fires during OpenOCD startup
+(@pxref{Configuration Stage});
+or @command{init_reset}, which fires during reset processing.
+
+You might also want to provide some project-specific reset
+schemes. For example, on a multi-target board the standard
+@command{reset} command would reset all targets, but you
+may need the ability to reset only one target at time and
+thus want to avoid using the board-wide SRST signal.
+
+@deffn {Overridable Procedure} init_reset mode
+This is invoked near the beginning of the @command{reset} command,
+usually to provide as much of a cold (power-up) reset as practical.
+By default it is also invoked from @command{jtag_init} if
+the scan chain does not respond to pure JTAG operations.
+The @var{mode} parameter is the parameter given to the
+low level reset command (@option{halt},
+@option{init}, or @option{run}), @option{setup},
+or potentially some other value.
+
+The default implementation just invokes @command{jtag arp_init-reset}.
+Replacements will normally build on low level JTAG
+operations such as @command{jtag_reset}.
+Operations here must not address individual TAPs
+(or their associated targets)
+until the JTAG scan chain has first been verified to work.
+
+Implementations must have verified the JTAG scan chain before
+they return.
+This is done by calling @command{jtag arp_init}
+(or @command{jtag arp_init-reset}).
+@end deffn
+
+@deffn Command {jtag arp_init}
+This validates the scan chain using just the four
+standard JTAG signals (TMS, TCK, TDI, TDO).
+It starts by issuing a JTAG-only reset.
+Then it performs checks to verify that the scan chain configuration
+matches the TAPs it can observe.
+Those checks include checking IDCODE values for each active TAP,
+and verifying the length of their instruction registers using
+TAP @code{-ircapture} and @code{-irmask} values.
+If these tests all pass, TAP @code{setup} events are
+issued to all TAPs with handlers for that event.
+@end deffn
+
+@deffn Command {jtag arp_init-reset}
+This uses TRST and SRST to try resetting
+everything on the JTAG scan chain
+(and anything else connected to SRST).
+It then invokes the logic of @command{jtag arp_init}.
+@end deffn
+
+
+@node TAP Declaration
+@chapter TAP Declaration
+@cindex TAP declaration
+@cindex TAP configuration
+
+@emph{Test Access Ports} (TAPs) are the core of JTAG.
+TAPs serve many roles, including:
+
+@itemize @bullet
+@item @b{Debug Target} A CPU TAP can be used as a GDB debug target
+@item @b{Flash Programing} Some chips program the flash directly via JTAG.
+Others do it indirectly, making a CPU do it.
+@item @b{Program Download} Using the same CPU support GDB uses,
+you can initialize a DRAM controller, download code to DRAM, and then
+start running that code.
+@item @b{Boundary Scan} Most chips support boundary scan, which
+helps test for board assembly problems like solder bridges
+and missing connections
+@end itemize
+
+OpenOCD must know about the active TAPs on your board(s).
+Setting up the TAPs is the core task of your configuration files.
+Once those TAPs are set up, you can pass their names to code
+which sets up CPUs and exports them as GDB targets,
+probes flash memory, performs low-level JTAG operations, and more.
+
+@section Scan Chains
+@cindex scan chain
+
+TAPs are part of a hardware @dfn{scan chain},
+which is daisy chain of TAPs.
+They also need to be added to
+OpenOCD's software mirror of that hardware list,
+giving each member a name and associating other data with it.
+Simple scan chains, with a single TAP, are common in
+systems with a single microcontroller or microprocessor.
+More complex chips may have several TAPs internally.
+Very complex scan chains might have a dozen or more TAPs:
+several in one chip, more in the next, and connecting
+to other boards with their own chips and TAPs.
+
+You can display the list with the @command{scan_chain} command.
+(Don't confuse this with the list displayed by the @command{targets}
+command, presented in the next chapter.
+That only displays TAPs for CPUs which are configured as
+debugging targets.)
+Here's what the scan chain might look like for a chip more than one TAP:
+
+@verbatim
+ TapName Enabled IdCode Expected IrLen IrCap IrMask Instr
+-- ------------------ ------- ---------- ---------- ----- ----- ------ -----
+ 0 omap5912.dsp Y 0x03df1d81 0x03df1d81 38 0 0 0x...
+ 1 omap5912.arm Y 0x0692602f 0x0692602f 4 0x1 0 0xc
+ 2 omap5912.unknown Y 0x00000000 0x00000000 8 0 0 0xff
+@end verbatim
+
+Unfortunately those TAPs can't always be autoconfigured,
+because not all devices provide good support for that.
+JTAG doesn't require supporting IDCODE instructions, and
+chips with JTAG routers may not link TAPs into the chain
+until they are told to do so.
+
+The configuration mechanism currently supported by OpenOCD
+requires explicit configuration of all TAP devices using
+@command{jtag newtap} commands, as detailed later in this chapter.
+A command like this would declare one tap and name it @code{chip1.cpu}:
+
+@example
+jtag newtap chip1 cpu -irlen 4 -expected-id 0x3ba00477
+@end example
+
+Each target configuration file lists the TAPs provided
+by a given chip.
+Board configuration files combine all the targets on a board,
+and so forth.
+Note that @emph{the order in which TAPs are declared is very important.}
+It must match the order in the JTAG scan chain, both inside
+a single chip and between them.
+@xref{FAQ TAP Order}.
+
+For example, the ST Microsystems STR912 chip has
+three separate TAPs@footnote{See the ST
+document titled: @emph{STR91xFAxxx, Section 3.15 Jtag Interface, Page:
+28/102, Figure 3: JTAG chaining inside the STR91xFA}.
+@url{http://eu.st.com/stonline/products/literature/ds/13495.pdf}}.
+To configure those taps, @file{target/str912.cfg}
+includes commands something like this:
+
+@example
+jtag newtap str912 flash ... params ...
+jtag newtap str912 cpu ... params ...
+jtag newtap str912 bs ... params ...
+@end example
+
+Actual config files use a variable instead of literals like
+@option{str912}, to support more than one chip of each type.
+@xref{Config File Guidelines}.
+
+@deffn Command {jtag names}
+Returns the names of all current TAPs in the scan chain.
+Use @command{jtag cget} or @command{jtag tapisenabled}
+to examine attributes and state of each TAP.
+@example
+foreach t [jtag names] @{
+ puts [format "TAP: %s\n" $t]
+@}
+@end example
+@end deffn
+
+@deffn Command {scan_chain}
+Displays the TAPs in the scan chain configuration,
+and their status.
+The set of TAPs listed by this command is fixed by
+exiting the OpenOCD configuration stage,
+but systems with a JTAG router can
+enable or disable TAPs dynamically.
+In addition to the enable/disable status, the contents of
+each TAP's instruction register can also change.
+@end deffn
+
+@c FIXME! "jtag cget" should be able to return all TAP
+@c attributes, like "$target_name cget" does for targets.
+
+@c Probably want "jtag eventlist", and a "tap-reset" event
+@c (on entry to RESET state).
+
+@section TAP Names
+@cindex dotted name
+
+When TAP objects are declared with @command{jtag newtap},
+a @dfn{dotted.name} is created for the TAP, combining the
+name of a module (usually a chip) and a label for the TAP.
+For example: @code{xilinx.tap}, @code{str912.flash},
+@code{omap3530.jrc}, @code{dm6446.dsp}, or @code{stm32.cpu}.
+Many other commands use that dotted.name to manipulate or
+refer to the TAP. For example, CPU configuration uses the
+name, as does declaration of NAND or NOR flash banks.
+
+The components of a dotted name should follow ``C'' symbol
+name rules: start with an alphabetic character, then numbers
+and underscores are OK; while others (including dots!) are not.
+
+@quotation Tip
+In older code, JTAG TAPs were numbered from 0..N.
+This feature is still present.
+However its use is highly discouraged, and
+should not be relied on; it will be removed by mid-2010.
+Update all of your scripts to use TAP names rather than numbers,
+by paying attention to the runtime warnings they trigger.
+Using TAP numbers in target configuration scripts prevents
+reusing those scripts on boards with multiple targets.
+@end quotation
+
+@section TAP Declaration Commands
+
+@c shouldn't this be(come) a {Config Command}?
+@anchor{jtag newtap}
+@deffn Command {jtag newtap} chipname tapname configparams...
+Declares a new TAP with the dotted name @var{chipname}.@var{tapname},
+and configured according to the various @var{configparams}.
+
+The @var{chipname} is a symbolic name for the chip.
+Conventionally target config files use @code{$_CHIPNAME},
+defaulting to the model name given by the chip vendor but
+overridable.
+
+@cindex TAP naming convention
+The @var{tapname} reflects the role of that TAP,
+and should follow this convention:
+
+@itemize @bullet
+@item @code{bs} -- For boundary scan if this is a seperate TAP;
+@item @code{cpu} -- The main CPU of the chip, alternatively
+@code{arm} and @code{dsp} on chips with both ARM and DSP CPUs,
+@code{arm1} and @code{arm2} on chips two ARMs, and so forth;
+@item @code{etb} -- For an embedded trace buffer (example: an ARM ETB11);
+@item @code{flash} -- If the chip has a flash TAP, like the str912;
+@item @code{jrc} -- For JTAG route controller (example: the ICEpick modules
+on many Texas Instruments chips, like the OMAP3530 on Beagleboards);
+@item @code{tap} -- Should be used only FPGA or CPLD like devices
+with a single TAP;
+@item @code{unknownN} -- If you have no idea what the TAP is for (N is a number);
+@item @emph{when in doubt} -- Use the chip maker's name in their data sheet.
+For example, the Freescale IMX31 has a SDMA (Smart DMA) with
+a JTAG TAP; that TAP should be named @code{sdma}.
+@end itemize
+
+Every TAP requires at least the following @var{configparams}:
+
+@itemize @bullet
+@item @code{-irlen} @var{NUMBER}
+@*The length in bits of the
+instruction register, such as 4 or 5 bits.
+@end itemize
+
+A TAP may also provide optional @var{configparams}:
+
+@itemize @bullet
+@item @code{-disable} (or @code{-enable})
+@*Use the @code{-disable} parameter to flag a TAP which is not
+linked in to the scan chain after a reset using either TRST
+or the JTAG state machine's @sc{reset} state.
+You may use @code{-enable} to highlight the default state
+(the TAP is linked in).
+@xref{Enabling and Disabling TAPs}.
+@item @code{-expected-id} @var{number}
+@*A non-zero @var{number} represents a 32-bit IDCODE
+which you expect to find when the scan chain is examined.
+These codes are not required by all JTAG devices.
+@emph{Repeat the option} as many times as required if more than one
+ID code could appear (for example, multiple versions).
+Specify @var{number} as zero to suppress warnings about IDCODE
+values that were found but not included in the list.
+
+Provide this value if at all possible, since it lets OpenOCD
+tell when the scan chain it sees isn't right. These values
+are provided in vendors' chip documentation, usually a technical
+reference manual. Sometimes you may need to probe the JTAG
+hardware to find these values.
+@xref{Autoprobing}.
+@item @code{-ircapture} @var{NUMBER}
+@*The bit pattern loaded by the TAP into the JTAG shift register
+on entry to the @sc{ircapture} state, such as 0x01.
+JTAG requires the two LSBs of this value to be 01.
+By default, @code{-ircapture} and @code{-irmask} are set
+up to verify that two-bit value. You may provide
+additional bits, if you know them, or indicate that
+a TAP doesn't conform to the JTAG specification.
+@item @code{-irmask} @var{NUMBER}
+@*A mask used with @code{-ircapture}
+to verify that instruction scans work correctly.
+Such scans are not used by OpenOCD except to verify that
+there seems to be no problems with JTAG scan chain operations.
+@end itemize
+@end deffn
+
+@section Other TAP commands
+
+@deffn Command {jtag cget} dotted.name @option{-event} name
+@deffnx Command {jtag configure} dotted.name @option{-event} name string
+At this writing this TAP attribute
+mechanism is used only for event handling.
+(It is not a direct analogue of the @code{cget}/@code{configure}
+mechanism for debugger targets.)
+See the next section for information about the available events.
+
+The @code{configure} subcommand assigns an event handler,
+a TCL string which is evaluated when the event is triggered.
+The @code{cget} subcommand returns that handler.
+@end deffn
+
+@anchor{TAP Events}
+@section TAP Events
+@cindex events
+@cindex TAP events
+
+OpenOCD includes two event mechanisms.
+The one presented here applies to all JTAG TAPs.
+The other applies to debugger targets,
+which are associated with certain TAPs.
+
+The TAP events currently defined are:
+
+@itemize @bullet
+@item @b{post-reset}
+@* The TAP has just completed a JTAG reset.
+The tap may still be in the JTAG @sc{reset} state.
+Handlers for these events might perform initialization sequences
+such as issuing TCK cycles, TMS sequences to ensure
+exit from the ARM SWD mode, and more.
+
+Because the scan chain has not yet been verified, handlers for these events
+@emph{should not issue commands which scan the JTAG IR or DR registers}
+of any particular target.
+@b{NOTE:} As this is written (September 2009), nothing prevents such access.
+@item @b{setup}
+@* The scan chain has been reset and verified.
+This handler may enable TAPs as needed.
+@item @b{tap-disable}
+@* The TAP needs to be disabled. This handler should
+implement @command{jtag tapdisable}
+by issuing the relevant JTAG commands.
+@item @b{tap-enable}
+@* The TAP needs to be enabled. This handler should
+implement @command{jtag tapenable}
+by issuing the relevant JTAG commands.
+@end itemize
+
+If you need some action after each JTAG reset, which isn't actually
+specific to any TAP (since you can't yet trust the scan chain's
+contents to be accurate), you might:
+
+@example
+jtag configure CHIP.jrc -event post-reset @{
+ echo "JTAG Reset done"
+ ... non-scan jtag operations to be done after reset
+@}
+@end example
+
+
+@anchor{Enabling and Disabling TAPs}
+@section Enabling and Disabling TAPs
+@cindex JTAG Route Controller
+@cindex jrc
+
+In some systems, a @dfn{JTAG Route Controller} (JRC)
+is used to enable and/or disable specific JTAG TAPs.
+Many ARM based chips from Texas Instruments include
+an ``ICEpick'' module, which is a JRC.
+Such chips include DaVinci and OMAP3 processors.
+
+A given TAP may not be visible until the JRC has been
+told to link it into the scan chain; and if the JRC
+has been told to unlink that TAP, it will no longer
+be visible.
+Such routers address problems that JTAG ``bypass mode''
+ignores, such as:
+
+@itemize
+@item The scan chain can only go as fast as its slowest TAP.
+@item Having many TAPs slows instruction scans, since all
+TAPs receive new instructions.
+@item TAPs in the scan chain must be powered up, which wastes
+power and prevents debugging some power management mechanisms.
+@end itemize
+
+The IEEE 1149.1 JTAG standard has no concept of a ``disabled'' tap,
+as implied by the existence of JTAG routers.
+However, the upcoming IEEE 1149.7 framework (layered on top of JTAG)
+does include a kind of JTAG router functionality.
+
+@c (a) currently the event handlers don't seem to be able to
+@c fail in a way that could lead to no-change-of-state.
+
+In OpenOCD, tap enabling/disabling is invoked by the Tcl commands
+shown below, and is implemented using TAP event handlers.
+So for example, when defining a TAP for a CPU connected to
+a JTAG router, your @file{target.cfg} file
+should define TAP event handlers using
+code that looks something like this:
+
+@example
+jtag configure CHIP.cpu -event tap-enable @{
+ ... jtag operations using CHIP.jrc
+@}
+jtag configure CHIP.cpu -event tap-disable @{
+ ... jtag operations using CHIP.jrc
+@}
+@end example
+
+Then you might want that CPU's TAP enabled almost all the time:
+
+@example
+jtag configure $CHIP.jrc -event setup "jtag tapenable $CHIP.cpu"
+@end example
+
+Note how that particular setup event handler declaration
+uses quotes to evaluate @code{$CHIP} when the event is configured.
+Using brackets @{ @} would cause it to be evaluated later,
+at runtime, when it might have a different value.
+
+@deffn Command {jtag tapdisable} dotted.name
+If necessary, disables the tap
+by sending it a @option{tap-disable} event.
+Returns the string "1" if the tap
+specified by @var{dotted.name} is enabled,
+and "0" if it is disabled.
+@end deffn
+
+@deffn Command {jtag tapenable} dotted.name
+If necessary, enables the tap
+by sending it a @option{tap-enable} event.
+Returns the string "1" if the tap
+specified by @var{dotted.name} is enabled,
+and "0" if it is disabled.
+@end deffn
+
+@deffn Command {jtag tapisenabled} dotted.name
+Returns the string "1" if the tap
+specified by @var{dotted.name} is enabled,
+and "0" if it is disabled.
+
+@quotation Note
+Humans will find the @command{scan_chain} command more helpful
+for querying the state of the JTAG taps.
+@end quotation
+@end deffn
+
+@anchor{Autoprobing}
+@section Autoprobing
+@cindex autoprobe
+@cindex JTAG autoprobe
+
+TAP configuration is the first thing that needs to be done
+after interface and reset configuration. Sometimes it's
+hard finding out what TAPs exist, or how they are identified.
+Vendor documentation is not always easy to find and use.
+
+To help you get past such problems, OpenOCD has a limited
+@emph{autoprobing} ability to look at the scan chain, doing
+a @dfn{blind interrogation} and then reporting the TAPs it finds.
+To use this mechanism, start the OpenOCD server with only data
+that configures your JTAG interface, and arranges to come up
+with a slow clock (many devices don't support fast JTAG clocks
+right when they come out of reset).
+
+For example, your @file{openocd.cfg} file might have:
+
+@example
+source [find interface/olimex-arm-usb-tiny-h.cfg]
+reset_config trst_and_srst
+jtag_rclk 8
+@end example
+
+When you start the server without any TAPs configured, it will
+attempt to autoconfigure the TAPs. There are two parts to this:
+
+@enumerate
+@item @emph{TAP discovery} ...
+After a JTAG reset (sometimes a system reset may be needed too),
+each TAP's data registers will hold the contents of either the
+IDCODE or BYPASS register.
+If JTAG communication is working, OpenOCD will see each TAP,
+and report what @option{-expected-id} to use with it.
+@item @emph{IR Length discovery} ...
+Unfortunately JTAG does not provide a reliable way to find out
+the value of the @option{-irlen} parameter to use with a TAP
+that is discovered.
+If OpenOCD can discover the length of a TAP's instruction
+register, it will report it.
+Otherwise you may need to consult vendor documentation, such
+as chip data sheets or BSDL files.
+@end enumerate
+
+In many cases your board will have a simple scan chain with just
+a single device. Here's what OpenOCD reported with one board
+that's a bit more complex:
+
+@example
+clock speed 8 kHz
+There are no enabled taps. AUTO PROBING MIGHT NOT WORK!!
+AUTO auto0.tap - use "jtag newtap auto0 tap -expected-id 0x2b900f0f ..."
+AUTO auto1.tap - use "jtag newtap auto1 tap -expected-id 0x07926001 ..."
+AUTO auto2.tap - use "jtag newtap auto2 tap -expected-id 0x0b73b02f ..."
+AUTO auto0.tap - use "... -irlen 4"
+AUTO auto1.tap - use "... -irlen 4"
+AUTO auto2.tap - use "... -irlen 6"
+no gdb ports allocated as no target has been specified
+@end example
+
+Given that information, you should be able to either find some existing
+config files to use, or create your own. If you create your own, you
+would configure from the bottom up: first a @file{target.cfg} file
+with these TAPs, any targets associated with them, and any on-chip
+resources; then a @file{board.cfg} with off-chip resources, clocking,
+and so forth.
+
+@node CPU Configuration
+@chapter CPU Configuration
+@cindex GDB target
+
+This chapter discusses how to set up GDB debug targets for CPUs.
+You can also access these targets without GDB
+(@pxref{Architecture and Core Commands},
+and @ref{Target State handling}) and
+through various kinds of NAND and NOR flash commands.
+If you have multiple CPUs you can have multiple such targets.
+
+We'll start by looking at how to examine the targets you have,
+then look at how to add one more target and how to configure it.
+
+@section Target List
+@cindex target, current
+@cindex target, list
+
+All targets that have been set up are part of a list,
+where each member has a name.
+That name should normally be the same as the TAP name.
+You can display the list with the @command{targets}
+(plural!) command.
+This display often has only one CPU; here's what it might
+look like with more than one:
+@verbatim
+ TargetName Type Endian TapName State
+-- ------------------ ---------- ------ ------------------ ------------
+ 0* at91rm9200.cpu arm920t little at91rm9200.cpu running
+ 1 MyTarget cortex_m3 little mychip.foo tap-disabled
+@end verbatim
+
+One member of that list is the @dfn{current target}, which
+is implicitly referenced by many commands.
+It's the one marked with a @code{*} near the target name.
+In particular, memory addresses often refer to the address
+space seen by that current target.
+Commands like @command{mdw} (memory display words)
+and @command{flash erase_address} (erase NOR flash blocks)
+are examples; and there are many more.
+
+Several commands let you examine the list of targets:
+
+@deffn Command {target count}
+@emph{Note: target numbers are deprecated; don't use them.
+They will be removed shortly after August 2010, including this command.
+Iterate target using @command{target names}, not by counting.}
+
+Returns the number of targets, @math{N}.
+The highest numbered target is @math{N - 1}.
+@example
+set c [target count]
+for @{ set x 0 @} @{ $x < $c @} @{ incr x @} @{
+ # Assuming you have created this function
+ print_target_details $x
+@}
+@end example
+@end deffn
+
+@deffn Command {target current}
+Returns the name of the current target.
+@end deffn
+
+@deffn Command {target names}
+Lists the names of all current targets in the list.
+@example
+foreach t [target names] @{
+ puts [format "Target: %s\n" $t]
+@}
+@end example
+@end deffn
+
+@deffn Command {target number} number
+@emph{Note: target numbers are deprecated; don't use them.
+They will be removed shortly after August 2010, including this command.}
+
+The list of targets is numbered starting at zero.
+This command returns the name of the target at index @var{number}.
+@example
+set thename [target number $x]
+puts [format "Target %d is: %s\n" $x $thename]
+@end example
+@end deffn
+
+@c yep, "target list" would have been better.
+@c plus maybe "target setdefault".
+
+@deffn Command targets [name]
+@emph{Note: the name of this command is plural. Other target
+command names are singular.}
+
+With no parameter, this command displays a table of all known
+targets in a user friendly form.
+
+With a parameter, this command sets the current target to
+the given target with the given @var{name}; this is
+only relevant on boards which have more than one target.
+@end deffn
+
+@section Target CPU Types and Variants
+@cindex target type
+@cindex CPU type
+@cindex CPU variant
+
+Each target has a @dfn{CPU type}, as shown in the output of
+the @command{targets} command. You need to specify that type
+when calling @command{target create}.
+The CPU type indicates more than just the instruction set.
+It also indicates how that instruction set is implemented,
+what kind of debug support it integrates,
+whether it has an MMU (and if so, what kind),
+what core-specific commands may be available
+(@pxref{Architecture and Core Commands}),
+and more.
+
+For some CPU types, OpenOCD also defines @dfn{variants} which
+indicate differences that affect their handling.
+For example, a particular implementation bug might need to be
+worked around in some chip versions.
+
+It's easy to see what target types are supported,
+since there's a command to list them.
+However, there is currently no way to list what target variants
+are supported (other than by reading the OpenOCD source code).
+
+@anchor{target types}
+@deffn Command {target types}
+Lists all supported target types.
+At this writing, the supported CPU types and variants are:
+
+@itemize @bullet
+@item @code{arm11} -- this is a generation of ARMv6 cores
+@item @code{arm720t} -- this is an ARMv4 core with an MMU
+@item @code{arm7tdmi} -- this is an ARMv4 core
+@item @code{arm920t} -- this is an ARMv5 core with an MMU
+@item @code{arm926ejs} -- this is an ARMv5 core with an MMU
+@item @code{arm966e} -- this is an ARMv5 core
+@item @code{arm9tdmi} -- this is an ARMv4 core
+@item @code{avr} -- implements Atmel's 8-bit AVR instruction set.
+(Support for this is preliminary and incomplete.)
+@item @code{cortex_a8} -- this is an ARMv7 core with an MMU
+@item @code{cortex_m3} -- this is an ARMv7 core, supporting only the
+compact Thumb2 instruction set. It supports one variant:
+@itemize @minus
+@item @code{lm3s} ... Use this when debugging older Stellaris LM3S targets.
+This will cause OpenOCD to use a software reset rather than asserting
+SRST, to avoid a issue with clearing the debug registers.
+This is fixed in Fury Rev B, DustDevil Rev B, Tempest; these revisions will
+be detected and the normal reset behaviour used.
+@end itemize
+@item @code{dragonite} -- resembles arm966e
+@item @code{fa526} -- resembles arm920 (w/o Thumb)
+@item @code{feroceon} -- resembles arm926
+@item @code{mips_m4k} -- a MIPS core. This supports one variant:
+@itemize @minus
+@item @code{ejtag_srst} ... Use this when debugging targets that do not
+provide a functional SRST line on the EJTAG connector. This causes
+OpenOCD to instead use an EJTAG software reset command to reset the
+processor.
+You still need to enable @option{srst} on the @command{reset_config}
+command to enable OpenOCD hardware reset functionality.
+@end itemize
+@item @code{xscale} -- this is actually an architecture,
+not a CPU type. It is based on the ARMv5 architecture.
+There are several variants defined:
+@itemize @minus
+@item @code{ixp42x}, @code{ixp45x}, @code{ixp46x},
+@code{pxa27x} ... instruction register length is 7 bits
+@item @code{pxa250}, @code{pxa255},
+@code{pxa26x} ... instruction register length is 5 bits
+@end itemize
+@end itemize
+@end deffn
+
+To avoid being confused by the variety of ARM based cores, remember
+this key point: @emph{ARM is a technology licencing company}.
+(See: @url{http://www.arm.com}.)
+The CPU name used by OpenOCD will reflect the CPU design that was
+licenced, not a vendor brand which incorporates that design.
+Name prefixes like arm7, arm9, arm11, and cortex
+reflect design generations;
+while names like ARMv4, ARMv5, ARMv6, and ARMv7
+reflect an architecture version implemented by a CPU design.
+
+@anchor{Target Configuration}
+@section Target Configuration
+
+Before creating a ``target'', you must have added its TAP to the scan chain.
+When you've added that TAP, you will have a @code{dotted.name}
+which is used to set up the CPU support.
+The chip-specific configuration file will normally configure its CPU(s)
+right after it adds all of the chip's TAPs to the scan chain.
+
+Although you can set up a target in one step, it's often clearer if you
+use shorter commands and do it in two steps: create it, then configure
+optional parts.
+All operations on the target after it's created will use a new
+command, created as part of target creation.
+
+The two main things to configure after target creation are
+a work area, which usually has target-specific defaults even
+if the board setup code overrides them later;
+and event handlers (@pxref{Target Events}), which tend
+to be much more board-specific.
+The key steps you use might look something like this
+
+@example
+target create MyTarget cortex_m3 -chain-position mychip.cpu
+$MyTarget configure -work-area-phys 0x08000 -work-area-size 8096
+$MyTarget configure -event reset-deassert-pre @{ jtag_rclk 5 @}
+$MyTarget configure -event reset-init @{ myboard_reinit @}
+@end example
+
+You should specify a working area if you can; typically it uses some
+on-chip SRAM.
+Such a working area can speed up many things, including bulk
+writes to target memory;
+flash operations like checking to see if memory needs to be erased;
+GDB memory checksumming;
+and more.
+
+@quotation Warning
+On more complex chips, the work area can become
+inaccessible when application code
+(such as an operating system)
+enables or disables the MMU.
+For example, the particular MMU context used to acess the virtual
+address will probably matter ... and that context might not have
+easy access to other addresses needed.
+At this writing, OpenOCD doesn't have much MMU intelligence.
+@end quotation
+
+It's often very useful to define a @code{reset-init} event handler.
+For systems that are normally used with a boot loader,
+common tasks include updating clocks and initializing memory
+controllers.
+That may be needed to let you write the boot loader into flash,
+in order to ``de-brick'' your board; or to load programs into
+external DDR memory without having run the boot loader.
+
+@deffn Command {target create} target_name type configparams...
+This command creates a GDB debug target that refers to a specific JTAG tap.
+It enters that target into a list, and creates a new
+command (@command{@var{target_name}}) which is used for various
+purposes including additional configuration.
+
+@itemize @bullet
+@item @var{target_name} ... is the name of the debug target.
+By convention this should be the same as the @emph{dotted.name}
+of the TAP associated with this target, which must be specified here
+using the @code{-chain-position @var{dotted.name}} configparam.
+
+This name is also used to create the target object command,
+referred to here as @command{$target_name},
+and in other places the target needs to be identified.
+@item @var{type} ... specifies the target type. @xref{target types}.
+@item @var{configparams} ... all parameters accepted by
+@command{$target_name configure} are permitted.
+If the target is big-endian, set it here with @code{-endian big}.
+If the variant matters, set it here with @code{-variant}.
+
+You @emph{must} set the @code{-chain-position @var{dotted.name}} here.
+@end itemize
+@end deffn
+
+@deffn Command {$target_name configure} configparams...
+The options accepted by this command may also be
+specified as parameters to @command{target create}.
+Their values can later be queried one at a time by
+using the @command{$target_name cget} command.
+
+@emph{Warning:} changing some of these after setup is dangerous.
+For example, moving a target from one TAP to another;
+and changing its endianness or variant.
+
+@itemize @bullet
+
+@item @code{-chain-position} @var{dotted.name} -- names the TAP
+used to access this target.
+
+@item @code{-endian} (@option{big}|@option{little}) -- specifies
+whether the CPU uses big or little endian conventions
+
+@item @code{-event} @var{event_name} @var{event_body} --
+@xref{Target Events}.
+Note that this updates a list of named event handlers.
+Calling this twice with two different event names assigns
+two different handlers, but calling it twice with the
+same event name assigns only one handler.
+
+@item @code{-variant} @var{name} -- specifies a variant of the target,
+which OpenOCD needs to know about.
+
+@item @code{-work-area-backup} (@option{0}|@option{1}) -- says
+whether the work area gets backed up; by default,
+@emph{it is not backed up.}
+When possible, use a working_area that doesn't need to be backed up,
+since performing a backup slows down operations.
+For example, the beginning of an SRAM block is likely to
+be used by most build systems, but the end is often unused.
+
+@item @code{-work-area-size} @var{size} -- specify work are size,
+in bytes. The same size applies regardless of whether its physical
+or virtual address is being used.
+
+@item @code{-work-area-phys} @var{address} -- set the work area
+base @var{address} to be used when no MMU is active.
+
+@item @code{-work-area-virt} @var{address} -- set the work area
+base @var{address} to be used when an MMU is active.
+@emph{Do not specify a value for this except on targets with an MMU.}
+The value should normally correspond to a static mapping for the
+@code{-work-area-phys} address, set up by the current operating system.
+
+@end itemize
+@end deffn
+
+@section Other $target_name Commands
+@cindex object command
+
+The Tcl/Tk language has the concept of object commands,
+and OpenOCD adopts that same model for targets.
+
+A good Tk example is a on screen button.
+Once a button is created a button
+has a name (a path in Tk terms) and that name is useable as a first
+class command. For example in Tk, one can create a button and later
+configure it like this:
+
+@example
+# Create
+button .foobar -background red -command @{ foo @}
+# Modify
+.foobar configure -foreground blue
+# Query
+set x [.foobar cget -background]
+# Report
+puts [format "The button is %s" $x]
+@end example
+
+In OpenOCD's terms, the ``target'' is an object just like a Tcl/Tk
+button, and its object commands are invoked the same way.
+
+@example
+str912.cpu mww 0x1234 0x42
+omap3530.cpu mww 0x5555 123
+@end example
+
+The commands supported by OpenOCD target objects are:
+
+@deffn Command {$target_name arp_examine}
+@deffnx Command {$target_name arp_halt}
+@deffnx Command {$target_name arp_poll}
+@deffnx Command {$target_name arp_reset}
+@deffnx Command {$target_name arp_waitstate}
+Internal OpenOCD scripts (most notably @file{startup.tcl})
+use these to deal with specific reset cases.
+They are not otherwise documented here.
+@end deffn
+
+@deffn Command {$target_name array2mem} arrayname width address count
+@deffnx Command {$target_name mem2array} arrayname width address count
+These provide an efficient script-oriented interface to memory.
+The @code{array2mem} primitive writes bytes, halfwords, or words;
+while @code{mem2array} reads them.
+In both cases, the TCL side uses an array, and
+the target side uses raw memory.
+
+The efficiency comes from enabling the use of
+bulk JTAG data transfer operations.
+The script orientation comes from working with data
+values that are packaged for use by TCL scripts;
+@command{mdw} type primitives only print data they retrieve,
+and neither store nor return those values.
+
+@itemize
+@item @var{arrayname} ... is the name of an array variable
+@item @var{width} ... is 8/16/32 - indicating the memory access size
+@item @var{address} ... is the target memory address
+@item @var{count} ... is the number of elements to process
+@end itemize
+@end deffn
+
+@deffn Command {$target_name cget} queryparm
+Each configuration parameter accepted by
+@command{$target_name configure}
+can be individually queried, to return its current value.
+The @var{queryparm} is a parameter name
+accepted by that command, such as @code{-work-area-phys}.
+There are a few special cases:
+
+@itemize @bullet
+@item @code{-event} @var{event_name} -- returns the handler for the
+event named @var{event_name}.
+This is a special case because setting a handler requires
+two parameters.
+@item @code{-type} -- returns the target type.
+This is a special case because this is set using
+@command{target create} and can't be changed
+using @command{$target_name configure}.
+@end itemize
+
+For example, if you wanted to summarize information about
+all the targets you might use something like this:
+
+@example
+foreach name [target names] @{
+ set y [$name cget -endian]
+ set z [$name cget -type]
+ puts [format "Chip %d is %s, Endian: %s, type: %s" \
+ $x $name $y $z]
+@}
+@end example
+@end deffn
+
+@anchor{target curstate}
+@deffn Command {$target_name curstate}
+Displays the current target state:
+@code{debug-running},
+@code{halted},
+@code{reset},
+@code{running}, or @code{unknown}.
+(Also, @pxref{Event Polling}.)
+@end deffn
+
+@deffn Command {$target_name eventlist}
+Displays a table listing all event handlers
+currently associated with this target.
+@xref{Target Events}.
+@end deffn
+
+@deffn Command {$target_name invoke-event} event_name
+Invokes the handler for the event named @var{event_name}.
+(This is primarily intended for use by OpenOCD framework
+code, for example by the reset code in @file{startup.tcl}.)
+@end deffn
+
+@deffn Command {$target_name mdw} addr [count]
+@deffnx Command {$target_name mdh} addr [count]
+@deffnx Command {$target_name mdb} 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}).
+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 {$target_name mww} addr word
+@deffnx Command {$target_name mwh} addr halfword
+@deffnx Command {$target_name mwb} addr byte
+Writes the specified @var{word} (32 bits),
+@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
+at the specified address @var{addr}.
+@end deffn
+
+@anchor{Target Events}
+@section Target Events
+@cindex target events
+@cindex events
+At various times, certain things can happen, or you want them to happen.
+For example:
+@itemize @bullet
+@item What should happen when GDB connects? Should your target reset?
+@item When GDB tries to flash the target, do you need to enable the flash via a special command?
+@item During reset, do you need to write to certain memory locations
+to set up system clocks or
+to reconfigure the SDRAM?
+@end itemize
+
+All of the above items can be addressed by target event handlers.
+These are set up by @command{$target_name configure -event} or
+@command{target create ... -event}.
+
+The programmer's model matches the @code{-command} option used in Tcl/Tk
+buttons and events. The two examples below act the same, but one creates
+and invokes a small procedure while the other inlines it.
+
+@example
+proc my_attach_proc @{ @} @{
+ echo "Reset..."
+ reset halt
+@}
+mychip.cpu configure -event gdb-attach my_attach_proc
+mychip.cpu configure -event gdb-attach @{
+ echo "Reset..."
+ reset halt
+@}
+@end example
+
+The following target events are defined:
+
+@itemize @bullet
+@item @b{debug-halted}
+@* The target has halted for debug reasons (i.e.: breakpoint)
+@item @b{debug-resumed}
+@* The target has resumed (i.e.: gdb said run)
+@item @b{early-halted}
+@* Occurs early in the halt process
+@ignore
+@item @b{examine-end}
+@* Currently not used (goal: when JTAG examine completes)
+@item @b{examine-start}
+@* Currently not used (goal: when JTAG examine starts)
+@end ignore
+@item @b{gdb-attach}
+@* When GDB connects
+@item @b{gdb-detach}
+@* When GDB disconnects
+@item @b{gdb-end}
+@* When the target has halted and GDB is not doing anything (see early halt)
+@item @b{gdb-flash-erase-start}
+@* Before the GDB flash process tries to erase the flash
+@item @b{gdb-flash-erase-end}
+@* After the GDB flash process has finished erasing the flash
+@item @b{gdb-flash-write-start}
+@* Before GDB writes to the flash
+@item @b{gdb-flash-write-end}
+@* After GDB writes to the flash
+@item @b{gdb-start}
+@* Before the target steps, gdb is trying to start/resume the target
+@item @b{halted}
+@* The target has halted
+@ignore
+@item @b{old-gdb_program_config}
+@* DO NOT USE THIS: Used internally
+@item @b{old-pre_resume}
+@* DO NOT USE THIS: Used internally
+@end ignore
+@item @b{reset-assert-pre}
+@* Issued as part of @command{reset} processing
+after @command{reset_init} was triggered
+but before SRST alone is re-asserted on the tap.
+@item @b{reset-assert-post}
+@* Issued as part of @command{reset} processing
+when SRST is asserted on the tap.
+@item @b{reset-deassert-pre}
+@* Issued as part of @command{reset} processing
+when SRST is about to be released on the tap.
+@item @b{reset-deassert-post}
+@* Issued as part of @command{reset} processing
+when SRST has been released on the tap.
+@item @b{reset-end}
+@* Issued as the final step in @command{reset} processing.
+@ignore
+@item @b{reset-halt-post}
+@* Currently not used
+@item @b{reset-halt-pre}
+@* Currently not used
+@end ignore
+@item @b{reset-init}
+@* Used by @b{reset init} command for board-specific initialization.
+This event fires after @emph{reset-deassert-post}.
+
+This is where you would configure PLLs and clocking, set up DRAM so
+you can download programs that don't fit in on-chip SRAM, set up pin
+multiplexing, and so on.
+(You may be able to switch to a fast JTAG clock rate here, after
+the target clocks are fully set up.)
+@item @b{reset-start}
+@* Issued as part of @command{reset} processing
+before @command{reset_init} is called.
+
+This is the most robust place to use @command{jtag_rclk}
+or @command{jtag_khz} to switch to a low JTAG clock rate,
+when reset disables PLLs needed to use a fast clock.
+@ignore
+@item @b{reset-wait-pos}
+@* Currently not used
+@item @b{reset-wait-pre}
+@* Currently not used
+@end ignore
+@item @b{resume-start}
+@* Before any target is resumed
+@item @b{resume-end}
+@* After all targets have resumed
+@item @b{resume-ok}
+@* Success
+@item @b{resumed}
+@* Target has resumed
+@end itemize
+
+
+@node Flash Commands
+@chapter Flash Commands
+
+OpenOCD has different commands for NOR and NAND flash;
+the ``flash'' command works with NOR flash, while
+the ``nand'' command works with NAND flash.
+This partially reflects different hardware technologies:
+NOR flash usually supports direct CPU instruction and data bus access,
+while data from a NAND flash must be copied to memory before it can be
+used. (SPI flash must also be copied to memory before use.)
+However, the documentation also uses ``flash'' as a generic term;
+for example, ``Put flash configuration in board-specific files''.
+
+Flash Steps:
+@enumerate
+@item Configure via the command @command{flash bank}
+@* Do this in a board-specific configuration file,
+passing parameters as needed by the driver.
+@item Operate on the flash via @command{flash subcommand}
+@* Often commands to manipulate the flash are typed by a human, or run
+via a script in some automated way. Common tasks include writing a
+boot loader, operating system, or other data.
+@item GDB Flashing
+@* Flashing via GDB requires the flash be configured via ``flash
+bank'', and the GDB flash features be enabled.
+@xref{GDB Configuration}.
+@end enumerate
+
+Many CPUs have the ablity to ``boot'' from the first flash bank.
+This means that misprogramming that bank can ``brick'' a system,
+so that it can't boot.
+JTAG tools, like OpenOCD, are often then used to ``de-brick'' the
+board by (re)installing working boot firmware.
+
+@anchor{NOR Configuration}
+@section Flash Configuration Commands
+@cindex flash configuration
+
+@deffn {Config Command} {flash bank} driver base size chip_width bus_width target [driver_options]
+Configures a flash bank which provides persistent storage
+for addresses from @math{base} to @math{base + size - 1}.
+These banks will often be visible to GDB through the target's memory map.
+In some cases, configuring a flash bank will activate extra commands;
+see the driver-specific documentation.
+
+@itemize @bullet
+@item @var{driver} ... identifies the controller driver
+associated with the flash bank being declared.
+This is usually @code{cfi} for external flash, or else
+the name of a microcontroller with embedded flash memory.
+@xref{Flash Driver List}.
+@item @var{base} ... Base address of the flash chip.
+@item @var{size} ... Size of the chip, in bytes.
+For some drivers, this value is detected from the hardware.
+@item @var{chip_width} ... Width of the flash chip, in bytes;
+ignored for most microcontroller drivers.
+@item @var{bus_width} ... Width of the data bus used to access the
+chip, in bytes; ignored for most microcontroller drivers.
+@item @var{target} ... Names the target used to issue
+commands to the flash controller.
+@comment Actually, it's currently a controller-specific parameter...
+@item @var{driver_options} ... drivers may support, or require,
+additional parameters. See the driver-specific documentation
+for more information.
+@end itemize
+@quotation Note
+This command is not available after OpenOCD initialization has completed.
+Use it in board specific configuration files, not interactively.
+@end quotation
+@end deffn
+
+@comment the REAL name for this command is "ocd_flash_banks"
+@comment less confusing would be: "flash list" (like "nand list")
+@deffn Command {flash banks}
+Prints a one-line summary of each device declared
+using @command{flash bank}, numbered from zero.
+Note that this is the @emph{plural} form;
+the @emph{singular} form is a very different command.
+@end deffn
+
+@deffn Command {flash probe} num
+Identify the flash, or validate the parameters of the configured flash. Operation
+depends on the flash type.
+The @var{num} parameter is a value shown by @command{flash banks}.
+Most flash commands will implicitly @emph{autoprobe} the bank;
+flash drivers can distinguish between probing and autoprobing,
+but most don't bother.
+@end deffn
+
+@section Erasing, Reading, Writing to Flash
+@cindex flash erasing
+@cindex flash reading
+@cindex flash writing
+@cindex flash programming
+
+One feature distinguishing NOR flash from NAND or serial flash technologies
+is that for read access, it acts exactly like any other addressible memory.
+This means you can use normal memory read commands like @command{mdw} or
+@command{dump_image} with it, with no special @command{flash} subcommands.
+@xref{Memory access}, and @ref{Image access}.
+
+Write access works differently. Flash memory normally needs to be erased
+before it's written. Erasing a sector turns all of its bits to ones, and
+writing can turn ones into zeroes. This is why there are special commands
+for interactive erasing and writing, and why GDB needs to know which parts
+of the address space hold NOR flash memory.
+
+@quotation Note
+Most of these erase and write commands leverage the fact that NOR flash
+chips consume target address space. They implicitly refer to the current
+JTAG target, and map from an address in that target's address space
+back to a flash bank.
+@comment In May 2009, those mappings may fail if any bank associated
+@comment with that target doesn't succesfuly autoprobe ... bug worth fixing?
+A few commands use abstract addressing based on bank and sector numbers,
+and don't depend on searching the current target and its address space.
+Avoid confusing the two command models.
+@end quotation
+
+Some flash chips implement software protection against accidental writes,
+since such buggy writes could in some cases ``brick'' a system.
+For such systems, erasing and writing may require sector protection to be
+disabled first.
+Examples include CFI flash such as ``Intel Advanced Bootblock flash'',
+and AT91SAM7 on-chip flash.
+@xref{flash protect}.
+
+@anchor{flash erase_sector}
+@deffn Command {flash erase_sector} num first last
+Erase sectors in bank @var{num}, starting at sector @var{first}
+up to and including @var{last}.
+Sector numbering starts at 0.
+Providing a @var{last} sector of @option{last}
+specifies "to the end of the flash bank".
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {flash erase_address} address length
+Erase sectors starting at @var{address} for @var{length} bytes.
+The flash bank to use is inferred from the @var{address}, and
+the specified length must stay within that bank.
+As a special case, when @var{length} is zero and @var{address} is
+the start of the bank, the whole flash is erased.
+@end deffn
+
+@deffn Command {flash fillw} address word length
+@deffnx Command {flash fillh} address halfword length
+@deffnx Command {flash fillb} address byte length
+Fills flash memory with the specified @var{word} (32 bits),
+@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
+starting at @var{address} and continuing
+for @var{length} units (word/halfword/byte).
+No erasure is done before writing; when needed, that must be done
+before issuing this command.
+Writes are done in blocks of up to 1024 bytes, and each write is
+verified by reading back the data and comparing it to what was written.
+The flash bank to use is inferred from the @var{address} of
+each block, and the specified length must stay within that bank.
+@end deffn
+@comment no current checks for errors if fill blocks touch multiple banks!
+
+@anchor{flash write_bank}
+@deffn Command {flash write_bank} num filename offset
+Write the binary @file{filename} to flash bank @var{num},
+starting at @var{offset} bytes from the beginning of the bank.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@anchor{flash write_image}
+@deffn Command {flash write_image} [erase] [unlock] filename [offset] [type]
+Write the image @file{filename} to the current target's flash bank(s).
+A relocation @var{offset} may be specified, in which case it is added
+to the base address for each section in the image.
+The file [@var{type}] can be specified
+explicitly as @option{bin} (binary), @option{ihex} (Intel hex),
+@option{elf} (ELF file), @option{s19} (Motorola s19).
+@option{mem}, or @option{builder}.
+The relevant flash sectors will be erased prior to programming
+if the @option{erase} parameter is given. If @option{unlock} is
+provided, then the flash banks are unlocked before erase and
+program. The flash bank to use is inferred from the @var{address} of
+each image segment.
+@end deffn
+
+@section Other Flash commands
+@cindex flash protection
+
+@deffn Command {flash erase_check} num
+Check erase state of sectors in flash bank @var{num},
+and display that status.
+The @var{num} parameter is a value shown by @command{flash banks}.
+This is the only operation that
+updates the erase state information displayed by @option{flash info}. That means you have
+to issue a @command{flash erase_check} command after erasing or programming the device
+to get updated information.
+(Code execution may have invalidated any state records kept by OpenOCD.)
+@end deffn
+
+@deffn Command {flash info} num
+Print info about flash bank @var{num}
+The @var{num} parameter is a value shown by @command{flash banks}.
+The information includes per-sector protect status.
+@end deffn
+
+@anchor{flash protect}
+@deffn Command {flash protect} num first last (@option{on}|@option{off})
+Enable (@option{on}) or disable (@option{off}) protection of flash sectors
+in flash bank @var{num}, starting at sector @var{first}
+and continuing up to and including @var{last}.
+Providing a @var{last} sector of @option{last}
+specifies "to the end of the flash bank".
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {flash protect_check} num
+Check protection state of sectors in flash bank @var{num}.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@comment @option{flash erase_sector} using the same syntax.
+@end deffn
+
+@anchor{Flash Driver List}
+@section Flash Driver List
+As noted above, the @command{flash bank} command requires a driver name,
+and allows driver-specific options and behaviors.
+Some drivers also activate driver-specific commands.
+
+@subsection External Flash
+
+@deffn {Flash Driver} cfi
+@cindex Common Flash Interface
+@cindex CFI
+The ``Common Flash Interface'' (CFI) is the main standard for
+external NOR flash chips, each of which connects to a
+specific external chip select on the CPU.
+Frequently the first such chip is used to boot the system.
+Your board's @code{reset-init} handler might need to
+configure additional chip selects using other commands (like: @command{mww} to
+configure a bus and its timings), or
+perhaps configure a GPIO pin that controls the ``write protect'' pin
+on the flash chip.
+The CFI driver can use a target-specific working area to significantly
+speed up operation.
+
+The CFI driver can accept the following optional parameters, in any order:
+
+@itemize
+@item @var{jedec_probe} ... is used to detect certain non-CFI flash ROMs,
+like AM29LV010 and similar types.
+@item @var{x16_as_x8} ... when a 16-bit flash is hooked up to an 8-bit bus.
+@end itemize
+
+To configure two adjacent banks of 16 MBytes each, both sixteen bits (two bytes)
+wide on a sixteen bit bus:
+
+@example
+flash bank cfi 0x00000000 0x01000000 2 2 $_TARGETNAME
+flash bank cfi 0x01000000 0x01000000 2 2 $_TARGETNAME
+@end example
+
+To configure one bank of 32 MBytes
+built from two sixteen bit (two byte) wide parts wired in parallel
+to create a thirty-two bit (four byte) bus with doubled throughput:
+
+@example
+flash bank cfi 0x00000000 0x02000000 2 4 $_TARGETNAME
+@end example
+
+@c "cfi part_id" disabled
+@end deffn
+
+@subsection Internal Flash (Microcontrollers)
+
+@deffn {Flash Driver} aduc702x
+The ADUC702x analog microcontrollers from Analog Devices
+include internal flash and use ARM7TDMI cores.
+The aduc702x flash driver works with models ADUC7019 through ADUC7028.
+The setup command only requires the @var{target} argument
+since all devices in this family have the same memory layout.
+
+@example
+flash bank aduc702x 0 0 0 0 $_TARGETNAME
+@end example
+@end deffn
+
+@deffn {Flash Driver} at91sam3
+@cindex at91sam3
+All members of the AT91SAM3 microcontroller family from
+Atmel include internal flash and use ARM's Cortex-M3 core. The driver
+currently (6/22/09) recognizes the AT91SAM3U[1/2/4][C/E] chips. Note
+that the driver was orginaly developed and tested using the
+AT91SAM3U4E, using a SAM3U-EK eval board. Support for other chips in
+the family was cribbed from the data sheet. @emph{Note to future
+readers/updaters: Please remove this worrysome comment after other
+chips are confirmed.}
+
+The AT91SAM3U4[E/C] (256K) chips have two flash banks; most other chips
+have one flash bank. In all cases the flash banks are at
+the following fixed locations:
+
+@example
+# Flash bank 0 - all chips
+flash bank at91sam3 0x00080000 0 1 1 $_TARGETNAME
+# Flash bank 1 - only 256K chips
+flash bank at91sam3 0x00100000 0 1 1 $_TARGETNAME
+@end example
+
+Internally, the AT91SAM3 flash memory is organized as follows.
+Unlike the AT91SAM7 chips, these are not used as parameters
+to the @command{flash bank} command:
+
+@itemize
+@item @emph{N-Banks:} 256K chips have 2 banks, others have 1 bank.
+@item @emph{Bank Size:} 128K/64K Per flash bank
+@item @emph{Sectors:} 16 or 8 per bank
+@item @emph{SectorSize:} 8K Per Sector
+@item @emph{PageSize:} 256 bytes per page. Note that OpenOCD operates on 'sector' sizes, not page sizes.
+@end itemize
+
+The AT91SAM3 driver adds some additional commands:
+
+@deffn Command {at91sam3 gpnvm}
+@deffnx Command {at91sam3 gpnvm clear} number
+@deffnx Command {at91sam3 gpnvm set} number
+@deffnx Command {at91sam3 gpnvm show} [@option{all}|number]
+With no parameters, @command{show} or @command{show all},
+shows the status of all GPNVM bits.
+With @command{show} @var{number}, displays that bit.
+
+With @command{set} @var{number} or @command{clear} @var{number},
+modifies that GPNVM bit.
+@end deffn
+
+@deffn Command {at91sam3 info}
+This command attempts to display information about the AT91SAM3
+chip. @emph{First} it read the @code{CHIPID_CIDR} [address 0x400e0740, see
+Section 28.2.1, page 505 of the AT91SAM3U 29/may/2009 datasheet,
+document id: doc6430A] and decodes the values. @emph{Second} it reads the
+various clock configuration registers and attempts to display how it
+believes the chip is configured. By default, the SLOWCLK is assumed to
+be 32768 Hz, see the command @command{at91sam3 slowclk}.
+@end deffn
+
+@deffn Command {at91sam3 slowclk} [value]
+This command shows/sets the slow clock frequency used in the
+@command{at91sam3 info} command calculations above.
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} at91sam7
+All members of the AT91SAM7 microcontroller family from Atmel include
+internal flash and use ARM7TDMI cores. The driver automatically
+recognizes a number of these chips using the chip identification
+register, and autoconfigures itself.
+
+@example
+flash bank at91sam7 0 0 0 0 $_TARGETNAME
+@end example
+
+For chips which are not recognized by the controller driver, you must
+provide additional parameters in the following order:
+
+@itemize
+@item @var{chip_model} ... label used with @command{flash info}
+@item @var{banks}
+@item @var{sectors_per_bank}
+@item @var{pages_per_sector}
+@item @var{pages_size}
+@item @var{num_nvm_bits}
+@item @var{freq_khz} ... required if an external clock is provided,
+optional (but recommended) when the oscillator frequency is known
+@end itemize
+
+It is recommended that you provide zeroes for all of those values
+except the clock frequency, so that everything except that frequency
+will be autoconfigured.
+Knowing the frequency helps ensure correct timings for flash access.
+
+The flash controller handles erases automatically on a page (128/256 byte)
+basis, so explicit erase commands are not necessary for flash programming.
+However, there is an ``EraseAll`` command that can erase an entire flash
+plane (of up to 256KB), and it will be used automatically when you issue
+@command{flash erase_sector} or @command{flash erase_address} commands.
+
+@deffn Command {at91sam7 gpnvm} bitnum (@option{set}|@option{clear})
+Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
+bit for the processor. Each processor has a number of such bits,
+used for controlling features such as brownout detection (so they
+are not truly general purpose).
+@quotation Note
+This assumes that the first flash bank (number 0) is associated with
+the appropriate at91sam7 target.
+@end quotation
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} avr
+The AVR 8-bit microcontrollers from Atmel integrate flash memory.
+@emph{The current implementation is incomplete.}
+@comment - defines mass_erase ... pointless given flash_erase_address
+@end deffn
+
+@deffn {Flash Driver} ecosflash
+@emph{No idea what this is...}
+The @var{ecosflash} driver defines one mandatory parameter,
+the name of a modules of target code which is downloaded
+and executed.
+@end deffn
+
+@deffn {Flash Driver} lpc2000
+Most members of the LPC1700 and LPC2000 microcontroller families from NXP
+include internal flash and use Cortex-M3 (LPC1700) or ARM7TDMI (LPC2000) cores.
+
+@quotation Note
+There are LPC2000 devices which are not supported by the @var{lpc2000}
+driver:
+The LPC2888 is supported by the @var{lpc288x} driver.
+The LPC29xx family is supported by the @var{lpc2900} driver.
+@end quotation
+
+The @var{lpc2000} driver defines two mandatory and one optional parameters,
+which must appear in the following order:
+
+@itemize
+@item @var{variant} ... required, may be
+@var{lpc2000_v1} (older LPC21xx and LPC22xx)
+@var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx)
+or @var{lpc1700} (LPC175x and LPC176x)
+@item @var{clock_kHz} ... the frequency, in kiloHertz,
+at which the core is running
+@item @var{calc_checksum} ... optional (but you probably want to provide this!),
+telling the driver to calculate a valid checksum for the exception vector table.
+@end itemize
+
+LPC flashes don't require the chip and bus width to be specified.
+
+@example
+flash bank lpc2000 0x0 0x7d000 0 0 $_TARGETNAME \
+ lpc2000_v2 14765 calc_checksum
+@end example
+
+@deffn {Command} {lpc2000 part_id} bank
+Displays the four byte part identifier associated with
+the specified flash @var{bank}.
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} lpc288x
+The LPC2888 microcontroller from NXP needs slightly different flash
+support from its lpc2000 siblings.
+The @var{lpc288x} driver defines one mandatory parameter,
+the programming clock rate in Hz.
+LPC flashes don't require the chip and bus width to be specified.
+
+@example
+flash bank lpc288x 0 0 0 0 $_TARGETNAME 12000000
+@end example
+@end deffn
+
+@deffn {Flash Driver} lpc2900
+This driver supports the LPC29xx ARM968E based microcontroller family
+from NXP.
+
+The predefined parameters @var{base}, @var{size}, @var{chip_width} and
+@var{bus_width} of the @code{flash bank} command are ignored. Flash size and
+sector layout are auto-configured by the driver.
+The driver has one additional mandatory parameter: The CPU clock rate
+(in kHz) at the time the flash operations will take place. Most of the time this
+will not be the crystal frequency, but a higher PLL frequency. The
+@code{reset-init} event handler in the board script is usually the place where
+you start the PLL.
+
+The driver rejects flashless devices (currently the LPC2930).
+
+The EEPROM in LPC2900 devices is not mapped directly into the address space.
+It must be handled much more like NAND flash memory, and will therefore be
+handled by a separate @code{lpc2900_eeprom} driver (not yet available).
+
+Sector protection in terms of the LPC2900 is handled transparently. Every time a
+sector needs to be erased or programmed, it is automatically unprotected.
+What is shown as protection status in the @code{flash info} command, is
+actually the LPC2900 @emph{sector security}. This is a mechanism to prevent a
+sector from ever being erased or programmed again. As this is an irreversible
+mechanism, it is handled by a special command (@code{lpc2900 secure_sector}),
+and not by the standard @code{flash protect} command.
+
+Example for a 125 MHz clock frequency:
+@example
+flash bank lpc2900 0 0 0 0 $_TARGETNAME 125000
+@end example
+
+Some @code{lpc2900}-specific commands are defined. In the following command list,
+the @var{bank} parameter is the bank number as obtained by the
+@code{flash banks} command.
+
+@deffn Command {lpc2900 signature} bank
+Calculates a 128-bit hash value, the @emph{signature}, from the whole flash
+content. This is a hardware feature of the flash block, hence the calculation is
+very fast. You may use this to verify the content of a programmed device against
+a known signature.
+Example:
+@example
+lpc2900 signature 0
+ signature: 0x5f40cdc8:0xc64e592e:0x10490f89:0x32a0f317
+@end example
+@end deffn
+
+@deffn Command {lpc2900 read_custom} bank filename
+Reads the 912 bytes of customer information from the flash index sector, and
+saves it to a file in binary format.
+Example:
+@example
+lpc2900 read_custom 0 /path_to/customer_info.bin
+@end example
+@end deffn
+
+The index sector of the flash is a @emph{write-only} sector. It cannot be
+erased! In order to guard against unintentional write access, all following
+commands need to be preceeded by a successful call to the @code{password}
+command:
+
+@deffn Command {lpc2900 password} bank password
+You need to use this command right before each of the following commands:
+@code{lpc2900 write_custom}, @code{lpc2900 secure_sector},
+@code{lpc2900 secure_jtag}.
+
+The password string is fixed to "I_know_what_I_am_doing".
+Example:
+@example
+lpc2900 password 0 I_know_what_I_am_doing
+ Potentially dangerous operation allowed in next command!
+@end example
+@end deffn
+
+@deffn Command {lpc2900 write_custom} bank filename type
+Writes the content of the file into the customer info space of the flash index
+sector. The filetype can be specified with the @var{type} field. Possible values
+for @var{type} are: @var{bin} (binary), @var{ihex} (Intel hex format),
+@var{elf} (ELF binary) or @var{s19} (Motorola S-records). The file must
+contain a single section, and the contained data length must be exactly
+912 bytes.
+@quotation Attention
+This cannot be reverted! Be careful!
+@end quotation
+Example:
+@example
+lpc2900 write_custom 0 /path_to/customer_info.bin bin
+@end example
+@end deffn
+
+@deffn Command {lpc2900 secure_sector} bank first last
+Secures the sector range from @var{first} to @var{last} (including) against
+further program and erase operations. The sector security will be effective
+after the next power cycle.
+@quotation Attention
+This cannot be reverted! Be careful!
+@end quotation
+Secured sectors appear as @emph{protected} in the @code{flash info} command.
+Example:
+@example
+lpc2900 secure_sector 0 1 1
+flash info 0
+ #0 : lpc2900 at 0x20000000, size 0x000c0000, (...)
+ # 0: 0x00000000 (0x2000 8kB) not protected
+ # 1: 0x00002000 (0x2000 8kB) protected
+ # 2: 0x00004000 (0x2000 8kB) not protected
+@end example
+@end deffn
+
+@deffn Command {lpc2900 secure_jtag} bank
+Irreversibly disable the JTAG port. The new JTAG security setting will be
+effective after the next power cycle.
+@quotation Attention
+This cannot be reverted! Be careful!
+@end quotation
+Examples:
+@example
+lpc2900 secure_jtag 0
+@end example
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} ocl
+@emph{No idea what this is, other than using some arm7/arm9 core.}
+
+@example
+flash bank ocl 0 0 0 0 $_TARGETNAME
+@end example
+@end deffn
+
+@deffn {Flash Driver} pic32mx
+The PIC32MX microcontrollers are based on the MIPS 4K cores,
+and integrate flash memory.
+@emph{The current implementation is incomplete.}
+
+@example
+flash bank pix32mx 0 0 0 0 $_TARGETNAME
+@end example
+
+@comment numerous *disabled* commands are defined:
+@comment - chip_erase ... pointless given flash_erase_address
+@comment - lock, unlock ... pointless given protect on/off (yes?)
+@comment - pgm_word ... shouldn't bank be deduced from address??
+Some pic32mx-specific commands are defined:
+@deffn Command {pic32mx pgm_word} address value bank
+Programs the specified 32-bit @var{value} at the given @var{address}
+in the specified chip @var{bank}.
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} stellaris
+All members of the Stellaris LM3Sxxx microcontroller family from
+Texas Instruments
+include internal flash and use ARM Cortex M3 cores.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
+@footnote{Currently there is a @command{stellaris mass_erase} command.
+That seems pointless since the same effect can be had using the
+standard @command{flash erase_address} command.}
+
+@example
+flash bank stellaris 0 0 0 0 $_TARGETNAME
+@end example
+@end deffn
+
+@deffn {Flash Driver} stm32x
+All members of the STM32 microcontroller family from ST Microelectronics
+include internal flash and use ARM Cortex M3 cores.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
+
+@example
+flash bank stm32x 0 0 0 0 $_TARGETNAME
+@end example
+
+Some stm32x-specific commands
+@footnote{Currently there is a @command{stm32x mass_erase} command.
+That seems pointless since the same effect can be had using the
+standard @command{flash erase_address} command.}
+are defined:
+
+@deffn Command {stm32x lock} num
+Locks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32x unlock} num
+Unlocks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32x options_read} num
+Read and display the stm32 option bytes written by
+the @command{stm32x options_write} command.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP})
+Writes the stm32 option byte with the specified values.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} str7x
+All members of the STR7 microcontroller family from ST Microelectronics
+include internal flash and use ARM7TDMI cores.
+The @var{str7x} driver defines one mandatory parameter, @var{variant},
+which is either @code{STR71x}, @code{STR73x} or @code{STR75x}.
+
+@example
+flash bank str7x 0x40000000 0x00040000 0 0 $_TARGETNAME STR71x
+@end example
+
+@deffn Command {str7x disable_jtag} bank
+Activate the Debug/Readout protection mechanism
+for the specified flash bank.
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} str9x
+Most members of the STR9 microcontroller family from ST Microelectronics
+include internal flash and use ARM966E cores.
+The str9 needs the flash controller to be configured using
+the @command{str9x flash_config} command prior to Flash programming.
+
+@example
+flash bank str9x 0x40000000 0x00040000 0 0 $_TARGETNAME
+str9x flash_config 0 4 2 0 0x80000
+@end example
+
+@deffn Command {str9x flash_config} num bbsr nbbsr bbadr nbbadr
+Configures the str9 flash controller.
+The @var{num} parameter is a value shown by @command{flash banks}.
+
+@itemize @bullet
+@item @var{bbsr} - Boot Bank Size register
+@item @var{nbbsr} - Non Boot Bank Size register
+@item @var{bbadr} - Boot Bank Start Address register
+@item @var{nbbadr} - Boot Bank Start Address register
+@end itemize
+@end deffn
+
+@end deffn
+
+@deffn {Flash Driver} tms470
+Most members of the TMS470 microcontroller family from Texas Instruments
+include internal flash and use ARM7TDMI cores.
+This driver doesn't require the chip and bus width to be specified.
+
+Some tms470-specific commands are defined:
+
+@deffn Command {tms470 flash_keyset} key0 key1 key2 key3
+Saves programming keys in a register, to enable flash erase and write commands.
+@end deffn
+
+@deffn Command {tms470 osc_mhz} clock_mhz
+Reports the clock speed, which is used to calculate timings.
+@end deffn
+
+@deffn Command {tms470 plldis} (0|1)
+Disables (@var{1}) or enables (@var{0}) use of the PLL to speed up
+the flash clock.
+@end deffn
+@end deffn
+
+@subsection str9xpec driver
+@cindex str9xpec
+
+Here is some background info to help
+you better understand how this driver works. OpenOCD has two flash drivers for
+the str9:
+@enumerate
+@item
+Standard driver @option{str9x} programmed via the str9 core. Normally used for
+flash programming as it is faster than the @option{str9xpec} driver.
+@item
+Direct programming @option{str9xpec} using the flash controller. This is an
+ISC compilant (IEEE 1532) tap connected in series with the str9 core. The str9
+core does not need to be running to program using this flash driver. Typical use
+for this driver is locking/unlocking the target and programming the option bytes.
+@end enumerate
+
+Before we run any commands using the @option{str9xpec} driver we must first disable
+the str9 core. This example assumes the @option{str9xpec} driver has been
+configured for flash bank 0.
+@example
+# assert srst, we do not want core running
+# while accessing str9xpec flash driver
+jtag_reset 0 1
+# turn off target polling
+poll off
+# disable str9 core
+str9xpec enable_turbo 0
+# read option bytes
+str9xpec options_read 0
+# re-enable str9 core
+str9xpec disable_turbo 0
+poll on
+reset halt
+@end example
+The above example will read the str9 option bytes.
+When performing a unlock remember that you will not be able to halt the str9 - it
+has been locked. Halting the core is not required for the @option{str9xpec} driver
+as mentioned above, just issue the commands above manually or from a telnet prompt.
+
+@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} controller 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{controller} ... identifies the 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} 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
+
+@c note EXTREMELY ANNOYING word wrap at column 75
+@c even when lines are e.g. 100+ columns ...
+@c coded in startup.tcl
+@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.
+@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}.
+
+@emph{With no arguments}:
+list all available registers for the current target,
+showing number, name, size, value, and cache status.
+
+@emph{With number/name}: display that register's value.
+
+@emph{With both number/name and value}: set register's value.
+
+Cores may have surprisingly many registers in their
+Debug and trace infrastructure:
+
+@example
+> reg
+(0) r0 (/32): 0x0000D3C2 (dirty: 1, valid: 1)
+(1) r1 (/32): 0xFD61F31C (dirty: 0, valid: 1)
+(2) r2 (/32): 0x00022551 (dirty: 0, valid: 1)
+...
+(164) ETM_CONTEXTID_COMPARATOR_MASK (/32): \
+ 0x00000000 (dirty: 0, valid: 0)
+>
+@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 (September 2009) only ARM7 and ARM9 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
+
+@deffn Command {etm tracemode} [type context_id_bits cycle_accurate branch_output]
+Displays what data that ETM will collect.
+If arguments are provided, first configures that data.
+When the configuration changes, tracing is stopped
+and any buffered trace data is invalidated.
+
+@itemize
+@item @var{type} ... describing how data accesses are traced,
+when they pass any ViewData filtering that that was set up.
+The value is one of
+@option{none} (save nothing),
+@option{data} (save data),
+@option{address} (save addresses),
+@option{all} (save data and addresses)
+@item @var{context_id_bits} ... 0, 8, 16, or 32
+@item @var{cycle_accurate} ... @option{enable} or @option{disable}
+cycle-accurate instruction tracing.
+Before ETMv3, enabling this causes much extra data to be recorded.
+@item @var{branch_output} ... @option{enable} or @option{disable}.
+Disable this unless you need to try reconstructing the instruction
+trace stream without an image of the code.
+@end itemize
+@end deffn
+
+@deffn Command {etm trigger_percent} [percent]
+This displays, or optionally changes, the trace port driver's
+behavior after the ETM's configured @emph{trigger} event fires.
+It controls how much more trace data is saved after the (single)
+trace trigger becomes active.
+
+@itemize
+@item The default corresponds to @emph{trace around} usage,
+recording 50 percent data before the event and the rest
+afterwards.
+@item The minimum value of @var{percent} is 2 percent,
+recording almost exclusively data before the trigger.
+Such extreme @emph{trace before} usage can help figure out
+what caused that event to happen.
+@item The maximum value of @var{percent} is 100 percent,
+recording data almost exclusively after the event.
+This extreme @emph{trace after} usage might help sort out
+how the event caused trouble.
+@end itemize
+@c REVISIT allow "break" too -- enter debug mode.
+@end deffn
+
+@subsection ETM Trace Operation
+
+After setting up the ETM, you can use it to collect data.
+That data can be exported to files for later analysis.
+It can also be parsed with OpenOCD, for basic sanity checking.
+
+To configure what is being traced, you will need to write
+various trace registers using @command{reg ETM_*} commands.
+For the definitions of these registers, read ARM publication
+@emph{IHI 0014, ``Embedded Trace Macrocell, Architecture Specification''}.
+Be aware that most of the relevant registers are write-only,
+and that ETM resources are limited. There are only a handful
+of address comparators, data comparators, counters, and so on.
+
+Examples of scenarios you might arrange to trace include:
+
+@itemize
+@item Code flow within a function, @emph{excluding} subroutines
+it calls. Use address range comparators to enable tracing
+for instruction access within that function's body.
+@item Code flow within a function, @emph{including} subroutines
+it calls. Use the sequencer and address comparators to activate
+tracing on an ``entered function'' state, then deactivate it by
+exiting that state when the function's exit code is invoked.
+@item Code flow starting at the fifth invocation of a function,
+combining one of the above models with a counter.
+@item CPU data accesses to the registers for a particular device,
+using address range comparators and the ViewData logic.
+@item Such data accesses only during IRQ handling, combining the above
+model with sequencer triggers which on entry and exit to the IRQ handler.
+@item @emph{... more}
+@end itemize
+
+At this writing, September 2009, there are no Tcl utility
+procedures to help set up any common tracing scenarios.
+
+@deffn Command {etm analyze}
+Reads trace data into memory, if it wasn't already present.
+Decodes and prints the data that was collected.
+@end deffn
+
+@deffn Command {etm dump} filename
+Stores the captured trace data in @file{filename}.
+@end deffn
+
+@deffn Command {etm image} filename [base_address] [type]
+Opens an image file.
+@end deffn
+
+@deffn Command {etm load} filename
+Loads captured trace data from @file{filename}.
+@end deffn
+
+@deffn Command {etm start}
+Starts trace data collection.
+@end deffn
+
+@deffn Command {etm stop}
+Stops trace data collection.
+@end deffn
+
+@anchor{Trace Port Drivers}
+@subsection Trace Port Drivers
+
+To use an ETM trace port it must be associated with a driver.
+
+@deffn {Trace Port Driver} dummy
+Use the @option{dummy} driver if you are configuring an ETM that's
+not connected to anything (on-chip ETB or off-chip trace connector).
+@emph{This driver lets OpenOCD talk to the ETM, but it does not expose
+any trace data collection.}
+@deffn {Config Command} {etm_dummy config} target
+Associates the ETM for @var{target} with a dummy driver.
+@end deffn
+@end deffn
+
+@deffn {Trace Port Driver} etb
+Use the @option{etb} driver if you are configuring an ETM
+to use on-chip ETB memory.
+@deffn {Config Command} {etb config} target etb_tap
+Associates the ETM for @var{target} with the ETB at @var{etb_tap}.
+You can see the ETB registers using the @command{reg} command.
+@end deffn
+@end deffn
+
+@deffn {Trace Port Driver} oocd_trace
+This driver isn't available unless OpenOCD was explicitly configured
+with the @option{--enable-oocd_trace} option. You probably don't want
+to configure it unless you've built the appropriate prototype hardware;
+it's @emph{proof-of-concept} software.
+
+Use the @option{oocd_trace} driver if you are configuring an ETM that's
+connected to an off-chip trace connector.
+
+@deffn {Config Command} {oocd_trace config} target tty
+Associates the ETM for @var{target} with a trace driver which
+collects data through the serial port @var{tty}.
+@end deffn
+
+@deffn Command {oocd_trace resync}
+Re-synchronizes with the capture clock.
+@end deffn
+
+@deffn Command {oocd_trace status}
+Reports whether the capture clock is locked or not.
+@end deffn
+@end deffn
+
+
+@section Generic ARM
+@cindex ARM
+
+These commands should be available on all ARM processors.
+They are available in addition to other core-specific
+commands that may be available.
+
+@deffn Command {arm core_state} [@option{arm}|@option{thumb}]
+Displays the core_state, optionally changing it to process
+either @option{arm} or @option{thumb} instructions.
+The target may later be resumed in the currently set core_state.
+(Processors may also support the Jazelle state, but
+that is not currently supported in OpenOCD.)
+@end deffn
+
+@deffn Command {arm disassemble} address [count [@option{thumb}]]
+@cindex disassemble
+Disassembles @var{count} instructions starting at @var{address}.
+If @var{count} is not specified, a single instruction is disassembled.
+If @option{thumb} is specified, or the low bit of the address is set,
+Thumb (16-bit) instructions are used;
+else ARM (32-bit) instructions are used.
+(Processors may also support the Jazelle state, but
+those instructions are not currently understood by OpenOCD.)
+@end deffn
+
+@deffn Command {arm reg}
+Display a table of all banked core registers, fetching the current value from every
+core mode if necessary. OpenOCD versions before rev. 60 didn't fetch the current
+register value.
+@end deffn
+
+@subsection ARM7 and ARM9 specific commands
+@cindex ARM7
+@cindex ARM9
+
+These commands are specific to ARM7 and ARM9 cores, like ARM7TDMI, ARM720T,
+ARM9TDMI, ARM920T or ARM926EJ-S.
+They are available in addition to the ARMv4/5 commands,
+and any other core-specific commands that may be available.
+
+@deffn Command {arm7_9 dbgrq} (@option{enable}|@option{disable})
+Control use of the EmbeddedIce DBGRQ signal to force entry into debug mode,
+instead of breakpoints. This should be
+safe for all but ARM7TDMI--S cores (like Philips LPC).
+This feature is enabled by default on most ARM9 cores,
+including ARM9TDMI, ARM920T, and ARM926EJ-S.
+@end deffn
+
+@deffn Command {arm7_9 dcc_downloads} (@option{enable}|@option{disable})
+@cindex DCC
+Control the use of the debug communications channel (DCC) to write larger (>128 byte)
+amounts of memory. DCC downloads offer a huge speed increase, but might be
+unsafe, especially with targets running at very low speeds. This command was introduced
+with OpenOCD rev. 60, and requires a few bytes of working area.
+@end deffn
+
+@anchor{arm7_9 fast_memory_access}
+@deffn Command {arm7_9 fast_memory_access} (@option{enable}|@option{disable})
+Enable or disable memory writes and reads that don't check completion of
+the operation. This provides a huge speed increase, especially with USB JTAG
+cables (FT2232), but might be unsafe if used with targets running at very low
+speeds, like the 32kHz startup clock of an AT91RM9200.
+@end deffn
+
+@deffn {Debug Command} {arm7_9 write_core_reg} num mode word
+@emph{This is intended for use while debugging OpenOCD; you probably
+shouldn't use it.}
+
+Writes a 32-bit @var{word} to register @var{num} (from 0 to 16)
+as used in the specified @var{mode}
+(where e.g. mode 16 is "user" and mode 19 is "supervisor";
+the M4..M0 bits of the PSR).
+Registers 0..15 are the normal CPU registers such as r0(0), r1(1) ... pc(15).
+Register 16 is the mode-specific SPSR,
+unless the specified mode is 0xffffffff (32-bit all-ones)
+in which case register 16 is the CPSR.
+The write goes directly to the CPU, bypassing the register cache.
+@end deffn
+
+@deffn {Debug Command} {arm7_9 write_xpsr} word (@option{0}|@option{1})
+@emph{This is intended for use while debugging OpenOCD; you probably
+shouldn't use it.}
+
+If the second parameter is zero, writes @var{word} to the
+Current Program Status register (CPSR).
+Else writes @var{word} to the current mode's Saved PSR (SPSR).
+In both cases, this bypasses the register cache.
+@end deffn
+
+@deffn {Debug Command} {arm7_9 write_xpsr_im8} byte rotate (@option{0}|@option{1})
+@emph{This is intended for use while debugging OpenOCD; you probably
+shouldn't use it.}
+
+Writes eight bits to the CPSR or SPSR,
+first rotating them by @math{2*rotate} bits,
+and bypassing the register cache.
+This has lower JTAG overhead than writing the entire CPSR or SPSR
+with @command{arm7_9 write_xpsr}.
+@end deffn
+
+@subsection ARM720T specific commands
+@cindex ARM720T
+
+These commands are available to ARM720T based CPUs,
+which are implementations of the ARMv4T architecture
+based on the ARM7TDMI-S integer core.
+They are available in addition to the ARMv4/5 and ARM7/ARM9 commands.
+
+@deffn Command {arm720t cp15} regnum [value]
+Display cp15 register @var{regnum};
+else if a @var{value} is provided, that value is written to that register.
+@end deffn
+
+@subsection ARM9 specific commands
+@cindex ARM9
+
+ARM9-family cores are built around ARM9TDMI or ARM9E (including ARM9EJS)
+integer processors.
+Such cores include the ARM920T, ARM926EJ-S, and ARM966.
+
+@c 9-june-2009: tried this on arm920t, it didn't work.
+@c no-params always lists nothing caught, and that's how it acts.
+@c 23-oct-2009: doesn't work _consistently_ ... as if the ICE
+@c versions have different rules about when they commit writes.
+
+@anchor{arm9 vector_catch}
+@deffn Command {arm9 vector_catch} [@option{all}|@option{none}|list]
+@cindex vector_catch
+Vector Catch hardware provides a sort of dedicated breakpoint
+for hardware events such as reset, interrupt, and abort.
+You can use this to conserve normal breakpoint resources,
+so long as you're not concerned with code that branches directly
+to those hardware vectors.
+
+This always finishes by listing the current configuration.
+If parameters are provided, it first reconfigures the
+vector catch hardware to intercept
+@option{all} of the hardware vectors,
+@option{none} of them,
+or a list with one or more of the following:
+@option{reset} @option{undef} @option{swi} @option{pabt} @option{dabt}
+@option{irq} @option{fiq}.
+@end deffn
+
+@subsection ARM920T specific commands
+@cindex ARM920T
+
+These commands are available to ARM920T based CPUs,
+which are implementations of the ARMv4T architecture
+built using the ARM9TDMI integer core.
+They are available in addition to the ARMv4/5, ARM7/ARM9,
+and ARM9TDMI commands.
+
+@deffn Command {arm920t cache_info}
+Print information about the caches found. This allows to see whether your target
+is an ARM920T (2x16kByte cache) or ARM922T (2x8kByte cache).
+@end deffn
+
+@deffn Command {arm920t cp15} regnum [value]
+Display cp15 register @var{regnum};
+else if a @var{value} is provided, that value is written to that register.
+@end deffn
+
+@deffn Command {arm920t cp15i} opcode [value [address]]
+Interpreted access using cp15 @var{opcode}.
+If no @var{value} is provided, the result is displayed.
+Else if that value is written using the specified @var{address},
+or using zero if no other address is not provided.
+@end deffn
+
+@deffn Command {arm920t read_cache} filename
+Dump the content of ICache and DCache to a file named @file{filename}.
+@end deffn
+
+@deffn Command {arm920t read_mmu} filename
+Dump the content of the ITLB and DTLB to a file named @file{filename}.
+@end deffn
+
+@subsection ARM926ej-s specific commands
+@cindex ARM926ej-s
+
+These commands are available to ARM926ej-s based CPUs,
+which are implementations of the ARMv5TEJ architecture
+based on the ARM9EJ-S integer core.
+They are available in addition to the ARMv4/5, ARM7/ARM9,
+and ARM9TDMI commands.
+
+The Feroceon cores also support these commands, although
+they are not built from ARM926ej-s designs.
+
+@deffn Command {arm926ejs cache_info}
+Print information about the caches found.
+@end deffn
+
+@deffn Command {arm926ejs cp15} opcode1 opcode2 CRn CRm regnum [value]
+Accesses cp15 register @var{regnum} using
+@var{opcode1}, @var{opcode2}, @var{CRn}, and @var{CRm}.
+If a @var{value} is provided, that value is written to that register.
+Else that register is read and displayed.
+@end deffn
+
+@subsection ARM966E specific commands
+@cindex ARM966E
+
+These commands are available to ARM966 based CPUs,
+which are implementations of the ARMv5TE architecture.
+They are available in addition to the ARMv4/5, ARM7/ARM9,
+and ARM9TDMI commands.
+
+@deffn Command {arm966e cp15} regnum [value]
+Display cp15 register @var{regnum};
+else if a @var{value} is provided, that value is written to that register.
+@end deffn
+
+@subsection XScale specific commands
+@cindex XScale
+
+Some notes about the debug implementation on the XScale CPUs:
+
+The XScale CPU provides a special debug-only mini-instruction cache
+(mini-IC) in which exception vectors and target-resident debug handler
+code are placed by OpenOCD. In order to get access to the CPU, OpenOCD
+must point vector 0 (the reset vector) to the entry of the debug
+handler. However, this means that the complete first cacheline in the
+mini-IC is marked valid, which makes the CPU fetch all exception
+handlers from the mini-IC, ignoring the code in RAM.
+
+OpenOCD currently does not sync the mini-IC entries with the RAM
+contents (which would fail anyway while the target is running), so
+the user must provide appropriate values using the @code{xscale
+vector_table} command.
+
+It is recommended to place a pc-relative indirect branch in the vector
+table, and put the branch destination somewhere in memory. Doing so
+makes sure the code in the vector table stays constant regardless of
+code layout in memory:
+@example
+_vectors:
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ .org 0x100
+ .long real_reset_vector
+ .long real_ui_handler
+ .long real_swi_handler
+ .long real_pf_abort
+ .long real_data_abort
+ .long 0 /* unused */
+ .long real_irq_handler
+ .long real_fiq_handler
+@end example
+
+The debug handler must be placed somewhere in the address space using
+the @code{xscale debug_handler} command. The allowed locations for the
+debug handler are either (0x800 - 0x1fef800) or (0xfe000800 -
+0xfffff800). The default value is 0xfe000800.
+
+
+These commands are available to XScale based CPUs,
+which are implementations of the ARMv5TE architecture.
+
+@deffn Command {xscale analyze_trace}
+Displays the contents of the trace buffer.
+@end deffn
+
+@deffn Command {xscale cache_clean_address} address
+Changes the address used when cleaning the data cache.
+@end deffn
+
+@deffn Command {xscale cache_info}
+Displays information about the CPU caches.
+@end deffn
+
+@deffn Command {xscale cp15} regnum [value]
+Display cp15 register @var{regnum};
+else if a @var{value} is provided, that value is written to that register.
+@end deffn
+
+@deffn Command {xscale debug_handler} target address
+Changes the address used for the specified target's debug handler.
+@end deffn
+
+@deffn Command {xscale dcache} (@option{enable}|@option{disable})
+Enables or disable the CPU's data cache.
+@end deffn
+
+@deffn Command {xscale dump_trace} filename
+Dumps the raw contents of the trace buffer to @file{filename}.
+@end deffn
+
+@deffn Command {xscale icache} (@option{enable}|@option{disable})
+Enables or disable the CPU's instruction cache.
+@end deffn
+
+@deffn Command {xscale mmu} (@option{enable}|@option{disable})
+Enables or disable the CPU's memory management unit.
+@end deffn
+
+@deffn Command {xscale trace_buffer} (@option{enable}|@option{disable}) [@option{fill} [n] | @option{wrap}]
+Enables or disables the trace buffer,
+and controls how it is emptied.
+@end deffn
+
+@deffn Command {xscale trace_image} filename [offset [type]]
+Opens a trace image from @file{filename}, optionally rebasing
+its segment addresses by @var{offset}.
+The image @var{type} may be one of
+@option{bin} (binary), @option{ihex} (Intel hex),
+@option{elf} (ELF file), @option{s19} (Motorola s19),
+@option{mem}, or @option{builder}.
+@end deffn
+
+@anchor{xscale vector_catch}
+@deffn Command {xscale vector_catch} [mask]
+@cindex vector_catch
+Display a bitmask showing the hardware vectors to catch.
+If the optional parameter is provided, first set the bitmask to that value.
+
+The mask bits correspond with bit 16..23 in the DCSR:
+@example
+0x01 Trap Reset
+0x02 Trap Undefined Instructions
+0x04 Trap Software Interrupt
+0x08 Trap Prefetch Abort
+0x10 Trap Data Abort
+0x20 reserved
+0x40 Trap IRQ
+0x80 Trap FIQ
+@end example
+@end deffn
+
+@anchor{xscale vector_table}
+@deffn Command {xscale vector_table} [<low|high> <index> <value>]
+@cindex vector_table
+
+Set an entry in the mini-IC vector table. There are two tables: one for
+low vectors (at 0x00000000), and one for high vectors (0xFFFF0000), each
+holding the 8 exception vectors. @var{index} can be 1-7, because vector 0
+points to the debug handler entry and can not be overwritten.
+@var{value} holds the 32-bit opcode that is placed in the mini-IC.
+
+Without arguments, the current settings are displayed.
+
+@end deffn
+
+@section ARMv6 Architecture
+@cindex ARMv6
+
+@subsection ARM11 specific commands
+@cindex ARM11
+
+@deffn Command {arm11 memwrite burst} [value]
+Displays the value of the memwrite burst-enable flag,
+which is enabled by default. Burst writes are only used
+for memory writes larger than 1 word. Single word writes
+are likely to be from reset init scripts and those writes
+are often to non-memory locations which could easily have
+many wait states, which could easily break burst writes.
+If @var{value} is defined, first assigns that.
+@end deffn
+
+@deffn Command {arm11 memwrite error_fatal} [value]
+Displays the value of the memwrite error_fatal flag,
+which is enabled by default.
+If @var{value} is defined, first assigns that.
+@end deffn
+
+@deffn Command {arm11 step_irq_enable} [value]
+Displays the value of the flag controlling whether
+IRQs are enabled during single stepping;
+they are disabled by default.
+If @var{value} is defined, first assigns that.
+@end deffn
+
+@deffn Command {arm11 vcr} [value]
+@cindex vector_catch
+Displays the value of the @emph{Vector Catch Register (VCR)},
+coprocessor 14 register 7.
+If @var{value} is defined, first assigns that.
+
+Vector Catch hardware provides dedicated breakpoints
+for certain hardware events.
+The specific bit values are core-specific (as in fact is using
+coprocessor 14 register 7 itself) but all current ARM11
+cores @emph{except the ARM1176} use the same six bits.
+@end deffn
+
+@section ARMv7 Architecture
+@cindex ARMv7
+
+@subsection ARMv7 Debug Access Port (DAP) specific commands
+@cindex Debug Access Port
+@cindex DAP
+These commands are specific to ARM architecture v7 Debug Access Port (DAP),
+included on cortex-m3 and cortex-a8 systems.
+They are available in addition to other core-specific commands that may be available.
+
+@deffn Command {dap info} [num]
+Displays dap info for ap @var{num}, defaulting to the currently selected AP.
+@end deffn
+
+@deffn Command {dap apsel} [num]
+Select AP @var{num}, defaulting to 0.
+@end deffn
+
+@deffn Command {dap apid} [num]
+Displays id register from AP @var{num},
+defaulting to the currently selected AP.
+@end deffn
+
+@deffn Command {dap baseaddr} [num]
+Displays debug base address from AP @var{num},
+defaulting to the currently selected AP.
+@end deffn
+
+@deffn Command {dap memaccess} [value]
+Displays the number of extra tck for mem-ap memory bus access [0-255].
+If @var{value} is defined, first assigns that.
+@end deffn
+
+@subsection ARMv7-A specific commands
+@cindex ARMv7-A
+
+@deffn Command {armv7a disassemble} address [count [@option{thumb}]]
+@cindex disassemble
+Disassembles @var{count} instructions starting at @var{address}.
+If @var{count} is not specified, a single instruction is disassembled.
+If @option{thumb} is specified, or the low bit of the address is set,
+Thumb2 (mixed 16/32-bit) instructions are used;
+else ARM (32-bit) instructions are used.
+With a handful of exceptions, ThumbEE instructions are the same as Thumb2;
+ThumbEE disassembly currently has no explicit support.
+(Processors may also support the Jazelle state, but
+those instructions are not currently understood by OpenOCD.)
+@end deffn
+
+
+@subsection Cortex-M3 specific commands
+@cindex Cortex-M3
+
+@deffn Command {cortex_m3 disassemble} address [count]
+@cindex disassemble
+Disassembles @var{count} Thumb2 instructions starting at @var{address}.
+If @var{count} is not specified, a single instruction is disassembled.
+@end deffn
+
+@deffn Command {cortex_m3 maskisr} (@option{on}|@option{off})
+Control masking (disabling) interrupts during target step/resume.
+@end deffn
+
+@deffn Command {cortex_m3 vector_catch} [@option{all}|@option{none}|list]
+@cindex vector_catch
+Vector Catch hardware provides dedicated breakpoints
+for certain hardware events.
+
+Parameters request interception of
+@option{all} of these hardware event vectors,
+@option{none} of them,
+or one or more of the following:
+@option{hard_err} for a HardFault exception;
+@option{mm_err} for a MemManage exception;
+@option{bus_err} for a BusFault exception;
+@option{irq_err},
+@option{state_err},
+@option{chk_err}, or
+@option{nocp_err} for various UsageFault exceptions; or
+@option{reset}.
+If NVIC setup code does not enable them,
+MemManage, BusFault, and UsageFault exceptions
+are mapped to HardFault.
+UsageFault checks for
+divide-by-zero and unaligned access
+must also be explicitly enabled.
+
+This finishes by listing the current vector catch configuration.
+@end deffn
+
+@anchor{Software Debug Messages and Tracing}
+@section Software Debug Messages and Tracing
+@cindex Linux-ARM DCC support
+@cindex tracing
+@cindex libdcc
+@cindex DCC
+OpenOCD can process certain requests from target software. Currently
+@command{target_request debugmsgs}
+is supported only for @option{arm7_9} and @option{cortex_m3} cores.
+These messages are received as part of target polling, so
+you need to have @command{poll on} active to receive them.
+They are intrusive in that they will affect program execution
+times. If that is a problem, @pxref{ARM Hardware Tracing}.
+
+See @file{libdcc} in the contrib dir for more details.
+In addition to sending strings, characters, and
+arrays of various size integers from the target,
+@file{libdcc} also exports a software trace point mechanism.
+The target being debugged may
+issue trace messages which include a 24-bit @dfn{trace point} number.
+Trace point support includes two distinct mechanisms,
+each supported by a command:
+
+@itemize
+@item @emph{History} ... A circular buffer of trace points
+can be set up, and then displayed at any time.
+This tracks where code has been, which can be invaluable in
+finding out how some fault was triggered.
+
+The buffer may overflow, since it collects records continuously.
+It may be useful to use some of the 24 bits to represent a
+particular event, and other bits to hold data.
+
+@item @emph{Counting} ... An array of counters can be set up,
+and then displayed at any time.
+This can help establish code coverage and identify hot spots.
+
+The array of counters is directly indexed by the trace point
+number, so trace points with higher numbers are not counted.
+@end itemize
+
+Linux-ARM kernels have a ``Kernel low-level debugging
+via EmbeddedICE DCC channel'' option (CONFIG_DEBUG_ICEDCC,
+depends on CONFIG_DEBUG_LL) which uses this mechanism to
+deliver messages before a serial console can be activated.
+This is not the same format used by @file{libdcc}.
+Other software, such as the U-Boot boot loader, sometimes
+does the same thing.
+
+@deffn Command {target_request debugmsgs} [@option{enable}|@option{disable}|@option{charmsg}]
+Displays current handling of target DCC message requests.
+These messages may be sent to the debugger while the target is running.
+The optional @option{enable} and @option{charmsg} parameters
+both enable the messages, while @option{disable} disables them.
+
+With @option{charmsg} the DCC words each contain one character,
+as used by Linux with CONFIG_DEBUG_ICEDCC;
+otherwise the libdcc format is used.
+@end deffn
+
+@deffn Command {trace history} [@option{clear}|count]
+With no parameter, displays all the trace points that have triggered
+in the order they triggered.
+With the parameter @option{clear}, erases all current trace history records.
+With a @var{count} parameter, allocates space for that many
+history records.
+@end deffn
+
+@deffn Command {trace point} [@option{clear}|identifier]
+With no parameter, displays all trace point identifiers and how many times
+they have been triggered.
+With the parameter @option{clear}, erases all current trace point counters.
+With a numeric @var{identifier} parameter, creates a new a trace point counter
+and associates it with that identifier.
+
+@emph{Important:} The identifier and the trace point number
+are not related except by this command.
+These trace point numbers always start at zero (from server startup,
+or after @command{trace point clear}) and count up from there.
+@end deffn
+
+
+@node JTAG Commands
+@chapter JTAG Commands
+@cindex JTAG Commands
+Most general purpose JTAG commands have been presented earlier.
+(@xref{JTAG Speed}, @ref{Reset Configuration}, and @ref{TAP Declaration}.)
+Lower level JTAG commands, as presented here,
+may be needed to work with targets which require special
+attention during operations such as reset or initialization.
+
+To use these commands you will need to understand some
+of the basics of JTAG, including:
+
+@itemize @bullet
+@item A JTAG scan chain consists of a sequence of individual TAP
+devices such as a CPUs.
+@item Control operations involve moving each TAP through the same
+standard state machine (in parallel)
+using their shared TMS and clock signals.
+@item Data transfer involves shifting data through the chain of
+instruction or data registers of each TAP, writing new register values
+while the reading previous ones.
+@item Data register sizes are a function of the instruction active in
+a given TAP, while instruction register sizes are fixed for each TAP.
+All TAPs support a BYPASS instruction with a single bit data register.
+@item The way OpenOCD differentiates between TAP devices is by
+shifting different instructions into (and out of) their instruction
+registers.
+@end itemize
+
+@section Low Level JTAG Commands
+
+These commands are used by developers who need to access
+JTAG instruction or data registers, possibly controlling
+the order of TAP state transitions.
+If you're not debugging OpenOCD internals, or bringing up a
+new JTAG adapter or a new type of TAP device (like a CPU or
+JTAG router), you probably won't need to use these commands.
+
+@deffn Command {drscan} tap [numbits value]+ [@option{-endstate} tap_state]
+Loads the data register of @var{tap} with a series of bit fields
+that specify the entire register.
+Each field is @var{numbits} bits long with
+a numeric @var{value} (hexadecimal encouraged).
+The return value holds the original value of each
+of those fields.
+
+For example, a 38 bit number might be specified as one
+field of 32 bits then one of 6 bits.
+@emph{For portability, never pass fields which are more
+than 32 bits long. Many OpenOCD implementations do not
+support 64-bit (or larger) integer values.}
+
+All TAPs other than @var{tap} must be in BYPASS mode.
+The single bit in their data registers does not matter.
+
+When @var{tap_state} is specified, the JTAG state machine is left
+in that state.
+For example @sc{drpause} might be specified, so that more
+instructions can be issued before re-entering the @sc{run/idle} state.
+If the end state is not specified, the @sc{run/idle} state is entered.
+
+@quotation Warning
+OpenOCD does not record information about data register lengths,
+so @emph{it is important that you get the bit field lengths right}.
+Remember that different JTAG instructions refer to different
+data registers, which may have different lengths.
+Moreover, those lengths may not be fixed;
+the SCAN_N instruction can change the length of
+the register accessed by the INTEST instruction
+(by connecting a different scan chain).
+@end quotation
+@end deffn
+
+@deffn Command {flush_count}
+Returns the number of times the JTAG queue has been flushed.
+This may be used for performance tuning.
+
+For example, flushing a queue over USB involves a
+minimum latency, often several milliseconds, which does
+not change with the amount of data which is written.
+You may be able to identify performance problems by finding
+tasks which waste bandwidth by flushing small transfers too often,
+instead of batching them into larger operations.
+@end deffn
+
+@deffn Command {irscan} [tap instruction]+ [@option{-endstate} tap_state]
+For each @var{tap} listed, loads the instruction register
+with its associated numeric @var{instruction}.
+(The number of bits in that instruction may be displayed
+using the @command{scan_chain} command.)
+For other TAPs, a BYPASS instruction is loaded.
+
+When @var{tap_state} is specified, the JTAG state machine is left
+in that state.
+For example @sc{irpause} might be specified, so the data register
+can be loaded before re-entering the @sc{run/idle} state.
+If the end state is not specified, the @sc{run/idle} state is entered.
+
+@quotation Note
+OpenOCD currently supports only a single field for instruction
+register values, unlike data register values.
+For TAPs where the instruction register length is more than 32 bits,
+portable scripts currently must issue only BYPASS instructions.
+@end quotation
+@end deffn
+
+@deffn Command {jtag_reset} trst srst
+Set values of reset signals.
+The @var{trst} and @var{srst} parameter values may be
+@option{0}, indicating that reset is inactive (pulled or driven high),
+or @option{1}, indicating it is active (pulled or driven low).
+The @command{reset_config} command should already have been used
+to configure how the board and JTAG adapter treat these two
+signals, and to say if either signal is even present.
+@xref{Reset Configuration}.
+
+Note that TRST is specially handled.
+It actually signifies JTAG's @sc{reset} state.
+So if the board doesn't support the optional TRST signal,
+or it doesn't support it along with the specified SRST value,
+JTAG reset is triggered with TMS and TCK signals
+instead of the TRST signal.
+And no matter how that JTAG reset is triggered, once
+the scan chain enters @sc{reset} with TRST inactive,
+TAP @code{post-reset} events are delivered to all TAPs
+with handlers for that event.
+@end deffn
+
+@deffn Command {pathmove} start_state [next_state ...]
+Start by moving to @var{start_state}, which
+must be one of the @emph{stable} states.
+Unless it is the only state given, this will often be the
+current state, so that no TCK transitions are needed.
+Then, in a series of single state transitions
+(conforming to the JTAG state machine) shift to
+each @var{next_state} in sequence, one per TCK cycle.
+The final state must also be stable.
+@end deffn
+
+@deffn Command {runtest} @var{num_cycles}
+Move to the @sc{run/idle} state, and execute at least
+@var{num_cycles} of the JTAG clock (TCK).
+Instructions often need some time
+to execute before they take effect.
+@end deffn
+
+@c tms_sequence (short|long)
+@c ... temporary, debug-only, other than USBprog bug workaround...
+
+@deffn Command {verify_ircapture} (@option{enable}|@option{disable})
+Verify values captured during @sc{ircapture} and returned
+during IR scans. Default is enabled, but this can be
+overridden by @command{verify_jtag}.
+This flag is ignored when validating JTAG chain configuration.
+@end deffn
+
+@deffn Command {verify_jtag} (@option{enable}|@option{disable})
+Enables verification of DR and IR scans, to help detect
+programming errors. For IR scans, @command{verify_ircapture}
+must also be enabled.
+Default is enabled.
+@end deffn
+
+@section TAP state names
+@cindex TAP state names
+
+The @var{tap_state} names used by OpenOCD in the @command{drscan},
+@command{irscan}, and @command{pathmove} commands are the same
+as those used in SVF boundary scan documents, except that
+SVF uses @sc{idle} instead of @sc{run/idle}.
+
+@itemize @bullet
+@item @b{RESET} ... @emph{stable} (with TMS high);
+acts as if TRST were pulsed
+@item @b{RUN/IDLE} ... @emph{stable}; don't assume this always means IDLE
+@item @b{DRSELECT}
+@item @b{DRCAPTURE}
+@item @b{DRSHIFT} ... @emph{stable}; TDI/TDO shifting
+through the data register
+@item @b{DREXIT1}
+@item @b{DRPAUSE} ... @emph{stable}; data register ready
+for update or more shifting
+@item @b{DREXIT2}
+@item @b{DRUPDATE}
+@item @b{IRSELECT}
+@item @b{IRCAPTURE}
+@item @b{IRSHIFT} ... @emph{stable}; TDI/TDO shifting
+through the instruction register
+@item @b{IREXIT1}
+@item @b{IRPAUSE} ... @emph{stable}; instruction register ready
+for update or more shifting
+@item @b{IREXIT2}
+@item @b{IRUPDATE}
+@end itemize
+
+Note that only six of those states are fully ``stable'' in the
+face of TMS fixed (low except for @sc{reset})
+and a free-running JTAG clock. For all the
+others, the next TCK transition changes to a new state.
+
+@itemize @bullet
+@item From @sc{drshift} and @sc{irshift}, clock transitions will
+produce side effects by changing register contents. The values
+to be latched in upcoming @sc{drupdate} or @sc{irupdate} states
+may not be as expected.
+@item @sc{run/idle}, @sc{drpause}, and @sc{irpause} are reasonable
+choices after @command{drscan} or @command{irscan} commands,
+since they are free of JTAG side effects.
+@item @sc{run/idle} may have side effects that appear at non-JTAG
+levels, such as advancing the ARM9E-S instruction pipeline.
+Consult the documentation for the TAP(s) you are working with.
+@end itemize
+
+@node Boundary Scan Commands
+@chapter Boundary Scan Commands
+
+One of the original purposes of JTAG was to support
+boundary scan based hardware testing.
+Although its primary focus is to support On-Chip Debugging,
+OpenOCD also includes some boundary scan commands.
+
+@section SVF: Serial Vector Format
+@cindex Serial Vector Format
+@cindex SVF
+
+The Serial Vector Format, better known as @dfn{SVF}, is a
+way to represent JTAG test patterns in text files.
+OpenOCD supports running such test files.
+
+@deffn Command {svf} filename [@option{quiet}]
+This issues a JTAG reset (Test-Logic-Reset) and then
+runs the SVF script from @file{filename}.
+Unless the @option{quiet} option is specified,
+each command is logged before it is executed.
+@end deffn
+
+@section XSVF: Xilinx Serial Vector Format
+@cindex Xilinx Serial Vector Format
+@cindex XSVF
+
+The Xilinx Serial Vector Format, better known as @dfn{XSVF}, is a
+binary representation of SVF which is optimized for use with
+Xilinx devices.
+OpenOCD supports running such test files.
+
+@quotation Important
+Not all XSVF commands are supported.
+@end quotation
+
+@deffn Command {xsvf} (tapname|@option{plain}) filename [@option{virt2}] [@option{quiet}]
+This issues a JTAG reset (Test-Logic-Reset) and then
+runs the XSVF script from @file{filename}.
+When a @var{tapname} is specified, the commands are directed at
+that TAP.
+When @option{virt2} is specified, the @sc{xruntest} command counts
+are interpreted as TCK cycles instead of microseconds.
+Unless the @option{quiet} option is specified,
+messages are logged for comments and some retries.
+@end deffn
+
+The OpenOCD sources also include two utility scripts
+for working with XSVF; they are not currently installed
+after building the software.
+You may find them useful:
+
+@itemize
+@item @emph{svf2xsvf} ... converts SVF files into the extended XSVF
+syntax understood by the @command{xsvf} command; see notes below.
+@item @emph{xsvfdump} ... converts XSVF files into a text output format;
+understands the OpenOCD extensions.
+@end itemize
+
+The input format accepts a handful of non-standard extensions.
+These include three opcodes corresponding to SVF extensions
+from Lattice Semiconductor (LCOUNT, LDELAY, LDSR), and
+two opcodes supporting a more accurate translation of SVF
+(XTRST, XWAITSTATE).
+If @emph{xsvfdump} shows a file is using those opcodes, it
+probably will not be usable with other XSVF tools.
+
+
+@node TFTP
+@chapter TFTP
+@cindex TFTP
+If OpenOCD runs on an embedded host(as ZY1000 does), then TFTP can
+be used to access files on PCs (either the developer's PC or some other PC).
+
+The way this works on the ZY1000 is to prefix a filename by
+"/tftp/ip/" and append the TFTP path on the TFTP
+server (tftpd). For example,
+
+@example
+load_image /tftp/10.0.0.96/c:\temp\abc.elf
+@end example
+
+will load c:\temp\abc.elf from the developer pc (10.0.0.96) into memory as
+if the file was hosted on the embedded host.
+
+In order to achieve decent performance, you must choose a TFTP server
+that supports a packet size bigger than the default packet size (512 bytes). There
+are numerous TFTP servers out there (free and commercial) and you will have to do
+a bit of googling to find something that fits your requirements.
+
+@node GDB and OpenOCD
+@chapter GDB and OpenOCD
+@cindex GDB
+OpenOCD complies with the remote gdbserver protocol, and as such can be used
+to debug remote targets.
+
+@anchor{Connecting to GDB}
+@section Connecting to GDB
+@cindex Connecting to GDB
+Use GDB 6.7 or newer with OpenOCD if you run into trouble. For
+instance GDB 6.3 has a known bug that produces bogus memory access
+errors, which has since been fixed: look up 1836 in
+@url{http://sourceware.org/cgi-bin/gnatsweb.pl?database=gdb}
+
+OpenOCD can communicate with GDB in two ways:
+
+@enumerate
+@item
+A socket (TCP/IP) connection is typically started as follows:
+@example
+target remote localhost:3333
+@end example
+This would cause GDB to connect to the gdbserver on the local pc using port 3333.
+@item
+A pipe connection is typically started as follows:
+@example
+target remote | openocd --pipe
+@end example
+This would cause GDB to run OpenOCD and communicate using pipes (stdin/stdout).
+Using this method has the advantage of GDB starting/stopping OpenOCD for the debug
+session.
+@end enumerate
+
+To list the available OpenOCD commands type @command{monitor help} on the
+GDB command line.
+
+OpenOCD supports the gdb @option{qSupported} packet, this enables information
+to be sent by the GDB remote server (i.e. OpenOCD) to GDB. Typical information includes
+packet size and the device's memory map.
+
+Previous versions of OpenOCD required the following GDB options to increase
+the packet size and speed up GDB communication:
+@example
+set remote memory-write-packet-size 1024
+set remote memory-write-packet-size fixed
+set remote memory-read-packet-size 1024
+set remote memory-read-packet-size fixed
+@end example
+This is now handled in the @option{qSupported} PacketSize and should not be required.
+
+@section Programming using GDB
+@cindex Programming using GDB
+
+By default the target memory map is sent to GDB. This can be disabled by
+the following OpenOCD configuration option:
+@example
+gdb_memory_map disable
+@end example
+For this to function correctly a valid flash configuration must also be set
+in OpenOCD. For faster performance you should also configure a valid
+working area.
+
+Informing GDB of the memory map of the target will enable GDB to protect any
+flash areas of the target and use hardware breakpoints by default. This means
+that the OpenOCD option @command{gdb_breakpoint_override} is not required when
+using a memory map. @xref{gdb_breakpoint_override}.
+
+To view the configured memory map in GDB, use the GDB command @option{info mem}
+All other unassigned addresses within GDB are treated as RAM.
+
+GDB 6.8 and higher set any memory area not in the memory map as inaccessible.
+This can be changed to the old behaviour by using the following GDB command
+@example
+set mem inaccessible-by-default off
+@end example
+
+If @command{gdb_flash_program enable} is also used, GDB will be able to
+program any flash memory using the vFlash interface.
+
+GDB will look at the target memory map when a load command is given, if any
+areas to be programmed lie within the target flash area the vFlash packets
+will be used.
+
+If the target needs configuring before GDB programming, an event
+script can be executed:
+@example
+$_TARGETNAME configure -event EVENTNAME BODY
+@end example
+
+To verify any flash programming the GDB command @option{compare-sections}
+can be used.
+
+@node Tcl Scripting API
+@chapter Tcl Scripting API
+@cindex Tcl Scripting API
+@cindex Tcl scripts
+@section API rules
+
+The commands are stateless. E.g. the telnet command line has a concept
+of currently active target, the Tcl API proc's take this sort of state
+information as an argument to each proc.
+
+There are three main types of return values: single value, name value
+pair list and lists.
+
+Name value pair. The proc 'foo' below returns a name/value pair
+list.
+
+@verbatim
+
+ > set foo(me) Duane
+ > set foo(you) Oyvind
+ > set foo(mouse) Micky
+ > set foo(duck) Donald
+
+If one does this:
+
+ > set foo
+
+The result is:
+
+ me Duane you Oyvind mouse Micky duck Donald
+
+Thus, to get the names of the associative array is easy:
+
+ foreach { name value } [set foo] {
+ puts "Name: $name, Value: $value"
+ }
+@end verbatim
+
+Lists returned must be relatively small. Otherwise a range
+should be passed in to the proc in question.
+
+@section Internal low-level Commands
+
+By low-level, the intent is a human would not directly use these commands.
+
+Low-level commands are (should be) prefixed with "ocd_", e.g.
+@command{ocd_flash_banks}
+is the low level API upon which @command{flash banks} is implemented.
+
+@itemize @bullet
+@item @b{ocd_mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
+
+Read memory and return as a Tcl array for script processing
+@item @b{ocd_array2mem} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
+
+Convert a Tcl array to memory locations and write the values
+@item @b{ocd_flash_banks} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}> <@var{target}> [@option{driver options} ...]
+
+Return information about the flash banks
+@end itemize
+
+OpenOCD commands can consist of two words, e.g. "flash banks". The
+@file{startup.tcl} "unknown" proc will translate this into a Tcl proc
+called "flash_banks".
+
+@section OpenOCD specific Global Variables
+
+Real Tcl has ::tcl_platform(), and platform::identify, and many other
+variables. JimTCL, as implemented in OpenOCD creates $ocd_HOSTOS which
+holds one of the following values:
+
+@itemize @bullet
+@item @b{winxx} Built using Microsoft Visual Studio
+@item @b{linux} Linux is the underlying operating sytem
+@item @b{darwin} Darwin (mac-os) is the underlying operating sytem.
+@item @b{cygwin} Running under Cygwin
+@item @b{mingw32} Running under MingW32
+@item @b{other} Unknown, none of the above.
+@end itemize
+
+Note: 'winxx' was choosen because today (March-2009) no distinction is made between Win32 and Win64.
+
+@quotation Note
+We should add support for a variable like Tcl variable
+@code{tcl_platform(platform)}, it should be called
+@code{jim_platform} (because it
+is jim, not real tcl).
+@end quotation
+
+@node FAQ
+@chapter FAQ
+@cindex faq
+@enumerate
+@anchor{FAQ RTCK}
+@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
+@cindex RTCK
+@cindex adaptive clocking
+@*
+
+In digital circuit design it is often refered to as ``clock
+synchronisation'' the JTAG interface uses one clock (TCK or TCLK)
+operating at some speed, your target is operating at another. The two
+clocks are not synchronised, they are ``asynchronous''
+
+In order for the two to work together they must be synchronised. Otherwise
+the two systems will get out of sync with each other and nothing will
+work. There are 2 basic options:
+@enumerate
+@item
+Use a special circuit.
+@item
+One clock must be some multiple slower than the other.
+@end enumerate
+
+@b{Does this really matter?} For some chips and some situations, this
+is a non-issue (i.e.: A 500MHz ARM926) but for others - for example some
+Atmel SAM7 and SAM9 chips start operation from reset at 32kHz -
+program/enable the oscillators and eventually the main clock. It is in
+those critical times you must slow the JTAG clock to sometimes 1 to
+4kHz.
+
+Imagine debugging a 500MHz ARM926 hand held battery powered device
+that ``deep sleeps'' at 32kHz between every keystroke. It can be
+painful.
+
+@b{Solution #1 - A special circuit}
+
+In order to make use of this, your JTAG dongle must support the RTCK
+feature. Not all dongles support this - keep reading!
+
+The RTCK signal often found in some ARM chips is used to help with
+this problem. ARM has a good description of the problem described at
+this link: @url{http://www.arm.com/support/faqdev/4170.html} [checked
+28/nov/2008]. Link title: ``How does the JTAG synchronisation logic
+work? / how does adaptive clocking work?''.
+
+The nice thing about adaptive clocking is that ``battery powered hand
+held device example'' - the adaptiveness works perfectly all the
+time. One can set a break point or halt the system in the deep power
+down code, slow step out until the system speeds up.
+
+Note that adaptive clocking may also need to work at the board level,
+when a board-level scan chain has multiple chips.
+Parallel clock voting schemes are good way to implement this,
+both within and between chips, and can easily be implemented
+with a CPLD.
+It's not difficult to have logic fan a module's input TCK signal out
+to each TAP in the scan chain, and then wait until each TAP's RTCK comes
+back with the right polarity before changing the output RTCK signal.
+Texas Instruments makes some clock voting logic available
+for free (with no support) in VHDL form; see
+@url{http://tiexpressdsp.com/index.php/Adaptive_Clocking}
+
+@b{Solution #2 - Always works - but may be slower}
+
+Often this is a perfectly acceptable solution.
+
+In most simple terms: Often the JTAG clock must be 1/10 to 1/12 of
+the target clock speed. But what that ``magic division'' is varies
+depending on the chips on your board.
+@b{ARM rule of thumb} Most ARM based systems require an 6:1 division;
+ARM11 cores use an 8:1 division.
+@b{Xilinx rule of thumb} is 1/12 the clock speed.
+
+Note: Many FTDI2232C based JTAG dongles are limited to 6MHz.
+
+You can still debug the 'low power' situations - you just need to
+manually adjust the clock speed at every step. While painful and
+tedious, it is not always practical.
+
+It is however easy to ``code your way around it'' - i.e.: Cheat a little,
+have a special debug mode in your application that does a ``high power
+sleep''. If you are careful - 98% of your problems can be debugged
+this way.
+
+Note that on ARM you may need to avoid using the @emph{wait for interrupt}
+operation in your idle loops even if you don't otherwise change the CPU
+clock rate.
+That operation gates the CPU clock, and thus the JTAG clock; which
+prevents JTAG access. One consequence is not being able to @command{halt}
+cores which are executing that @emph{wait for interrupt} operation.
+
+To set the JTAG frequency use the command:
+
+@example
+# Example: 1.234MHz
+jtag_khz 1234
+@end example
+
+
+@item @b{Win32 Pathnames} Why don't backslashes work in Windows paths?
+
+OpenOCD uses Tcl and a backslash is an escape char. Use @{ and @}
+around Windows filenames.
+
+@example
+> echo \a
+
+> echo @{\a@}
+\a
+> echo "\a"
+
+>
+@end example
+
+
+@item @b{Missing: cygwin1.dll} OpenOCD complains about a missing cygwin1.dll.
+
+Make sure you have Cygwin installed, or at least a version of OpenOCD that
+claims to come with all the necessary DLLs. When using Cygwin, try launching
+OpenOCD from the Cygwin shell.
+
+@item @b{Breakpoint Issue} I'm trying to set a breakpoint using GDB (or a frontend like Insight or
+Eclipse), but OpenOCD complains that "Info: arm7_9_common.c:213
+arm7_9_add_breakpoint(): sw breakpoint requested, but software breakpoints not enabled".
+
+GDB issues software breakpoints when a normal breakpoint is requested, or to implement
+source-line single-stepping. On ARMv4T systems, like ARM7TDMI, ARM720T or ARM920T,
+software breakpoints consume one of the two available hardware breakpoints.
+
+@item @b{LPC2000 Flash} When erasing or writing LPC2000 on-chip flash, the operation fails at random.
+
+Make sure the core frequency specified in the @option{flash lpc2000} line matches the
+clock at the time you're programming the flash. If you've specified the crystal's
+frequency, make sure the PLL is disabled. If you've specified the full core speed
+(e.g. 60MHz), make sure the PLL is enabled.
+
+@item @b{Amontec Chameleon} When debugging using an Amontec Chameleon in its JTAG Accelerator configuration,
+I keep getting "Error: amt_jtagaccel.c:184 amt_wait_scan_busy(): amt_jtagaccel timed
+out while waiting for end of scan, rtck was disabled".
+
+Make sure your PC's parallel port operates in EPP mode. You might have to try several
+settings in your PC BIOS (ECP, EPP, and different versions of those).
+
+@item @b{Data Aborts} When debugging with OpenOCD and GDB (plain GDB, Insight, or Eclipse),
+I get lots of "Error: arm7_9_common.c:1771 arm7_9_read_memory():
+memory read caused data abort".
+
+The errors are non-fatal, and are the result of GDB trying to trace stack frames
+beyond the last valid frame. It might be possible to prevent this by setting up
+a proper "initial" stack frame, if you happen to know what exactly has to
+be done, feel free to add this here.
+
+@b{Simple:} In your startup code - push 8 registers of zeros onto the
+stack before calling main(). What GDB is doing is ``climbing'' the run
+time stack by reading various values on the stack using the standard
+call frame for the target. GDB keeps going - until one of 2 things
+happen @b{#1} an invalid frame is found, or @b{#2} some huge number of
+stackframes have been processed. By pushing zeros on the stack, GDB
+gracefully stops.
+
+@b{Debugging Interrupt Service Routines} - In your ISR before you call
+your C code, do the same - artifically push some zeros onto the stack,
+remember to pop them off when the ISR is done.
+
+@b{Also note:} If you have a multi-threaded operating system, they
+often do not @b{in the intrest of saving memory} waste these few
+bytes. Painful...
+
+
+@item @b{JTAG Reset Config} I get the following message in the OpenOCD console (or log file):
+"Warning: arm7_9_common.c:679 arm7_9_assert_reset(): srst resets test logic, too".
+
+This warning doesn't indicate any serious problem, as long as you don't want to
+debug your core right out of reset. Your .cfg file specified @option{jtag_reset