-\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename openocd.info
-@settitle Open On-Chip Debugger (OpenOCD)
+@settitle OpenOCD User's Guide
@dircategory Development
@direntry
-@paragraphindent 0
-* OpenOCD: (openocd). Open On-Chip Debugger.
+* OpenOCD: (openocd). OpenOCD User's Guide
@end direntry
+@paragraphindent 0
@c %**end of header
@include version.texi
@copying
+This User's Guide documents
+release @value{VERSION},
+dated @value{UPDATED},
+of the Open On-Chip Debugger (OpenOCD).
+
@itemize @bullet
@item Copyright @copyright{} 2008 The OpenOCD Project
@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
@end copying
@titlepage
-@title Open On-Chip Debugger (OpenOCD)
-@subtitle Edition @value{EDITION} for OpenOCD version @value{VERSION}
+@titlefont{@emph{Open On-Chip Debugger:}}
+@sp 1
+@title OpenOCD User's Guide
+@subtitle for release @value{VERSION}
@subtitle @value{UPDATED}
+
@page
@vskip 0pt plus 1filll
@insertcopying
@summarycontents
@contents
-@node Top, About, , (dir)
-@top OpenOCD
-
-This manual documents edition @value{EDITION} of the Open On-Chip Debugger
-(OpenOCD) version @value{VERSION}, @value{UPDATED}.
+@ifnottex
+@node Top
+@top OpenOCD User's Guide
@insertcopying
+@end ifnottex
@menu
* About:: About OpenOCD
* Daemon Configuration:: Daemon Configuration
* Interface - Dongle Configuration:: Interface - Dongle Configuration
* Reset Configuration:: Reset Configuration
-* Tap Creation:: Tap Creation
-* Target Configuration:: Target Configuration
+* TAP Creation:: TAP Creation
+* CPU Configuration:: CPU Configuration
* Flash Commands:: Flash Commands
* NAND Flash Commands:: NAND Flash Commands
* General Commands:: General Commands
+* Architecture and Core Commands:: Architecture and Core Commands
* JTAG Commands:: JTAG Commands
* Sample Scripts:: Sample Target Scripts
* TFTP:: TFTP
* FAQ:: Frequently Asked Questions
* Tcl Crash Course:: Tcl Crash Course
* License:: GNU Free Documentation License
+
@comment DO NOT use the plain word ``Index'', reason: CYGWIN filename
@comment case issue with ``Index.html'' and ``index.html''
@comment Occurs when creating ``--html --no-split'' output
devices.
@b{JTAG:} OpenOCD uses a ``hardware interface dongle'' to communicate
-with the JTAG (IEEE 1149.1) compliant taps on your target board.
+with the JTAG (IEEE 1149.1) compliant TAPs on your target board.
+A @dfn{TAP} is a ``Test Access Port'', a module which processes
+special instructions and data. TAPs are daisy-chained within and
+between chips and boards.
@b{Dongles:} OpenOCD currently supports many types of hardware dongles: USB
based, parallel port based, and other standalone boxes that run
@uref{http://openocd.berlios.de/web/}
+@section Latest User's Guide:
+
+The user's guide you are now reading may not be the latest one
+available. A version for more recent code may be available.
+Its HTML form is published irregularly at:
+
+@uref{http://openocd.berlios.de/doc/}
+
+PDF form is likewise published at:
+
+@uref{http://openocd.berlios.de/doc/pdf/}
+
+@section OpenOCD User's Forum
+
+There is an OpenOCD forum (phpBB) hosted by SparkFun:
+
+@uref{http://forum.sparkfun.com/viewforum.php?f=18}
+
@node Developers
@chapter OpenOCD Developer Resources
The OpenOCD Developer Mailing List provides the primary means of
communication between developers:
- @uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
+@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}
+@uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
+
@node Building OpenOCD
@chapter Building OpenOCD
svn checkout svn://svn.berlios.de/openocd/trunk openocd
@end example
-Building OpenOCD requires a recent version of the GNU autotools (autoconf >= 2.59 and automake >= 1.9).
+If you prefer GIT based tools, the @command{git-svn} package works too:
+
+@example
+ git svn clone -s svn://svn.berlios.de/openocd
+@end example
+
+Building OpenOCD from a repository requires a recent version of the
+GNU autotools (autoconf >= 2.59 and automake >= 1.9).
For building on Windows,
you have to use Cygwin. Make sure that your @env{PATH} environment variable contains no
other locations with Unix utils (like UnxUtils) - these can't handle the Cygwin
board file. Boards may also contain multiple targets, i.e.: Two CPUs, or
a CPU and an FPGA or CPLD.
@item @b{target}
-@* Think chip. The ``target'' directory represents a JTAG tap (or
-chip) OpenOCD should control, not a board. Two common types of targets
+@* Think chip. The ``target'' directory represents the JTAG TAPs
+on a chip
+which OpenOCD should control, not a board. Two common types of targets
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.
@end itemize
@b{If needed...} The user in their ``openocd.cfg'' file or the board
@enumerate
@item Set defaults
-@item Create taps
+@item Add TAPs to the scan chain
+@item Add CPU targets
@item Reset configuration
-@item Work areas
@item CPU/Chip/CPU-Core specific features
@item On-Chip flash
@end enumerate
# variable: _TARGETNAME = network.cpu
# other commands can refer to the "network.cpu" tap.
$_TARGETNAME configure .... params for this CPU..
-
+
set ENDIAN little
set CHIPNAME video
source [find target/pxa270.cfg]
# variable: _TARGETNAME = video.cpu
# other commands can refer to the "video.cpu" tap.
$_TARGETNAME configure .... params for this CPU..
-
+
unset ENDIAN
set CHIPNAME xilinx
source [find target/spartan3.cfg]
# these names still work!
network.cpu configure ... params
video.cpu configure ... params
-
@end example
@subsection Default Value Boiler Plate Code
@example
# SIMPLE example
-if @{ [info exists CHIPNAME] @} @{
- set _CHIPNAME $CHIPNAME
-@} else @{
+if @{ [info exists CHIPNAME] @} @{
+ set _CHIPNAME $CHIPNAME
+@} else @{
set _CHIPNAME sam7x256
@}
-if @{ [info exists ENDIAN] @} @{
- set _ENDIAN $ENDIAN
-@} else @{
+if @{ [info exists ENDIAN] @} @{
+ set _ENDIAN $ENDIAN
+@} else @{
set _ENDIAN little
@}
@} else @{
set _CPUTAPID 0x3f0f0f0f
@}
-
@end example
-@subsection Creating Taps
-After the ``defaults'' are choosen [see above] the taps are created.
+@subsection Adding TAPs to the Scan Chain
+After the ``defaults'' are set up,
+add the TAPs on each chip to the JTAG scan chain.
+@xref{TAP Creation}, and the naming convention
+for taps.
-@b{SIMPLE example:} such as an Atmel AT91SAM7X256
+In the simplest case the chip has only one TAP,
+probably for a CPU or FPGA.
+The config file for the Atmel AT91SAM7X256
+looks (in part) like this:
@example
-# for an ARM7TDMI.
-set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf \
-expected-id $_CPUTAPID
@end example
-@b{COMPLEX example:}
+A board with two such at91sam7 chips would be able
+to source such a config file twice, with different
+values for @code{CHIPNAME} and @code{CPUTAPID}, so
+it adds a different TAP each time.
-This is an SNIP/example for an STR912 - which has 3 internal taps. Key features shown:
+There are more complex examples too, with chips that have
+multiple TAPs. Ones worth looking at include:
-@enumerate
-@item @b{Unform tap names} - See: Tap Naming Convention
-@item @b{_TARGETNAME} is created at the end where used.
-@end enumerate
-
-@example
-if @{ [info exists FLASHTAPID ] @} @{
- set _FLASHTAPID $FLASHTAPID
-@} else @{
- set _FLASHTAPID 0x25966041
-@}
-jtag newtap $_CHIPNAME flash -irlen 8 -ircapture 0x1 -irmask 0x1 \
- -expected-id $_FLASHTAPID
-
-if @{ [info exists CPUTAPID ] @} @{
- set _CPUTAPID $CPUTAPID
-@} else @{
- set _CPUTAPID 0x25966041
-@}
-jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0xf -irmask 0xe \
- -expected-id $_CPUTAPID
+@itemize
+@item @file{target/omap3530.cfg} -- with a disabled ARM, and a JRC
+(there's a DSP too, which is not listed)
+@item @file{target/str912.cfg} -- with flash, CPU, and boundary scan
+@item @file{target/ti_dm355.cfg} -- with ETM, ARM, and JRC (this JRC
+is not currently used)
+@end itemize
+@subsection Add CPU targets
-if @{ [info exists BSTAPID ] @} @{
- set _BSTAPID $BSTAPID
-@} else @{
- set _BSTAPID 0x1457f041
-@}
-jtag newtap $_CHIPNAME bs -irlen 5 -ircapture 0x1 -irmask 0x1 \
- -expected-id $_BSTAPID
+After adding a TAP for a CPU, you should set it up so that
+GDB and other commands can use it.
+@xref{CPU Configuration}.
+For the at91sam7 example above, the command can look like this:
-set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
+@example
+target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME
@end example
-@b{Tap Naming Convention}
-
-See the command ``jtag newtap'' for detail, but in brief the names you should use are:
+Work areas are small RAM areas associated with CPU targets.
+They are used by OpenOCD to speed up downloads,
+and to download small snippets of code to program flash chips.
+If the chip includes a form of ``on-chip-ram'' - and many do - define
+a work area if you can.
+Again using the at91sam7 as an example, this can look like:
-@itemize @bullet
-@item @b{tap}
-@item @b{cpu}
-@item @b{flash}
-@item @b{bs}
-@item @b{etb}
-@item @b{jrc}
-@item @b{unknownN} - it happens :-(
-@end itemize
+@example
+$_TARGETNAME configure -work-area-phys 0x00200000 \
+ -work-area-size 0x4000 -work-area-backup 0
+@end example
@subsection Reset Configuration
managed. If these are @b{CHIP SPECIFIC} they go here, if they are
@b{BOARD SPECIFIC} they go in the board file.
-@subsection Work Areas
-
-Work areas are small RAM areas used by OpenOCD to speed up downloads,
-and to download small snippets of code to program flash chips.
-
-If the chip includes a form of ``on-chip-ram'' - and many do - define
-a reasonable work area and use the ``backup'' option.
-
-@b{PROBLEMS:} On more complex chips, this ``work area'' may become
-inaccessible if/when the application code enables or disables the MMU.
-
@subsection ARM Core Specific Hacks
If the chip has a DCC, enable it. If the chip is an ARM9 with some
examination of the instruction and data bus activity. Trace
activity is controlled through an ``Embedded Trace Module'' (ETM)
on one of the core's scan chains. The ETM emits voluminous data
-through a ``trace port''. The trace port is accessed in one
-of two ways. When its signals are pinned out from the chip,
-boards may provide a special high speed debugging connector;
-software support for this is not configured by default, use
-the ``--enable-oocd_trace'' option. Alternatively, trace data
-may be stored an on-chip SRAM which is packaged as an ``Embedded
-Trace Buffer'' (ETB). An ETB has its own TAP, usually right after
-its associated ARM core. OpenOCD supports the ETM, and your
-target configuration should set it up with the relevant trace
-port: ``etb'' for chips which use that, else the board-specific
-option will be either ``oocd_trace'' or ``dummy''.
+through a ``trace port''. (@xref{ARM Tracing}.)
+If you are using an external trace port,
+configure it in your board config file.
+If you are using an on-chip ``Embedded Trace Buffer'' (ETB),
+configure it in your target config file.
@example
etm config $_TARGETNAME 16 normal full etb
@* JIM-Tcl was introduced to OpenOCD in spring 2008.
@item @b{Need a crash course in Tcl?}
-@* See: @xref{Tcl Crash Course}.
+@*@xref{Tcl Crash Course}.
@end itemize
@node Daemon Configuration
the port @var{number} defaults to 4444.
@end deffn
-@section GDB Configuration
@anchor{GDB Configuration}
+@section GDB Configuration
@cindex GDB
@cindex GDB configuration
You can reconfigure some GDB behaviors if needed.
@xref{Target Create}, about declaring individual targets.
@xref{Target Events}, about configuring target-specific event handling.
-@deffn {Command} gdb_breakpoint_override <hard|soft|disable>
@anchor{gdb_breakpoint_override}
+@deffn {Command} gdb_breakpoint_override <hard|soft|disable>
Force breakpoint type for gdb @command{break} commands.
The raison d'etre for this option is to support GDB GUI's which don't
distinguish hard versus soft breakpoints, if the default OpenOCD and
Default behaviour is @var{resume}.
@end deffn
-@deffn {Config command} gdb_flash_program <enable|disable>
@anchor{gdb_flash_program}
+@deffn {Config command} gdb_flash_program <enable|disable>
Set to @var{enable} to cause OpenOCD to program the flash memory when a
vFlash packet is received.
The default behaviour is @var{enable}.
@verbatim
interface arm-jtag-ew
@end verbatim
-@section Interface Command
+
+@section Interface Configuration
The interface command tells OpenOCD what type of JTAG dongle you are
using. Depending on the type of dongle, you may need to have one or
more additional commands.
-@itemize @bullet
+@deffn {Config Command} {interface} name
+Use the interface driver @var{name} to connect to the
+target.
+@end deffn
+
+@deffn Command {jtag interface}
+Returns the name of the interface driver being used.
+@end deffn
-@item @b{interface} <@var{name}>
-@cindex interface
-@*Use the interface driver <@var{name}> to connect to the
-target. Currently supported interfaces are
+@section Interface Drivers
+
+Currently supported interface drivers are:
@itemize @minus
@item @b{arm-jtag-ew}
@* Olimex ARM-JTAG-EW USB adapter
-@comment - End parameters
-@end itemize
-@comment - End Interface
@end itemize
+
@subsection parport options
@itemize @bullet
The OpenOCD default value is 2 and for some systems a value of 10 has proved useful.
@end itemize
-@subsection ep93xx options
-@cindex ep93xx options
-Currently, there are no options available for the ep93xx interface.
-
-@section JTAG Speed
@anchor{JTAG Speed}
+@section JTAG Speed
JTAG clock setup is part of system setup.
It @emph{does not belong with interface setup} since any interface
only knows a few of the constraints for the JTAG clock speed.
board-specific script might do things like setting up DRAM.
(@xref{Reset Command}.)
-@section SRST and TRST Signal Issues
+@section SRST and TRST Issues
Because SRST and TRST are hardware signals, they can have a
variety of system-specific constraints. Some of the most
signals to both levels (push/pull) to minimize rise times.
Use the @command{reset_config} @var{trst_type} and
@var{srst_type} parameters to say how to drive reset signals.
+
+@item @emph{Special initialization} ... Targets sometimes need
+special JTAG initialization sequences to handle chip-specific
+issues (not limited to errata).
+For example, certain JTAG commands might need to be issued while
+the system as a whole is in a reset state (SRST active)
+but the JTAG scan chain is usable (TRST inactive).
+(@xref{JTAG Commands}, where the @command{jtag_reset}
+command is presented.)
@end itemize
There can also be other issues.
@deffn {Command} reset_config mode_flag ...
This command tells OpenOCD the reset configuration
-of your combination of JTAG interface, board, and target.
+of your combination of JTAG board and target in target
+configuration scripts.
+
+If you have an interface that does not support SRST and
+TRST(unlikely), then you may be able to work around that
+problem by using a reset_config command to override any
+settings in the target configuration script.
+
+SRST and TRST has a fairly well understood definition and
+behaviour in the JTAG specification, but vendors take
+liberties to achieve various more or less clearly understood
+goals. Sometimes documentation is available, other times it
+is not. OpenOCD has the reset_config command to allow OpenOCD
+to deal with the various common cases.
The @var{mode_flag} options can be specified in any order, but only one
of each type -- @var{signals}, @var{combination}, @var{trst_type},
@end deffn
-@node Tap Creation
-@chapter Tap Creation
-@cindex tap creation
-@cindex tap configuration
+@node TAP Creation
+@chapter TAP Creation
+@cindex TAP creation
+@cindex TAP configuration
-In order for OpenOCD to control a target, a JTAG tap must be
-defined/created.
+@emph{Test Access Ports} (TAPs) are the core of JTAG.
+TAPs serve many roles, including:
-Commands to create taps are normally found in a configuration file and
-are not normally typed by a human.
-
-When a tap is created a @b{dotted.name} is created for the tap. Other
-commands use that dotted.name to manipulate or refer to the tap.
-
-Tap Uses:
@itemize @bullet
-@item @b{Debug Target} A tap can be used by a GDB debug target
-@item @b{Flash Programing} Some chips program the flash directly via JTAG,
-instead of indirectly by making a CPU do it.
-@item @b{Boundry Scan} Some chips support boundary scan.
+@item @b{Debug Target} A CPU TAP can be used as a GDB debug target
+@item @b{Flash Programing} Some chips program the flash directly via JTAG.
+Others do it indirectly, making a CPU do it.
+@item @b{Program Download} Using the same CPU support GDB uses,
+you can initialize a DRAM controller, download code to DRAM, and then
+start running that code.
+@item @b{Boundary Scan} Most chips support boundary scan, which
+helps test for board assembly problems like solder bridges
+and missing connections
@end itemize
+OpenOCD must know about the active TAPs on your board(s).
+Setting up the TAPs is the core task of your configuration files.
+Once those TAPs are set up, you can pass their names to code
+which sets up CPUs and exports them as GDB targets,
+probes flash memory, performs low-level JTAG operations, and more.
+
+@section Scan Chains
+
+OpenOCD uses a JTAG adapter (interface) to talk to your board,
+which has a daisy chain of TAPs.
+That daisy chain is called a @dfn{scan chain}.
+Simple configurations may have a single TAP in the scan chain,
+perhaps for a microcontroller.
+Complex configurations might have a dozen or more TAPs:
+several in one chip, more in the next, and connecting
+to other boards with their own chips and TAPs.
+
+Unfortunately those TAPs can't always be autoconfigured,
+because not all devices provide good support for that.
+(JTAG doesn't require supporting IDCODE instructions.)
+The configuration mechanism currently supported by OpenOCD
+requires explicit configuration of all TAP devices using
+@command{jtag newtap} commands.
+One like this would create a tap named @code{chip1.cpu}:
-@section jtag newtap
-@b{@t{jtag newtap CHIPNAME TAPNAME configparams ....}}
-@cindex jtag_device
-@cindex jtag newtap
-@cindex tap
-@cindex tap order
-@cindex tap geometry
+@example
+jtag newtap chip1 cpu -irlen 7 -ircapture 0x01 -irmask 0x55
+@end example
+
+Each target configuration file lists the TAPs provided
+by a given chip.
+Board configuration files combine all the targets on a board,
+and so forth.
+Note that @emph{the order in which TAPs are created is very important.}
+It must match the order in the JTAG scan chain, both inside
+a single chip and between them.
+
+For example, the ST Microsystems STR912 chip has
+three separate TAPs@footnote{See the ST
+document titled: @emph{STR91xFAxxx, Section 3.15 Jtag Interface, Page:
+28/102, Figure 3: JTAG chaining inside the STR91xFA}.
+@url{http://eu.st.com/stonline/products/literature/ds/13495.pdf}
+Checked: 28-Nov-2008}.
+To configure those taps, @file{target/str912.cfg}
+includes commands something like this:
-@comment START options
-@itemize @bullet
-@item @b{CHIPNAME}
-@* is a symbolic name of the chip.
-@item @b{TAPNAME}
-@* is a symbol name of a tap present on the chip.
-@item @b{Required configparams}
-@* Every tap has 3 required configparams, and several ``optional
-parameters'', the required parameters are:
-@comment START REQUIRED
-@itemize @bullet
-@item @b{-irlen NUMBER} - the length in bits of the instruction register, mostly 4 or 5 bits.
-@item @b{-ircapture NUMBER} - the IDCODE capture command, usually 0x01.
-@item @b{-irmask NUMBER} - the corresponding mask for the IR register. For
-some devices, there are bits in the IR that aren't used. This lets you mask
-them off when doing comparisons. In general, this should just be all ones for
-the size of the IR.
-@comment END REQUIRED
-@end itemize
-An example of a FOOBAR Tap
@example
-jtag newtap foobar tap -irlen 7 -ircapture 0x42 -irmask 0x55
+jtag newtap str912 flash ... params ...
+jtag newtap str912 cpu ... params ...
+jtag newtap str912 bs ... params ...
@end example
-Creates the tap ``foobar.tap'' with the instruction register (IR) is 7
-bits long, during Capture-IR 0x42 is loaded into the IR, and bits
-[6,4,2,0] are checked.
-@item @b{Optional configparams}
-@comment START Optional
+Actual config files use a variable instead of literals like
+@option{str912}, to support more than one chip of each type.
+@xref{Config File Guidelines}.
+
+@section TAP Names
+
+When a TAP objects is created with @command{jtag newtap},
+a @dfn{dotted.name} is created for the TAP, combining the
+name of a module (usually a chip) and a label for the TAP.
+For example: @code{xilinx.tap}, @code{str912.flash},
+@code{omap3530.jrc}, @code{dm6446.dsp}, or @code{stm32.cpu}.
+Many other commands use that dotted.name to manipulate or
+refer to the TAP. For example, CPU configuration uses the
+name, as does declaration of NAND or NOR flash banks.
+
+The components of a dotted name should follow ``C'' symbol
+name rules: start with an alphabetic character, then numbers
+and underscores are OK; while others (including dots!) are not.
+
+@quotation Tip
+In older code, JTAG TAPs were numbered from 0..N.
+This feature is still present.
+However its use is highly discouraged, and
+should not be counted upon.
+Update all of your scripts to use TAP names rather than numbers.
+Using TAP numbers in target configuration scripts prevents
+reusing on boards with multiple targets.
+@end quotation
+
+@anchor{TAP Creation Commands}
+@section TAP Creation Commands
+
+@c shouldn't this be(come) a {Config Command}?
+@anchor{jtag newtap}
+@deffn Command {jtag newtap} chipname tapname configparams...
+Creates a new TAP with the dotted name @var{chipname}.@var{tapname},
+and configured according to the various @var{configparams}.
+
+The @var{chipname} is a symbolic name for the chip.
+Conventionally target config files use @code{$_CHIPNAME},
+defaulting to the model name given by the chip vendor but
+overridable.
+
+@cindex TAP naming convention
+The @var{tapname} reflects the role of that TAP,
+and should follow this convention:
+
@itemize @bullet
-@item @b{-expected-id NUMBER}
-@* By default it is zero. If non-zero represents the
-expected tap ID used when the JTAG chain is examined. Repeat
-the option as many times as required if multiple id's can be
-expected. See below.
-@item @b{-disable}
-@item @b{-enable}
-@* By default not specified the tap is enabled. Some chips have a
-JTAG route controller (JRC) that is used to enable and/or disable
-specific JTAG taps. You can later enable or disable any JTAG tap via
-the command @b{jtag tapenable DOTTED.NAME} or @b{jtag tapdisable
-DOTTED.NAME}
-@comment END Optional
+@item @code{bs} -- For boundary scan if this is a seperate TAP;
+@item @code{cpu} -- The main CPU of the chip, alternatively
+@code{arm} and @code{dsp} on chips with both ARM and DSP CPUs,
+@code{arm1} and @code{arm2} on chips two ARMs, and so forth;
+@item @code{etb} -- For an embedded trace buffer (example: an ARM ETB11);
+@item @code{flash} -- If the chip has a flash TAP, like the str912;
+@item @code{jrc} -- For JTAG route controller (example: the ICEpick modules
+on many Texas Instruments chips, like the OMAP3530 on Beagleboards);
+@item @code{tap} -- Should be used only FPGA or CPLD like devices
+with a single TAP;
+@item @code{unknownN} -- If you have no idea what the TAP is for (N is a number);
+@item @emph{when in doubt} -- Use the chip maker's name in their data sheet.
+For example, the Freescale IMX31 has a SDMA (Smart DMA) with
+a JTAG TAP; that TAP should be named @code{sdma}.
@end itemize
-@comment END OPTIONS
-@end itemize
-@b{Notes:}
-@comment START NOTES
-@itemize @bullet
-@item @b{Technically}
-@* newtap is a sub command of the ``jtag'' command
-@item @b{Big Picture Background}
-@*GDB Talks to OpenOCD using the GDB protocol via
-TCP/IP. OpenOCD then uses the JTAG interface (the dongle) to
-control the JTAG chain on your board. Your board has one or more chips
-in a @i{daisy chain configuration}. Each chip may have one or more
-JTAG taps. GDB ends up talking via OpenOCD to one of the taps.
-@item @b{NAME Rules}
-@*Names follow ``C'' symbol name rules (start with alpha ...)
-@item @b{TAPNAME - Conventions}
+Every TAP requires at least the following @var{configparams}:
+
@itemize @bullet
-@item @b{tap} - should be used only FPGA or CPLD like devices with a single tap.
-@item @b{cpu} - the main CPU of the chip, alternatively @b{foo.arm} and @b{foo.dsp}
-@item @b{flash} - if the chip has a flash tap, example: str912.flash
-@item @b{bs} - for boundary scan if this is a seperate tap.
-@item @b{etb} - for an embedded trace buffer (example: an ARM ETB11)
-@item @b{jrc} - for JTAG route controller (example: OMAP3530 found on Beagleboards)
-@item @b{unknownN} - where N is a number if you have no idea what the tap is for
-@item @b{Other names} - Freescale IMX31 has a SDMA (smart dma) with a JTAG tap, that tap should be called the ``sdma'' tap.
-@item @b{When in doubt} - use the chip maker's name in their data sheet.
+@item @code{-ircapture} @var{NUMBER}
+@*The IDCODE capture command, such as 0x01.
+@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
-@item @b{DOTTED.NAME}
-@* @b{CHIPNAME}.@b{TAPNAME} creates the tap name, aka: the
-@b{Dotted.Name} is the @b{CHIPNAME} and @b{TAPNAME} combined with a
-dot (period); for example: @b{xilinx.tap}, @b{str912.flash},
-@b{omap3530.jrc}, or @b{stm32.cpu} The @b{dotted.name} is used in
-numerous other places to refer to various taps.
-@item @b{ORDER}
-@* The order this command appears via the config files is
-important.
-@item @b{Multi Tap Example}
-@* This example is based on the ST Microsystems STR912. See the ST
-document titled: @b{STR91xFAxxx, Section 3.15 Jtag Interface, Page:
-28/102, Figure 3: JTAG chaining inside the STR91xFA}.
-@url{http://eu.st.com/stonline/products/literature/ds/13495.pdf}
-@*@b{checked: 28/nov/2008}
+A TAP may also provide optional @var{configparams}:
-The diagram shows that the TDO pin connects to the flash tap, flash TDI
-connects to the CPU debug tap, CPU TDI connects to the boundary scan
-tap which then connects to the TDI pin.
+@itemize @bullet
+@item @code{-disable} (or @code{-enable})
+@*Use the @code{-disable} paramater to flag a TAP which is not
+linked in to the scan chain when it is declared.
+You may use @code{-enable} to highlight the default state
+(the TAP is linked in).
+@xref{Enabling and Disabling TAPs}.
+@item @code{-expected-id} @var{number}
+@*A non-zero value represents the expected 32-bit IDCODE
+found when the JTAG 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).
+@end itemize
+@end deffn
-@example
- # The order is...
- # create tap: 'str912.flash'
- jtag newtap str912 flash ... params ...
- # create tap: 'str912.cpu'
- jtag newtap str912 cpu ... params ...
- # create tap: 'str912.bs'
- jtag newtap str912 bs ... params ...
-@end example
+@c @deffn Command {jtag arp_init-reset}
+@c ... more or less "init" ?
-@item @b{Note: Deprecated} - Index Numbers
-@* Prior to 28/nov/2008, JTAG taps where numbered from 0..N this
-feature is still present, however its use is highly discouraged and
-should not be counted upon. Update all of your scripts to use
-TAP names rather than numbers.
-@item @b{Multiple chips}
-@* If your board has multiple chips, you should be
-able to @b{source} two configuration files, in the proper order, and
-have the taps created in the proper order.
-@comment END NOTES
-@end itemize
-@comment at command level
-@comment DOCUMENT old command
-@section jtag_device - REMOVED
-@example
-@b{jtag_device} <@var{IR length}> <@var{IR capture}> <@var{IR mask}> <@var{IDCODE instruction}>
-@end example
-@cindex jtag_device
-
-@* @b{Removed: 28/nov/2008} This command has been removed and replaced
-by the ``jtag newtap'' command. The documentation remains here so that
-one can easily convert the old syntax to the new syntax. About the old
-syntax: The old syntax is positional, i.e.: The 3rd parameter is the
-``irmask''. The new syntax requires named prefixes, and supports
-additional options, for example ``-expected-id 0x3f0f0f0f''. Please refer to the
-@b{jtag newtap} command for details.
-@example
-OLD: jtag_device 8 0x01 0xe3 0xfe
-NEW: jtag newtap CHIPNAME TAPNAME -irlen 8 -ircapture 0x01 -irmask 0xe3
-@end example
+@anchor{Enabling and Disabling TAPs}
+@section Enabling and Disabling TAPs
+@cindex TAP events
-@section Enable/Disable Taps
-@b{Note:} These commands are intended to be used as a machine/script
-interface. Humans might find the ``scan_chain'' command more helpful
-when querying the state of the JTAG taps.
+In some systems, a @dfn{JTAG Route Controller} (JRC)
+is used to enable and/or disable specific JTAG TAPs.
+Many ARM based chips from Texas Instruments include
+an ``ICEpick'' module, which is a JRC.
+Such chips include DaVinci and OMAP3 processors.
-@b{By default, all taps are enabled}
+A given TAP may not be visible until the JRC has been
+told to link it into the scan chain; and if the JRC
+has been told to unlink that TAP, it will no longer
+be visible.
+Such routers address problems that JTAG ``bypass mode''
+ignores, such as:
-@itemize @bullet
-@item @b{jtag tapenable} @var{DOTTED.NAME}
-@item @b{jtag tapdisable} @var{DOTTED.NAME}
-@item @b{jtag tapisenabled} @var{DOTTED.NAME}
+@itemize
+@item The scan chain can only go as fast as its slowest TAP.
+@item Having many TAPs slows instruction scans, since all
+TAPs receive new instructions.
+@item TAPs in the scan chain must be powered up, which wastes
+power and prevents debugging some power management mechanisms.
@end itemize
-@cindex tap enable
-@cindex tap disable
-@cindex JRC
-@cindex route controller
-These commands are used when your target has a JTAG route controller
-that effectively adds or removes a tap from the JTAG chain in a
-non-standard way.
+The IEEE 1149.1 JTAG standard has no concept of a ``disabled'' tap,
+as implied by the existence of JTAG routers.
+However, the upcoming IEEE 1149.7 framework (layered on top of JTAG)
+does include a kind of JTAG router functionality.
-The ``standard way'' to remove a tap would be to place the tap in
-bypass mode. But with the advent of modern chips, this is not always a
-good solution. Some taps operate slowly, others operate fast, and
-there are other JTAG clock synchronisation problems one must face. To
-solve that problem, the JTAG route controller was introduced. Rather
-than ``bypass'' the tap, the tap is completely removed from the
-circuit and skipped.
+@c (a) currently the event handlers don't seem to be able to
+@c fail in a way that could lead to no-change-of-state.
+@c (b) eventually non-event configuration should be possible,
+@c in which case some this documentation must move.
+@deffn Command {jtag cget} dotted.name @option{-event} name
+@deffnx Command {jtag configure} dotted.name @option{-event} name string
+At this writing this mechanism is used only for event handling,
+and the only two events relate to TAP enabling and disabling.
-From OpenOCD's point of view, a JTAG tap is in one of 3 states:
+The @code{configure} subcommand assigns an event handler,
+a TCL string which is evaluated when the event is triggered.
+The @code{cget} subcommand returns that handler.
+The two possible values for an event @var{name}
+are @option{tap-disable} and @option{tap-enable}.
-@itemize @bullet
-@item @b{Enabled - Not In ByPass} and has a variable bit length
-@item @b{Enabled - In ByPass} and has a length of exactly 1 bit.
-@item @b{Disabled} and has a length of ZERO and is removed from the circuit.
-@end itemize
+So for example, when defining a TAP for a CPU connected to
+a JTAG router, you should define TAP event handlers using
+code that looks something like this:
-The IEEE JTAG definition has no concept of a ``disabled'' tap.
-@b{Historical note:} this feature was added 28/nov/2008
+@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
+@end deffn
-@b{jtag tapisenabled DOTTED.NAME}
+@deffn Command {jtag tapdisable} dotted.name
+@deffnx Command {jtag tapenable} dotted.name
+@deffnx Command {jtag tapisenabled} dotted.name
+These three commands all return the string "1" if the tap
+specified by @var{dotted.name} is enabled,
+and "0" if it is disbabled.
+The @command{tapenable} variant first enables the tap
+by sending it a @option{tap-enable} event.
+The @command{tapdisable} variant first disables the tap
+by sending it a @option{tap-disable} event.
-This command returns 1 if the named tap is currently enabled, 0 if not.
-This command exists so that scripts that manipulate a JRC (like the
-OMAP3530 has) can determine if OpenOCD thinks a tap is presently
-enabled or disabled.
+@quotation Note
+Humans will find the @command{scan_chain} command more helpful
+than the script-oriented @command{tapisenabled}
+for querying the state of the JTAG taps.
+@end quotation
+@end deffn
-@page
-@node Target Configuration
-@chapter Target Configuration
+@node CPU Configuration
+@chapter CPU Configuration
@cindex GDB target
-This chapter discusses how to create a GDB debug target. Before
-creating a ``target'' a JTAG tap DOTTED.NAME must exist first.
+This chapter discusses how to create a GDB debug target for a CPU.
+You can also access these targets without GDB
+(@pxref{Architecture and Core Commands}) and, where relevant,
+through various kinds of NAND and NOR flash commands.
+Also, if you have multiple CPUs you can have multiple such targets.
+
+Before creating a ``target'', you must have added its TAP to the scan chain.
+When you've added that TAP, you will have a @code{dotted.name}
+which is used to set up the CPU support.
+The chip-specific configuration file will normally configure its CPU(s)
+right after it adds all of the chip's TAPs to the scan chain.
@section targets [NAME]
-@b{Note:} This command name is PLURAL - not singular.
+@b{Note:} This command name is PLURAL - not singular.
With NO parameter, this plural @b{targets} command lists all known
targets in a human friendly form.
Example:
@verbatim
(gdb) mon targets
- CmdName Type Endian ChainPos State
+ CmdName Type Endian ChainPos State
-- ---------- ---------- ---------- -------- ----------
0: target0 arm7tdmi little 0 halted
@end verbatim
@* Lists all supported target types (perhaps some are not yet in this document).
@item @b{names}
@* Lists all current debug target names, for example: 'str912.cpu' or 'pxa27.cpu' example usage:
-@verbatim
+@verbatim
foreach t [target names] {
puts [format "Target: %s\n" $t]
}
@section TARGETNAME (object) commands
@b{Use:} Once a target is created, an ``object name'' that represents the
target is created. By convention, the target name is identical to the
-tap name. In a multiple target system, one can preceed many common
+tap name. In a multiple target system, one can precede many common
commands with a specific target name and effect only that target.
@example
str912.cpu mww 0x1234 0x42
# Report
puts [format "The button is %s" $x]
@end example
-
+
In OpenOCD's terms, the ``target'' is an object just like a Tcl/Tk
button. Commands available as a ``target object'' are:
@* Invokes the specific event manually for the target
@end itemize
+@anchor{Target Events}
@section Target Events
@cindex events
-@anchor{Target Events}
At various times, certain things can happen, or you want them to happen.
Examples:
@}
mychip.cpu configure -event gdb-attach my_attach_proc
mychip.cpu configure -event gdb-attach @{
- puts "Reset..."
- reset halt
+ puts "Reset..."
+ reset halt
@}
@end example
@* Success
@item @b{resumed}
@* Target has resumed
-@item @b{tap-enable}
-@* Executed by @b{jtag tapenable DOTTED.NAME} command. Example:
-@example
-jtag configure DOTTED.NAME -event tap-enable @{
- puts "Enabling CPU"
- ...
-@}
-@end example
-@item @b{tap-disable}
-@*Executed by @b{jtag tapdisable DOTTED.NAME} command. Example:
-@example
-jtag configure DOTTED.NAME -event tap-disable @{
- puts "Disabling CPU"
- ...
-@}
-@end example
@end itemize
-@section Target Create
@anchor{Target Create}
+@section Target Create
@cindex target
@cindex target creation
@}
@end example
+@b{PROBLEM:} On more complex chips, the work area can become
+inaccessible when application code enables or disables the MMU.
+For example, the MMU context used to acess the virtual address
+will probably matter.
+
@section Target Variants
@itemize @bullet
@item @b{cortex_m3}
configuration command to enable OpenOCD hardware reset functionality.
@comment END variants
@end itemize
-@section working_area - Command Removed
-@cindex working_area
-@*@b{Please use the ``$_TARGETNAME configure -work-area-... parameters instead}
-@* This documentation remains because there are existing scripts that
-still use this that need to be converted.
-@example
- working_area target# address size backup| [virtualaddress]
-@end example
-@* The target# is a the 0 based target numerical index.
@node Flash Commands
@chapter Flash Commands
is that for read access, it acts exactly like any other addressible memory.
This means you can use normal memory read commands like @command{mdw} or
@command{dump_image} with it, with no special @command{flash} subcommands.
-@xref{Memory access}.
-@xref{Image access}.
+@xref{Memory access}, and @ref{Image access}.
Write access works differently. Flash memory normally needs to be erased
before it's written. Erasing a sector turns all of its bits to ones, and
@comment @option{flash erase_sector} using the same syntax.
@end deffn
-@section Flash Drivers, Options, and Commands
@anchor{Flash Driver List}
+@section Flash Drivers, Options, and Commands
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.
with the wrong ECC data can cause them to be marked as bad.
@end deffn
-@section NAND Drivers, Options, and Commands
@anchor{NAND Driver List}
+@section NAND Drivers, Options, and Commands
As noted above, the @command{nand device} command allows
driver-specific options and behaviors.
Some controllers also activate controller-specific commands.
@cindex shutdown
@*Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).
+@anchor{debug_level}
@subsection debug_level [@var{n}]
@cindex debug_level
-@anchor{debug_level}
@*Display or adjust debug level to n<0-3>
@subsection fast [@var{enable|disable}]
state.
-@section Memory access commands
@anchor{Memory access}
+@section Memory access commands
@subsection meminfo
-display available RAM memory.
+display available RAM memory on OpenOCD host. Used in OpenOCD regression testing scripts. Mainly
+useful on embedded targets, PC type hosts have complimentary tools like Valgrind to address
+resource tracking problems.
@subsection Memory peek/poke type commands
These commands allow accesses of a specific size to the memory
system. Often these are used to configure the current target in some
@*write memory byte (8bit)
@end itemize
-@section Image loading commands
@anchor{Image access}
+@section Image loading commands
+@anchor{load_image}
@subsection load_image
@b{load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
@cindex load_image
-@anchor{load_image}
@*Load image <@var{file}> to target memory at <@var{address}>
@subsection fast_load_image
@b{fast_load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
@cindex fast_load_image
-@anchor{fast_load_image}
@*Normally you should be using @b{load_image} or GDB load. However, for
testing purposes or when I/O overhead is significant(OpenOCD running on an embedded
host), storing the image in memory and uploading the image to the target
@subsection fast_load
@b{fast_load}
@cindex fast_image
-@anchor{fast_image}
@*Loads an image stored in memory by @b{fast_load_image} to the current target. Must be preceeded by fast_load_image.
+@anchor{dump_image}
@subsection dump_image
@b{dump_image} <@var{file}> <@var{address}> <@var{size}>
@cindex dump_image
-@anchor{dump_image}
@*Dump <@var{size}> bytes of target memory starting at <@var{address}> to a
(binary) <@var{file}>.
@subsection verify_image
@end itemize
-@section Architecture and Core Specific Commands
+@node Architecture and Core Commands
+@chapter Architecture and Core Commands
@cindex Architecture Specific Commands
@cindex Core Specific Commands
Most CPUs have specialized JTAG operations to support debugging.
OpenOCD packages most such operations in its standard command framework.
Some of those operations don't fit well in that framework, so they are
-exposed here using architecture or implementation specific commands.
+exposed here as architecture or implementation (core) specific commands.
+
+@anchor{ARM Tracing}
+@section ARM Tracing
+@cindex ETM
+@cindex ETB
+
+CPUs based on ARM cores may include standard tracing interfaces,
+based on an ``Embedded Trace Module'' (ETM) which sends voluminous
+address and data bus trace records to a ``Trace Port''.
+
+@itemize
+@item
+Development-oriented boards will sometimes provide a high speed
+trace connector for collecting that data, when the particular CPU
+supports such an interface.
+(The standard connector is a 38-pin Mictor, with both JTAG
+and trace port support.)
+Those trace connectors are supported by higher end JTAG adapters
+and some logic analyzer modules; frequently those modules can
+buffer several megabytes of trace data.
+Configuring an ETM coupled to such an external trace port belongs
+in the board-specific configuration file.
+@item
+If the CPU doesn't provide an external interface, it probably
+has an ``Embedded Trace Buffer'' (ETB) on the chip, which is a
+dedicated SRAM. 4KBytes is one common ETB size.
+Configuring an ETM coupled only to an ETB belongs in the CPU-specific
+(target) configuration file, since it works the same on all boards.
+@end itemize
+
+ETM support in OpenOCD doesn't seem to be widely used yet.
+
+@quotation Issues
+ETM support may be buggy, and at least some @command{etm config}
+parameters should be detected by asking the ETM for them.
+It seems like a GDB hookup should be possible,
+as well as triggering trace on specific events
+(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.
+@end quotation
+
+@subsection ETM Configuration
+ETM setup is coupled with the trace port driver configuration.
+
+@deffn {Config Command} {etm config} target width mode clocking driver
+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}.
+The @var{clocking} must be @option{half} or @option{full}.
+
+@quotation Note
+You can see the ETM registers using the @command{reg} command, although
+not all of those possible registers are present in every ETM.
+@end quotation
+@end deffn
+
+@deffn Command {etm info}
+Displays information about the current target's ETM.
+@end deffn
+
+@deffn Command {etm status}
+Displays status of the current target's ETM:
+is the ETM idle, or is it collecting data?
+Did trace data overflow?
+Was it triggered?
+@end deffn
+
+@deffn Command {etm tracemode} [type context_id_bits cycle_accurate branch_output]
+Displays what data that ETM will collect.
+If arguments are provided, first configures that data.
+When the configuration changes, tracing is stopped
+and any buffered trace data is invalidated.
+
+@itemize
+@item @var{type} ... 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}
+@end itemize
+@end deffn
+
+@deffn Command {etm trigger_percent} percent
+@emph{Buggy and effectively a NOP ... @var{percent} from 2..100}
+@end deffn
+
+@subsection ETM Trace Operation
+
+After setting up the ETM, you can use it to collect data.
+That data can be exported to files for later analysis.
+It can also be parsed with OpenOCD, for basic sanity checking.
+
+@deffn Command {etm analyze}
+Reads trace data into memory, if it wasn't already present.
+Decodes and prints the data that was collected.
+@end deffn
+
+@deffn Command {etm dump} filename
+Stores the captured trace data in @file{filename}.
+@end deffn
+
+@deffn Command {etm image} filename [base_address] [type]
+Opens an image file.
+@end deffn
+
+@deffn Command {etm load} filename
+Loads captured trace data from @file{filename}.
+@end deffn
+
+@deffn Command {etm start}
+Starts trace data collection.
+@end deffn
+
+@deffn Command {etm stop}
+Stops trace data collection.
+@end deffn
+
+@anchor{Trace Port Drivers}
+@subsection Trace Port Drivers
+
+To use an ETM trace port it must be associated with a driver.
+
+@deffn {Trace Port Driver} dummy
+Use the @option{dummy} driver if you are configuring an ETM that's
+not connected to anything (on-chip ETB or off-chip trace connector).
+@emph{This driver lets OpenOCD talk to the ETM, but it does not expose
+any trace data collection.}
+@deffn {Config Command} {etm_dummy config} target
+Associates the ETM for @var{target} with a dummy driver.
+@end deffn
+@end deffn
+
+@deffn {Trace Port Driver} etb
+Use the @option{etb} driver if you are configuring an ETM
+to use on-chip ETB memory.
+@deffn {Config Command} {etb config} target etb_tap
+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
+@end deffn
-@subsection ARMv4 and ARMv5 Architecture
+@deffn {Trace Port Driver} oocd_trace
+This driver isn't available unless OpenOCD was explicitly configured
+with the @option{--enable-oocd_trace} option. You probably don't want
+to configure it unless you've built the appropriate prototype hardware;
+it's @emph{proof-of-concept} software.
+
+Use the @option{oocd_trace} driver if you are configuring an ETM that's
+connected to an off-chip trace connector.
+
+@deffn {Config Command} {oocd_trace config} target tty
+Associates the ETM for @var{target} with a trace driver which
+collects data through the serial port @var{tty}.
+@end deffn
+
+@deffn Command {oocd_trace resync}
+Re-synchronizes with the capture clock.
+@end deffn
+
+@deffn Command {oocd_trace status}
+Reports whether the capture clock is locked or not.
+@end deffn
+@end deffn
+
+
+@section ARMv4 and ARMv5 Architecture
@cindex ARMv4 specific commands
@cindex ARMv5 specific commands
register value.
@end deffn
-@subsubsection ARM7 and ARM9 specific commands
+@subsection ARM7 and ARM9 specific commands
@cindex ARM7 specific commands
@cindex ARM9 specific commands
with @command{arm7_9 write_xpsr}.
@end deffn
-@subsubsection ARM720T specific commands
+@subsection ARM720T specific commands
@cindex ARM720T specific commands
These commands are available to ARM720T based CPUs,
and display the result.
@end deffn
-@subsubsection ARM9TDMI specific commands
+@subsection ARM9TDMI specific commands
@cindex ARM9TDMI specific commands
Many ARM9-family CPUs are built around ARM9TDMI integer cores,
@option{irq} @option{fiq}.
@end deffn
-@subsubsection ARM920T specific commands
+@subsection ARM920T specific commands
@cindex ARM920T specific commands
These commands are available to ARM920T based CPUs,
and display the result.
@end deffn
-@subsubsection ARM926EJ-S specific commands
+@subsection ARM926EJ-S specific commands
@cindex ARM926EJ-S specific commands
These commands are available to ARM926EJ-S based CPUs,
and display the result.
@end deffn
-@subsubsection ARM966E specific commands
+@subsection ARM966E specific commands
@cindex ARM966E specific commands
These commands are available to ARM966 based CPUs,
else if a @var{value} is provided, that value is written to that register.
@end deffn
-@subsubsection XScale specific commands
+@subsection XScale specific commands
@cindex XScale specific commands
These commands are available to XScale based CPUs,
Provide a bitmask showing the vectors to catch.
@end deffn
-@subsection ARMv6 Architecture
+@section ARMv6 Architecture
-@subsubsection ARM11 specific commands
+@subsection ARM11 specific commands
@cindex ARM11 specific commands
@deffn Command {arm11 mcr} p1 p2 p3 p4 p5
If @var{value} is defined, first assigns that.
@end deffn
-@subsection ARMv7 Architecture
+@section ARMv7 Architecture
+
+@subsection ARMv7 Debug Access Port (DAP) specific commands
+@cindex ARMv7 Debug Access Port (DAP) specific commands
+These commands are specific to ARM architecture v7 Debug Access Port (DAP),
+included on cortex-m3 and cortex-a8 systems.
+They are available in addition to other core-specific commands that may be available.
+
+@deffn Command {dap info} [num]
+Displays dap info for ap [num], default currently selected AP.
+@end deffn
+
+@deffn Command {dap apsel} [num]
+Select a different AP [num] (default 0).
+@end deffn
+
+@deffn Command {dap apid} [num]
+Displays id reg from AP [num], default currently selected AP.
+@end deffn
+
+@deffn Command {dap baseaddr} [num]
+Displays debug base address from AP [num], default currently selected AP.
+@end deffn
-@subsubsection Cortex-M3 specific commands
+@deffn Command {dap memaccess} [value]
+Displays the number of extra tck for mem-ap memory bus access [0-255].
+If value is defined, first assigns that.
+@end deffn
+
+@subsection Cortex-M3 specific commands
@cindex Cortex-M3 specific commands
@deffn Command {cortex_m3 maskisr} (on|off)
@deffn Command {target_request debugmsgs} [enable|disable|charmsg]
Displays current handling of target DCC message requests.
These messages may be sent to the debugger while the target is running.
-The optional @option{enable} and @option{charmsg} parameters are
-equivalent; both enable the messages, @option{disable} disables them.
+The optional @option{enable} and @option{charmsg} parameters
+both enable the messages, while @option{disable} disables them.
+With @option{charmsg} the DCC words each contain one character,
+as used by Linux with CONFIG_DEBUG_ICEDCC;
+otherwise the libdcc format is used.
@end deffn
@node JTAG Commands
@chapter JTAG Commands
@cindex JTAG Commands
-Generally most people will not use the bulk of these commands. They
-are mostly used by the OpenOCD developers or those who need to
-directly manipulate the JTAG taps.
-
-In general these commands control JTAG taps at a very low level. For
-example if you need to control a JTAG Route Controller (i.e.: the
-OMAP3530 on the Beagle Board has one) you might use these commands in
-a script or an event procedure.
-@section Commands
-@cindex Commands
+Most general purpose JTAG commands have been presented earlier.
+(@xref{JTAG Speed}, @ref{Reset Configuration}, and @ref{TAP Creation}.)
+Lower level JTAG commands, as presented here,
+may be needed to work with targets which require special
+attention during operations such as reset or initialization.
+
+To use these commands you will need to understand some
+of the basics of JTAG, including:
+
@itemize @bullet
-@item @b{scan_chain}
-@cindex scan_chain
-@*Print current scan chain configuration.
-@item @b{jtag_reset} <@var{trst}> <@var{srst}>
-@cindex jtag_reset
-@*Toggle reset lines.
-@item @b{endstate} <@var{tap_state}>
-@cindex endstate
-@*Finish JTAG operations in <@var{tap_state}>.
-@item @b{runtest} <@var{num_cycles}>
-@cindex runtest
-@*Move to Run-Test/Idle, and execute <@var{num_cycles}>
-@item @b{statemove} [@var{tap_state}]
-@cindex statemove
-@*Move to current endstate or [@var{tap_state}]
-@item @b{irscan} <@var{device}> <@var{instr}> [@var{dev2}] [@var{instr2}] ...
-@cindex irscan
-@*Execute IR scan <@var{device}> <@var{instr}> [@var{dev2}] [@var{instr2}] ...
-@item @b{drscan} <@var{device}> [@var{dev2}] [@var{var2}] ...
-@cindex drscan
-@*Execute DR scan <@var{device}> [@var{dev2}] [@var{var2}] ...
-@item @b{verify_ircapture} <@option{enable}|@option{disable}>
-@cindex verify_ircapture
-@*Verify value captured during Capture-IR. Default is enabled.
-@item @b{var} <@var{name}> [@var{num_fields}|@var{del}] [@var{size1}] ...
-@cindex var
-@*Allocate, display or delete variable <@var{name}> [@var{num_fields}|@var{del}] [@var{size1}] ...
-@item @b{field} <@var{var}> <@var{field}> [@var{value}|@var{flip}]
-@cindex field
-Display/modify variable field <@var{var}> <@var{field}> [@var{value}|@var{flip}].
+@item A JTAG scan chain consists of a sequence of individual TAP
+devices such as a CPUs.
+@item Control operations involve moving each TAP through the same
+standard state machine (in parallel)
+using their shared TMS and clock signals.
+@item Data transfer involves shifting data through the chain of
+instruction or data registers of each TAP, writing new register values
+while the reading previous ones.
+@item Data register sizes are a function of the instruction active in
+a given TAP, while instruction register sizes are fixed for each TAP.
+All TAPs support a BYPASS instruction with a single bit data register.
+@item The way OpenOCD differentiates between TAP devices is by
+shifting different instructions into (and out of) their instruction
+registers.
@end itemize
-@section Tap states
-@cindex Tap states
-Available tap_states are:
+@section Low Level JTAG Commands
+
+These commands are used by developers who need to access
+JTAG instruction or data registers, possibly controlling
+the order of TAP state transitions.
+If you're not debugging OpenOCD internals, or bringing up a
+new JTAG adapter or a new type of TAP device (like a CPU or
+JTAG router), you probably won't need to use these commands.
+
+@deffn Command {drscan} tap [numbits value]+ [@option{-endstate} tap_state]
+Loads the data register of @var{tap} with a series of bit fields
+that specify the entire register.
+Each field is @var{numbits} bits long with
+a numeric @var{value} (hexadecimal encouraged).
+The return value holds the original value of each
+of those fields.
+
+For example, a 38 bit number might be specified as one
+field of 32 bits then one of 6 bits.
+@emph{For portability, never pass fields which are more
+than 32 bits long. Many OpenOCD implementations do not
+support 64-bit (or larger) integer values.}
+
+All TAPs other than @var{tap} must be in BYPASS mode.
+The single bit in their data registers does not matter.
+
+When @var{tap_state} is specified, the JTAG state machine is left
+in that state.
+For example @sc{drpause} might be specified, so that more
+instructions can be issued before re-entering the @sc{run/idle} state.
+If the end state is not specified, the @sc{run/idle} state is entered.
+
+@quotation Warning
+OpenOCD does not record information about data register lengths,
+so @emph{it is important that you get the bit field lengths right}.
+Remember that different JTAG instructions refer to different
+data registers, which may have different lengths.
+Moreover, those lengths may not be fixed;
+the SCAN_N instruction can change the length of
+the register accessed by the INTEST instruction
+(by connecting a different scan chain).
+@end quotation
+@end deffn
+
+@deffn Command {flush_count}
+Returns the number of times the JTAG queue has been flushed.
+This may be used for performance tuning.
+
+For example, flushing a queue over USB involves a
+minimum latency, often several milliseconds, which does
+not change with the amount of data which is written.
+You may be able to identify performance problems by finding
+tasks which waste bandwidth by flushing small transfers too often,
+instead of batching them into larger operations.
+@end deffn
+
+@deffn Command {endstate} tap_state
+Flush any pending JTAG operations,
+and return with all TAPs in @var{tap_state}.
+This state should be a stable state such as @sc{reset},
+@sc{run/idle},
+@sc{drpause}, or @sc{irpause}.
+@end deffn
+
+@deffn Command {irscan} [tap instruction]+ [@option{-endstate} tap_state]
+For each @var{tap} listed, loads the instruction register
+with its associated numeric @var{instruction}.
+(The number of bits in that instruction may be displayed
+using the @command{scan_chain} command.)
+For other TAPs, a BYPASS instruction is loaded.
+
+When @var{tap_state} is specified, the JTAG state machine is left
+in that state.
+For example @sc{irpause} might be specified, so the data register
+can be loaded before re-entering the @sc{run/idle} state.
+If the end state is not specified, the @sc{run/idle} state is entered.
+
+@quotation Note
+OpenOCD currently supports only a single field for instruction
+register values, unlike data register values.
+For TAPs where the instruction register length is more than 32 bits,
+portable scripts currently must issue only BYPASS instructions.
+@end quotation
+@end deffn
+
+@deffn Command {jtag_reset} trst srst
+Set values of reset signals.
+The @var{trst} and @var{srst} parameter values may be
+@option{0}, indicating that reset is inactive (pulled or driven high),
+or @option{1}, indicating it is active (pulled or driven low).
+The @command{reset_config} command should already have been used
+to configure how the board and JTAG adapter treat these two
+signals, and to say if either signal is even present.
+@xref{Reset Configuration}.
+@end deffn
+
+@deffn Command {runtest} @var{num_cycles}
+Move to the @sc{run/idle} state, and execute at least
+@var{num_cycles} of the JTAG clock (TCK).
+Instructions often need some time
+to execute before they take effect.
+@end deffn
+
+@deffn Command {scan_chain}
+Displays the TAPs in the scan chain configuration,
+and their status.
+The set of TAPs listed by this command is fixed by
+exiting the OpenOCD configuration stage,
+but systems with a JTAG router can
+enable or disable TAPs dynamically.
+In addition to the enable/disable status, the contents of
+each TAP's instruction register can also change.
+@end deffn
+
+@c tms_sequence (short|long)
+@c ... temporary, debug-only, probably gone before 0.2 ships
+
+@deffn Command {verify_ircapture} (@option{enable}|@option{disable})
+Verify values captured during @sc{ircapture} and returned
+during IR scans. Default is enabled, but this can be
+overridden by @command{verify_jtag}.
+@end deffn
+
+@deffn Command {verify_jtag} (@option{enable}|@option{disable})
+Enables verification of DR and IR scans, to help detect
+programming errors. For IR scans, @command{verify_ircapture}
+must also be enabled.
+Default is enabled.
+@end deffn
+
+@section TAP state names
+@cindex TAP state names
+
+The @var{tap_state} names used by OpenOCD in the @command{drscan},
+@command{endstate}, and @command{irscan} commands are:
+
@itemize @bullet
@item @b{RESET}
-@cindex RESET
-@item @b{IDLE}
-@cindex IDLE
+@item @b{RUN/IDLE}
@item @b{DRSELECT}
-@cindex DRSELECT
@item @b{DRCAPTURE}
-@cindex DRCAPTURE
@item @b{DRSHIFT}
-@cindex DRSHIFT
@item @b{DREXIT1}
-@cindex DREXIT1
@item @b{DRPAUSE}
-@cindex DRPAUSE
@item @b{DREXIT2}
-@cindex DREXIT2
@item @b{DRUPDATE}
-@cindex DRUPDATE
@item @b{IRSELECT}
-@cindex IRSELECT
@item @b{IRCAPTURE}
-@cindex IRCAPTURE
@item @b{IRSHIFT}
-@cindex IRSHIFT
@item @b{IREXIT1}
-@cindex IREXIT1
@item @b{IRPAUSE}
-@cindex IRPAUSE
@item @b{IREXIT2}
-@cindex IREXIT2
@item @b{IRUPDATE}
-@cindex IRUPDATE
@end itemize
+Note that only six of those states are fully ``stable'' in the
+face of TMS fixed and a free-running JTAG clock; for all the
+others, the next TCK transition changes to a new state.
+
+@itemize @bullet
+@item @sc{reset} is probably most useful with @command{endstate},
+but entering it frequently has side effects.
+(This is the only stable state with TMS high.)
+@item From @sc{drshift} and @sc{irshift}, clock transitions will
+produce side effects by changing register contents. The values
+to be latched in upcoming @sc{drupdate} or @sc{irupdate} states
+may not be as expected.
+@item @sc{run/idle}, @sc{drpause}, and @sc{irpause} are reasonable
+choices after @command{drscan} or @command{irscan} commands,
+since they are free of side effects.
+@end itemize
@node TFTP
@chapter TFTP
OpenOCD complies with the remote gdbserver protocol, and as such can be used
to debug remote targets.
+@anchor{Connecting to GDB}
@section Connecting to GDB
@cindex Connecting to GDB
-@anchor{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
@node Upgrading
@chapter Deprecated/Removed Commands
@cindex Deprecated/Removed Commands
-Certain OpenOCD commands have been deprecated/removed during the various revisions.
+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}
@*Use @command{arm7_9 fast_memory_access} instead.
@xref{arm7_9 fast_memory_access}.
@item @b{arm7_9 force_hw_bkpts}
-@cindex 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}
-@cindex arm7_9 sw_bkpts
@*On by default. @xref{gdb_breakpoint_override}.
@item @b{daemon_startup}
-@cindex 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}
-@cindex dump_binary
@*use @option{dump_image} command with same args. @xref{dump_image}.
@item @b{flash erase}
-@cindex flash erase
@*use @option{flash erase_sector} command with same args. @xref{flash erase_sector}.
@item @b{flash write}
-@cindex flash write
@*use @option{flash write_bank} command with same args. @xref{flash write_bank}.
@item @b{flash write_binary}
-@cindex flash write_binary
@*use @option{flash write_bank} command with same args. @xref{flash write_bank}.
@item @b{flash auto_erase}
-@cindex 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
@end itemize
@item @b{load_binary}
-@cindex load_binary
@*use @option{load_image} command with same args. @xref{load_image}.
@item @b{run_and_halt_time}
-@cindex run_and_halt_time
@*This command has been removed for simpler reset behaviour, it can be simulated with the
following commands:
@smallexample
halt
@end smallexample
@item @b{target} <@var{type}> <@var{endian}> <@var{jtag-position}>
-@cindex target
@*use the create subcommand of @option{target}.
@item @b{target_script} <@var{target#}> <@var{eventname}> <@var{scriptname}>
-@cindex target_script
@*use <@var{target_name}> configure -event <@var{eventname}> "script <@var{scriptname}>"
@item @b{working_area}
-@cindex 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
@chapter FAQ
@cindex faq
@enumerate
-@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
@anchor{FAQ RTCK}
+@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
@cindex RTCK
@cindex adaptive clocking
@*
GDB issues software breakpoints when a normal breakpoint is requested, or to implement
source-line single-stepping. On ARMv4T systems, like ARM7TDMI, ARM720T or ARM920T,
-software breakpoints consume one of the two available hardware breakpoints.
+software breakpoints consume one of the two available hardware breakpoints.
@item @b{LPC2000 Flash} When erasing or writing LPC2000 on-chip flash, the operation fails at random.
arm7_9_execute_sys_speed(): timeout waiting for SYSCOMP
TODO.
-
+
@end enumerate
@node Tcl Crash Course
SetResult( interp, "WRONG number of parameters");
return ERROR;
@}
-
+
// argv[0] = the ascii string just like C
// Execute the start statement.
SetResult( interp, "" );
return SUCCESS;
@}
-@end example
+@end example
Every other command IF, WHILE, FORMAT, PUTS, EXPR, everything works
in the same basic way.
@* SOURCE reads a file and executes as a script.
@end enumerate
@subsection format command
-@b{Where:} Generally occurs in numerous places.
+@b{Where:} Generally occurs in numerous places.
@* Tcl has no command like @b{printf()}, instead it has @b{format}, which is really more like
@b{sprintf()}.
@b{Example}
Code Review / openocd.git / blobdiff