* TFTP:: TFTP
* GDB and OpenOCD:: Using GDB and OpenOCD
* Tcl Scripting API:: Tcl Scripting API
-* Upgrading:: Deprecated/Removed Commands
* FAQ:: Frequently Asked Questions
* Tcl Crash Course:: Tcl Crash Course
* License:: GNU Free Documentation License
@uref{git://openocd.git.sourceforge.net/gitroot/openocd/openocd}
+You may prefer to use a mirror and the HTTP protocol:
+
+@uref{http://repo.or.cz/r/openocd.git}
+
With standard GIT tools, use @command{git clone} to initialize
a local repository, and @command{git pull} to update it.
There are also gitweb pages letting you browse the repository
@uref{http://openocd.git.sourceforge.net/git/gitweb.cgi?p=openocd/openocd}
+@uref{http://repo.or.cz/w/openocd.git}
+
The @file{README} file contains the instructions for building the project
from the repository or a snapshot.
That's because there is no external memory (flash, DDR RAM), and
the board differences are encapsulated by application code.
+@item Maybe you don't know yet what your board looks like to JTAG.
+Once you know the @file{interface.cfg} file to use, you may
+need help from OpenOCD to discover what's on the board.
+Once you find the TAPs, you can just search for appropriate
+configuration files ... or write your own, from the bottom up.
+@xref{Autoprobing}.
+
@item You can often reuse some standard config files but
need to write a few new ones, probably a @file{board.cfg} file.
You will be using commands described later in this User's Guide,
that the @code{reset-init} event handler does.
@item
-Likewise, the @command{arm9tdmi vector_catch} command (or
+Likewise, the @command{arm9 vector_catch} command (or
@cindex vector_catch
its siblings @command{xscale vector_catch}
and @command{cortex_m3 vector_catch}) can be a timesaver
You should find the following directories under @t{$(INSTALLDIR)/scripts},
with files including the ones listed here.
Use them as-is where you can; or as models for new files.
-
@itemize @bullet
@item @file{interface} ...
think JTAG Dongle. Files that configure JTAG adapters go here.
Because this is so very board-specific, and chip-specific, no examples
are included here.
Instead, look at the board config files distributed with OpenOCD.
-If you have a boot loader, its source code may also be useful.
+If you have a boot loader, its source code will help; so will
+configuration files for other JTAG tools
+(@pxref{Translating Configuration Files}).
@end quotation
Some of this code could probably be shared between different boards.
looks (in part) like this:
@example
-jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf \
- -expected-id $_CPUTAPID
+jtag newtap $_CHIPNAME cpu -irlen 4 -expected-id $_CPUTAPID
@end example
A board with two such at91sam7 chips would be able
@item pxa270 - again - CS0 flash - it goes in the board file.
@end itemize
+@anchor{Translating Configuration Files}
+@section Translating Configuration Files
+@cindex translation
+If you have a configuration file for another hardware debugger
+or toolset (Abatron, BDI2000, BDI3000, CCS,
+Lauterbach, Segger, Macraigor, etc.), translating
+it into OpenOCD syntax is often quite straightforward. The most tricky
+part of creating a configuration script is oftentimes the reset init
+sequence where e.g. PLLs, DRAM and the like is set up.
+
+One trick that you can use when translating is to write small
+Tcl procedures to translate the syntax into OpenOCD syntax. This
+can avoid manual translation errors and make it easier to
+convert other scripts later on.
+
+Example of transforming quirky arguments to a simple search and
+replace job:
+
+@example
+# Lauterbach syntax(?)
+#
+# Data.Set c15:0x042f %long 0x40000015
+#
+# OpenOCD syntax when using procedure below.
+#
+# setc15 0x01 0x00050078
+
+proc setc15 @{regs value@} @{
+ global TARGETNAME
+
+ echo [format "set p15 0x%04x, 0x%08x" $regs $value]
+
+ mcr 15 [expr ($regs>>12)&0x7] \
+ [expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] \
+ [expr ($regs>>8)&0x7] $value
+@}
+@end example
+
+
+
@node Daemon Configuration
@chapter Daemon Configuration
@cindex initialization
After it leaves this stage, configuration commands may no
longer be issued.
+@section Entering the Run Stage
+
The first thing OpenOCD does after leaving the configuration
stage is to verify that it can talk to the scan chain
(list of TAPs) which has been configured.
fast, and not providing the right IDCODE values for the TAPs
on the scan chain.
+Once OpenOCD has entered the run stage, a number of commands
+become available.
+A number of these relate to the debug targets you may have declared.
+For example, the @command{mww} command will not be available until
+a target has been successfuly instantiated.
+If you want to use those commands, you may need to force
+entry to the run stage.
+
@deffn {Config Command} init
This command terminates the configuration stage and
-enters the normal command mode. This can be useful to add commands to
-the startup scripts and commands such as resetting the target,
+enters the run stage. This helps when you need to have
+the startup scripts manage tasks such as resetting the target,
programming flash, etc. To reset the CPU upon startup, add "init" and
"reset" at the end of the config script or at the end of the OpenOCD
command line using the @option{-c} command line switch.
the memory read/write commands. This includes @command{nand probe}.
@end deffn
+@deffn {Overridable Procedure} jtag_init
+This is invoked at server startup to verify that it can talk
+to the scan chain (list of TAPs) which has been configured.
+
+The default implementation first tries @command{jtag arp_init},
+which uses only a lightweight JTAG reset before examining the
+scan chain.
+If that fails, it tries again, using a harder reset
+from the overridable procedure @command{init_reset}.
+
+Implementations must have verified the JTAG scan chain before
+they return.
+This is done by calling @command{jtag arp_init}
+(or @command{jtag arp_init-reset}).
+@end deffn
+
@anchor{TCP/IP Ports}
@section TCP/IP Ports
@cindex TCP port
breakpoints if the memory map has been set up for flash regions.
@end deffn
-@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 @option{resume}.
-@end deffn
-
@anchor{gdb_flash_program}
@deffn {Config Command} gdb_flash_program (@option{enable}|@option{disable})
Set to @option{enable} to cause OpenOCD to program the flash memory when a
you may encounter a problem.
@end deffn
+@deffn Command {parport_toggling_time} [nanoseconds]
+Displays how many nanoseconds the hardware needs to toggle TCK;
+the parport driver uses this value to obey the
+@command{jtag_khz} configuration.
+When the optional @var{nanoseconds} parameter is given,
+that setting is changed before displaying the current value.
+
+The default setting should work reasonably well on commodity PC hardware.
+However, you may want to calibrate for your specific hardware.
+@quotation Tip
+To measure the toggling time with a logic analyzer or a digital storage
+oscilloscope, follow the procedure below:
+@example
+> parport_toggling_time 1000
+> jtag_khz 500
+@end example
+This sets the maximum JTAG clock speed of the hardware, but
+the actual speed probably deviates from the requested 500 kHz.
+Now, measure the time between the two closest spaced TCK transitions.
+You can use @command{runtest 1000} or something similar to generate a
+large set of samples.
+Update the setting to match your measurement:
+@example
+> parport_toggling_time <measured nanoseconds>
+@end example
+Now the clock speed will be a better match for @command{jtag_khz rate}
+commands given in OpenOCD scripts and event handlers.
+
+You can do something similar with many digital multimeters, but note
+that you'll probably need to run the clock continuously for several
+seconds before it decides what clock rate to show. Adjust the
+toggling time up or down until the measured clock rate is a good
+match for the jtag_khz rate you specified; be conservative.
+@end quotation
+@end deffn
+
@deffn {Config Command} {parport_write_on_exit} (on|off)
This will configure the parallel driver to write a known
cable-specific value to the parallel interface on exiting OpenOCD
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.)
+Many systems treat combined assertion of SRST and TRST as a
+trigger for a harder reset than SRST alone.
+Such custom reset handling is discussed later in this chapter.
@end itemize
There can also be other issues.
@section Commands for Handling Resets
+@deffn {Command} jtag_nsrst_assert_width milliseconds
+Minimum amount of time (in milliseconds) OpenOCD should wait
+after asserting nSRST (active-low system reset) before
+allowing it to be deasserted.
+@end deffn
+
@deffn {Command} jtag_nsrst_delay milliseconds
How long (in milliseconds) OpenOCD should wait after deasserting
nSRST (active-low system reset) before starting new JTAG operations.
probably have hardware debouncing, implying you should use this.
@end deffn
+@deffn {Command} jtag_ntrst_assert_width milliseconds
+Minimum amount of time (in milliseconds) OpenOCD should wait
+after asserting nTRST (active-low JTAG TAP reset) before
+allowing it to be deasserted.
+@end deffn
+
@deffn {Command} jtag_ntrst_delay milliseconds
How long (in milliseconds) OpenOCD should wait after deasserting
nTRST (active-low JTAG TAP reset) before starting new JTAG operations.
@quotation Tip
If your board provides SRST and/or TRST through the JTAG connector,
-you must declare that or else those signals will not be used.
+you must declare that so those signals can be used.
@end quotation
@item
@end itemize
@end deffn
+@section Custom Reset Handling
+@cindex events
+
+OpenOCD has several ways to help support the various reset
+mechanisms provided by chip and board vendors.
+The commands shown in the previous section give standard parameters.
+There are also @emph{event handlers} associated with TAPs or Targets.
+Those handlers are Tcl procedures you can provide, which are invoked
+at particular points in the reset sequence.
+
+After configuring those mechanisms, you might still
+find your board doesn't start up or reset correctly.
+For example, maybe it needs a slightly different sequence
+of SRST and/or TRST manipulations, because of quirks that
+the @command{reset_config} mechanism doesn't address;
+or asserting both might trigger a stronger reset, which
+needs special attention.
+
+Experiment with lower level operations, such as @command{jtag_reset}
+and the @command{jtag arp_*} operations shown here,
+to find a sequence of operations that works.
+@xref{JTAG Commands}.
+When you find a working sequence, it can be used to override
+@command{jtag_init}, which fires during OpenOCD startup
+(@pxref{Configuration Stage});
+or @command{init_reset}, which fires during reset processing.
+
+You might also want to provide some project-specific reset
+schemes. For example, on a multi-target board the standard
+@command{reset} command would reset all targets, but you
+may need the ability to reset only one target at time and
+thus want to avoid using the board-wide SRST signal.
+
+@deffn {Overridable Procedure} init_reset mode
+This is invoked near the beginning of the @command{reset} command,
+usually to provide as much of a cold (power-up) reset as practical.
+By default it is also invoked from @command{jtag_init} if
+the scan chain does not respond to pure JTAG operations.
+The @var{mode} parameter is the parameter given to the
+low level reset command (@option{halt},
+@option{init}, or @option{run}), @option{setup},
+or potentially some other value.
+
+The default implementation just invokes @command{jtag arp_init-reset}.
+Replacements will normally build on low level JTAG
+operations such as @command{jtag_reset}.
+Operations here must not address individual TAPs
+(or their associated targets)
+until the JTAG scan chain has first been verified to work.
+
+Implementations must have verified the JTAG scan chain before
+they return.
+This is done by calling @command{jtag arp_init}
+(or @command{jtag arp_init-reset}).
+@end deffn
+
+@deffn Command {jtag arp_init}
+This validates the scan chain using just the four
+standard JTAG signals (TMS, TCK, TDI, TDO).
+It starts by issuing a JTAG-only reset.
+Then it performs checks to verify that the scan chain configuration
+matches the TAPs it can observe.
+Those checks include checking IDCODE values for each active TAP,
+and verifying the length of their instruction registers using
+TAP @code{-ircapture} and @code{-irmask} values.
+If these tests all pass, TAP @code{setup} events are
+issued to all TAPs with handlers for that event.
+@end deffn
+
+@deffn Command {jtag arp_init-reset}
+This uses TRST and SRST to try resetting
+everything on the JTAG scan chain
+(and anything else connected to SRST).
+It then invokes the logic of @command{jtag arp_init}.
+@end deffn
+
@node TAP Declaration
@chapter TAP Declaration
A command like this would declare one tap and name it @code{chip1.cpu}:
@example
-jtag newtap chip1 cpu -irlen 7 -ircapture 0x01 -irmask 0x55
+jtag newtap chip1 cpu -irlen 4 -expected-id 0x3ba00477
@end example
Each target configuration file lists the TAPs provided
ID code could appear (for example, multiple versions).
Specify @var{number} as zero to suppress warnings about IDCODE
values that were found but not included in the list.
+
+Provide this value if at all possible, since it lets OpenOCD
+tell when the scan chain it sees isn't right. These values
+are provided in vendors' chip documentation, usually a technical
+reference manual. Sometimes you may need to probe the JTAG
+hardware to find these values.
+@xref{Autoprobing}.
@item @code{-ircapture} @var{NUMBER}
@*The bit pattern loaded by the TAP into the JTAG shift register
on entry to the @sc{ircapture} state, such as 0x01.
JTAG requires the two LSBs of this value to be 01.
By default, @code{-ircapture} and @code{-irmask} are set
-up to verify that two-bit value; but you may provide
-additional bits, if you know them.
+up to verify that two-bit value. You may provide
+additional bits, if you know them, or indicate that
+a TAP doesn't conform to the JTAG specification.
@item @code{-irmask} @var{NUMBER}
@*A mask used with @code{-ircapture}
to verify that instruction scans work correctly.
@section Other TAP commands
-@c @deffn Command {jtag arp_init-reset}
-@c ... more or less "toggle TRST ... and SRST too, what the heck"
-
@deffn Command {jtag cget} dotted.name @option{-event} name
@deffnx Command {jtag configure} dotted.name @option{-event} name string
At this writing this TAP attribute
@end quotation
@end deffn
+@anchor{Autoprobing}
+@section Autoprobing
+@cindex autoprobe
+@cindex JTAG autoprobe
+
+TAP configuration is the first thing that needs to be done
+after interface and reset configuration. Sometimes it's
+hard finding out what TAPs exist, or how they are identified.
+Vendor documentation is not always easy to find and use.
+
+To help you get past such problems, OpenOCD has a limited
+@emph{autoprobing} ability to look at the scan chain, doing
+a @dfn{blind interrogation} and then reporting the TAPs it finds.
+To use this mechanism, start the OpenOCD server with only data
+that configures your JTAG interface, and arranges to come up
+with a slow clock (many devices don't support fast JTAG clocks
+right when they come out of reset).
+
+For example, your @file{openocd.cfg} file might have:
+
+@example
+source [find interface/olimex-arm-usb-tiny-h.cfg]
+reset_config trst_and_srst
+jtag_rclk 8
+@end example
+
+When you start the server without any TAPs configured, it will
+attempt to autoconfigure the TAPs. There are two parts to this:
+
+@enumerate
+@item @emph{TAP discovery} ...
+After a JTAG reset (sometimes a system reset may be needed too),
+each TAP's data registers will hold the contents of either the
+IDCODE or BYPASS register.
+If JTAG communication is working, OpenOCD will see each TAP,
+and report what @option{-expected-id} to use with it.
+@item @emph{IR Length discovery} ...
+Unfortunately JTAG does not provide a reliable way to find out
+the value of the @option{-irlen} parameter to use with a TAP
+that is discovered.
+If OpenOCD can discover the length of a TAP's instruction
+register, it will report it.
+Otherwise you may need to consult vendor documentation, such
+as chip data sheets or BSDL files.
+@end enumerate
+
+In many cases your board will have a simple scan chain with just
+a single device. Here's what OpenOCD reported with one board
+that's a bit more complex:
+
+@example
+clock speed 8 kHz
+There are no enabled taps. AUTO PROBING MIGHT NOT WORK!!
+AUTO auto0.tap - use "jtag newtap auto0 tap -expected-id 0x2b900f0f ..."
+AUTO auto1.tap - use "jtag newtap auto1 tap -expected-id 0x07926001 ..."
+AUTO auto2.tap - use "jtag newtap auto2 tap -expected-id 0x0b73b02f ..."
+AUTO auto0.tap - use "... -irlen 4"
+AUTO auto1.tap - use "... -irlen 4"
+AUTO auto2.tap - use "... -irlen 6"
+no gdb ports allocated as no target has been specified
+@end example
+
+Given that information, you should be able to either find some existing
+config files to use, or create your own. If you create your own, you
+would configure from the bottom up: first a @file{target.cfg} file
+with these TAPs, any targets associated with them, and any on-chip
+resources; then a @file{board.cfg} with off-chip resources, clocking,
+and so forth.
+
@node CPU Configuration
@chapter CPU Configuration
@cindex GDB target
@itemize @bullet
@item @code{arm11} -- this is a generation of ARMv6 cores
-@item @code{arm720t} -- this is an ARMv4 core
+@item @code{arm720t} -- this is an ARMv4 core with an MMU
@item @code{arm7tdmi} -- this is an ARMv4 core
-@item @code{arm920t} -- this is an ARMv5 core
-@item @code{arm926ejs} -- this is an ARMv5 core
+@item @code{arm920t} -- this is an ARMv5 core with an MMU
+@item @code{arm926ejs} -- this is an ARMv5 core with an MMU
@item @code{arm966e} -- this is an ARMv5 core
@item @code{arm9tdmi} -- this is an ARMv4 core
@item @code{avr} -- implements Atmel's 8-bit AVR instruction set.
(Support for this is preliminary and incomplete.)
-@item @code{cortex_a8} -- this is an ARMv7 core
+@item @code{cortex_a8} -- this is an ARMv7 core with an MMU
@item @code{cortex_m3} -- this is an ARMv7 core, supporting only the
compact Thumb2 instruction set. It supports one variant:
@itemize @minus
This is fixed in Fury Rev B, DustDevil Rev B, Tempest; these revisions will
be detected and the normal reset behaviour used.
@end itemize
+@item @code{dragonite} -- resembles arm966e
@item @code{fa526} -- resembles arm920 (w/o Thumb)
@item @code{feroceon} -- resembles arm926
@item @code{mips_m4k} -- a MIPS core. This supports one variant:
For example, the beginning of an SRAM block is likely to
be used by most build systems, but the end is often unused.
-@item @code{-work-area-size} @var{size} -- specify/set the work area
+@item @code{-work-area-size} @var{size} -- specify work are size,
+in bytes. The same size applies regardless of whether its physical
+or virtual address is being used.
@item @code{-work-area-phys} @var{address} -- set the work area
base @var{address} to be used when no MMU is active.
@item @code{-work-area-virt} @var{address} -- set the work area
base @var{address} to be used when an MMU is active.
+@emph{Do not specify a value for this except on targets with an MMU.}
+The value should normally correspond to a static mapping for the
+@code{-work-area-phys} address, set up by the current operating system.
@end itemize
@end deffn
@end ignore
@item @b{reset-assert-pre}
@* Issued as part of @command{reset} processing
-after SRST and/or TRST were activated and deactivated,
+after @command{reset_init} was triggered
but before SRST alone is re-asserted on the tap.
@item @b{reset-assert-post}
@* Issued as part of @command{reset} processing
the target clocks are fully set up.)
@item @b{reset-start}
@* Issued as part of @command{reset} processing
-before either SRST or TRST are activated.
+before @command{reset_init} is called.
-This is the most robust place to switch to a low JTAG clock rate, if
-SRST disables PLLs needed to use a fast clock.
+This is the most robust place to use @command{jtag_rclk}
+or @command{jtag_khz} to switch to a low JTAG clock rate,
+when reset disables PLLs needed to use a fast clock.
@ignore
@item @b{reset-wait-pos}
@* Currently not used
@end deffn
@anchor{flash write_image}
-@deffn Command {flash write_image} [erase] filename [offset] [type]
+@deffn Command {flash write_image} [erase] [unlock] filename [offset] [type]
Write the image @file{filename} to the current target's flash bank(s).
A relocation @var{offset} may be specified, in which case it is added
to the base address for each section in the image.
@option{elf} (ELF file), @option{s19} (Motorola s19).
@option{mem}, or @option{builder}.
The relevant flash sectors will be erased prior to programming
-if the @option{erase} parameter is given.
-The flash bank to use is inferred from the @var{address} of
+if the @option{erase} parameter is given. If @option{unlock} is
+provided, then the flash banks are unlocked before erase and
+program. The flash bank to use is inferred from the @var{address} of
each image segment.
@end deffn
@end deffn
@anchor{Flash Driver List}
-@section Flash Drivers, Options, and Commands
+@section Flash Driver List
As noted above, the @command{flash bank} command requires a driver name,
and allows driver-specific options and behaviors.
Some drivers also activate driver-specific commands.
Frequently the first such chip is used to boot the system.
Your board's @code{reset-init} handler might need to
configure additional chip selects using other commands (like: @command{mww} to
-configure a bus and its timings) , or
+configure a bus and its timings), or
perhaps configure a GPIO pin that controls the ``write protect'' pin
on the flash chip.
The CFI driver can use a target-specific working area to significantly
flash bank cfi 0x00000000 0x01000000 2 2 $_TARGETNAME
flash bank cfi 0x01000000 0x01000000 2 2 $_TARGETNAME
@end example
+
+To configure one bank of 32 MBytes
+built from two sixteen bit (two byte) wide parts wired in parallel
+to create a thirty-two bit (four byte) bus with doubled throughput:
+
+@example
+flash bank cfi 0x00000000 0x02000000 2 4 $_TARGETNAME
+@end example
+
@c "cfi part_id" disabled
@end deffn
@end itemize
@end deffn
+@deffn Command {nand verify} num filename offset [option...]
+@cindex NAND verification
+@cindex NAND programming
+Verify the binary data in the file has been programmed to the
+specified NAND device, starting at the specified offset.
+The @var{num} parameter is the value shown by @command{nand list}.
+
+Use a complete path name for @var{filename}, so you don't depend
+on the directory used to start the OpenOCD server.
+
+The @var{offset} must be an exact multiple of the device's page size.
+All data in the file will be read and compared to the contents of the
+flash, assuming it doesn't run past the end of the device.
+As with @command{nand write}, only full pages are verified, so any extra
+space in the last page will be filled with 0xff bytes.
+
+The same @var{options} accepted by @command{nand write},
+and the file will be processed similarly to produce the buffers that
+can be compared against the contents produced from @command{nand dump}.
+
+@b{NOTE:} This will not work when the underlying NAND controller
+driver's @code{write_page} routine must update the OOB with a
+hardward-computed ECC before the data is written. This limitation may
+be removed in a future release.
+@end deffn
+
@section Other NAND commands
@cindex NAND other commands
@end deffn
@anchor{NAND Driver List}
-@section NAND Drivers, Options, and Commands
+@section NAND Driver List
As noted above, the @command{nand device} command allows
driver-specific options and behaviors.
Some controllers also activate controller-specific commands.
about what TAP is the current target, or about MMU configuration.
@end enumerate
-@deffn Command mdw addr [count]
-@deffnx Command mdh addr [count]
-@deffnx Command mdb addr [count]
+@deffn Command mdw [phys] addr [count]
+@deffnx Command mdh [phys] addr [count]
+@deffnx Command mdb [phys] addr [count]
Display contents of address @var{addr}, as
32-bit words (@command{mdw}), 16-bit halfwords (@command{mdh}),
or 8-bit bytes (@command{mdb}).
+When the current target has an MMU which is present and active,
+@var{addr} is interpreted as a virtual address.
+Otherwise, or if the optional @var{phys} flag is specified,
+@var{addr} is interpreted as a physical address.
If @var{count} is specified, displays that many units.
(If you want to manipulate the data instead of displaying it,
see the @code{mem2array} primitives.)
@end deffn
-@deffn Command mww addr word
-@deffnx Command mwh addr halfword
-@deffnx Command mwb addr byte
+@deffn Command mww [phys] addr word
+@deffnx Command mwh [phys] addr halfword
+@deffnx Command mwb [phys] addr byte
Writes the specified @var{word} (32 bits),
-@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
+@var{halfword} (16 bits), or @var{byte} (8-bit) value,
at the specified address @var{addr}.
+When the current target has an MMU which is present and active,
+@var{addr} is interpreted as a virtual address.
+Otherwise, or if the optional @var{phys} flag is specified,
+@var{addr} is interpreted as a physical address.
@end deffn
This is a software breakpoint, unless @option{hw} is specified
in which case it will be a hardware breakpoint.
-(@xref{arm9tdmi vector_catch}, or @pxref{xscale vector_catch},
+(@xref{arm9 vector_catch}, or @pxref{xscale vector_catch},
for similar mechanisms that do not consume hardware breakpoints.)
@end deffn
@quotation Issues
ETM support may be buggy, and at least some @command{etm config}
parameters should be detected by asking the ETM for them.
+
+ETM trigger events could also implement a kind of complex
+hardware breakpoint, much more powerful than the simple
+watchpoint hardware exported by EmbeddedICE modules.
+@emph{Such breakpoints can be triggered even when using the
+dummy trace port driver}.
+
It seems like a GDB hookup should be possible,
-as well as triggering trace on specific events
+as well as tracing only during specific states
(perhaps @emph{handling IRQ 23} or @emph{calls foo()}).
+
There should be GUI tools to manipulate saved trace data and help
analyse it in conjunction with the source code.
It's unclear how much of a common interface is shared
with the current XScale trace support, or should be
shared with eventual Nexus-style trace module support.
+
At this writing (September 2009) only ARM7 and ARM9 support
for ETM modules is available. The code should be able to
work with some newer cores; but not all of them support
Declares the ETM associated with @var{target}, and associates it
with a given trace port @var{driver}. @xref{Trace Port Drivers}.
-Several of the parameters must reflect the trace port configuration.
-The @var{width} must be either 4, 8, or 16.
-The @var{mode} must be @option{normal}, @option{multiplexted},
-or @option{demultiplexted}.
+Several of the parameters must reflect the trace port capabilities,
+which are a function of silicon capabilties (exposed later
+using @command{etm info}) and of what hardware is connected to
+that port (such as an external pod, or ETB).
+The @var{width} must be either 4, 8, or 16,
+except with ETMv3.0 and newer modules which may also
+support 1, 2, 24, 32, 48, and 64 bit widths.
+(With those versions, @command{etm info} also shows whether
+the selected port width and mode are supported.)
+
+The @var{mode} must be @option{normal}, @option{multiplexed},
+or @option{demultiplexed}.
The @var{clocking} must be @option{half} or @option{full}.
+@quotation Warning
+With ETMv3.0 and newer, the bits set with the @var{mode} and
+@var{clocking} parameters both control the mode.
+This modified mode does not map to the values supported by
+previous ETM modules, so this syntax is subject to change.
+@end quotation
+
@quotation Note
You can see the ETM registers using the @command{reg} command.
Not all possible registers are present in every ETM.
@deffn Command {etm info}
Displays information about the current target's ETM.
+This includes resource counts from the @code{ETM_CONFIG} register,
+as well as silicon capabilities (except on rather old modules).
+from the @code{ETM_SYS_CONFIG} register.
@end deffn
@deffn Command {etm status}
@end deffn
-@section ARMv4 and ARMv5 Architecture
-@cindex ARMv4
-@cindex ARMv5
+@section Generic ARM
+@cindex ARM
-These commands are specific to ARM architecture v4 and v5,
-including all ARM7 or ARM9 systems and Intel XScale.
+These commands should be available on all ARM processors.
They are available in addition to other core-specific
commands that may be available.
-@deffn Command {armv4_5 core_state} [@option{arm}|@option{thumb}]
+@deffn Command {arm core_state} [@option{arm}|@option{thumb}]
Displays the core_state, optionally changing it to process
either @option{arm} or @option{thumb} instructions.
The target may later be resumed in the currently set core_state.
that is not currently supported in OpenOCD.)
@end deffn
-@deffn Command {armv4_5 disassemble} address [count [@option{thumb}]]
+@deffn Command {arm disassemble} address [count [@option{thumb}]]
@cindex disassemble
Disassembles @var{count} instructions starting at @var{address}.
If @var{count} is not specified, a single instruction is disassembled.
those instructions are not currently understood by OpenOCD.)
@end deffn
-@deffn Command {armv4_5 reg}
+@deffn Command {arm reg}
Display a table of all banked core registers, fetching the current value from every
core mode if necessary. OpenOCD versions before rev. 60 didn't fetch the current
register value.
else if a @var{value} is provided, that value is written to that register.
@end deffn
-@deffn Command {arm720t mdw_phys} addr [count]
-@deffnx Command {arm720t mdh_phys} addr [count]
-@deffnx Command {arm720t mdb_phys} addr [count]
-Display contents of physical address @var{addr}, as
-32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
-or 8-bit bytes (@command{mdb_phys}).
-If @var{count} is specified, displays that many units.
-@end deffn
-
-@deffn Command {arm720t mww_phys} addr word
-@deffnx Command {arm720t mwh_phys} addr halfword
-@deffnx Command {arm720t mwb_phys} addr byte
-Writes the specified @var{word} (32 bits),
-@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
-at the specified physical address @var{addr}.
-@end deffn
-
-@deffn Command {arm720t virt2phys} va
-Translate a virtual address @var{va} to a physical address
-and display the result.
-@end deffn
-
@subsection ARM9 specific commands
@cindex ARM9
integer processors.
Such cores include the ARM920T, ARM926EJ-S, and ARM966.
-For historical reasons, one command shared by these cores starts
-with the @command{arm9tdmi} prefix.
-This is true even for ARM9E based processors, which implement the
-ARMv5TE architecture instead of ARMv4T.
-
@c 9-june-2009: tried this on arm920t, it didn't work.
@c no-params always lists nothing caught, and that's how it acts.
+@c 23-oct-2009: doesn't work _consistently_ ... as if the ICE
+@c versions have different rules about when they commit writes.
-@anchor{arm9tdmi vector_catch}
-@deffn Command {arm9tdmi vector_catch} [@option{all}|@option{none}|list]
+@anchor{arm9 vector_catch}
+@deffn Command {arm9 vector_catch} [@option{all}|@option{none}|list]
@cindex vector_catch
Vector Catch hardware provides a sort of dedicated breakpoint
for hardware events such as reset, interrupt, and abort.
@option{all} of the hardware vectors,
@option{none} of them,
or a list with one or more of the following:
-@option{reset} @option{undef} @option{swi} @option{pabt} @option{dabt} @option{reserved}
+@option{reset} @option{undef} @option{swi} @option{pabt} @option{dabt}
@option{irq} @option{fiq}.
@end deffn
or using zero if no other address is not provided.
@end deffn
-@deffn Command {arm920t mdw_phys} addr [count]
-@deffnx Command {arm920t mdh_phys} addr [count]
-@deffnx Command {arm920t mdb_phys} addr [count]
-Display contents of physical address @var{addr}, as
-32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
-or 8-bit bytes (@command{mdb_phys}).
-If @var{count} is specified, displays that many units.
-@end deffn
-
-@deffn Command {arm920t mww_phys} addr word
-@deffnx Command {arm920t mwh_phys} addr halfword
-@deffnx Command {arm920t mwb_phys} addr byte
-Writes the specified @var{word} (32 bits),
-@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
-at the specified physical address @var{addr}.
-@end deffn
-
@deffn Command {arm920t read_cache} filename
Dump the content of ICache and DCache to a file named @file{filename}.
@end deffn
Dump the content of the ITLB and DTLB to a file named @file{filename}.
@end deffn
-@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
Else that register is read and displayed.
@end deffn
-@deffn Command {arm926ejs mdw_phys} addr [count]
-@deffnx Command {arm926ejs mdh_phys} addr [count]
-@deffnx Command {arm926ejs mdb_phys} addr [count]
-Display contents of physical address @var{addr}, as
-32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
-or 8-bit bytes (@command{mdb_phys}).
-If @var{count} is specified, displays that many units.
-@end deffn
-
-@deffn Command {arm926ejs mww_phys} addr word
-@deffnx Command {arm926ejs mwh_phys} addr halfword
-@deffnx Command {arm926ejs mwb_phys} addr byte
-Writes the specified @var{word} (32 bits),
-@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
-at the specified physical address @var{addr}.
-@end deffn
-
-@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
@subsection ARM11 specific commands
@cindex ARM11
-@deffn Command {arm11 mcr} pX opc1 CRn CRm opc2 value
-Write @var{value} to a coprocessor @var{pX} register
-passing parameters @var{CRn},
-@var{CRm}, opcodes @var{opc1} and @var{opc2},
-and the MCR instruction.
-(The difference beween this and the MCR2 instruction is
-one bit in the encoding, effecively a fifth parameter.)
-@end deffn
-
@deffn Command {arm11 memwrite burst} [value]
Displays the value of the memwrite burst-enable flag,
-which is enabled by default.
+which is enabled by default. Burst writes are only used
+for memory writes larger than 1 word. Single word writes
+are likely to be from reset init scripts and those writes
+are often to non-memory locations which could easily have
+many wait states, which could easily break burst writes.
If @var{value} is defined, first assigns that.
@end deffn
If @var{value} is defined, first assigns that.
@end deffn
-@deffn Command {arm11 mrc} pX opc1 CRn CRm opc2
-Read a coprocessor @var{pX} register passing parameters @var{CRn},
-@var{CRm}, opcodes @var{opc1} and @var{opc2},
-and the MRC instruction.
-(The difference beween this and the MRC2 instruction is
-one bit in the encoding, effecively a fifth parameter.)
-Displays the result.
-@end deffn
-
-@deffn Command {arm11 no_increment} [value]
-Displays the value of the flag controlling whether
-some read or write operations increment the pointer
-(the default behavior) or not (acting like a FIFO).
-If @var{value} is defined, first assigns that.
-@end deffn
-
@deffn Command {arm11 step_irq_enable} [value]
Displays the value of the flag controlling whether
IRQs are enabled during single stepping;
to configure how the board and JTAG adapter treat these two
signals, and to say if either signal is even present.
@xref{Reset Configuration}.
+
+Note that TRST is specially handled.
+It actually signifies JTAG's @sc{reset} state.
+So if the board doesn't support the optional TRST signal,
+or it doesn't support it along with the specified SRST value,
+JTAG reset is triggered with TMS and TCK signals
+instead of the TRST signal.
+And no matter how that JTAG reset is triggered, once
+the scan chain enters @sc{reset} with TRST inactive,
+TAP @code{post-reset} events are delivered to all TAPs
+with handlers for that event.
+@end deffn
+
+@deffn Command {pathmove} start_state [next_state ...]
+Start by moving to @var{start_state}, which
+must be one of the @emph{stable} states.
+Unless it is the only state given, this will often be the
+current state, so that no TCK transitions are needed.
+Then, in a series of single state transitions
+(conforming to the JTAG state machine) shift to
+each @var{next_state} in sequence, one per TCK cycle.
+The final state must also be stable.
@end deffn
@deffn Command {runtest} @var{num_cycles}
@end deffn
@c tms_sequence (short|long)
-@c ... temporary, debug-only, probably gone before 0.2 ships
+@c ... temporary, debug-only, other than USBprog bug workaround...
@deffn Command {verify_ircapture} (@option{enable}|@option{disable})
Verify values captured during @sc{ircapture} and returned
during IR scans. Default is enabled, but this can be
overridden by @command{verify_jtag}.
+This flag is ignored when validating JTAG chain configuration.
@end deffn
@deffn Command {verify_jtag} (@option{enable}|@option{disable})
@cindex TAP state names
The @var{tap_state} names used by OpenOCD in the @command{drscan},
-and @command{irscan} commands are:
+@command{irscan}, and @command{pathmove} commands are the same
+as those used in SVF boundary scan documents, except that
+SVF uses @sc{idle} instead of @sc{run/idle}.
@itemize @bullet
-@item @b{RESET} ... should act as if TRST were active
-@item @b{RUN/IDLE} ... don't assume this always means IDLE
+@item @b{RESET} ... @emph{stable} (with TMS high);
+acts as if TRST were pulsed
+@item @b{RUN/IDLE} ... @emph{stable}; don't assume this always means IDLE
@item @b{DRSELECT}
@item @b{DRCAPTURE}
-@item @b{DRSHIFT} ... TDI/TDO shifting through the data register
+@item @b{DRSHIFT} ... @emph{stable}; TDI/TDO shifting
+through the data register
@item @b{DREXIT1}
-@item @b{DRPAUSE} ... data register ready for update or more shifting
+@item @b{DRPAUSE} ... @emph{stable}; data register ready
+for update or more shifting
@item @b{DREXIT2}
@item @b{DRUPDATE}
@item @b{IRSELECT}
@item @b{IRCAPTURE}
-@item @b{IRSHIFT} ... TDI/TDO shifting through the instruction register
+@item @b{IRSHIFT} ... @emph{stable}; TDI/TDO shifting
+through the instruction register
@item @b{IREXIT1}
-@item @b{IRPAUSE} ... instruction register ready for update or more shifting
+@item @b{IRPAUSE} ... @emph{stable}; instruction register ready
+for update or more shifting
@item @b{IREXIT2}
@item @b{IRUPDATE}
@end itemize
@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
+@item @sc{run/idle} may have side effects that appear at non-JTAG
levels, such as advancing the ARM9E-S instruction pipeline.
Consult the documentation for the TAP(s) you are working with.
@end itemize
messages are logged for comments and some retries.
@end deffn
+The OpenOCD sources also include two utility scripts
+for working with XSVF; they are not currently installed
+after building the software.
+You may find them useful:
+
+@itemize
+@item @emph{svf2xsvf} ... converts SVF files into the extended XSVF
+syntax understood by the @command{xsvf} command; see notes below.
+@item @emph{xsvfdump} ... converts XSVF files into a text output format;
+understands the OpenOCD extensions.
+@end itemize
+
+The input format accepts a handful of non-standard extensions.
+These include three opcodes corresponding to SVF extensions
+from Lattice Semiconductor (LCOUNT, LDELAY, LDSR), and
+two opcodes supporting a more accurate translation of SVF
+(XTRST, XWAITSTATE).
+If @emph{xsvfdump} shows a file is using those opcodes, it
+probably will not be usable with other XSVF tools.
+
+
@node TFTP
@chapter TFTP
@cindex TFTP
@section OpenOCD specific Global Variables
-@subsection HostOS
-
Real Tcl has ::tcl_platform(), and platform::identify, and many other
-variables. JimTCL, as implemented in OpenOCD creates $HostOS which
+variables. JimTCL, as implemented in OpenOCD creates $ocd_HOSTOS which
holds one of the following values:
@itemize @bullet
is jim, not real tcl).
@end quotation
-@node Upgrading
-@chapter Deprecated/Removed Commands
-@cindex Deprecated/Removed Commands
-Certain OpenOCD commands have been deprecated or
-removed during the various revisions.
-
-Upgrade your scripts as soon as possible.
-These descriptions for old commands may be removed
-a year after the command itself was removed.
-This means that in January 2010 this chapter may
-become much shorter.
-
-@itemize @bullet
-@item @b{arm7_9 fast_writes}
-@cindex arm7_9 fast_writes
-@*Use @command{arm7_9 fast_memory_access} instead.
-@xref{arm7_9 fast_memory_access}.
-@item @b{endstate}
-@cindex endstate
-@*An buggy old command that would not really work since background polling would wipe out the global endstate
-@item @b{arm7_9 force_hw_bkpts}
-@*Use @command{gdb_breakpoint_override} instead. Note that GDB will use hardware breakpoints
-for flash if the GDB memory map has been set up(default when flash is declared in
-target configuration). @xref{gdb_breakpoint_override}.
-@item @b{arm7_9 sw_bkpts}
-@*On by default. @xref{gdb_breakpoint_override}.
-@item @b{daemon_startup}
-@*this config option has been removed, simply adding @option{init} and @option{reset halt} to
-the end of your config script will give the same behaviour as using @option{daemon_startup reset}
-and @option{target cortex_m3 little reset_halt 0}.
-@item @b{dump_binary}
-@*use @option{dump_image} command with same args. @xref{dump_image}.
-@item @b{flash erase}
-@*use @option{flash erase_sector} command with same args. @xref{flash erase_sector}.
-@item @b{flash write}
-@*use @option{flash write_bank} command with same args. @xref{flash write_bank}.
-@item @b{flash write_binary}
-@*use @option{flash write_bank} command with same args. @xref{flash write_bank}.
-@item @b{flash auto_erase}
-@*use @option{flash write_image} command passing @option{erase} as the first parameter. @xref{flash write_image}.
-
-@item @b{jtag_device}
-@*use the @command{jtag newtap} command, converting from positional syntax
-to named prefixes, and naming the TAP.
-@xref{jtag newtap}.
-Note that if you try to use the old command, a message will tell you the
-right new command to use; and that the fourth parameter in the old syntax
-was never actually used.
-@example
-OLD: jtag_device 8 0x01 0xe3 0xfe
-NEW: jtag newtap CHIPNAME TAPNAME \
- -irlen 8 -ircapture 0x01 -irmask 0xe3
-@end example
-
-@item @b{jtag_speed} value
-@*@xref{JTAG Speed}.
-Usually, a value of zero means maximum
-speed. The actual effect of this option depends on the JTAG interface used.
-@itemize @minus
-@item wiggler: maximum speed / @var{number}
-@item ft2232: 6MHz / (@var{number}+1)
-@item amt jtagaccel: 8 / 2**@var{number}
-@item jlink: maximum speed in kHz (0-12000), 0 will use RTCK
-@item rlink: 24MHz / @var{number}, but only for certain values of @var{number}
-@comment end speed list.
-@end itemize
-
-@item @b{load_binary}
-@*use @option{load_image} command with same args. @xref{load_image}.
-@item @b{run_and_halt_time}
-@*This command has been removed for simpler reset behaviour, it can be simulated with the
-following commands:
-@smallexample
-reset run
-sleep 100
-halt
-@end smallexample
-@item @b{target} <@var{type}> <@var{endian}> <@var{jtag-position}>
-@*use the create subcommand of @option{target}.
-@item @b{target_script} <@var{target#}> <@var{eventname}> <@var{scriptname}>
-@*use <@var{target_name}> configure -event <@var{eventname}> "script <@var{scriptname}>"
-@item @b{working_area}
-@*use the @option{configure} subcommand of @option{target} to set the work-area-virt, work-area-phy, work-area-size, and work-area-backup properties of the target.
-@end itemize
-
@node FAQ
@chapter FAQ
@cindex faq
Code Review / openocd.git / blobdiff