* Daemon Configuration:: Daemon Configuration
* Interface - Dongle Configuration:: Interface - Dongle Configuration
* Reset Configuration:: Reset Configuration
-* TAP Creation:: TAP Creation
+* TAP Declaration:: TAP Declaration
* CPU Configuration:: CPU Configuration
* Flash Commands:: Flash Commands
* NAND Flash Commands:: NAND Flash Commands
available. A version for more recent code may be available.
Its HTML form is published irregularly at:
-@uref{http://openocd.berlios.de/doc/}
+@uref{http://openocd.berlios.de/doc/html/index.html}
PDF form is likewise published at:
-@uref{http://openocd.berlios.de/doc/pdf/}
+@uref{http://openocd.berlios.de/doc/pdf/openocd.pdf}
@section OpenOCD User's Forum
@item SDRAM configuration (size, speed, etc.
@item Board specific IO configuration (i.e.: GPIO pins might disable a 2nd flash)
@item Multiple TARGET source statements
+@item Reset configuration
@item All things that are not ``inside a chip''
@item Things inside a chip go in a 'target' file
@end enumerate
@item Set defaults
@item Add TAPs to the scan chain
@item Add CPU targets
-@item Reset configuration
@item CPU/Chip/CPU-Core specific features
@item On-Chip flash
@end enumerate
@subsection Adding TAPs to the Scan Chain
After the ``defaults'' are set up,
add the TAPs on each chip to the JTAG scan chain.
-@xref{TAP Creation}, and the naming convention
+@xref{TAP Declaration}, and the naming convention
for taps.
In the simplest case the chip has only one TAP,
A board with two such at91sam7 chips would be able
to source such a config file twice, with different
-values for @code{CHIPNAME} and @code{CPUTAPID}, so
+values for @code{CHIPNAME}, so
it adds a different TAP each time.
There are more complex examples too, with chips that have
For the at91sam7 example above, the command can look like this:
@example
+set _TARGETNAME $_CHIPNAME.cpu
target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME
@end example
@example
$_TARGETNAME configure -work-area-phys 0x00200000 \
- -work-area-size 0x4000 -work-area-backup 0
+ -work-area-size 0x4000 -work-area-backup 0
@end example
@subsection Reset Configuration
+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. If these are @b{CHIP SPECIFIC} they go here, if they are
-@b{BOARD SPECIFIC} they go in the board file.
+managed. In the unusual case that these are @emph{chip specific}
+and can never be changed by board wiring, they could go here.
@subsection ARM Core Specific Hacks
@cindex GDB configuration
You can reconfigure some GDB behaviors if needed.
The ones listed here are static and global.
-@xref{Target Create}, about declaring individual targets.
+@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 <hard|soft|disable>
+@deffn {Command} gdb_breakpoint_override [@option{hard}|@option{soft}|@option{disable}]
Force breakpoint type for gdb @command{break} commands.
-The raison d'etre for this option is to support GDB GUI's which don't
+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.
-
-This option replaces older arm7_9 target commands that addressed
-the same issue.
@end deffn
-@deffn {Config command} gdb_detach <resume|reset|halt|nothing>
+@deffn {Config command} gdb_detach (@option{resume}|@option{reset}|@option{halt}|@option{nothing})
Configures what OpenOCD will do when GDB detaches from the daemon.
-Default behaviour is @var{resume}.
+Default behaviour is @option{resume}.
@end deffn
@anchor{gdb_flash_program}
-@deffn {Config command} gdb_flash_program <enable|disable>
-Set to @var{enable} to cause OpenOCD to program the flash memory when a
+@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 @var{enable}.
+The default behaviour is @option{enable}.
@end deffn
-@deffn {Config command} gdb_memory_map <enable|disable>
-Set to @var{enable} to cause OpenOCD to send the memory configuration to GDB when
+@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 @var{enable}.
+Default behaviour is @option{enable}.
@xref{gdb_flash_program}.
@end deffn
-@deffn {Config command} gdb_report_data_abort <enable|disable>
+@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 @var{disable};
-use @var{enable} see these errors reported.
+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
-Interface commands are normally found in an interface configuration
-file which is sourced by your openocd.cfg file. These commands tell
-OpenOCD what type of JTAG dongle you have and how to talk to it.
-@section Simple Complete Interface Examples
-@b{A Turtelizer FT2232 Based JTAG Dongle}
-@verbatim
-#interface
-interface ft2232
-ft2232_device_desc "Turtelizer JTAG/RS232 Adapter A"
-ft2232_layout turtelizer2
-ft2232_vid_pid 0x0403 0xbdc8
-@end verbatim
-@b{A SEGGER Jlink}
-@verbatim
+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 verbatim
-@b{A Raisonance RLink}
-@verbatim
-# rlink interface
-interface rlink
-@end verbatim
-@b{Parallel Port}
-@verbatim
-interface parport
-parport_port 0xc8b8
-parport_cable wiggler
-jtag_speed 0
-@end verbatim
-@b{ARM-JTAG-EW}
-@verbatim
-interface arm-jtag-ew
-@end verbatim
-@section Interface Command
+@end example
-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.
+Most adapters need a bit more configuration than that.
-@itemize @bullet
-@item @b{interface} <@var{name}>
-@cindex interface
-@*Use the interface driver <@var{name}> to connect to the
-target. Currently supported interfaces are
+@section Interface Configuration
-@itemize @minus
+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.
-@item @b{parport}
-@* PC parallel port bit-banging (Wigglers, PLD download cable, ...)
+@deffn {Config Command} {interface} name
+Use the interface driver @var{name} to connect to the
+target.
+@end deffn
-@item @b{amt_jtagaccel}
-@* Amontec Chameleon in its JTAG Accelerator configuration connected to a PC's EPP
-mode parallel port
+@deffn Command {interface_list}
+List the interface drivers that have been built into
+the running copy of OpenOCD.
+@end deffn
-@item @b{ft2232}
-@* FTDI FT2232 (USB) based devices using either the open-source libftdi or the binary only
-FTD2XX driver. The FTD2XX is superior in performance, but not available on every
-platform. The libftdi uses libusb, and should be portable to all systems that provide
-libusb.
+@deffn Command {jtag interface}
+Returns the name of the interface driver being used.
+@end deffn
-@item @b{ep93xx}
-@*Cirrus Logic EP93xx based single-board computer bit-banging (in development)
+@section Interface Drivers
-@item @b{presto}
-@* ASIX PRESTO USB JTAG programmer.
+Each of the interface drivers listed here must be explicitly
+enabled when OpenOCD is configured, in order to be made
+available at run time.
-@item @b{usbprog}
-@* usbprog is a freely programmable USB adapter.
+@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:
-@item @b{gw16012}
-@* Gateworks GW16012 JTAG programmer.
+@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
-@item @b{jlink}
-@* Segger jlink USB adapter
+@deffn {Config Command} rtck [@option{enable}|@option{disable}]
+Displays status of RTCK option.
+Optionally sets that option first.
+@end deffn
+@end deffn
-@item @b{rlink}
-@* Raisonance RLink USB adapter
+@deffn {Interface Driver} {arm-jtag-ew}
+Olimex ARM-JTAG-EW USB adapter
+This has one driver-specific command:
-@item @b{vsllink}
-@* vsllink is part of Versaloon which is a versatile USB programmer.
+@deffn Command {armjtagew_info}
+Logs some status
+@end deffn
+@end deffn
-@item @b{arm-jtag-ew}
-@* Olimex ARM-JTAG-EW USB adapter
-@comment - End parameters
-@end itemize
-@comment - End Interface
-@end itemize
-@subsection parport options
+@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
-@itemize @bullet
-@item @b{parport_port} <@var{number}>
-@cindex parport_port
-@*Either the address of the I/O port (default: 0x378 for LPT1) or the number of
-the @file{/dev/parport} device
+@deffn {Interface Driver} {dummy}
+A dummy software-only driver for debugging.
+@end deffn
-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.
-@item @b{parport_cable} <@var{name}>
-@cindex parport_cable
-@*The layout of the parallel port cable used to connect to the target.
-Currently supported cables are
-@itemize @minus
-@item @b{wiggler}
-@cindex wiggler
-The original Wiggler layout, also supported by several clones, such
-as the Olimex ARM-JTAG
-@item @b{wiggler2}
-@cindex wiggler2
-Same as original wiggler except an led is fitted on D5.
-@item @b{wiggler_ntrst_inverted}
-@cindex wiggler_ntrst_inverted
-Same as original wiggler except TRST is inverted.
-@item @b{old_amt_wiggler}
-@cindex old_amt_wiggler
-The Wiggler configuration that comes with Amontec's Chameleon Programmer. The new
-version available from the website uses the original Wiggler layout ('@var{wiggler}')
-@item @b{chameleon}
-@cindex 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}
-@cindex dlc5
-The Xilinx Parallel cable III.
-@item @b{triton}
-@cindex 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{flashlink}
-@cindex flashlink
-The ST Parallel cable.
-@item @b{arm-jtag}
-@cindex arm-jtag
-Same as original wiggler except SRST and TRST connections reversed and
-TRST is also inverted.
-@item @b{altium}
-@cindex altium
-Altium Universal JTAG cable.
-@end itemize
-@item @b{parport_write_on_exit} <@var{on}|@var{off}>
-@cindex parport_write_on_exit
-@*This will configure the parallel driver to write a known value to the parallel
-interface on exiting OpenOCD
-@end itemize
+@deffn {Interface Driver} {ep93xx}
+Cirrus Logic EP93xx based single-board computer bit-banging (in development)
+@end deffn
-@subsection amt_jtagaccel options
-@itemize @bullet
-@item @b{parport_port} <@var{number}>
-@cindex parport_port
-@*Either the address of the I/O port (default: 0x378 for LPT1) or the number of the
-@file{/dev/parport} device
-@end itemize
-@subsection ft2232 options
+@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:
-@itemize @bullet
-@item @b{ft2232_device_desc} <@var{description}>
-@cindex ft2232_device_desc
-@*The USB device description of the FTDI FT2232 device. If not
+@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.
+@end deffn
-@b{TODO:} Confirm the following: On Windows the name needs to end with
-a ``space A''? Or not? It has to do with the FTD2xx driver. When must
-this be added and when must it not be added? Why can't the code in the
-interface or in OpenOCD automatically add this if needed? -- Duane.
-
-@item @b{ft2232_serial} <@var{serial-number}>
-@cindex ft2232_serial
-@*The serial number of the FTDI FT2232 device. If not specified, the FTDI default
-values are used.
-@item @b{ft2232_layout} <@var{name}>
-@cindex ft2232_layout
-@*The layout of the FT2232 GPIO signals used to control output-enables and reset
-signals. Valid layouts are
+@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{usbjtag}
-"USBJTAG-1" layout described in the original OpenOCD diploma thesis
-@item @b{jtagkey}
-Amontec JTAGkey and JTAGkey-Tiny
-@item @b{signalyzer}
-Signalyzer
-@item @b{olimex-jtag}
-Olimex ARM-USB-OCD
-@item @b{m5960}
-American Microsystems M5960
-@item @b{evb_lm3s811}
-Luminary Micro EVB_LM3S811 as a JTAG interface (not onboard processor), no TRST or
-SRST signals on external connector
-@item @b{comstick}
-Hitex STR9 comstick
-@item @b{stm32stick}
-Hitex STM32 Performance Stick
-@item @b{flyswatter}
-Tin Can Tools Flyswatter
-@item @b{turtelizer2}
-egnite Software turtelizer2
-@item @b{oocdlink}
-OOCDLink
-@item @b{axm0432_jtag}
-Axiom AXM-0432
-@item @b{cortino}
-Hitex Cortino JTAG interface
+@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{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{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
-@item @b{ft2232_vid_pid} <@var{vid}> <@var{pid}>
-@*The vendor ID and product ID of the FTDI FT2232 device. If not specified, the FTDI
-default values are used. Multiple <@var{vid}>, <@var{pid}> pairs may be given, e.g.
+@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
-@item @b{ft2232_latency} <@var{ms}>
-@*On some systems using FT2232 based JTAG interfaces the FT_Read function call in
+@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 {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
-@subsection ep93xx options
-@cindex ep93xx options
-Currently, there are no options available for the ep93xx interface.
+@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
board-specific script might do things like setting up DRAM.
(@xref{Reset Command}.)
-@section SRST and TRST Signal 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
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).
+(@xref{JTAG Commands}, where the @command{jtag_reset}
+command is presented.)
@end itemize
There can also be other issues.
@end deffn
-@node TAP Creation
-@chapter TAP Creation
-@cindex TAP creation
+@node TAP Declaration
+@chapter TAP Declaration
+@cindex TAP declaration
@cindex TAP configuration
@emph{Test Access Ports} (TAPs) are the core of JTAG.
The configuration mechanism currently supported by OpenOCD
requires explicit configuration of all TAP devices using
@command{jtag newtap} commands.
-One like this would create a tap named @code{chip1.cpu}:
+One like this would declare a tap and name it @code{chip1.cpu}:
@example
jtag newtap chip1 cpu -irlen 7 -ircapture 0x01 -irmask 0x55
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 created is very important.}
+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}
-Checked: 28-Nov-2008}.
+@url{http://eu.st.com/stonline/products/literature/ds/13495.pdf}}.
To configure those taps, @file{target/str912.cfg}
includes commands something like this:
@section TAP Names
-When a TAP objects is created with @command{jtag newtap},
+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},
reusing on boards with multiple targets.
@end quotation
-@anchor{TAP Creation Commands}
-@section TAP Creation Commands
+@section TAP Declaration Commands
@c shouldn't this be(come) a {Config Command}?
@anchor{jtag newtap}
@deffn Command {jtag newtap} chipname tapname configparams...
-Creates a new TAP with the dotted name @var{chipname}.@var{tapname},
+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.
@chapter CPU Configuration
@cindex GDB target
-This chapter discusses how to create a GDB debug target for a CPU.
+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, where relevant,
+(@pxref{Architecture and Core Commands},
+and @ref{Target State handling}) and
through various kinds of NAND and NOR flash commands.
-Also, if you have multiple CPUs you can have multiple such targets.
+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
+
+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}
+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
+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
+
+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
+@item @code{arm7tdmi} -- this is an ARMv4 core
+@item @code{arm920t} -- this is an ARMv5 core
+@item @code{arm926ejs} -- this is an ARMv5 core
+@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
+@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{feroceon} -- resembles arm926
+@item @code{mips_m4k} -- a MIPS core. This supports one variant:
+@itemize @minus
+@item @code{ejtag_srst} ... Use this when debugging targets that do not
+provide a functional SRST line on the EJTAG connector. This causes
+OpenOCD to instead use an EJTAG software reset command to reset the
+processor.
+You still need to enable @option{srst} on the @command{reset_config}
+command to enable OpenOCD hardware reset functionality.
+@end itemize
+@item @code{xscale} -- this is actually an architecture,
+not a CPU type. It is based on the ARMv5 architecture.
+There are several variants defined:
+@itemize @minus
+@item @code{ixp42x}, @code{ixp45x}, @code{ixp46x},
+@code{pxa27x} ... instruction register length is 7 bits
+@item @code{pxa250}, @code{pxa255},
+@code{pxa26x} ... instruction register length is 5 bits
+@end itemize
+@end itemize
+@end deffn
+
+To avoid being confused by the variety of ARM based cores, remember
+this key point: @emph{ARM is a technology licencing company}.
+(See: @url{http://www.arm.com}.)
+The CPU name used by OpenOCD will reflect the CPU design that was
+licenced, not a vendor brand which incorporates that design.
+Name prefixes like arm7, arm9, arm11, and cortex
+reflect design generations;
+while names like ARMv4, ARMv5, ARMv6, and ARMv7
+reflect an architecture version implemented by a CPU design.
+
+@anchor{Target Configuration}
+@section Target Configuration
Before creating a ``target'', you must have added its TAP to the scan chain.
When you've added that TAP, you will have a @code{dotted.name}
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.
-@section targets [NAME]
-@b{Note:} This command name is PLURAL - not singular.
+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.
-With NO parameter, this plural @b{targets} command lists all known
-targets in a human friendly form.
+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
-With a parameter, this plural @b{targets} command sets the current
-target to the given name. (i.e.: If there are multiple debug targets)
+@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
-Example:
-@verbatim
-(gdb) mon targets
- CmdName Type Endian ChainPos State
--- ---------- ---------- ---------- -------- ----------
- 0: target0 arm7tdmi little 0 halted
-@end verbatim
+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
-@section target COMMANDS
-@b{Note:} This command name is SINGULAR - not plural. It is used to
-manipulate specific targets, to create targets and other things.
+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.
-Once a target is created, a TARGETNAME (object) command is created;
-see below for details.
+@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.
-The TARGET command accepts these sub-commands:
@itemize @bullet
-@item @b{create} .. parameters ..
-@* creates a new target, see below for details.
-@item @b{types}
-@* Lists all supported target types (perhaps some are not yet in this document).
-@item @b{names}
-@* Lists all current debug target names, for example: 'str912.cpu' or 'pxa27.cpu' example usage:
-@verbatim
- foreach t [target names] {
- puts [format "Target: %s\n" $t]
- }
-@end verbatim
-@item @b{current}
-@* Returns the current target. OpenOCD always has, or refers to the ``current target'' in some way.
-By default, commands like: ``mww'' (used to write memory) operate on the current target.
-@item @b{number} @b{NUMBER}
-@* Internally OpenOCD maintains a list of targets - in numerical index
-(0..N-1) this command returns the name of the target at index N.
-Example usage:
-@verbatim
- set thename [target number $x]
- puts [format "Target %d is: %s\n" $x $thename]
-@end verbatim
-@item @b{count}
-@* Returns the number of targets known to OpenOCD (see number above)
-Example:
-@verbatim
- set c [target count]
- for { set x 0 } { $x < $c } { incr x } {
- # Assuming you have created this function
- print_target_details $x
- }
-@end verbatim
+@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, it doesn't.
+When possible, use a working_area that doesn't need to be backed up,
+since performing a backup slows down operations.
+
+@item @code{-work-area-size} @var{size} -- specify/set the work area
+
+@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.
@end itemize
+@end deffn
-@section TARGETNAME (object) commands
-@b{Use:} Once a target is created, an ``object name'' that represents the
-target is created. By convention, the target name is identical to the
-tap name. In a multiple target system, one can precede many common
-commands with a specific target name and effect only that target.
-@example
- str912.cpu mww 0x1234 0x42
- omap3530.cpu mww 0x5555 123
-@end example
+@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.
-@b{Model:} The Tcl/Tk language has the concept of object commands. A
-good 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 1st
+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]
+# 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. Commands available as a ``target object'' are:
+button, and its object commands are invoked the same way.
-@comment START targetobj commands.
-@itemize @bullet
-@item @b{configure} - configure the target; see Target Config/Cget Options below
-@item @b{cget} - query the target configuration; see Target Config/Cget Options below
-@item @b{curstate} - current target state (running, halt, etc.
-@item @b{eventlist}
-@* Intended for a human to see/read the currently configure target events.
-@item @b{Various Memory Commands} See the ``mww'' command elsewhere.
-@comment start memory
-@itemize @bullet
-@item @b{mww} ...
-@item @b{mwh} ...
-@item @b{mwb} ...
-@item @b{mdw} ...
-@item @b{mdh} ...
-@item @b{mdb} ...
-@comment end memory
-@end itemize
-@item @b{Memory To Array, Array To Memory}
-@* These are aimed at a machine interface to memory
-@itemize @bullet
-@item @b{mem2array ARRAYNAME WIDTH ADDRESS COUNT}
-@item @b{array2mem ARRAYNAME WIDTH ADDRESS COUNT}
-@* Where:
-@* @b{ARRAYNAME} is the name of an array variable
-@* @b{WIDTH} is 8/16/32 - indicating the memory access size
-@* @b{ADDRESS} is the target memory address
-@* @b{COUNT} is the number of elements to process
+@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
-@item @b{Used during ``reset''}
-@* These commands are used internally by the OpenOCD scripts to deal
-with odd reset situations and are not documented here.
+@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 @b{arp_examine}
-@item @b{arp_poll}
-@item @b{arp_reset}
-@item @b{arp_halt}
-@item @b{arp_waitstate}
-@end itemize
-@item @b{invoke-event} @b{EVENT-NAME}
-@* Invokes the specific event manually for the target
+@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
+for @{ set x 0 @} @{ $x < [target count] @} @{ incr x @} @{
+ set name [target number $x]
+ 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 events
At various times, certain things can happen, or you want them to happen.
-
-Examples:
+For example:
@itemize @bullet
@item What should happen when GDB connects? Should your target reset?
@item When GDB tries to flash the target, do you need to enable the flash via a special command?
-@item During reset, do you need to write to certain memory location to reconfigure the SDRAM?
+@item During reset, do you need to write to certain memory locations
+to set up system clocks or
+to reconfigure the SDRAM?
@end itemize
-All of the above items are handled by target events.
-
-To specify an event action, either during target creation, or later
-via ``$_TARGETNAME configure'' see this example.
-
-Syntactially, the option is: ``-event NAME BODY'' where NAME is a
-target event name, and BODY is a Tcl procedure or string of commands
-to execute.
+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 programmers model is the ``-command'' option used in Tcl/Tk
-buttons and events. Below are two identical examples, the first
-creates and invokes small procedure. The second inlines the procedure.
+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 @{ @} @{
- puts "RESET...."
- reset halt
- @}
- mychip.cpu configure -event gdb-attach my_attach_proc
- mychip.cpu configure -event gdb-attach @{
- puts "Reset..."
- reset halt
- @}
+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
-@section Current Events
-The following events are available:
+The following target events are defined:
+
@itemize @bullet
@item @b{debug-halted}
@* The target has halted for debug reasons (i.e.: breakpoint)
@item @b{old-pre_resume}
@* DO NOT USE THIS: Used internally
@item @b{reset-assert-pre}
-@* Before reset is asserted on the tap.
+@* Issued as part of @command{reset} processing
+after SRST and/or TRST were activated and deactivated,
+but before reset is asserted on the tap.
@item @b{reset-assert-post}
-@* Reset is now asserted on the tap.
+@* Issued as part of @command{reset} processing
+when reset is asserted on the tap.
@item @b{reset-deassert-pre}
-@* Reset is about to be released on the tap
+@* Issued as part of @command{reset} processing
+when reset is about to be released on the tap.
+
+For some chips, this may be a good place to make sure
+the JTAG clock is slow enough to work before the PLL
+has been set up to allow faster JTAG speeds.
@item @b{reset-deassert-post}
-@* Reset has been released on the tap
+@* Issued as part of @command{reset} processing
+when reset has been released on the tap.
@item @b{reset-end}
-@* Currently not used.
+@* Issued as the final step in @command{reset} processing.
@item @b{reset-halt-post}
@* Currently not usd
@item @b{reset-halt-pre}
@* Currently not used
@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.
@item @b{reset-start}
-@* Currently not used
+@* Issued as part of @command{reset} processing
+before either SRST or TRST are activated.
@item @b{reset-wait-pos}
@* Currently not used
@item @b{reset-wait-pre}
@* Target has resumed
@end itemize
-@anchor{Target Create}
-@section Target Create
-@cindex target
-@cindex target creation
-
-@example
-@b{target} @b{create} <@var{NAME}> <@var{TYPE}> <@var{PARAMS ...}>
-@end example
-@*This command creates a GDB debug target that refers to a specific JTAG tap.
-@comment START params
-@itemize @bullet
-@item @b{NAME}
-@* Is the name of the debug target. By convention it should be the tap
-DOTTED.NAME. This name is also used to create the target object
-command, and in other places the target needs to be identified.
-@item @b{TYPE}
-@* Specifies the target type, i.e.: ARM7TDMI, or Cortex-M3. Currently supported targets are:
-@comment START types
-@itemize @minus
-@item @b{arm7tdmi}
-@item @b{arm720t}
-@item @b{arm9tdmi}
-@item @b{arm920t}
-@item @b{arm922t}
-@item @b{arm926ejs}
-@item @b{arm966e}
-@item @b{cortex_m3}
-@item @b{feroceon}
-@item @b{xscale}
-@item @b{arm11}
-@item @b{mips_m4k}
-@comment end TYPES
-@end itemize
-@item @b{PARAMS}
-@*PARAMs are various target configuration parameters. The following ones are mandatory:
-@comment START mandatory
-@itemize @bullet
-@item @b{-endian big|little}
-@item @b{-chain-position DOTTED.NAME}
-@comment end MANDATORY
-@end itemize
-@comment END params
-@end itemize
-
-@section Target Config/Cget Options
-These options can be specified when the target is created, or later
-via the configure option or to query the target via cget.
-
-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 may help perform otherwise
-unavailable operations (like some coprocessor operations on ARM7/9 systems).
-@itemize @bullet
-@item @b{-type} - returns the target type
-@item @b{-event NAME BODY} see Target events
-@item @b{-work-area-virt [ADDRESS]} specify/set the work area base address
-which will be used when an MMU is active.
-@item @b{-work-area-phys [ADDRESS]} specify/set the work area base address
-which will be used when an MMU is inactive.
-@item @b{-work-area-size [ADDRESS]} specify/set the work area
-@item @b{-work-area-backup [0|1]} does the work area get backed up;
-by default, it doesn't. When possible, use a working_area that doesn't
-need to be backed up, since performing a backup slows down operations.
-@item @b{-endian [big|little]}
-@item @b{-variant [NAME]} some chips have variants OpenOCD needs to know about
-@item @b{-chain-position DOTTED.NAME} the tap name this target refers to.
-@end itemize
-Example:
-@example
- for @{ set x 0 @} @{ $x < [target count] @} @{ incr x @} @{
- set name [target number $x]
- set y [$name cget -endian]
- set z [$name cget -type]
- puts [format "Chip %d is %s, Endian: %s, type: %s" $x $y $z]
- @}
-@end example
-
-@b{PROBLEM:} On more complex chips, the work area can become
-inaccessible when application code enables or disables the MMU.
-For example, the MMU context used to acess the virtual address
-will probably matter.
-
-@section Target Variants
-@itemize @bullet
-@item @b{cortex_m3}
-@* Use variant @option{lm3s} 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.
-@item @b{xscale}
-@*Supported variants are
-@option{ixp42x}, @option{ixp45x}, @option{ixp46x},
-@option{pxa250}, @option{pxa255}, @option{pxa26x}.
-@item @b{mips_m4k}
-@* Use variant @option{ejtag_srst} 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 reset
-configuration command to enable OpenOCD hardware reset functionality.
-@comment END variants
-@end itemize
@node Flash Commands
@chapter Flash Commands
@itemize
@item @var{jedec_probe} ... is used to detect certain non-CFI flash ROMs,
like AM29LV010 and similar types.
-@item @var{x16_as_x8} ...
+@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)
has been locked. Halting the core is not required for the @option{str9xpec} driver
as mentioned above, just issue the commands above manually or from a telnet prompt.
-@subsubsection str9xpec driver options
-
-@b{flash bank str9xpec} <@var{base}> <@var{size}> 0 0 <@var{target}>
-@*Before using the flash commands the turbo mode must be enabled using str9xpec
-@option{enable_turbo} <@var{num>.}
-
+@deffn {Flash Driver} str9xpec
Only use this driver for locking/unlocking the device or configuring the option bytes.
Use the standard str9 driver for programming.
+Before using the flash commands the turbo mode must be enabled using the
+@command{str9xpec enable_turbo} command.
-@subsubsection str9xpec specific commands
-@cindex str9xpec specific commands
-These are flash specific commands when using the str9xpec driver.
+Several str9xpec-specific commands are defined:
-@itemize @bullet
-@item @b{str9xpec enable_turbo} <@var{num}>
-@cindex str9xpec enable_turbo
-@*enable turbo mode, will simply remove the str9 from the chain and talk
+@deffn Command {str9xpec disable_turbo} num
+Restore the str9 into JTAG chain.
+@end deffn
+
+@deffn Command {str9xpec enable_turbo} num
+Enable turbo mode, will simply remove the str9 from the chain and talk
directly to the embedded flash controller.
-@item @b{str9xpec disable_turbo} <@var{num}>
-@cindex str9xpec disable_turbo
-@*restore the str9 into JTAG chain.
-@item @b{str9xpec lock} <@var{num}>
-@cindex str9xpec lock
-@*lock str9 device. The str9 will only respond to an unlock command that will
+@end deffn
+
+@deffn Command {str9xpec lock} num
+Lock str9 device. The str9 will only respond to an unlock command that will
erase the device.
-@item @b{str9xpec unlock} <@var{num}>
-@cindex str9xpec unlock
-@*unlock str9 device.
-@item @b{str9xpec options_read} <@var{num}>
-@cindex str9xpec options_read
-@*read str9 option bytes.
-@item @b{str9xpec options_write} <@var{num}>
-@cindex str9xpec options_write
-@*write str9 option bytes.
-@end itemize
+@end deffn
-@subsubsection STR9 option byte configuration
-@cindex STR9 option byte configuration
+@deffn Command {str9xpec part_id} num
+Prints the part identifier for bank @var{num}.
+@end deffn
+
+@deffn Command {str9xpec options_cmap} num (@option{bank0}|@option{bank1})
+Configure str9 boot bank.
+@end deffn
+
+@deffn Command {str9xpec options_lvdsel} num (@option{vdd}|@option{vdd_vddq})
+Configure str9 lvd source.
+@end deffn
+
+@deffn Command {str9xpec options_lvdthd} num (@option{2.4v}|@option{2.7v})
+Configure str9 lvd threshold.
+@end deffn
+
+@deffn Command {str9xpec options_lvdwarn} bank (@option{vdd}|@option{vdd_vddq})
+Configure str9 lvd reset warning source.
+@end deffn
+
+@deffn Command {str9xpec options_read} num
+Read str9 option bytes.
+@end deffn
+
+@deffn Command {str9xpec options_write} num
+Write str9 option bytes.
+@end deffn
+
+@deffn Command {str9xpec unlock} num
+unlock str9 device.
+@end deffn
+
+@end deffn
-@itemize @bullet
-@item @b{str9xpec options_cmap} <@var{num}> <@option{bank0}|@option{bank1}>
-@cindex str9xpec options_cmap
-@*configure str9 boot bank.
-@item @b{str9xpec options_lvdthd} <@var{num}> <@option{2.4v}|@option{2.7v}>
-@cindex str9xpec options_lvdthd
-@*configure str9 lvd threshold.
-@item @b{str9xpec options_lvdsel} <@var{num}> <@option{vdd}|@option{vdd_vddq}>
-@cindex str9xpec options_lvdsel
-@*configure str9 lvd source.
-@item @b{str9xpec options_lvdwarn} <@var{bank}> <@option{vdd}|@option{vdd_vddq}>
-@cindex str9xpec options_lvdwarn
-@*configure str9 lvd reset warning source.
-@end itemize
@section mFlash
@subsection mFlash Configuration
@cindex mFlash Configuration
-@b{mflash bank} <@var{soc}> <@var{base}> <@var{RST pin}> <@var{target}>
-@cindex mflash bank
-@*Configures a mflash for <@var{soc}> host bank at
-<@var{base}>. Pin number format is dependent on host GPIO calling convention.
-Currently, mflash bank support s3c2440 and pxa270.
-(ex. of s3c2440) mflash <@var{RST pin}> is GPIO B1.
+@deffn {Config Command} {mflash bank} soc base RST_pin target
+Configures a mflash for @var{soc} host bank at
+address @var{base}.
+The pin number format depends on the host GPIO naming convention.
+Currently, the mflash driver supports s3c2440 and pxa270.
+
+Example for s3c2440 mflash where @var{RST pin} is GPIO B1:
@example
mflash bank s3c2440 0x10000000 1b 0
@end example
-(ex. of pxa270) mflash <@var{RST pin}> is GPIO 43.
+Example for pxa270 mflash where @var{RST pin} is GPIO 43:
@example
mflash bank pxa270 0x08000000 43 0
@end example
+@end deffn
@subsection mFlash commands
@cindex mFlash commands
-@itemize @bullet
-@item @b{mflash probe}
-@cindex mflash probe
-@*Probe mflash.
-@item @b{mflash write} <@var{num}> <@var{file}> <@var{offset}>
-@cindex mflash write
-@*Write the binary <@var{file}> to mflash bank <@var{num}>, starting at
-<@var{offset}> bytes from the beginning of the bank.
-@item @b{mflash dump} <@var{num}> <@var{file}> <@var{offset}> <@var{size}>
-@cindex mflash dump
-@*Dump <size> bytes, starting at <@var{offset}> bytes from the beginning of the <@var{num}> bank
-to a <@var{file}>.
-@item @b{mflash config pll} <@var{frequency}>
-@cindex mflash config pll
-@*Configure mflash pll. <@var{frequency}> is input frequency of mflash. The order is Hz.
+@deffn Command {mflash config pll} frequency
+Configure mflash PLL.
+The @var{frequency} is the mflash input frequency, in Hz.
Issuing this command will erase mflash's whole internal nand and write new pll.
After this command, mflash needs power-on-reset for normal operation.
If pll was newly configured, storage and boot(optional) info also need to be update.
-@item @b{mflash config boot}
-@cindex mflash config boot
-@*Configure bootable option. If bootable option is set, mflash offer the first 8 sectors
+@end deffn
+
+@deffn Command {mflash config boot}
+Configure bootable option.
+If bootable option is set, mflash offer the first 8 sectors
(4kB) for boot.
-@item @b{mflash config storage}
-@cindex mflash config storage
-@*Configure storage information. For the normal storage operation, this information must be
+@end deffn
+
+@deffn Command {mflash config storage}
+Configure storage information.
+For the normal storage operation, this information must be
written.
-@end itemize
+@end deffn
+
+@deffn Command {mflash dump} num filename offset size
+Dump @var{size} bytes, starting at @var{offset} bytes from the
+beginning of the bank @var{num}, to the file named @var{filename}.
+@end deffn
+
+@deffn Command {mflash probe}
+Probe mflash.
+@end deffn
+
+@deffn Command {mflash write} num filename offset
+Write the binary file @var{filename} to mflash bank @var{num}, starting at
+@var{offset} bytes from the beginning of the bank.
+@end deffn
@node NAND Flash Commands
@chapter NAND Flash Commands
status for each block.
@end deffn
-@deffn Command {nand raw_access} num <enable|disable>
+@deffn Command {nand raw_access} num (@option{enable}|@option{disable})
Sets or clears an flag affecting how page I/O is done.
The @var{num} parameter is the value shown by @command{nand list}.
@section Daemon Commands
-@subsection sleep [@var{msec}]
-@cindex sleep
-@*Wait for n milliseconds before resuming. Useful in connection with script files
-(@var{script} command and @var{target_script} configuration).
+@deffn Command sleep msec [@option{busy}]
+Wait for at least @var{msec} milliseconds before resuming.
+If @option{busy} is passed, busy-wait instead of sleeping.
+(This option is strongly discouraged.)
+Useful in connection with script files
+(@command{script} command and @command{target_name} configuration).
+@end deffn
-@subsection shutdown
-@cindex shutdown
-@*Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).
+@deffn Command shutdown
+Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).
+@end deffn
@anchor{debug_level}
-@subsection debug_level [@var{n}]
-@cindex debug_level
-@*Display or adjust debug level to n<0-3>
-
-@subsection fast [@var{enable|disable}]
-@cindex fast
-@*Default disabled. Set default behaviour of OpenOCD to be "fast and dangerous". For instance ARM7/9 DCC memory
-downloads and fast memory access will work if the JTAG interface isn't too fast and
-the core doesn't run at a too low frequency. Note that this option only changes the default
-and that the indvidual options, like DCC memory downloads, can be enabled and disabled
-individually.
+@deffn Command debug_level [n]
+@cindex message level
+Display debug level.
+If @var{n} (from 0..3) is provided, then set it to that level.
+This affects the kind of messages sent to the server log.
+Level 0 is error messages only;
+level 1 adds warnings;
+level 2 (the default) adds informational messages;
+and level 3 adds debugging messages.
+@end deffn
+
+@deffn Command fast (@option{enable}|@option{disable})
+Default disabled.
+Set default behaviour of OpenOCD to be "fast and dangerous".
+
+At this writing, this only affects the defaults for two ARM7/ARM9 parameters:
+fast memory access, and DCC downloads. Those parameters may still be
+individually overridden.
The target specific "dangerous" optimisation tweaking options may come and go
as more robust and user friendly ways are found to ensure maximum throughput
@example
openocd -c "fast enable" -c "interface dummy" -f target/str710.cfg
@end example
+@end deffn
-@subsection echo <@var{message}>
-@cindex echo
-@*Output message to stdio. e.g. echo "Programming - please wait"
-
-@subsection log_output <@var{file}>
-@cindex log_output
-@*Redirect logging to <file> (default: stderr)
+@deffn Command echo message
+Logs a message at "user" priority.
+Output @var{message} to stdout.
+@example
+echo "Downloading kernel -- please wait"
+@end example
+@end deffn
-@subsection script <@var{file}>
-@cindex script
-@*Execute commands from <file>
-See also: ``source [find FILENAME]''
+@deffn Command log_output [filename]
+Redirect logging to @var{filename};
+the initial log output channel is stderr.
+@end deffn
-@section Target state handling
-@subsection power <@var{on}|@var{off}>
-@cindex reg
-@*Turn power switch to target on/off.
-No arguments: print status.
-Not all interfaces support this.
-
-@subsection reg [@option{#}|@option{name}] [value]
-@cindex reg
-@*Access a single register by its number[@option{#}] or by its [@option{name}].
-No arguments: list all available registers for the current target.
-Number or name argument: display a register.
-Number or name and value arguments: set register value.
-
-@subsection poll [@option{on}|@option{off}]
-@cindex poll
-@*Poll the target for its current state. If the target is in debug mode, architecture
-specific information about the current state is printed. An optional parameter
-allows continuous polling to be enabled and disabled.
-
-@subsection halt [@option{ms}]
+@anchor{Target State handling}
+@section Target State handling
+@cindex reset
@cindex halt
-@*Send a halt request to the target and wait for it to halt for up to [@option{ms}] milliseconds.
-Default [@option{ms}] is 5 seconds if no arg given.
-Optional arg @option{ms} is a timeout in milliseconds. Using 0 as the [@option{ms}]
-will stop OpenOCD from waiting.
-
-@subsection wait_halt [@option{ms}]
-@cindex wait_halt
-@*Wait for the target to enter debug mode. Optional [@option{ms}] is
-a timeout in milliseconds. Default [@option{ms}] is 5 seconds if no
-arg is given.
-
-@subsection resume [@var{address}]
-@cindex resume
-@*Resume the target at its current code position, or at an optional address.
+@cindex target initialization
+
+In this section ``target'' refers to a CPU configured as
+shown earlier (@pxref{CPU Configuration}).
+These commands, like many, implicitly refer to
+a @dfn{current target} which is used to perform the
+various operations. The current target may be changed
+by using @command{targets} command with the name of the
+target which should become current.
+
+@deffn Command reg [(number|name) [value]]
+Access a single register by @var{number} or by its @var{name}.
+
+@emph{With no arguments}:
+list all available registers for the current target,
+showing number, name, size, value, and cache status.
+
+@emph{With number/name}: display that register's value.
+
+@emph{With both number/name and value}: set register's value.
+
+Cores may have surprisingly many registers in their
+Debug and trace infrastructure:
+
+@example
+> reg
+(0) r0 (/32): 0x0000D3C2 (dirty: 1, valid: 1)
+(1) r1 (/32): 0xFD61F31C (dirty: 0, valid: 1)
+(2) r2 (/32): 0x00022551 (dirty: 0, valid: 1)
+...
+(164) ETM_CONTEXTID_COMPARATOR_MASK (/32): \
+ 0x00000000 (dirty: 0, valid: 0)
+>
+@end example
+@end deffn
+
+@deffn Command halt [ms]
+@deffnx Command wait_halt [ms]
+The @command{halt} command first sends a halt request to the target,
+which @command{wait_halt} doesn't.
+Otherwise these behave the same: wait up to @var{ms} milliseconds,
+or 5 seconds if there is no parameter, for the target to halt
+(and enter debug mode).
+Using 0 as the @var{ms} parameter prevents OpenOCD from waiting.
+@end deffn
+
+@deffn Command resume [address]
+Resume the target at its current code position,
+or the optional @var{address} if it is provided.
OpenOCD will wait 5 seconds for the target to resume.
+@end deffn
-@subsection step [@var{address}]
-@cindex step
-@*Single-step the target at its current code position, or at an optional address.
+@deffn Command step [address]
+Single-step the target at its current code position,
+or the optional @var{address} if it is provided.
+@end deffn
@anchor{Reset Command}
-@subsection reset [@option{run}|@option{halt}|@option{init}]
-@cindex reset
-@*Perform a hard-reset. The optional parameter specifies what should
+@deffn Command reset
+@deffnx Command {reset run}
+@deffnx Command {reset halt}
+@deffnx Command {reset init}
+Perform as hard a reset as possible, using SRST if possible.
+@emph{All defined targets will be reset, and target
+events will fire during the reset sequence.}
+
+The optional parameter specifies what should
happen after the reset.
If there is no parameter, a @command{reset run} is executed.
The other options will not work on all systems.
@xref{Reset Configuration}.
+
@itemize @minus
-@item @b{run}
-@cindex reset run
-@*Let the target run.
-@item @b{halt}
-@cindex reset halt
-@*Immediately halt the target (works only with certain configurations).
-@item @b{init}
-@cindex reset init
-@*Immediately halt the target, and execute the reset script (works only with certain
-configurations)
+@item @b{run} Let the target run
+@item @b{halt} Immediately halt the target
+@item @b{init} Immediately halt the target, and execute the reset-init script
@end itemize
+@end deffn
-@subsection soft_reset_halt
-@cindex reset
-@*Requesting target halt and executing a soft reset. This is often used
+@deffn Command soft_reset_halt
+Requesting target halt and executing a soft reset. This is often used
when a target cannot be reset and halted. The target, after reset is
released begins to execute code. OpenOCD attempts to stop the CPU and
then sets the program counter back to the reset vector. Unfortunately
the code that was executed may have left the hardware in an unknown
state.
+@end deffn
+@section I/O Utilities
+
+These commands are available when
+OpenOCD is built with @option{--enable-ioutil}.
+They are mainly useful on embedded targets;
+PC type hosts have complementary tools.
+
+@emph{Note:} there are several more such commands.
+
+@deffn Command meminfo
+Display available RAM memory on OpenOCD host.
+Used in OpenOCD regression testing scripts.
+@end deffn
@anchor{Memory access}
@section Memory access commands
-@subsection meminfo
-display available RAM memory on OpenOCD host. Used in OpenOCD regression testing scripts. Mainly
-useful on embedded targets, PC type hosts have complimentary tools like Valgrind to address
-resource tracking problems.
-@subsection Memory peek/poke type commands
+@cindex memory access
+
These commands allow accesses of a specific size to the memory
system. Often these are used to configure the current target in some
-special way. For example - one may need to write certian values to the
+special way. For example - one may need to write certain values to the
SDRAM controller to enable SDRAM.
@enumerate
-@item To change the current target see the ``targets'' (plural) command
-@item In system level scripts these commands are deprecated, please use the TARGET object versions.
+@item Use the @command{targets} (plural) command
+to change the current target.
+@item In system level scripts these commands are deprecated.
+Please use their TARGET object siblings to avoid making assumptions
+about what TAP is the current target, or about MMU configuration.
@end enumerate
-@itemize @bullet
-@item @b{mdw} <@var{addr}> [@var{count}]
-@cindex mdw
-@*display memory words (32bit)
-@item @b{mdh} <@var{addr}> [@var{count}]
-@cindex mdh
-@*display memory half-words (16bit)
-@item @b{mdb} <@var{addr}> [@var{count}]
-@cindex mdb
-@*display memory bytes (8bit)
-@item @b{mww} <@var{addr}> <@var{value}>
-@cindex mww
-@*write memory word (32bit)
-@item @b{mwh} <@var{addr}> <@var{value}>
-@cindex mwh
-@*write memory half-word (16bit)
-@item @b{mwb} <@var{addr}> <@var{value}>
-@cindex mwb
-@*write memory byte (8bit)
-@end itemize
+@deffn Command mdw addr [count]
+@deffnx Command mdh addr [count]
+@deffnx Command 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 mww addr word
+@deffnx Command mwh addr halfword
+@deffnx Command 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{Image access}
@section Image loading commands
-@anchor{load_image}
-@subsection load_image
-@b{load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
-@cindex load_image
-@*Load image <@var{file}> to target memory at <@var{address}>
-@subsection fast_load_image
-@b{fast_load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
-@cindex fast_load_image
-@*Normally you should be using @b{load_image} or GDB load. However, for
+@cindex image loading
+@cindex image dumping
+
+@anchor{dump_image}
+@deffn Command {dump_image} filename address size
+Dump @var{size} bytes of target memory starting at @var{address} to the
+binary file named @var{filename}.
+@end deffn
+
+@deffn Command {fast_load}
+Loads an image stored in memory by @command{fast_load_image} to the
+current target. Must be preceeded by fast_load_image.
+@end deffn
+
+@deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
+Normally you should be using @command{load_image} or GDB load. However, for
testing purposes or when I/O overhead is significant(OpenOCD running on an embedded
host), storing the image in memory and uploading the image to the target
can be a way to upload e.g. multiple debug sessions when the binary does not change.
-Arguments are the same as @b{load_image}, but the image is stored in OpenOCD host
+Arguments are the same as @command{load_image}, but the image is stored in OpenOCD host
memory, i.e. does not affect target. This approach is also useful when profiling
target programming performance as I/O and target programming can easily be profiled
separately.
-@subsection fast_load
-@b{fast_load}
-@cindex fast_image
-@*Loads an image stored in memory by @b{fast_load_image} to the current target. Must be preceeded by fast_load_image.
-@anchor{dump_image}
-@subsection dump_image
-@b{dump_image} <@var{file}> <@var{address}> <@var{size}>
-@cindex dump_image
-@*Dump <@var{size}> bytes of target memory starting at <@var{address}> to a
-(binary) <@var{file}>.
-@subsection verify_image
-@b{verify_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
-@cindex verify_image
-@*Verify <@var{file}> against target memory starting at <@var{address}>.
+@end deffn
+
+@anchor{load_image}
+@deffn Command {load_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
+Load image from file @var{filename} to target memory at @var{address}.
+The file format may optionally be specified
+(@option{bin}, @option{ihex}, or @option{elf})
+@end deffn
+
+@deffn Command {verify_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
+Verify @var{filename} against target memory starting at @var{address}.
+The file format may optionally be specified
+(@option{bin}, @option{ihex}, or @option{elf})
This will first attempt a comparison using a CRC checksum, if this fails it will try a binary compare.
+@end deffn
-@section Breakpoint commands
-@cindex Breakpoint commands
-@itemize @bullet
-@item @b{bp} <@var{addr}> <@var{len}> [@var{hw}]
-@cindex bp
-@*set breakpoint <address> <length> [hw]
-@item @b{rbp} <@var{addr}>
-@cindex rbp
-@*remove breakpoint <adress>
-@item @b{wp} <@var{addr}> <@var{len}> <@var{r}|@var{w}|@var{a}> [@var{value}] [@var{mask}]
-@cindex wp
-@*set watchpoint <address> <length> <r/w/a> [value] [mask]
-@item @b{rwp} <@var{addr}>
-@cindex rwp
-@*remove watchpoint <adress>
-@end itemize
+@section Breakpoint and Watchpoint commands
+@cindex breakpoint
+@cindex watchpoint
-@section Misc Commands
-@cindex Other Target Commands
-@itemize
-@item @b{profile} <@var{seconds}> <@var{gmon.out}>
+CPUs often make debug modules accessible through JTAG, with
+hardware support for a handful of code breakpoints and data
+watchpoints.
+In addition, CPUs almost always support software breakpoints.
-Profiling samples the CPU's program counter as quickly as possible, which is useful for non-intrusive stochastic profiling.
+@deffn Command {bp} [address len [@option{hw}]]
+With no parameters, lists all active breakpoints.
+Else sets a breakpoint on code execution starting
+at @var{address} for @var{length} bytes.
+This is a software breakpoint, unless @option{hw} is specified
+in which case it will be a hardware breakpoint.
+@end deffn
-@end itemize
+@deffn Command {rbp} address
+Remove the breakpoint at @var{address}.
+@end deffn
+
+@deffn Command {rwp} address
+Remove data watchpoint on @var{address}
+@end deffn
+
+@deffn Command {wp} [address len [(@option{r}|@option{w}|@option{a}) [value [mask]]]]
+With no parameters, lists all active watchpoints.
+Else sets a data watchpoint on data from @var{address} for @var{length} bytes.
+The watch point is an "access" watchpoint unless
+the @option{r} or @option{w} parameter is provided,
+defining it as respectively a read or write watchpoint.
+If a @var{value} is provided, that value is used when determining if
+the watchpoint should trigger. The value may be first be masked
+using @var{mask} to mark ``don't care'' fields.
+@end deffn
+
+@section Misc Commands
+@cindex profiling
+
+@deffn Command {profile} seconds filename
+Profiling samples the CPU's program counter as quickly as possible,
+which is useful for non-intrusive stochastic profiling.
+Saves up to 10000 sampines in @file{filename} using ``gmon.out'' format.
+@end deffn
@node Architecture and Core Commands
@chapter Architecture and Core Commands
@section ARMv4 and ARMv5 Architecture
-@cindex ARMv4 specific commands
-@cindex ARMv5 specific commands
+@cindex ARMv4
+@cindex ARMv5
These commands are specific to ARM architecture v4 and v5,
including all ARM7 or ARM9 systems and Intel XScale.
They are available in addition to other core-specific
commands that may be available.
-@deffn Command {armv4_5 core_state} [arm|thumb]
+@deffn Command {armv4_5 core_state} [@option{arm}|@option{thumb}]
Displays the core_state, optionally changing it to process
either @option{arm} or @option{thumb} instructions.
The target may later be resumed in the currently set core_state.
@end deffn
@deffn Command {armv4_5 reg}
-Display a list of all banked core registers, fetching the current value from every
+Display a table of all banked core registers, fetching the current value from every
core mode if necessary. OpenOCD versions before rev. 60 didn't fetch the current
register value.
@end deffn
@subsection ARM7 and ARM9 specific commands
-@cindex ARM7 specific commands
-@cindex ARM9 specific commands
+@cindex ARM7
+@cindex ARM9
These commands are specific to ARM7 and ARM9 cores, like ARM7TDMI, ARM720T,
ARM9TDMI, ARM920T or ARM926EJ-S.
They are available in addition to the ARMv4/5 commands,
and any other core-specific commands that may be available.
-@deffn Command {arm7_9 dbgrq} (enable|disable)
+@deffn Command {arm7_9 dbgrq} (@option{enable}|@option{disable})
Control use of the EmbeddedIce DBGRQ signal to force entry into debug mode,
instead of breakpoints. This should be
safe for all but ARM7TDMI--S cores (like Philips LPC).
@end deffn
-@deffn Command {arm7_9 dcc_downloads} (enable|disable)
+@deffn Command {arm7_9 dcc_downloads} (@option{enable}|@option{disable})
@cindex DCC
Control the use of the debug communications channel (DCC) to write larger (>128 byte)
amounts of memory. DCC downloads offer a huge speed increase, but might be
@end deffn
@anchor{arm7_9 fast_memory_access}
-@deffn Command {arm7_9 fast_memory_access} (enable|disable)
+@deffn Command {arm7_9 fast_memory_access} (@option{enable}|@option{disable})
Enable or disable memory writes and reads that don't check completion of
the operation. This provides a huge speed increase, especially with USB JTAG
cables (FT2232), but might be unsafe if used with targets running at very low
The write goes directly to the CPU, bypassing the register cache.
@end deffn
-@deffn {Debug Command} {arm7_9 write_xpsr} word (0|1)
+@deffn {Debug Command} {arm7_9 write_xpsr} word (@option{0}|@option{1})
@emph{This is intended for use while debugging OpenOCD; you probably
shouldn't use it.}
In both cases, this bypasses the register cache.
@end deffn
-@deffn {Debug Command} {arm7_9 write_xpsr_im8} byte rotate (0|1)
+@deffn {Debug Command} {arm7_9 write_xpsr_im8} byte rotate (@option{0}|@option{1})
@emph{This is intended for use while debugging OpenOCD; you probably
shouldn't use it.}
@end deffn
@subsection ARM720T specific commands
-@cindex ARM720T specific commands
+@cindex ARM720T
These commands are available to ARM720T based CPUs,
which are implementations of the ARMv4T architecture
@end deffn
@subsection ARM9TDMI specific commands
-@cindex ARM9TDMI specific commands
+@cindex ARM9TDMI
Many ARM9-family CPUs are built around ARM9TDMI integer cores,
or processors resembling ARM9TDMI, and can use these commands.
Such cores include the ARM920T, ARM926EJ-S, and ARM966.
-@deffn Command {arm9tdmi vector_catch} (all|none|list)
+@deffn Command {arm9tdmi vector_catch} (@option{all}|@option{none}|list)
Catch arm9 interrupt vectors, can be @option{all}, @option{none},
or a list with one or more of the following:
@option{reset} @option{undef} @option{swi} @option{pabt} @option{dabt} @option{reserved}
@end deffn
@subsection ARM920T specific commands
-@cindex ARM920T specific commands
+@cindex ARM920T
These commands are available to ARM920T based CPUs,
which are implementations of the ARMv4T architecture
Dump the content of the ITLB and DTLB to a file named @file{filename}.
@end deffn
-@deffn Command {arm920t virt2phys} @var{va}
+@deffn Command {arm920t virt2phys} va
Translate a virtual address @var{va} to a physical address
and display the result.
@end deffn
-@subsection ARM926EJ-S specific commands
-@cindex ARM926EJ-S specific commands
+@subsection ARM926ej-s specific commands
+@cindex ARM926ej-s
-These commands are available to ARM926EJ-S based CPUs,
+These commands are available to ARM926ej-s based CPUs,
which are implementations of the ARMv5TEJ architecture
based on the ARM9EJ-S integer core.
They are available in addition to the ARMv4/5, ARM7/ARM9,
and ARM9TDMI commands.
+The Feroceon cores also support these commands, although
+they are not built from ARM926ej-s designs.
+
@deffn Command {arm926ejs cache_info}
Print information about the caches found.
@end deffn
at the specified physical address @var{addr}.
@end deffn
-@deffn Command {arm926ejs virt2phys} @var{va}
+@deffn Command {arm926ejs virt2phys} va
Translate a virtual address @var{va} to a physical address
and display the result.
@end deffn
@subsection ARM966E specific commands
-@cindex ARM966E specific commands
+@cindex ARM966E
These commands are available to ARM966 based CPUs,
which are implementations of the ARMv5TE architecture.
@end deffn
@subsection XScale specific commands
-@cindex XScale specific commands
+@cindex XScale
These commands are available to XScale based CPUs,
which are implementations of the ARMv5TE architecture.
Changes the address used for the specified target's debug handler.
@end deffn
-@deffn Command {xscale dcache} (enable|disable)
+@deffn Command {xscale dcache} (@option{enable}|@option{disable})
Enables or disable the CPU's data cache.
@end deffn
Dumps the raw contents of the trace buffer to @file{filename}.
@end deffn
-@deffn Command {xscale icache} (enable|disable)
+@deffn Command {xscale icache} (@option{enable}|@option{disable})
Enables or disable the CPU's instruction cache.
@end deffn
-@deffn Command {xscale mmu} (enable|disable)
+@deffn Command {xscale mmu} (@option{enable}|@option{disable})
Enables or disable the CPU's memory management unit.
@end deffn
-@deffn Command {xscale trace_buffer} (enable|disable) [fill [n] | wrap]
+@deffn Command {xscale trace_buffer} (@option{enable}|@option{disable}) [@option{fill} [n] | @option{wrap}]
Enables or disables the trace buffer,
and controls how it is emptied.
@end deffn
@end deffn
@section ARMv6 Architecture
+@cindex ARMv6
@subsection ARM11 specific commands
-@cindex ARM11 specific commands
+@cindex ARM11
@deffn Command {arm11 mcr} p1 p2 p3 p4 p5
Read coprocessor register
@end deffn
@section ARMv7 Architecture
+@cindex ARMv7
@subsection ARMv7 Debug Access Port (DAP) specific commands
-@cindex ARMv7 Debug Access Port (DAP) specific commands
+@cindex Debug Access Port
+@cindex DAP
These commands are specific to ARM architecture v7 Debug Access Port (DAP),
included on cortex-m3 and cortex-a8 systems.
They are available in addition to other core-specific commands that may be available.
@deffn Command {dap info} [num]
-Displays dap info for ap [num], default currently selected AP.
+Displays dap info for ap @var{num}, defaulting to the currently selected AP.
@end deffn
@deffn Command {dap apsel} [num]
-Select a different AP [num] (default 0).
+Select AP @var{num}, defaulting to 0.
@end deffn
@deffn Command {dap apid} [num]
-Displays id reg from AP [num], default currently selected AP.
+Displays id register from AP @var{num},
+defaulting to the currently selected AP.
@end deffn
@deffn Command {dap baseaddr} [num]
-Displays debug base address from AP [num], default currently selected AP.
+Displays debug base address from AP @var{num},
+defaulting to the currently selected AP.
@end deffn
@deffn Command {dap memaccess} [value]
Displays the number of extra tck for mem-ap memory bus access [0-255].
-If value is defined, first assigns that.
+If @var{value} is defined, first assigns that.
@end deffn
@subsection Cortex-M3 specific commands
-@cindex Cortex-M3 specific commands
+@cindex Cortex-M3
-@deffn Command {cortex_m3 maskisr} (on|off)
+@deffn Command {cortex_m3 maskisr} (@option{on}|@option{off})
Control masking (disabling) interrupts during target step/resume.
@end deffn
depends on CONFIG_DEBUG_LL) which uses this mechanism to
deliver messages before a serial console can be activated.
-@deffn Command {target_request debugmsgs} [enable|disable|charmsg]
+@deffn Command {target_request debugmsgs} [@option{enable}|@option{disable}|@option{charmsg}]
Displays current handling of target DCC message requests.
These messages may be sent to the debugger while the target is running.
The optional @option{enable} and @option{charmsg} parameters
@node JTAG Commands
@chapter JTAG Commands
@cindex JTAG Commands
-Generally most people will not use the bulk of these commands. They
-are mostly used by the OpenOCD developers or those who need to
-directly manipulate the JTAG taps.
-
-In general these commands control JTAG taps at a very low level. For
-example if you need to control a JTAG Route Controller (i.e.: the
-OMAP3530 on the Beagle Board has one) you might use these commands in
-a script or an event procedure.
-@section Commands
-@cindex Commands
+Most general purpose JTAG commands have been presented earlier.
+(@xref{JTAG Speed}, @ref{Reset Configuration}, and @ref{TAP Declaration}.)
+Lower level JTAG commands, as presented here,
+may be needed to work with targets which require special
+attention during operations such as reset or initialization.
+
+To use these commands you will need to understand some
+of the basics of JTAG, including:
+
@itemize @bullet
-@item @b{scan_chain}
-@cindex scan_chain
-@*Print current scan chain configuration.
-@item @b{jtag_reset} <@var{trst}> <@var{srst}>
-@cindex jtag_reset
-@*Toggle reset lines.
-@item @b{endstate} <@var{tap_state}>
-@cindex endstate
-@*Finish JTAG operations in <@var{tap_state}>.
-@item @b{runtest} <@var{num_cycles}>
-@cindex runtest
-@*Move to Run-Test/Idle, and execute <@var{num_cycles}>
-@item @b{statemove} [@var{tap_state}]
-@cindex statemove
-@*Move to current endstate or [@var{tap_state}]
-@item @b{irscan} <@var{device}> <@var{instr}> [@var{dev2}] [@var{instr2}] ...
-@cindex irscan
-@*Execute IR scan <@var{device}> <@var{instr}> [@var{dev2}] [@var{instr2}] ...
-@item @b{drscan} <@var{device}> [@var{dev2}] [@var{var2}] ...
-@cindex drscan
-@*Execute DR scan <@var{device}> [@var{dev2}] [@var{var2}] ...
-@item @b{verify_ircapture} <@option{enable}|@option{disable}>
-@cindex verify_ircapture
-@*Verify value captured during Capture-IR. Default is enabled.
-@item @b{var} <@var{name}> [@var{num_fields}|@var{del}] [@var{size1}] ...
-@cindex var
-@*Allocate, display or delete variable <@var{name}> [@var{num_fields}|@var{del}] [@var{size1}] ...
-@item @b{field} <@var{var}> <@var{field}> [@var{value}|@var{flip}]
-@cindex field
-Display/modify variable field <@var{var}> <@var{field}> [@var{value}|@var{flip}].
+@item A JTAG scan chain consists of a sequence of individual TAP
+devices such as a CPUs.
+@item Control operations involve moving each TAP through the same
+standard state machine (in parallel)
+using their shared TMS and clock signals.
+@item Data transfer involves shifting data through the chain of
+instruction or data registers of each TAP, writing new register values
+while the reading previous ones.
+@item Data register sizes are a function of the instruction active in
+a given TAP, while instruction register sizes are fixed for each TAP.
+All TAPs support a BYPASS instruction with a single bit data register.
+@item The way OpenOCD differentiates between TAP devices is by
+shifting different instructions into (and out of) their instruction
+registers.
@end itemize
-@section Tap states
-@cindex Tap states
-Available tap_states are:
+@section Low Level JTAG Commands
+
+These commands are used by developers who need to access
+JTAG instruction or data registers, possibly controlling
+the order of TAP state transitions.
+If you're not debugging OpenOCD internals, or bringing up a
+new JTAG adapter or a new type of TAP device (like a CPU or
+JTAG router), you probably won't need to use these commands.
+
+@deffn Command {drscan} tap [numbits value]+ [@option{-endstate} tap_state]
+Loads the data register of @var{tap} with a series of bit fields
+that specify the entire register.
+Each field is @var{numbits} bits long with
+a numeric @var{value} (hexadecimal encouraged).
+The return value holds the original value of each
+of those fields.
+
+For example, a 38 bit number might be specified as one
+field of 32 bits then one of 6 bits.
+@emph{For portability, never pass fields which are more
+than 32 bits long. Many OpenOCD implementations do not
+support 64-bit (or larger) integer values.}
+
+All TAPs other than @var{tap} must be in BYPASS mode.
+The single bit in their data registers does not matter.
+
+When @var{tap_state} is specified, the JTAG state machine is left
+in that state.
+For example @sc{drpause} might be specified, so that more
+instructions can be issued before re-entering the @sc{run/idle} state.
+If the end state is not specified, the @sc{run/idle} state is entered.
+
+@quotation Warning
+OpenOCD does not record information about data register lengths,
+so @emph{it is important that you get the bit field lengths right}.
+Remember that different JTAG instructions refer to different
+data registers, which may have different lengths.
+Moreover, those lengths may not be fixed;
+the SCAN_N instruction can change the length of
+the register accessed by the INTEST instruction
+(by connecting a different scan chain).
+@end quotation
+@end deffn
+
+@deffn Command {flush_count}
+Returns the number of times the JTAG queue has been flushed.
+This may be used for performance tuning.
+
+For example, flushing a queue over USB involves a
+minimum latency, often several milliseconds, which does
+not change with the amount of data which is written.
+You may be able to identify performance problems by finding
+tasks which waste bandwidth by flushing small transfers too often,
+instead of batching them into larger operations.
+@end deffn
+
+@deffn Command {irscan} [tap instruction]+ [@option{-endstate} tap_state]
+For each @var{tap} listed, loads the instruction register
+with its associated numeric @var{instruction}.
+(The number of bits in that instruction may be displayed
+using the @command{scan_chain} command.)
+For other TAPs, a BYPASS instruction is loaded.
+
+When @var{tap_state} is specified, the JTAG state machine is left
+in that state.
+For example @sc{irpause} might be specified, so the data register
+can be loaded before re-entering the @sc{run/idle} state.
+If the end state is not specified, the @sc{run/idle} state is entered.
+
+@quotation Note
+OpenOCD currently supports only a single field for instruction
+register values, unlike data register values.
+For TAPs where the instruction register length is more than 32 bits,
+portable scripts currently must issue only BYPASS instructions.
+@end quotation
+@end deffn
+
+@deffn Command {jtag_reset} trst srst
+Set values of reset signals.
+The @var{trst} and @var{srst} parameter values may be
+@option{0}, indicating that reset is inactive (pulled or driven high),
+or @option{1}, indicating it is active (pulled or driven low).
+The @command{reset_config} command should already have been used
+to configure how the board and JTAG adapter treat these two
+signals, and to say if either signal is even present.
+@xref{Reset Configuration}.
+@end deffn
+
+@deffn Command {runtest} @var{num_cycles}
+Move to the @sc{run/idle} state, and execute at least
+@var{num_cycles} of the JTAG clock (TCK).
+Instructions often need some time
+to execute before they take effect.
+@end deffn
+
+@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 tms_sequence (short|long)
+@c ... temporary, debug-only, probably gone before 0.2 ships
+
+@deffn Command {verify_ircapture} (@option{enable}|@option{disable})
+Verify values captured during @sc{ircapture} and returned
+during IR scans. Default is enabled, but this can be
+overridden by @command{verify_jtag}.
+@end deffn
+
+@deffn Command {verify_jtag} (@option{enable}|@option{disable})
+Enables verification of DR and IR scans, to help detect
+programming errors. For IR scans, @command{verify_ircapture}
+must also be enabled.
+Default is enabled.
+@end deffn
+
+@section TAP state names
+@cindex TAP state names
+
+The @var{tap_state} names used by OpenOCD in the @command{drscan},
+and @command{irscan} commands are:
+
@itemize @bullet
-@item @b{RESET}
-@cindex RESET
-@item @b{IDLE}
-@cindex IDLE
+@item @b{RESET} ... should act as if TRST were active
+@item @b{RUN/IDLE} ... don't assume this always means IDLE
@item @b{DRSELECT}
-@cindex DRSELECT
@item @b{DRCAPTURE}
-@cindex DRCAPTURE
-@item @b{DRSHIFT}
-@cindex DRSHIFT
+@item @b{DRSHIFT} ... TDI/TDO shifting through the data register
@item @b{DREXIT1}
-@cindex DREXIT1
-@item @b{DRPAUSE}
-@cindex DRPAUSE
+@item @b{DRPAUSE} ... data register ready for update or more shifting
@item @b{DREXIT2}
-@cindex DREXIT2
@item @b{DRUPDATE}
-@cindex DRUPDATE
@item @b{IRSELECT}
-@cindex IRSELECT
@item @b{IRCAPTURE}
-@cindex IRCAPTURE
-@item @b{IRSHIFT}
-@cindex IRSHIFT
+@item @b{IRSHIFT} ... TDI/TDO shifting through the instruction register
@item @b{IREXIT1}
-@cindex IREXIT1
-@item @b{IRPAUSE}
-@cindex IRPAUSE
+@item @b{IRPAUSE} ... instruction register ready for update or more shifting
@item @b{IREXIT2}
-@cindex IREXIT2
@item @b{IRUPDATE}
-@cindex IRUPDATE
@end itemize
+Note that only six of those states are fully ``stable'' in the
+face of TMS fixed (usually low)
+and a free-running JTAG clock. For all the
+others, the next TCK transition changes to a new state.
+
+@itemize @bullet
+@item From @sc{drshift} and @sc{irshift}, clock transitions will
+produce side effects by changing register contents. The values
+to be latched in upcoming @sc{drupdate} or @sc{irupdate} states
+may not be as expected.
+@item @sc{run/idle}, @sc{drpause}, and @sc{irpause} are reasonable
+choices after @command{drscan} or @command{irscan} commands,
+since they are free of JTAG side effects.
+However, @sc{run/idle} may have side effects that appear at other
+levels, such as advancing the ARM9E-S instruction pipeline.
+Consult the documentation for the TAP(s) you are working with.
+@end itemize
@node TFTP
@chapter TFTP
@item @b{arm7_9 fast_writes}
@cindex arm7_9 fast_writes
@*Use @command{arm7_9 fast_memory_access} instead.
+@item @b{endstate}
+@cindex endstate
+@*An buggy old command that would not really work since background polling would wipe out the global endstate
@xref{arm7_9 fast_memory_access}.
@item @b{arm7_9 force_hw_bkpts}
@*Use @command{gdb_breakpoint_override} instead. Note that GDB will use hardware breakpoints
else that needs to write to controller registers, perhaps for setting
up DRAM and loading it with code.
-@item @b{JTAG Tap Order} JTAG tap order - command order
+@anchor{FAQ TAP Order}
+@item @b{JTAG TAP Order} Do I have to declare the TAPS in some
+particular order?
+
+Yes; whenever you have more than one, you must declare them in
+the same order used by the hardware.
-Many newer devices have multiple JTAG taps. For example: ST
-Microsystems STM32 chips have two taps, a ``boundary scan tap'' and
-``Cortex-M3'' tap. Example: The STM32 reference manual, Document ID:
+Many newer devices have multiple JTAG TAPs. For example: ST
+Microsystems STM32 chips have two TAPs, a ``boundary scan TAP'' and
+``Cortex-M3'' TAP. Example: The STM32 reference manual, Document ID:
RM0008, Section 26.5, Figure 259, page 651/681, the ``TDI'' pin is
-connected to the boundary scan tap, which then connects to the
-Cortex-M3 tap, which then connects to the TDO pin.
+connected to the boundary scan TAP, which then connects to the
+Cortex-M3 TAP, which then connects to the TDO pin.
Thus, the proper order for the STM32 chip is: (1) The Cortex-M3, then
-(2) The boundary scan tap. If your board includes an additional JTAG
+(2) The boundary scan TAP. If your board includes an additional JTAG
chip in the scan chain (for example a Xilinx CPLD or FPGA) you could
place it before or after the STM32 chip in the chain. For example:
Code Review / openocd.git / blobdiff