* TFTP:: TFTP
* 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
@section OpenOCD User's Forum
-There is an OpenOCD forum (phpBB) hosted by SparkFun:
+There is an OpenOCD forum (phpBB) hosted by SparkFun,
+which might be helpful to you. Note that if you want
+anything to come to the attention of developers, you
+should post it to the OpenOCD Developer Mailing List
+instead of this forum.
@uref{http://forum.sparkfun.com/viewforum.php?f=18}
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.txt} file contains basic information about how
+to prepare patches.
@node JTAG Hardware Dongles
@* See: @url{http://www.oocdlink.com} By Joern Kaipf
@item @b{signalyzer}
@* See: @url{http://www.signalyzer.com}
-@item @b{evb_lm3s811}
-@* See: @url{http://www.luminarymicro.com} - The Stellaris LM3S811 eval board has an FTD2232C chip built in.
-@item @b{luminary_icdi}
-@* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug Interface (ICDI) Board, included in the Stellaris LM3S9B90 and LM3S9B92 Evaluation Kits.
+@item @b{Stellaris Eval Boards}
+@* See: @url{http://www.luminarymicro.com} - The Stellaris eval boards
+bundle FT2232-based JTAG and SWD support, which can be used to debug
+the Stellaris chips. Using separate JTAG adapters is optional.
+These boards can also be used as JTAG adapters to other target boards,
+disabling the Stellaris chip.
+@item @b{Luminary ICDI}
+@* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug
+Interface (ICDI) Boards are included in Stellaris LM3S9B90 and LM3S9B92
+Evaluation Kits. Like the non-detachable FT2232 support on the other
+Stellaris eval boards, they can be used to debug other target boards.
@item @b{olimex-jtag}
@* See: @url{http://www.olimex.com}
@item @b{flyswatter}
@* Link @url{http://www.hitex.com/index.php?id=cortino}
@end itemize
+@section USB-JTAG / Altera USB-Blaster compatibles
+
+These devices also show up as FTDI devices, but are not
+protocol-compatible with the FT2232 devices. They are, however,
+protocol-compatible among themselves. USB-JTAG devices typically consist
+of a FT245 followed by a CPLD that understands a particular protocol,
+or emulate this protocol using some other hardware.
+
+They may appear under different USB VID/PID depending on the particular
+product. The driver can be configured to search for any VID/PID pair
+(see the section on driver commands).
+
+@itemize
+@item @b{USB-JTAG} Kolja Waschk's USB Blaster-compatible adapter
+@* Link: @url{http://www.ixo.de/info/usb_jtag/}
+@item @b{Altera USB-Blaster}
+@* Link: @url{http://www.altera.com/literature/ug/ug_usb_blstr.pdf}
+@end itemize
+
@section USB JLINK based
There are several OEM versions of the Segger @b{JLINK} adapter. It is
an example of a micro controller based JTAG adapter, it uses an
--pipe | -p use pipes when talking to gdb
@end verbatim
-By default OpenOCD reads the file configuration file @file{openocd.cfg}
-in the current directory. To specify a different (or multiple)
-configuration file, you can use the ``-f'' option. For example:
+By default OpenOCD reads the configuration file @file{openocd.cfg}.
+To specify a different (or multiple)
+configuration file, you can use the @option{-f} option. For example:
@example
openocd -f config1.cfg -f config2.cfg -f config3.cfg
@end example
+Configuration files and scripts are searched for in
+@enumerate
+@item the current directory,
+@item any search dir specified on the command line using the @option{-s} option,
+@item @file{$HOME/.openocd} (not on Windows),
+@item the site wide script library @file{$pkgdatadir/site} and
+@item the OpenOCD-supplied script library @file{$pkgdatadir/scripts}.
+@end enumerate
+The first found file with a matching file name will be used.
+
+@section Simple setup, no customization
+
+In the best case, you can use two scripts from one of the script
+libraries, hook up your JTAG adapter, and start the server ... and
+your JTAG setup will just work "out of the box". Always try to
+start by reusing those scripts, but assume you'll need more
+customization even if this works. @xref{OpenOCD Project Setup}.
+
+If you find a script for your JTAG adapter, and for your board or
+target, you may be able to hook up your JTAG adapter then start
+the server like:
+
+@example
+openocd -f interface/ADAPTER.cfg -f board/MYBOARD.cfg
+@end example
+
+You might also need to configure which reset signals are present,
+using @option{-c 'reset_config trst_and_srst'} or something similar.
+If all goes well you'll see output something like
+
+@example
+Open On-Chip Debugger 0.4.0 (2010-01-14-15:06)
+For bug reports, read
+ http://openocd.berlios.de/doc/doxygen/bugs.html
+Info : JTAG tap: lm3s.cpu tap/device found: 0x3ba00477
+ (mfg: 0x23b, part: 0xba00, ver: 0x3)
+@end example
+
+Seeing that "tap/device found" message, and no warnings, means
+the JTAG communication is working. That's a key milestone, but
+you'll probably need more project-specific setup.
+
+@section What OpenOCD does as it starts
+
OpenOCD starts by processing the configuration commands provided
-on the command line or in @file{openocd.cfg}.
+on the command line or, if there were no @option{-c command} or
+@option{-f file.cfg} options given, in @file{openocd.cfg}.
@xref{Configuration Stage}.
At the end of the configuration stage it verifies the JTAG scan
chain defined using those commands; your configuration should
those channels.
If you are having problems, you can enable internal debug messages via
-the ``-d'' option.
+the @option{-d} option.
Also it is possible to interleave JIM-Tcl commands w/config scripts using the
@option{-c} command line switch.
You can redirect all output from the daemon to a file using the
@option{-l <logfile>} switch.
-Search paths for config/script files can be added to OpenOCD by using
-the @option{-s <search>} switch. The current directory and the OpenOCD
-target library is in the search path by default.
-
For details on the @option{-p} option. @xref{Connecting to GDB}.
Note! OpenOCD will launch the GDB & telnet server even if it can not
and then starting the OpenOCD server.
You also need to configure that server so that it knows
about that adapter and board, and helps your work.
+You may also want to connect OpenOCD to GDB, possibly
+using Eclipse or some other GUI.
@section Hooking up the JTAG Adapter
For Ethernet, consult the documentation and your network administrator.
For USB based JTAG adapters you have an easy sanity check at this point:
-does the host operating system see the JTAG adapter?
+does the host operating system see the JTAG adapter? If that host is an
+MS-Windows host, you'll need to install a driver before OpenOCD works.
@item @emph{Connect the adapter's power supply, if needed.}
This step is primarily for non-USB adapters,
single directory for your work with a given board.
When you start OpenOCD from that directory,
it searches there first for configuration files, scripts,
+files accessed through semihosting,
and for code you upload to the target board.
It is also the natural place to write files,
such as log files and data you download from the board.
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.
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
Other helper scripts might be used to write production system images,
involving considerably more than just a three stage bootloader.
+@section Target Software Changes
+
+Sometimes you may want to make some small changes to the software
+you're developing, to help make JTAG debugging work better.
+For example, in C or assembly language code you might
+use @code{#ifdef JTAG_DEBUG} (or its converse) around code
+handling issues like:
+
+@itemize @bullet
+
+@item @b{ARM Semihosting}...
+@cindex ARM semihosting
+When linked with a special runtime library provided with many
+toolchains@footnote{See chapter 8 "Semihosting" in
+@uref{http://infocenter.arm.com/help/topic/com.arm.doc.dui0203i/DUI0203I_rvct_developer_guide.pdf,
+ARM DUI 0203I}, the "RealView Compilation Tools Developer Guide".
+The CodeSourcery EABI toolchain also includes a semihosting library.},
+your target code can use I/O facilities on the debug host. That library
+provides a small set of system calls which are handled by OpenOCD.
+It can let the debugger provide your system console and a file system,
+helping with early debugging or providing a more capable environment
+for sometimes-complex tasks like installing system firmware onto
+NAND or SPI flash.
+
+@item @b{ARM Wait-For-Interrupt}...
+Many ARM chips synchronize the JTAG clock using the core clock.
+Low power states which stop that core clock thus prevent JTAG access.
+Idle loops in tasking environments often enter those low power states
+via the @code{WFI} instruction (or its coprocessor equivalent, before ARMv7).
+
+You may want to @emph{disable that instruction} in source code,
+or otherwise prevent using that state,
+to ensure you can get JTAG access at any time.
+For example, the OpenOCD @command{halt} command may not
+work for an idle processor otherwise.
+
+@item @b{Delay after reset}...
+Not all chips have good support for debugger access
+right after reset; many LPC2xxx chips have issues here.
+Similarly, applications that reconfigure pins used for
+JTAG access as they start will also block debugger access.
+
+To work with boards like this, @emph{enable a short delay loop}
+the first thing after reset, before "real" startup activities.
+For example, one second's delay is usually more than enough
+time for a JTAG debugger to attach, so that
+early code execution can be debugged
+or firmware can be replaced.
+
+@item @b{Debug Communications Channel (DCC)}...
+Some processors include mechanisms to send messages over JTAG.
+Many ARM cores support these, as do some cores from other vendors.
+(OpenOCD may be able to use this DCC internally, speeding up some
+operations like writing to memory.)
+
+Your application may want to deliver various debugging messages
+over JTAG, by @emph{linking with a small library of code}
+provided with OpenOCD and using the utilities there to send
+various kinds of message.
+@xref{Software Debug Messages and Tracing}.
+
+@end itemize
@node Config File Guidelines
@chapter Config File Guidelines
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.
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
values for @code{CHIPNAME}, so
it adds a different TAP each time.
-If there are one or more nonzero @option{-expected-id} values,
+If there are nonzero @option{-expected-id} values,
OpenOCD attempts to verify the actual tap id against those values.
It will issue error messages if there is mismatch, which
can help to pinpoint problems in OpenOCD configurations.
Some chips have specific ways the TRST and SRST signals are
managed. In the unusual case that these are @emph{chip specific}
and can never be changed by board wiring, they could go here.
+For example, some chips can't support JTAG debugging without
+both signals.
+
+Provide a @code{reset-assert} event handler if you can.
+Such a handler uses JTAG operations to reset the target,
+letting this target config be used in systems which don't
+provide the optional SRST signal, or on systems where you
+don't want to reset all targets at once.
+Such a handler might write to chip registers to force a reset,
+use a JRC to do that (preferable -- the target may be wedged!),
+or force a watchdog timer to trigger.
+(For Cortex-M3 targets, this is not necessary. The target
+driver knows how to use trigger an NVIC reset when SRST is
+not available.)
Some chips need special attention during reset handling if
they're going to be used with JTAG.
after the target's TAP has been reset, providing a
@code{reset-deassert-post} event handler that writes a chip
register to report that JTAG debugging is being done.
+Another would be reconfiguring the watchdog so that it stops
+counting while the core is halted in the debugger.
JTAG clocking constraints often change during reset, and in
some cases target config files (rather than board config files)
@item pxa270 - again - CS0 flash - it goes in the board file.
@end itemize
+@anchor{Translating Configuration Files}
+@section Translating Configuration Files
+@cindex translation
+If you have a configuration file for another hardware debugger
+or toolset (Abatron, BDI2000, BDI3000, CCS,
+Lauterbach, Segger, Macraigor, etc.), translating
+it into OpenOCD syntax is often quite straightforward. The most tricky
+part of creating a configuration script is oftentimes the reset init
+sequence where e.g. PLLs, DRAM and the like is set up.
+
+One trick that you can use when translating is to write small
+Tcl procedures to translate the syntax into OpenOCD syntax. This
+can avoid manual translation errors and make it easier to
+convert other scripts later on.
+
+Example of transforming quirky arguments to a simple search and
+replace job:
+
+@example
+# Lauterbach syntax(?)
+#
+# Data.Set c15:0x042f %long 0x40000015
+#
+# OpenOCD syntax when using procedure below.
+#
+# setc15 0x01 0x00050078
+
+proc setc15 @{regs value@} @{
+ global TARGETNAME
+
+ echo [format "set p15 0x%04x, 0x%08x" $regs $value]
+
+ arm mcr 15 [expr ($regs>>12)&0x7] \
+ [expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] \
+ [expr ($regs>>8)&0x7] $value
+@}
+@end example
+
+
+
@node Daemon Configuration
@chapter Daemon Configuration
@cindex initialization
When the OpenOCD server process starts up, it enters a
@emph{configuration stage} which is the only time that
certain commands, @emph{configuration commands}, may be issued.
+Normally, configuration commands are only available
+inside startup scripts.
+
In this manual, the definition of a configuration command is
presented as a @emph{Config Command}, not as a @emph{Command}
which may be issued interactively.
+The runtime @command{help} command also highlights configuration
+commands, and those which may be issued at any time.
Those configuration commands include declaration of TAPs,
flash banks,
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
If you disable all access through TCP/IP, you will need to
use the command line @option{-pipe} option.
-@deffn {Command} gdb_port (number)
+@deffn {Command} gdb_port [number]
@cindex GDB server
Specify or query the first port used for incoming GDB connections.
The GDB port for the
first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
When not specified during the configuration stage,
the port @var{number} defaults to 3333.
-When specified as zero, this port is not activated.
+When specified as zero, GDB remote access ports are not activated.
@end deffn
-@deffn {Command} tcl_port (number)
+@deffn {Command} tcl_port [number]
Specify or query the port used for a simplified RPC
connection that can be used by clients to issue TCL commands and get the
output from the Tcl engine.
When specified as zero, this port is not activated.
@end deffn
-@deffn {Command} telnet_port (number)
+@deffn {Command} telnet_port [number]
Specify or query the
port on which to listen for incoming telnet connections.
This port is intended for interaction with one human through TCL commands.
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 could use this from the TCL command shell, or
from GDB using @command{monitor poll} command.
+Leave background polling enabled while you're using GDB.
@example
> poll
background polling: on
@item @b{evb_lm3s811} Luminary Micro EVB_LM3S811 as a JTAG interface,
either for the local Cortex-M3 (SRST only)
or in a passthrough mode (neither SRST nor TRST)
-@item @b{luminary_icdi} Luminary In-Circuit Debug Interface (ICDI) Board
+This layout can not support the SWO trace mechanism, and should be
+used only for older boards (before rev C).
+@item @b{luminary_icdi} This layout should be used with most Luminary
+eval boards, including Rev C LM3S811 eval boards and the eponymous
+ICDI boards, to debug either the local Cortex-M3 or in passthrough mode
+to debug some other target. It can support the SWO trace mechanism.
@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)
@end example
@end deffn
+@deffn {Interface Driver} {usb_blaster}
+USB JTAG/USB-Blaster compatibles over one of the userspace libraries
+for FTDI chips. These interfaces have several commands, used to
+configure the driver before initializing the JTAG scan chain:
+
+@deffn {Config Command} {usb_blaster_device_desc} description
+Provides the USB device description (the @emph{iProduct string})
+of the FTDI FT245 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} {usb_blaster_vid_pid} vid pid
+The vendor ID and product ID of the FTDI FT245 device. If not specified,
+default values are used.
+Currently, only one @var{vid}, @var{pid} pair may be given, e.g. for
+Altera USB-Blaster (default):
+@example
+ft2232_vid_pid 0x09FB 0x6001
+@end example
+The following VID/PID is for Kolja Waschk's USB JTAG:
+@example
+ft2232_vid_pid 0x16C0 0x06AD
+@end example
+@end deffn
+
+@deffn {Command} {usb_blaster} (@option{pin6}|@option{pin8}) (@option{0}|@option{1})
+Sets the state of the unused GPIO pins on USB-Blasters (pins 6 and 8 on the
+female JTAG header). These pins can be used as SRST and/or TRST provided the
+appropriate connections are made on the target board.
+
+For example, to use pin 6 as SRST (as with an AVR board):
+@example
+$_TARGETNAME configure -event reset-assert \
+ "usb_blaster pin6 1; wait 1; usb_blaster pin6 0"
+@end example
+@end deffn
+
+@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.
+@deffn {Config Command} {parport_port} [port_number]
+Display either the address of the I/O port
+(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
+If a parameter is provided, first switch to use that port.
+This is a write-once setting.
@end deffn
@end deffn
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.
+Set the layout of the parallel port cable used to connect to the target.
+This is a write-once setting.
Currently valid cable @var{name} values include:
@itemize @minus
@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
+@deffn {Config Command} {parport_port} [port_number]
+Display either the address of the I/O port
+(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
+If a parameter is provided, first switch to use that port.
+This is a write-once setting.
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)
+@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} (@option{on}|@option{off})
This will configure the parallel driver to write a known
-cable-specific value to the parallel interface on exiting OpenOCD
+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:
+classic ``Wiggler'' cable on LPT2 might look something like this:
@example
interface parport
-parport_port 0xc8b8
+parport_port 0x278
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
+@deffn {Config Command} {presto_serial} serial_string
+Configures the USB serial number of the Presto device to use.
+@end deffn
@end deffn
@deffn {Interface Driver} {rlink}
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},
indicating everything behaves normally.
@option{srst_pulls_trst} states that the
-test logic is reset together with the reset of the system (e.g. Philips
+test logic is reset together with the reset of the system (e.g. NXP
LPC2000, "broken" board layout), @option{trst_pulls_srst} says that
the system is reset together with the test logic (only hypothetical, I
haven't seen hardware with such a bug, and can be worked around).
@option{combined} implies both @option{srst_pulls_trst} and
@option{trst_pulls_srst}.
-@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.
+
+@emph{When SRST is not an option} you must set
+up a @code{reset-assert} event handler for your target.
+For example, some JTAG adapters don't include the SRST signal;
+and some boards have multiple targets, and you won't always
+want to reset everything at once.
+
+After configuring those mechanisms, you might still
+find your board doesn't start up or reset correctly.
+For example, maybe it needs a slightly different sequence
+of SRST and/or TRST manipulations, because of quirks that
+the @command{reset_config} mechanism doesn't address;
+or asserting both might trigger a stronger reset, which
+needs special attention.
+
+Experiment with lower level operations, such as @command{jtag_reset}
+and the @command{jtag arp_*} operations shown here,
+to find a sequence of operations that works.
+@xref{JTAG Commands}.
+When you find a working sequence, it can be used to override
+@command{jtag_init}, which fires during OpenOCD startup
+(@pxref{Configuration Stage});
+or @command{init_reset}, which fires during reset processing.
+
+You might also want to provide some project-specific reset
+schemes. For example, on a multi-target board the standard
+@command{reset} command would reset all targets, but you
+may need the ability to reset only one target at time and
+thus want to avoid using the board-wide SRST signal.
+
+@deffn {Overridable Procedure} init_reset mode
+This is invoked near the beginning of the @command{reset} command,
+usually to provide as much of a cold (power-up) reset as practical.
+By default it is also invoked from @command{jtag_init} if
+the scan chain does not respond to pure JTAG operations.
+The @var{mode} parameter is the parameter given to the
+low level reset command (@option{halt},
+@option{init}, or @option{run}), @option{setup},
+or potentially some other value.
+
+The default implementation just invokes @command{jtag arp_init-reset}.
+Replacements will normally build on low level JTAG
+operations such as @command{jtag_reset}.
+Operations here must not address individual TAPs
+(or their associated targets)
+until the JTAG scan chain has first been verified to work.
+
+Implementations must have verified the JTAG scan chain before
+they return.
+This is done by calling @command{jtag arp_init}
+(or @command{jtag arp_init-reset}).
+@end deffn
+
+@deffn Command {jtag arp_init}
+This validates the scan chain using just the four
+standard JTAG signals (TMS, TCK, TDI, TDO).
+It starts by issuing a JTAG-only reset.
+Then it performs checks to verify that the scan chain configuration
+matches the TAPs it can observe.
+Those checks include checking IDCODE values for each active TAP,
+and verifying the length of their instruction registers using
+TAP @code{-ircapture} and @code{-irmask} values.
+If these tests all pass, TAP @code{setup} events are
+issued to all TAPs with handlers for that event.
+@end deffn
+
+@deffn Command {jtag arp_init-reset}
+This uses TRST and SRST to try resetting
+everything on the JTAG scan chain
+(and anything else connected to SRST).
+It then invokes the logic of @command{jtag arp_init}.
@end deffn
Here's what the scan chain might look like for a chip more than one TAP:
@verbatim
- TapName Enabled IdCode Expected IrLen IrCap IrMask Instr
--- ------------------ ------- ---------- ---------- ----- ----- ------ -----
- 0 omap5912.dsp Y 0x03df1d81 0x03df1d81 38 0 0 0x...
- 1 omap5912.arm Y 0x0692602f 0x0692602f 4 0x1 0 0xc
- 2 omap5912.unknown Y 0x00000000 0x00000000 8 0 0 0xff
+ TapName Enabled IdCode Expected IrLen IrCap IrMask
+-- ------------------ ------- ---------- ---------- ----- ----- ------
+ 0 omap5912.dsp Y 0x03df1d81 0x03df1d81 38 0x01 0x03
+ 1 omap5912.arm Y 0x0692602f 0x0692602f 4 0x01 0x0f
+ 2 omap5912.unknown Y 0x00000000 0x00000000 8 0x01 0x03
@end verbatim
+OpenOCD can detect some of that information, but not all
+of it. @xref{Autoprobing}.
Unfortunately those TAPs can't always be autoconfigured,
because not all devices provide good support for that.
JTAG doesn't require supporting IDCODE instructions, and
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
exiting the OpenOCD configuration stage,
but systems with a JTAG router can
enable or disable TAPs dynamically.
-In addition to the enable/disable status, the contents of
-each TAP's instruction register can also change.
@end deffn
@c FIXME! "jtag cget" should be able to return all TAP
Every TAP requires at least the following @var{configparams}:
@itemize @bullet
-@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.
-The value is used to verify that instruction scans work correctly.
@item @code{-irlen} @var{NUMBER}
@*The length in bits of the
instruction register, such as 4 or 5 bits.
-@item @code{-irmask} @var{NUMBER}
-@*A mask for the IR register.
-For some devices, there are bits in the IR that aren't used.
-This lets OpenOCD mask them off when doing IDCODE comparisons.
-In general, this should just be all ones for the size of the IR.
@end itemize
A TAP may also provide optional @var{configparams}:
(the TAP is linked in).
@xref{Enabling and Disabling TAPs}.
@item @code{-expected-id} @var{number}
-@*A non-zero value represents the expected 32-bit IDCODE
-found when the JTAG chain is examined.
+@*A non-zero @var{number} represents a 32-bit IDCODE
+which you expect to find when the scan chain is examined.
These codes are not required by all JTAG devices.
@emph{Repeat the option} as many times as required if more than one
ID code could appear (for example, multiple versions).
+Specify @var{number} as zero to suppress warnings about IDCODE
+values that were found but not included in the list.
+
+Provide this value if at all possible, since it lets OpenOCD
+tell when the scan chain it sees isn't right. These values
+are provided in vendors' chip documentation, usually a technical
+reference manual. Sometimes you may need to probe the JTAG
+hardware to find these values.
+@xref{Autoprobing}.
+@item @code{-ignore-version}
+@*Specify this to ignore the JTAG version field in the @code{-expected-id}
+option. When vendors put out multiple versions of a chip, or use the same
+JTAG-level ID for several largely-compatible chips, it may be more practical
+to ignore the version field than to update config files to handle all of
+the various chip IDs.
+@item @code{-ircapture} @var{NUMBER}
+@*The bit pattern loaded by the TAP into the JTAG shift register
+on entry to the @sc{ircapture} state, such as 0x01.
+JTAG requires the two LSBs of this value to be 01.
+By default, @code{-ircapture} and @code{-irmask} are set
+up to verify that two-bit value. You may provide
+additional bits, if you know them, or indicate that
+a TAP doesn't conform to the JTAG specification.
+@item @code{-irmask} @var{NUMBER}
+@*A mask used with @code{-ircapture}
+to verify that instruction scans work correctly.
+Such scans are not used by OpenOCD except to verify that
+there seems to be no problems with JTAG scan chain operations.
@end itemize
@end deffn
@section Other TAP commands
-@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
@itemize @bullet
@item @b{post-reset}
@* The TAP has just completed a JTAG reset.
-For the first such handler called, the tap is still
-in the JTAG @sc{reset} state.
+The tap may still be in the JTAG @sc{reset} state.
+Handlers for these events might perform initialization sequences
+such as issuing TCK cycles, TMS sequences to ensure
+exit from the ARM SWD mode, and more.
+
Because the scan chain has not yet been verified, handlers for these events
@emph{should not issue commands which scan the JTAG IR or DR registers}
of any particular target.
@b{NOTE:} As this is written (September 2009), nothing prevents such access.
+@item @b{setup}
+@* The scan chain has been reset and verified.
+This handler may enable TAPs as needed.
@item @b{tap-disable}
@* The TAP needs to be disabled. This handler should
implement @command{jtag tapdisable}
@example
jtag configure CHIP.jrc -event post-reset @{
- echo "Reset done"
+ echo "JTAG Reset done"
... non-scan jtag operations to be done after reset
@}
@end example
In OpenOCD, tap enabling/disabling is invoked by the Tcl commands
shown below, and is implemented using TAP event handlers.
So for example, when defining a TAP for a CPU connected to
-a JTAG router, you should define TAP event handlers using
+a JTAG router, your @file{target.cfg} file
+should define TAP event handlers using
code that looks something like this:
@example
jtag configure CHIP.cpu -event tap-enable @{
- echo "Enabling CPU TAP"
... jtag operations using CHIP.jrc
@}
jtag configure CHIP.cpu -event tap-disable @{
- echo "Disabling CPU TAP"
... jtag operations using CHIP.jrc
@}
@end example
+Then you might want that CPU's TAP enabled almost all the time:
+
+@example
+jtag configure $CHIP.jrc -event setup "jtag tapenable $CHIP.cpu"
+@end example
+
+Note how that particular setup event handler declaration
+uses quotes to evaluate @code{$CHIP} when the event is configured.
+Using brackets @{ @} would cause it to be evaluated later,
+at runtime, when it might have a different value.
+
@deffn Command {jtag tapdisable} dotted.name
If necessary, disables the tap
by sending it a @option{tap-disable} event.
Returns the string "1" if the tap
specified by @var{dotted.name} is enabled,
-and "0" if it is disbabled.
+and "0" if it is disabled.
@end deffn
@deffn Command {jtag tapenable} dotted.name
by sending it a @option{tap-enable} event.
Returns the string "1" if the tap
specified by @var{dotted.name} is enabled,
-and "0" if it is disbabled.
+and "0" if it is disabled.
@end deffn
@deffn Command {jtag tapisenabled} dotted.name
Returns the string "1" if the tap
specified by @var{dotted.name} is enabled,
-and "0" if it is disbabled.
+and "0" if it is disabled.
@quotation Note
Humans will find the @command{scan_chain} command more helpful
@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{dsp563xx} -- implements Freescale's 24-bit DSP.
+(Support for this is still incomplete.)
@item @code{fa526} -- resembles arm920 (w/o Thumb)
@item @code{feroceon} -- resembles arm926
@item @code{mips_m4k} -- a MIPS core. This supports one variant:
@code{pxa27x} ... instruction register length is 7 bits
@item @code{pxa250}, @code{pxa255},
@code{pxa26x} ... instruction register length is 5 bits
+@item @code{pxa3xx} ... instruction register length is 11 bits
@end itemize
@end itemize
@end deffn
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
@itemize @bullet
@item What should happen when GDB connects? Should your target reset?
@item When GDB tries to flash the target, do you need to enable the flash via a special command?
+@item Is using SRST appropriate (and possible) on your system?
+Or instead of that, do you need to issue JTAG commands to trigger reset?
+SRST usually resets everything on the scan chain, which can be inappropriate.
@item During reset, do you need to write to certain memory locations
to set up system clocks or
to reconfigure the SDRAM?
+How about configuring the watchdog timer, or other peripherals,
+to stop running while you hold the core stopped for debugging?
@end itemize
All of the above items can be addressed by target event handlers.
@end ignore
@item @b{reset-assert-pre}
@* Issued as part of @command{reset} processing
-after SRST and/or TRST were activated and deactivated,
-but before SRST alone is re-asserted on the tap.
+after @command{reset_init} was triggered
+but before either SRST alone is re-asserted on the scan chain,
+or @code{reset-assert} is triggered.
+@item @b{reset-assert}
+@* Issued as part of @command{reset} processing
+after @command{reset-assert-pre} was triggered.
+When such a handler is present, cores which support this event will use
+it instead of asserting SRST.
+This support is essential for debugging with JTAG interfaces which
+don't include an SRST line (JTAG doesn't require SRST), and for
+selective reset on scan chains that have multiple targets.
@item @b{reset-assert-post}
@* Issued as part of @command{reset} processing
-when SRST is asserted on the tap.
+after @code{reset-assert} has been triggered.
+or the target asserted SRST on the entire scan chain.
@item @b{reset-deassert-pre}
@* Issued as part of @command{reset} processing
-when SRST is about to be released on the tap.
+after @code{reset-assert-post} has been triggered.
@item @b{reset-deassert-post}
@* Issued as part of @command{reset} processing
-when SRST has been released on the tap.
+after @code{reset-deassert-pre} has been triggered
+and (if the target is using it) after SRST has been
+released on the scan chain.
@item @b{reset-end}
@* Issued as the final step in @command{reset} processing.
@ignore
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
@section Flash Configuration Commands
@cindex flash configuration
-@deffn {Config Command} {flash bank} driver base size chip_width bus_width target [driver_options]
+@deffn {Config Command} {flash bank} name driver base size chip_width bus_width target [driver_options]
Configures a flash bank which provides persistent storage
for addresses from @math{base} to @math{base + size - 1}.
These banks will often be visible to GDB through the target's memory map.
see the driver-specific documentation.
@itemize @bullet
+@item @var{name} ... may be used to reference the flash bank
+in other flash commands. A number is also available.
@item @var{driver} ... identifies the controller driver
associated with the flash bank being declared.
This is usually @code{cfi} for external flash, or else
@comment the REAL name for this command is "ocd_flash_banks"
@comment less confusing would be: "flash list" (like "nand list")
@deffn Command {flash banks}
-Prints a one-line summary of each device declared
-using @command{flash bank}, numbered from zero.
+Prints a one-line summary of each device that was
+declared using @command{flash bank}, numbered from zero.
Note that this is the @emph{plural} form;
the @emph{singular} form is a very different command.
@end deffn
+@deffn Command {flash list}
+Retrieves a list of associative arrays for each device that was
+declared using @command{flash bank}, numbered from zero.
+This returned list can be manipulated easily from within scripts.
+@end deffn
+
@deffn Command {flash probe} num
Identify the flash, or validate the parameters of the configured flash. Operation
depends on the flash type.
@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
-each image segment.
+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 address of
+each image section.
+
+@quotation Warning
+Be careful using the @option{erase} flag when the flash is holding
+data you want to preserve.
+Portions of the flash outside those described in the image's
+sections might be erased with no notice.
+@itemize
+@item
+When a section of the image being written does not fill out all the
+sectors it uses, the unwritten parts of those sectors are necessarily
+also erased, because sectors can't be partially erased.
+@item
+Data stored in sector "holes" between image sections are also affected.
+For example, "@command{flash write_image erase ...}" of an image with
+one byte at the beginning of a flash bank and one byte at the end
+erases the entire bank -- not just the two sectors being written.
+@end itemize
+Also, when flash protection is important, you must re-apply it after
+it has been removed by the @option{unlock} flag.
+@end quotation
+
@end deffn
@section Other Flash commands
@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
@command{flash erase_sector} or @command{flash erase_address} commands.
@deffn Command {at91sam7 gpnvm} bitnum (@option{set}|@option{clear})
-Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
+Set or clear a ``General Purpose Non-Volatile Memory'' (GPNVM)
bit for the processor. Each processor has a number of such bits,
used for controlling features such as brownout detection (so they
are not truly general purpose).
plus some additional configuration that's done after
OpenOCD has initialized.
-@deffn {Config Command} {nand device} controller target [configparams...]
+@deffn {Config Command} {nand device} name driver target [configparams...]
Declares a NAND device, which can be read and written to
after it has been configured through @command{nand probe}.
In OpenOCD, devices are single chips; this is unlike some
configuration files, not interactively.
@itemize @bullet
-@item @var{controller} ... identifies the controller driver
+@item @var{name} ... may be used to reference the NAND bank
+in most other NAND commands. A number is also available.
+@item @var{driver} ... identifies the NAND controller driver
associated with the NAND device being declared.
@xref{NAND Driver List}.
@item @var{target} ... names the target used when issuing
@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.
+@deffn {NAND Driver} at91sam9
+This driver handles the NAND controllers found on AT91SAM9 family chips from
+Atmel. It takes two extra parameters: address of the NAND chip;
+address of the ECC controller.
+@example
+nand device $NANDFLASH at91sam9 $CHIPNAME 0x40000000 0xfffffe800
+@end example
+AT91SAM9 chips support single-bit ECC hardware. The @code{write_page} and
+@code{read_page} methods are used to utilize the ECC hardware unless they are
+disabled by using the @command{nand raw_access} command. There are four
+additional commands that are needed to fully configure the AT91SAM9 NAND
+controller. Two are optional; most boards use the same wiring for ALE/CLE:
+@deffn Command {at91sam9 cle} num addr_line
+Configure the address line used for latching commands. The @var{num}
+parameter is the value shown by @command{nand list}.
+@end deffn
+@deffn Command {at91sam9 ale} num addr_line
+Configure the address line used for latching addresses. The @var{num}
+parameter is the value shown by @command{nand list}.
+@end deffn
+
+For the next two commands, it is assumed that the pins have already been
+properly configured for input or output.
+@deffn Command {at91sam9 rdy_busy} num pio_base_addr pin
+Configure the RDY/nBUSY input from the NAND device. The @var{num}
+parameter is the value shown by @command{nand list}. @var{pio_base_addr}
+is the base address of the PIO controller and @var{pin} is the pin number.
+@end deffn
+@deffn Command {at91sam9 ce} num pio_base_addr pin
+Configure the chip enable input to the NAND device. The @var{num}
+parameter is the value shown by @command{nand list}. @var{pio_base_addr}
+is the base address of the PIO controller and @var{pin} is the pin number.
+@end deffn
+@end deffn
+
@deffn {NAND Driver} davinci
This driver handles the NAND controllers found on DaVinci family
chips from Texas Instruments.
Exits the current telnet session.
@end deffn
-@c note EXTREMELY ANNOYING word wrap at column 75
-@c even when lines are e.g. 100+ columns ...
-@c coded in startup.tcl
@deffn {Command} help [string]
With no parameters, prints help text for all commands.
Otherwise, prints each helptext containing @var{string}.
Not every command provides helptext.
+
+Configuration commands, and commands valid at any time, are
+explicitly noted in parenthesis.
+In most cases, no such restriction is listed; this indicates commands
+which are only available after the configuration stage has completed.
@end deffn
@deffn Command sleep msec [@option{busy}]
@deffn Command reg [(number|name) [value]]
Access a single register by @var{number} or by its @var{name}.
+The target must generally be halted before access to CPU core
+registers is allowed. Depending on the hardware, some other
+registers may be accessible while the target is running.
@emph{With no arguments}:
list all available registers for the current target,
showing number, name, size, value, and cache status.
+For valid entries, a value is shown; valid entries
+which are also dirty (and will be written back later)
+are flagged as such.
@emph{With number/name}: display that register's value.
@emph{With both number/name and value}: set register's value.
+Writes may be held in a writeback cache internal to OpenOCD,
+so that setting the value marks the register as dirty instead
+of immediately flushing that value. Resuming CPU execution
+(including by single stepping) or otherwise activating the
+relevant module will flush such values.
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)
+===== ARM registers
+(0) r0 (/32): 0x0000D3C2 (dirty)
+(1) r1 (/32): 0xFD61F31C
+(2) r2 (/32)
...
-(164) ETM_CONTEXTID_COMPARATOR_MASK (/32): \
- 0x00000000 (dirty: 0, valid: 0)
+(164) ETM_contextid_comparator_mask (/32)
>
@end example
@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}).
+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
+
+At this writing (November 2009) only ARM7, ARM9, and ARM11 support
for ETM modules is available. The code should be able to
work with some newer cores; but not all of them support
this original style of JTAG access.
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}
-Displays status of the current target's ETM:
+Displays status of the current target's ETM and trace port driver:
is the ETM idle, or is it collecting data?
Did trace data overflow?
Was it triggered?
and any buffered trace data is invalidated.
@itemize
-@item @var{type} ... one of
+@item @var{type} ... describing how data accesses are traced,
+when they pass any ViewData filtering that that was set up.
+The value is one of
@option{none} (save nothing),
@option{data} (save data),
@option{address} (save addresses),
@option{all} (save data and addresses)
@item @var{context_id_bits} ... 0, 8, 16, or 32
@item @var{cycle_accurate} ... @option{enable} or @option{disable}
-@item @var{branch_output} ... @option{enable} or @option{disable}
+cycle-accurate instruction tracing.
+Before ETMv3, enabling this causes much extra data to be recorded.
+@item @var{branch_output} ... @option{enable} or @option{disable}.
+Disable this unless you need to try reconstructing the instruction
+trace stream without an image of the code.
@end itemize
@end deffn
-@deffn Command {etm trigger_percent} percent
-@emph{Buggy and effectively a NOP ... @var{percent} from 2..100}
+@deffn Command {etm trigger_debug} (@option{enable}|@option{disable})
+Displays whether ETM triggering debug entry (like a breakpoint) is
+enabled or disabled, after optionally modifying that configuration.
+The default behaviour is @option{disable}.
+Any change takes effect after the next @command{etm start}.
+
+By using script commands to configure ETM registers, you can make the
+processor enter debug state automatically when certain conditions,
+more complex than supported by the breakpoint hardware, happen.
@end deffn
@subsection ETM Trace Operation
Associates the ETM for @var{target} with the ETB at @var{etb_tap}.
You can see the ETB registers using the @command{reg} command.
@end deffn
+@deffn Command {etb trigger_percent} [percent]
+This displays, or optionally changes, ETB behavior after the
+ETM's configured @emph{trigger} event fires.
+It controls how much more trace data is saved after the (single)
+trace trigger becomes active.
+
+@itemize
+@item The default corresponds to @emph{trace around} usage,
+recording 50 percent data before the event and the rest
+afterwards.
+@item The minimum value of @var{percent} is 2 percent,
+recording almost exclusively data before the trigger.
+Such extreme @emph{trace before} usage can help figure out
+what caused that event to happen.
+@item The maximum value of @var{percent} is 100 percent,
+recording data almost exclusively after the event.
+This extreme @emph{trace after} usage might help sort out
+how the event caused trouble.
+@end itemize
+@c REVISIT allow "break" too -- enter debug mode.
+@end deffn
+
@end deffn
@deffn {Trace Port Driver} oocd_trace
@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.
If @option{thumb} is specified, or the low bit of the address is set,
-Thumb (16-bit) instructions are used;
+Thumb2 (mixed 16/32-bit) instructions are used;
else ARM (32-bit) instructions are used.
(Processors may also support the Jazelle state, but
those instructions are not currently understood by OpenOCD.)
+
+Note that all Thumb instructions are Thumb2 instructions,
+so older processors (without Thumb2 support) will still
+see correct disassembly of Thumb code.
+Also, ThumbEE opcodes are the same as Thumb2,
+with a handful of exceptions.
+ThumbEE disassembly currently has no explicit support.
+@end deffn
+
+@deffn Command {arm mcr} pX op1 CRn CRm op2 value
+Write @var{value} to a coprocessor @var{pX} register
+passing parameters @var{CRn},
+@var{CRm}, opcodes @var{opc1} and @var{opc2},
+and using the MCR instruction.
+(Parameter sequence matches the ARM instruction, but omits
+an ARM register.)
+@end deffn
+
+@deffn Command {arm mrc} pX coproc op1 CRn CRm op2
+Read a coprocessor @var{pX} register passing parameters @var{CRn},
+@var{CRm}, opcodes @var{opc1} and @var{opc2},
+and the MRC instruction.
+Returns the result so it can be manipulated by Jim scripts.
+(Parameter sequence matches the ARM instruction, but omits
+an ARM register.)
@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.
+core mode if necessary.
@end deffn
+@section ARMv4 and ARMv5 Architecture
+@cindex ARMv4
+@cindex ARMv5
+
+The ARMv4 and ARMv5 architectures are widely used in embedded systems,
+and introduced core parts of the instruction set in use today.
+That includes the Thumb instruction set, introduced in the ARMv4T
+variant.
+
@subsection ARM7 and ARM9 specific commands
@cindex ARM7
@cindex ARM9
These commands are specific to ARM7 and ARM9 cores, like ARM7TDMI, ARM720T,
ARM9TDMI, ARM920T or ARM926EJ-S.
-They are available in addition to the ARMv4/5 commands,
+They are available in addition to the ARM commands,
and any other core-specific commands that may be available.
-@deffn Command {arm7_9 dbgrq} (@option{enable}|@option{disable})
-Control use of the EmbeddedIce DBGRQ signal to force entry into debug mode,
-instead of breakpoints. This should be
-safe for all but ARM7TDMI--S cores (like Philips LPC).
+@deffn Command {arm7_9 dbgrq} [@option{enable}|@option{disable}]
+Displays the value of the flag controlling use of the
+the EmbeddedIce DBGRQ signal to force entry into debug mode,
+instead of breakpoints.
+If a boolean parameter is provided, first assigns that flag.
+
+This should be
+safe for all but ARM7TDMI-S cores (like NXP LPC).
This feature is enabled by default on most ARM9 cores,
including ARM9TDMI, ARM920T, and ARM926EJ-S.
@end deffn
-@deffn Command {arm7_9 dcc_downloads} (@option{enable}|@option{disable})
+@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
+Displays the value of the flag controlling use of the debug communications
+channel (DCC) to write larger (>128 byte) amounts of memory.
+If a boolean parameter is provided, first assigns that flag.
+
+DCC downloads offer a huge speed increase, but might be
unsafe, especially with targets running at very low speeds. This command was introduced
with OpenOCD rev. 60, and requires a few bytes of working area.
@end deffn
@anchor{arm7_9 fast_memory_access}
-@deffn Command {arm7_9 fast_memory_access} (@option{enable}|@option{disable})
-Enable or disable memory writes and reads that don't check completion of
-the operation. This provides a huge speed increase, especially with USB JTAG
+@deffn Command {arm7_9 fast_memory_access} [@option{enable}|@option{disable}]
+Displays the value of the flag controlling use of memory writes and reads
+that don't check completion of the operation.
+If a boolean parameter is provided, first assigns that flag.
+
+This provides a huge speed increase, especially with USB JTAG
cables (FT2232), but might be unsafe if used with targets running at very low
speeds, like the 32kHz startup clock of an AT91RM9200.
@end deffn
-@deffn {Debug Command} {arm7_9 write_core_reg} num mode word
-@emph{This is intended for use while debugging OpenOCD; you probably
-shouldn't use it.}
+@deffn Command {arm7_9 semihosting} [@option{enable}|@option{disable}]
+@cindex ARM semihosting
+Display status of semihosting, after optionally changing that status.
-Writes a 32-bit @var{word} to register @var{num} (from 0 to 16)
-as used in the specified @var{mode}
-(where e.g. mode 16 is "user" and mode 19 is "supervisor";
-the M4..M0 bits of the PSR).
-Registers 0..15 are the normal CPU registers such as r0(0), r1(1) ... pc(15).
-Register 16 is the mode-specific SPSR,
-unless the specified mode is 0xffffffff (32-bit all-ones)
-in which case register 16 is the CPSR.
-The write goes directly to the CPU, bypassing the register cache.
-@end deffn
-
-@deffn {Debug Command} {arm7_9 write_xpsr} word (@option{0}|@option{1})
-@emph{This is intended for use while debugging OpenOCD; you probably
-shouldn't use it.}
-
-If the second parameter is zero, writes @var{word} to the
-Current Program Status register (CPSR).
-Else writes @var{word} to the current mode's Saved PSR (SPSR).
-In both cases, this bypasses the register cache.
-@end deffn
-
-@deffn {Debug Command} {arm7_9 write_xpsr_im8} byte rotate (@option{0}|@option{1})
-@emph{This is intended for use while debugging OpenOCD; you probably
-shouldn't use it.}
-
-Writes eight bits to the CPSR or SPSR,
-first rotating them by @math{2*rotate} bits,
-and bypassing the register cache.
-This has lower JTAG overhead than writing the entire CPSR or SPSR
-with @command{arm7_9 write_xpsr}.
+Semihosting allows for code executing on an ARM target to use the
+I/O facilities on the host computer i.e. the system where OpenOCD
+is running. The target application must be linked against a library
+implementing the ARM semihosting convention that forwards operation
+requests by using a special SVC instruction that is trapped at the
+Supervisor Call vector by OpenOCD.
@end deffn
@subsection ARM720T specific commands
These commands are available to ARM720T based CPUs,
which are implementations of the ARMv4T architecture
based on the ARM7TDMI-S integer core.
-They are available in addition to the ARMv4/5 and ARM7/ARM9 commands.
-
-@deffn Command {arm720t cp15} regnum [value]
-Display cp15 register @var{regnum};
-else if a @var{value} is provided, that value is written to that register.
-@end deffn
-
-@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
+They are available in addition to the ARM and ARM7/ARM9 commands.
-@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 cp15} opcode [value]
+@emph{DEPRECATED -- avoid using this.
+Use the @command{arm mrc} or @command{arm mcr} commands instead.}
-@deffn Command {arm720t virt2phys} va
-Translate a virtual address @var{va} to a physical address
-and display the result.
+Display cp15 register returned by the ARM instruction @var{opcode};
+else if a @var{value} is provided, that value is written to that register.
+The @var{opcode} should be the value of either an MRC or MCR instruction.
@end deffn
@subsection ARM9 specific commands
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
These commands are available to ARM920T based CPUs,
which are implementations of the ARMv4T architecture
built using the ARM9TDMI integer core.
-They are available in addition to the ARMv4/5, ARM7/ARM9,
-and ARM9TDMI commands.
+They are available in addition to the ARM, ARM7/ARM9,
+and ARM9 commands.
@deffn Command {arm920t cache_info}
Print information about the caches found. This allows to see whether your target
@deffn Command {arm920t cp15} regnum [value]
Display cp15 register @var{regnum};
else if a @var{value} is provided, that value is written to that register.
+This uses "physical access" and the register number is as
+shown in bits 38..33 of table 9-9 in the ARM920T TRM.
+(Not all registers can be written.)
@end deffn
@deffn Command {arm920t cp15i} opcode [value [address]]
-Interpreted access using cp15 @var{opcode}.
+@emph{DEPRECATED -- avoid using this.
+Use the @command{arm mrc} or @command{arm mcr} commands instead.}
+
+Interpreted access using ARM instruction @var{opcode}, which should
+be the value of either an MRC or MCR instruction
+(as shown tables 9-11, 9-12, and 9-13 in the ARM920T TRM).
If no @var{value} is provided, the result is displayed.
Else if that value is written using the specified @var{address},
-or using zero if no other address is not provided.
-@end deffn
-
-@deffn Command {arm920t 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}.
+or using zero if no other address is provided.
@end deffn
@deffn Command {arm920t read_cache} filename
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
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.
+They are available in addition to the ARM, ARM7/ARM9,
+and ARM9 commands.
The Feroceon cores also support these commands, although
they are not built from ARM926ej-s designs.
Print information about the caches found.
@end deffn
-@deffn Command {arm926ejs cp15} opcode1 opcode2 CRn CRm regnum [value]
-Accesses cp15 register @var{regnum} using
-@var{opcode1}, @var{opcode2}, @var{CRn}, and @var{CRm}.
-If a @var{value} is provided, that value is written to that register.
-Else that register is read and displayed.
-@end deffn
-
-@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
These commands are available to ARM966 based CPUs,
which are implementations of the ARMv5TE architecture.
-They are available in addition to the ARMv4/5, ARM7/ARM9,
-and ARM9TDMI commands.
+They are available in addition to the ARM, ARM7/ARM9,
+and ARM9 commands.
@deffn Command {arm966e cp15} regnum [value]
Display cp15 register @var{regnum};
else if a @var{value} is provided, that value is written to that register.
+The six bit @var{regnum} values are bits 37..32 from table 7-2 of the
+ARM966E-S TRM.
+There is no current control over bits 31..30 from that table,
+as required for BIST support.
@end deffn
@subsection XScale specific commands
Changes the address used for the specified target's debug handler.
@end deffn
-@deffn Command {xscale dcache} (@option{enable}|@option{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} (@option{enable}|@option{disable})
+@deffn Command {xscale icache} [@option{enable}|@option{disable}]
Enables or disable the CPU's instruction cache.
@end deffn
-@deffn Command {xscale mmu} (@option{enable}|@option{disable})
+@deffn Command {xscale mmu} [@option{enable}|@option{disable}]
Enables or disable the CPU's memory management unit.
@end deffn
-@deffn Command {xscale trace_buffer} (@option{enable}|@option{disable}) [@option{fill} [n] | @option{wrap}]
-Enables or disables the trace buffer,
-and controls how it is emptied.
+@deffn Command {xscale trace_buffer} [@option{enable}|@option{disable} [@option{fill} [n] | @option{wrap}]]
+Displays the trace buffer status, after optionally
+enabling or disabling the trace buffer
+and modifying how it is emptied.
@end deffn
@deffn Command {xscale trace_image} filename [offset [type]]
@end deffn
@anchor{xscale vector_table}
-@deffn Command {xscale vector_table} [<low|high> <index> <value>]
+@deffn Command {xscale vector_table} [(@option{low}|@option{high}) index value]
@cindex vector_table
Set an entry in the mini-IC vector table. There are two tables: one for
@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]
+@deffn Command {arm11 memwrite burst} [@option{enable}|@option{disable}]
Displays the value of the memwrite burst-enable flag,
which is enabled by default.
-If @var{value} is defined, first assigns that.
+If a boolean parameter is provided, first assigns that flag.
+Burst writes are only used for memory writes larger than 1 word.
+They improve performance by assuming that the CPU has read each data
+word over JTAG and completed its write before the next word arrives,
+instead of polling for a status flag to verify that completion.
+This is usually safe, because JTAG runs much slower than the CPU.
@end deffn
-@deffn Command {arm11 memwrite error_fatal} [value]
+@deffn Command {arm11 memwrite error_fatal} [@option{enable}|@option{disable}]
Displays the value of the memwrite error_fatal flag,
which is enabled by default.
-If @var{value} is defined, first assigns that.
+If a boolean parameter is provided, first assigns that flag.
+When set, certain memory write errors cause earlier transfer termination.
@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]
+@deffn Command {arm11 step_irq_enable} [@option{enable}|@option{disable}]
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.
+IRQs are enabled during single stepping;
+they are disabled by default.
+If a boolean parameter is provided, first assigns that.
@end deffn
-@deffn Command {arm11 step_irq_enable} [value]
-Displays the value of the flag controlling whether
-IRQs are enabled during single stepping;
-they is disabled by default.
+@deffn Command {arm11 vcr} [value]
+@cindex vector_catch
+Displays the value of the @emph{Vector Catch Register (VCR)},
+coprocessor 14 register 7.
If @var{value} is defined, first assigns that.
+
+Vector Catch hardware provides dedicated breakpoints
+for certain hardware events.
+The specific bit values are core-specific (as in fact is using
+coprocessor 14 register 7 itself) but all current ARM11
+cores @emph{except the ARM1176} use the same six bits.
@end deffn
@section ARMv7 Architecture
@cindex 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.
+included on Cortex-M3 and Cortex-A8 systems.
They are available in addition to other core-specific commands that may be available.
-@deffn Command {dap info} [num]
-Displays dap info for ap @var{num}, defaulting to the currently selected AP.
+@deffn Command {dap apid} [num]
+Displays ID register from AP @var{num},
+defaulting to the currently selected AP.
@end deffn
@deffn Command {dap apsel} [num]
Select AP @var{num}, defaulting to 0.
@end deffn
-@deffn Command {dap apid} [num]
-Displays id register from AP @var{num},
+@deffn Command {dap baseaddr} [num]
+Displays debug base address from MEM-AP @var{num},
defaulting to the currently selected AP.
@end deffn
-@deffn Command {dap baseaddr} [num]
-Displays debug base address from AP @var{num},
+@deffn Command {dap info} [num]
+Displays the ROM table for MEM-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].
+Displays the number of extra tck cycles in the JTAG idle to use for MEM-AP
+memory bus access [0-255], giving additional time to respond to reads.
If @var{value} is defined, first assigns that.
@end deffn
-@subsection ARMv7-A specific commands
-@cindex ARMv7-A
-
-@deffn Command {armv7a disassemble} address [count [@option{thumb}]]
-@cindex disassemble
-Disassembles @var{count} instructions starting at @var{address}.
-If @var{count} is not specified, a single instruction is disassembled.
-If @option{thumb} is specified, or the low bit of the address is set,
-Thumb2 (mixed 16/32-bit) instructions are used;
-else ARM (32-bit) instructions are used.
-With a handful of exceptions, ThumbEE instructions are the same as Thumb2;
-ThumbEE disassembly currently has no explicit support.
-(Processors may also support the Jazelle state, but
-those instructions are not currently understood by OpenOCD.)
-@end deffn
-
-
@subsection Cortex-M3 specific commands
@cindex Cortex-M3
@cindex tracing
@cindex libdcc
@cindex DCC
-OpenOCD can process certain requests from target software. Currently
-@command{target_request debugmsgs}
+OpenOCD can process certain requests from target software, when
+the target uses appropriate libraries.
+The most powerful mechanism is semihosting, but there is also
+a lighter weight mechanism using only the DCC channel.
+
+Currently @command{target_request debugmsgs}
is supported only for @option{arm7_9} and @option{cortex_m3} cores.
These messages are received as part of target polling, so
you need to have @command{poll on} active to receive them.
otherwise the libdcc format is used.
@end deffn
-@deffn Command {trace history} (@option{clear}|count)
+@deffn Command {trace history} [@option{clear}|count]
With no parameter, displays all the trace points that have triggered
in the order they triggered.
With the parameter @option{clear}, erases all current trace history records.
history records.
@end deffn
-@deffn Command {trace point} (@option{clear}|identifier)
+@deffn Command {trace point} [@option{clear}|identifier]
With no parameter, displays all trace point identifiers and how many times
they have been triggered.
With the parameter @option{clear}, erases all current trace point counters.
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
@cindex GDB
OpenOCD complies with the remote gdbserver protocol, and as such can be used
to debug remote targets.
+Setting up GDB to work with OpenOCD can involve several components:
+
+@itemize
+@item OpenOCD itself may need to be configured. @xref{GDB Configuration}.
+@item GDB itself may need configuration, as shown in this chapter.
+@item If you have a GUI environment like Eclipse,
+that also will probably need to be configured.
+@end itemize
+
+Of course, the version of GDB you use will need to be one which has
+been built to know about the target CPU you're using. It's probably
+part of the tool chain you're using. For example, if you are doing
+cross-development for ARM on an x86 PC, instead of using the native
+x86 @command{gdb} command you might use @command{arm-none-eabi-gdb}
+if that's the tool chain used to compile your code.
@anchor{Connecting to GDB}
@section Connecting to GDB
@cindex Connecting to GDB
Use GDB 6.7 or newer with OpenOCD if you run into trouble. For
instance GDB 6.3 has a known bug that produces bogus memory access
-errors, which has since been fixed: look up 1836 in
-@url{http://sourceware.org/cgi-bin/gnatsweb.pl?database=gdb}
+errors, which has since been fixed; see
+@url{http://osdir.com/ml/gdb.bugs.discuss/2004-12/msg00018.html}
OpenOCD can communicate with GDB in two ways:
To list the available OpenOCD commands type @command{monitor help} on the
GDB command line.
+@section Sample GDB session startup
+
+With the remote protocol, GDB sessions start a little differently
+than they do when you're debugging locally.
+Here's an examples showing how to start a debug session with a
+small ARM program.
+In this case the program was linked to be loaded into SRAM on a Cortex-M3.
+Most programs would be written into flash (address 0) and run from there.
+
+@example
+$ arm-none-eabi-gdb example.elf
+(gdb) target remote localhost:3333
+Remote debugging using localhost:3333
+...
+(gdb) monitor reset halt
+...
+(gdb) load
+Loading section .vectors, size 0x100 lma 0x20000000
+Loading section .text, size 0x5a0 lma 0x20000100
+Loading section .data, size 0x18 lma 0x200006a0
+Start address 0x2000061c, load size 1720
+Transfer rate: 22 KB/sec, 573 bytes/write.
+(gdb) continue
+Continuing.
+...
+@end example
+
+You could then interrupt the GDB session to make the program break,
+type @command{where} to show the stack, @command{list} to show the
+code around the program counter, @command{step} through code,
+set breakpoints or watchpoints, and so on.
+
+@section Configuring GDB for OpenOCD
+
OpenOCD supports the gdb @option{qSupported} packet, this enables information
to be sent by the GDB remote server (i.e. OpenOCD) to GDB. Typical information includes
packet size and the device's memory map.
+You do not need to configure the packet size by hand,
+and the relevant parts of the memory map should be automatically
+set up when you declare (NOR) flash banks.
+
+However, there are other things which GDB can't currently query.
+You may need to set those up by hand.
+As OpenOCD starts up, you will often see a line reporting
+something like:
-Previous versions of OpenOCD required the following GDB options to increase
-the packet size and speed up GDB communication:
@example
-set remote memory-write-packet-size 1024
-set remote memory-write-packet-size fixed
-set remote memory-read-packet-size 1024
-set remote memory-read-packet-size fixed
+Info : lm3s.cpu: hardware has 6 breakpoints, 4 watchpoints
@end example
-This is now handled in the @option{qSupported} PacketSize and should not be required.
+
+You can pass that information to GDB with these commands:
+
+@example
+set remote hardware-breakpoint-limit 6
+set remote hardware-watchpoint-limit 4
+@end example
+
+With that particular hardware (Cortex-M3) the hardware breakpoints
+only work for code running from flash memory. Most other ARM systems
+do not have such restrictions.
@section Programming using GDB
@cindex Programming using GDB
@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
-@item @b{winxx} Built using Microsoft Visual Studio
-@item @b{linux} Linux is the underlying operating sytem
-@item @b{darwin} Darwin (mac-os) is the underlying operating sytem.
@item @b{cygwin} Running under Cygwin
+@item @b{darwin} Darwin (Mac-OS) is the underlying operating sytem.
+@item @b{freebsd} Running under FreeBSD
+@item @b{linux} Linux is the underlying operating sytem
@item @b{mingw32} Running under MingW32
+@item @b{winxx} Built using Microsoft Visual Studio
@item @b{other} Unknown, none of the above.
@end itemize
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
@}
@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