+@item @file{target/omap3530.cfg} -- with disabled ARM and DSP,
+plus a JRC to enable them
+@item @file{target/str912.cfg} -- with flash, CPU, and boundary scan
+@item @file{target/ti_dm355.cfg} -- with ETM, ARM, and JRC (this JRC
+is not currently used)
+@end itemize
+
+@subsection Add CPU targets
+
+After adding a TAP for a CPU, you should set it up so that
+GDB and other commands can use it.
+@xref{CPU Configuration}.
+For the at91sam7 example above, the command can look like this;
+note that @code{$_ENDIAN} is not needed, since OpenOCD defaults
+to little endian, and this chip doesn't support changing that.
+
+@example
+set _TARGETNAME $_CHIPNAME.cpu
+target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME
+@end example
+
+Work areas are small RAM areas associated with CPU targets.
+They are used by OpenOCD to speed up downloads,
+and to download small snippets of code to program flash chips.
+If the chip includes a form of ``on-chip-ram'' - and many do - define
+a work area if you can.
+Again using the at91sam7 as an example, this can look like:
+
+@example
+$_TARGETNAME configure -work-area-phys 0x00200000 \
+ -work-area-size 0x4000 -work-area-backup 0
+@end example
+
+@subsection Chip Reset Setup
+
+As a rule, you should put the @command{reset_config} command
+into the board file. Most things you think you know about a
+chip can be tweaked by the board.
+
+Some chips have specific ways the TRST and SRST signals are
+managed. In the unusual case that these are @emph{chip specific}
+and can never be changed by board wiring, they could go here.
+For example, some chips can't support JTAG debugging without
+both signals.
+
+Provide a @code{reset-assert} event handler if you can.
+Such a handler uses JTAG operations to reset the target,
+letting this target config be used in systems which don't
+provide the optional SRST signal, or on systems where you
+don't want to reset all targets at once.
+Such a handler might write to chip registers to force a reset,
+use a JRC to do that (preferable -- the target may be wedged!),
+or force a watchdog timer to trigger.
+(For Cortex-M3 targets, this is not necessary. The target
+driver knows how to use trigger an NVIC reset when SRST is
+not available.)
+
+Some chips need special attention during reset handling if
+they're going to be used with JTAG.
+An example might be needing to send some commands right
+after the target's TAP has been reset, providing a
+@code{reset-deassert-post} event handler that writes a chip
+register to report that JTAG debugging is being done.
+Another would be reconfiguring the watchdog so that it stops
+counting while the core is halted in the debugger.
+
+JTAG clocking constraints often change during reset, and in
+some cases target config files (rather than board config files)
+are the right places to handle some of those issues.
+For example, immediately after reset most chips run using a
+slower clock than they will use later.
+That means that after reset (and potentially, as OpenOCD
+first starts up) they must use a slower JTAG clock rate
+than they will use later.
+@xref{JTAG Speed}.
+
+@quotation Important
+When you are debugging code that runs right after chip
+reset, getting these issues right is critical.
+In particular, if you see intermittent failures when
+OpenOCD verifies the scan chain after reset,
+look at how you are setting up JTAG clocking.
+@end quotation
+
+@subsection ARM Core Specific Hacks
+
+If the chip has a DCC, enable it. If the chip is an ARM9 with some
+special high speed download features - enable it.
+
+If present, the MMU, the MPU and the CACHE should be disabled.
+
+Some ARM cores are equipped with trace support, which permits
+examination of the instruction and data bus activity. Trace
+activity is controlled through an ``Embedded Trace Module'' (ETM)
+on one of the core's scan chains. The ETM emits voluminous data
+through a ``trace port''. (@xref{ARM Hardware Tracing}.)
+If you are using an external trace port,
+configure it in your board config file.
+If you are using an on-chip ``Embedded Trace Buffer'' (ETB),
+configure it in your target config file.
+
+@example
+etm config $_TARGETNAME 16 normal full etb
+etb config $_TARGETNAME $_CHIPNAME.etb
+@end example
+
+@subsection Internal Flash Configuration
+
+This applies @b{ONLY TO MICROCONTROLLERS} that have flash built in.
+
+@b{Never ever} in the ``target configuration file'' define any type of
+flash that is external to the chip. (For example a BOOT flash on
+Chip Select 0.) Such flash information goes in a board file - not
+the TARGET (chip) file.
+
+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]
+
+ arm 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.
+
+@emph{When SRST is not an option} you must set
+up a @code{reset-assert} event handler for your target.
+For example, some JTAG adapters don't include the SRST signal;
+and some boards have multiple targets, and you won't always
+want to reset everything at once.
+
+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
+@item @code{pxa3xx} ... instruction register length is 11 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 Is using SRST appropriate (and possible) on your system?
+Or instead of that, do you need to issue JTAG commands to trigger reset?
+SRST usually resets everything on the scan chain, which can be inappropriate.
+@item During reset, do you need to write to certain memory locations
+to set up system clocks or
+to reconfigure the SDRAM?
+How about configuring the watchdog timer, or other peripherals,
+to stop running while you hold the core stopped for debugging?
+@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 either SRST alone is re-asserted on the scan chain,
+or @code{reset-assert} is triggered.
+@item @b{reset-assert}
+@* Issued as part of @command{reset} processing
+after @command{reset-assert-pre} was triggered.
+When such a handler is present, cores which support this event will use
+it instead of asserting SRST.
+This support is essential for debugging with JTAG interfaces which
+don't include an SRST line (JTAG doesn't require SRST), and for
+selective reset on scan chains that have multiple targets.
+@item @b{reset-assert-post}
+@* Issued as part of @command{reset} processing
+after @code{reset-assert} has been triggered.
+or the target asserted SRST on the entire scan chain.
+@item @b{reset-deassert-pre}
+@* Issued as part of @command{reset} processing
+after @code{reset-assert-post} has been triggered.
+@item @b{reset-deassert-post}
+@* Issued as part of @command{reset} processing
+after @code{reset-deassert-pre} has been triggered
+and (if the target is using it) after SRST has been
+released on the scan chain.
+@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} name 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{name} ... may be used to reference the flash bank
+in other flash commands.
+@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 that was
+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 list}
+Retrieves a list of associative arrays for each device that was
+declared using @command{flash bank}, numbered from zero.
+This returned list can be manipulated easily from within scripts.
+@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.