* GDB and OpenOCD:: Using GDB and OpenOCD
* Tcl Scripting API:: Tcl Scripting API
* Upgrading:: Deprecated/Removed Commands
-* Target Library:: Target Library
* FAQ:: Frequently Asked Questions
* Tcl Crash Course:: Tcl Crash Course
* License:: GNU Free Documentation License
The resources in this chapter are available for developers wishing to explore
or expand the OpenOCD source code.
-@section OpenOCD Subversion Repository
+@section OpenOCD GIT Repository
-You can download the current SVN version with an SVN client of your
-choice from the following repositories:
+During the 0.3.x release cycle, OpenOCD switched from Subversion to
+a GIT repository hosted at SourceForge. The repository URL is:
- @uref{svn://svn.berlios.de/openocd/trunk}
+@uref{git://openocd.git.sourceforge.net/gitroot/openocd/openocd}
-or
+You may prefer to use a mirror and the HTTP protocol:
- @uref{http://svn.berlios.de/svnroot/repos/openocd/trunk}
+@uref{http://repo.or.cz/r/openocd.git}
-Using the SVN command line client, you can use the following command to
-fetch the latest version (make sure there is no (non-svn) directory
-called "openocd" in the current directory):
+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
+with a web browser, or download arbitrary snapshots without
+needing a GIT client:
- svn checkout svn://svn.berlios.de/openocd/trunk openocd
+@uref{http://openocd.git.sourceforge.net/git/gitweb.cgi?p=openocd/openocd}
-If you prefer GIT based tools, the @command{git-svn} package works too:
+@uref{http://repo.or.cz/w/openocd.git}
- git svn clone -s svn://svn.berlios.de/openocd
-
-The ``README'' file contains the instructions for building the project
-from the repository.
+The @file{README} file contains the instructions for building the project
+from the repository or a snapshot.
Developers that want to contribute patches to the OpenOCD system are
-@b{strongly} encouraged to base their work off of the most recent trunk
-revision. Patches created against older versions may require additional
+@b{strongly} encouraged to work against mainline.
+Patches created against older versions may require additional
work from their submitter in order to be updated for newer releases.
@section Doxygen Developer Manual
-During the development of the 0.2.0 release, the OpenOCD project began
+During the 0.2.x release cycle, the OpenOCD project began
providing a Doxygen reference manual. This document contains more
technical information about the software internals, development
processes, and similar documentation:
This document is a work-in-progress, but contributions would be welcome
to fill in the gaps. All of the source files are provided in-tree,
-listed in the Doxyfile configuration in the top of the repository trunk.
+listed in the Doxyfile configuration in the top of the source tree.
@section OpenOCD Developer Mailing List
@uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
-All drivers developers are enouraged to also subscribe to the list of
-SVN commits to keep pace with the ongoing changes:
-
-@uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
+Discuss and submit patches to this list.
+The @file{PATCHES} file contains basic information about how
+to prepare patches.
@node JTAG Hardware Dongles
One might re-flash the board with a specific firmware version.
Another might set up a particular debugging or run-time environment.
+@quotation Important
+At this writing (October 2009) the command line method has
+problems with how it treats variables.
+For example, after @option{-c "set VAR value"}, or doing the
+same in a script, the variable @var{VAR} will have no value
+that can be tested in a later script.
+@end quotation
+
Here we will focus on the simpler solution: one user config
file, including basic configuration plus any TCL procedures
to simplify your work.
needs to get a new board working smoothly.
It provides guidelines for creating those files.
-You should find the following directories under @t{$(INSTALLDIR)/scripts}:
-
+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.
+@example
+$ ls interface
+arm-jtag-ew.cfg hitex_str9-comstick.cfg oocdlink.cfg
+arm-usb-ocd.cfg icebear.cfg openocd-usb.cfg
+at91rm9200.cfg jlink.cfg parport.cfg
+axm0432.cfg jtagkey2.cfg parport_dlc5.cfg
+calao-usb-a9260-c01.cfg jtagkey.cfg rlink.cfg
+calao-usb-a9260-c02.cfg jtagkey-tiny.cfg sheevaplug.cfg
+calao-usb-a9260.cfg luminary.cfg signalyzer.cfg
+chameleon.cfg luminary-icdi.cfg stm32-stick.cfg
+cortino.cfg luminary-lm3s811.cfg turtelizer2.cfg
+dummy.cfg olimex-arm-usb-ocd.cfg usbprog.cfg
+flyswatter.cfg olimex-jtag-tiny.cfg vsllink.cfg
+$
+@end example
@item @file{board} ...
think Circuit Board, PWA, PCB, they go by many names. Board files
-contain initialization items that are specific to a board. For
+contain initialization items that are specific to a board.
+They reuse target configuration files, since the same
+microprocessor chips are used on many boards,
+but support for external parts varies widely. For
example, the SDRAM initialization sequence for the board, or the type
of external flash and what address it uses. Any initialization
sequence to enable that external flash or SDRAM should be found in the
board file. Boards may also contain multiple targets: two CPUs; or
-a CPU and an FPGA or CPLD.
+a CPU and an FPGA.
+@example
+$ ls board
+arm_evaluator7t.cfg keil_mcb1700.cfg
+at91rm9200-dk.cfg keil_mcb2140.cfg
+at91sam9g20-ek.cfg linksys_nslu2.cfg
+atmel_at91sam7s-ek.cfg logicpd_imx27.cfg
+atmel_at91sam9260-ek.cfg mini2440.cfg
+atmel_sam3u_ek.cfg olimex_LPC2378STK.cfg
+crossbow_tech_imote2.cfg olimex_lpc_h2148.cfg
+csb337.cfg olimex_sam7_ex256.cfg
+csb732.cfg olimex_sam9_l9260.cfg
+digi_connectcore_wi-9c.cfg olimex_stm32_h103.cfg
+dm355evm.cfg omap2420_h4.cfg
+dm365evm.cfg osk5912.cfg
+dm6446evm.cfg pic-p32mx.cfg
+eir.cfg propox_mmnet1001.cfg
+ek-lm3s1968.cfg pxa255_sst.cfg
+ek-lm3s3748.cfg sheevaplug.cfg
+ek-lm3s811.cfg stm3210e_eval.cfg
+ek-lm3s9b9x.cfg stm32f10x_128k_eval.cfg
+hammer.cfg str910-eval.cfg
+hitex_lpc2929.cfg telo.cfg
+hitex_stm32-performancestick.cfg ti_beagleboard.cfg
+hitex_str9-comstick.cfg topas910.cfg
+iar_str912_sk.cfg topasa900.cfg
+imx27ads.cfg unknown_at91sam9260.cfg
+imx27lnst.cfg x300t.cfg
+imx31pdk.cfg zy1000.cfg
+$
+@end example
@item @file{target} ...
think chip. The ``target'' directory represents the JTAG TAPs
on a chip
are ARM chips and FPGA or CPLD chips.
When a chip has multiple TAPs (maybe it has both ARM and DSP cores),
the target config file defines all of them.
+@example
+$ ls target
+aduc702x.cfg imx27.cfg pxa255.cfg
+ar71xx.cfg imx31.cfg pxa270.cfg
+at91eb40a.cfg imx35.cfg readme.txt
+at91r40008.cfg is5114.cfg sam7se512.cfg
+at91rm9200.cfg ixp42x.cfg sam7x256.cfg
+at91sam3u1c.cfg lm3s1968.cfg samsung_s3c2410.cfg
+at91sam3u1e.cfg lm3s3748.cfg samsung_s3c2440.cfg
+at91sam3u2c.cfg lm3s6965.cfg samsung_s3c2450.cfg
+at91sam3u2e.cfg lm3s811.cfg samsung_s3c4510.cfg
+at91sam3u4c.cfg lm3s9b9x.cfg samsung_s3c6410.cfg
+at91sam3u4e.cfg lpc1768.cfg sharp_lh79532.cfg
+at91sam3uXX.cfg lpc2103.cfg smdk6410.cfg
+at91sam7sx.cfg lpc2124.cfg smp8634.cfg
+at91sam9260.cfg lpc2129.cfg stm32.cfg
+c100.cfg lpc2148.cfg str710.cfg
+c100config.tcl lpc2294.cfg str730.cfg
+c100helper.tcl lpc2378.cfg str750.cfg
+c100regs.tcl lpc2478.cfg str912.cfg
+cs351x.cfg lpc2900.cfg telo.cfg
+davinci.cfg mega128.cfg ti_dm355.cfg
+dragonite.cfg netx500.cfg ti_dm365.cfg
+epc9301.cfg omap2420.cfg ti_dm6446.cfg
+feroceon.cfg omap3530.cfg tmpa900.cfg
+icepick.cfg omap5912.cfg tmpa910.cfg
+imx21.cfg pic32mx.cfg xba_revA3.cfg
+$
+@end example
+@item @emph{more} ... browse for other library files which may be useful.
+For example, there are various generic and CPU-specific utilities.
@end itemize
The @file{openocd.cfg} user config
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.
@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]
+
+ arm11 mcr $TARGETNAME 15 [expr ($regs>>12)&0x7] \
+ [expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] \
+ [expr ($regs>>8)&0x7] $value
+@}
+@end example
+
+
+
@node Daemon Configuration
@chapter Daemon Configuration
@cindex initialization
the 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
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.
@end deffn
@deffn {Command} reset_config mode_flag ...
-This command tells OpenOCD the reset configuration
+This command displays or modifies the reset configuration
of your combination of JTAG board and target in target
configuration scripts.
with a board that only wires up SRST.)
The @var{mode_flag} options can be specified in any order, but only one
-of each type -- @var{signals}, @var{combination}, @var{trst_type},
+of each type -- @var{signals}, @var{combination},
+@var{gates},
+@var{trst_type},
and @var{srst_type} -- may be specified at a time.
If you don't provide a new value for a given type, its previous
value (perhaps the default) is unchanged.
TRST just to declare that if the JTAG adapter should want to drive SRST,
it must explicitly be driven high (@option{srst_push_pull}).
+@itemize
+@item
@var{signals} can specify which of the reset signals are connected.
For example, If the JTAG interface provides SRST, but the board doesn't
connect that signal properly, then OpenOCD can't use it.
@option{srst_only} and @option{trst_and_srst}.
@quotation Tip
-If your board provides SRST or TRST through the JTAG connector,
-you must declare that or else those signals will not be used.
+If your board provides SRST and/or TRST through the JTAG connector,
+you must declare that so those signals can be used.
@end quotation
+@item
The @var{combination} is an optional value specifying broken reset
signal implementations.
The default behaviour if no option given is @option{separate},
@option{combined} implies both @option{srst_pulls_trst} and
@option{trst_pulls_srst}.
-@option{srst_gates_jtag} indicates that asserting SRST gates the
+@item
+The @var{gates} tokens control flags that describe some cases where
+JTAG may be unvailable during reset.
+@option{srst_gates_jtag} (default)
+indicates that asserting SRST gates the
JTAG clock. This means that no communication can happen on JTAG
while SRST is asserted.
+Its converse is @option{srst_nogate}, indicating that JTAG commands
+can safely be issued while SRST is active.
+@end itemize
The optional @var{trst_type} and @var{srst_type} parameters allow the
driver mode of each reset line to be specified. These values only affect
JTAG interfaces with support for different driver modes, like the Amontec
-JTAGkey and JTAGAccelerator. Also, they are necessarily ignored if the
+JTAGkey and JTAG Accelerator. Also, they are necessarily ignored if the
relevant signal (TRST or SRST) is not connected.
+@itemize
+@item
Possible @var{trst_type} driver modes for the test reset signal (TRST)
-are @option{trst_push_pull} (default) and @option{trst_open_drain}.
+are the default @option{trst_push_pull}, and @option{trst_open_drain}.
Most boards connect this signal to a pulldown, so the JTAG TAPs
never leave reset unless they are hooked up to a JTAG adapter.
+@item
Possible @var{srst_type} driver modes for the system reset signal (SRST)
are the default @option{srst_open_drain}, and @option{srst_push_pull}.
Most boards connect this signal to a pullup, and allow the
signal to be pulled low by various events including system
powerup and pressing a reset button.
+@end itemize
+@end deffn
+
+@section Custom Reset Handling
+@cindex events
+
+OpenOCD has several ways to help support the various reset
+mechanisms provided by chip and board vendors.
+The commands shown in the previous section give standard parameters.
+There are also @emph{event handlers} associated with TAPs or Targets.
+Those handlers are Tcl procedures you can provide, which are invoked
+at particular points in the reset sequence.
+
+After configuring those mechanisms, you might still
+find your board doesn't start up or reset correctly.
+For example, maybe it needs a slightly different sequence
+of SRST and/or TRST manipulations, because of quirks that
+the @command{reset_config} mechanism doesn't address;
+or asserting both might trigger a stronger reset, which
+needs special attention.
+
+Experiment with lower level operations, such as @command{jtag_reset}
+and the @command{jtag arp_*} operations shown here,
+to find a sequence of operations that works.
+@xref{JTAG Commands}.
+When you find a working sequence, it can be used to override
+@command{jtag_init}, which fires during OpenOCD startup
+(@pxref{Configuration Stage});
+or @command{init_reset}, which fires during reset processing.
+
+You might also want to provide some project-specific reset
+schemes. For example, on a multi-target board the standard
+@command{reset} command would reset all targets, but you
+may need the ability to reset only one target at time and
+thus want to avoid using the board-wide SRST signal.
+
+@deffn {Overridable Procedure} init_reset mode
+This is invoked near the beginning of the @command{reset} command,
+usually to provide as much of a cold (power-up) reset as practical.
+By default it is also invoked from @command{jtag_init} if
+the scan chain does not respond to pure JTAG operations.
+The @var{mode} parameter is the parameter given to the
+low level reset command (@option{halt},
+@option{init}, or @option{run}), @option{setup},
+or potentially some other value.
+
+The default implementation just invokes @command{jtag arp_init-reset}.
+Replacements will normally build on low level JTAG
+operations such as @command{jtag_reset}.
+Operations here must not address individual TAPs
+(or their associated targets)
+until the JTAG scan chain has first been verified to work.
+
+Implementations must have verified the JTAG scan chain before
+they return.
+This is done by calling @command{jtag arp_init}
+(or @command{jtag arp_init-reset}).
+@end deffn
+
+@deffn Command {jtag arp_init}
+This validates the scan chain using just the four
+standard JTAG signals (TMS, TCK, TDI, TDO).
+It starts by issuing a JTAG-only reset.
+Then it performs checks to verify that the scan chain configuration
+matches the TAPs it can observe.
+Those checks include checking IDCODE values for each active TAP,
+and verifying the length of their instruction registers using
+TAP @code{-ircapture} and @code{-irmask} values.
+If these tests all pass, TAP @code{setup} events are
+issued to all TAPs with handlers for that event.
+@end deffn
+
+@deffn Command {jtag arp_init-reset}
+This uses TRST and SRST to try resetting
+everything on the JTAG scan chain
+(and anything else connected to SRST).
+It then invokes the logic of @command{jtag arp_init}.
@end deffn
@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 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
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}).
If @var{count} is specified, displays that many units.
+@var{phys} is an optional flag to indicate to use
+physical address and bypass MMU
(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,
at the specified address @var{addr}.
+@var{phys} is an optional flag to indicate to use
+physical address and bypass MMU
@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.
+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.
The @var{mode} must be @option{normal}, @option{multiplexted},
or @option{demultiplexted}.
@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}
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
@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]
@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
@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
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}
@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
@}
@end example
-@node Target Library
-@chapter Target Library
-@cindex Target Library
-
-OpenOCD comes with a target configuration script library. These scripts can be
-used as-is or serve as a starting point.
-
-The target library is published together with the OpenOCD executable and
-the path to the target library is in the OpenOCD script search path.
-Similarly there are example scripts for configuring the JTAG interface.
-
-The command line below uses the example parport configuration script
-that ship with OpenOCD, then configures the str710.cfg target and
-finally issues the init and reset commands. The communication speed
-is set to 10kHz for reset and 8MHz for post reset.
-
-@example
-openocd -f interface/parport.cfg -f target/str710.cfg \
- -c "init" -c "reset"
-@end example
-
-To list the target scripts available:
-
-@example
-$ ls /usr/local/lib/openocd/target
-
-arm7_fast.cfg lm3s6965.cfg pxa255.cfg stm32.cfg xba_revA3.cfg
-at91eb40a.cfg lpc2148.cfg pxa255_sst.cfg str710.cfg zy1000.cfg
-at91r40008.cfg lpc2294.cfg sam7s256.cfg str912.cfg
-at91sam9260.cfg nslu2.cfg sam7x256.cfg wi-9c.cfg
-@end example
-
@include fdl.texi
@node OpenOCD Concept Index
Code Review / openocd.git / blobdiff