* 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
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
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
# these names still work!
network.cpu configure ... params
video.cpu configure ... params
-
@end example
@subsection Default Value Boiler Plate Code
@} 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
@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
+
+@section Interface Drivers
-@item @b{interface} <@var{name}>
-@cindex interface
-@*Use the interface driver <@var{name}> to connect to the
-target. Currently supported interfaces are
+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.
-
@anchor{JTAG Speed}
@section JTAG Speed
JTAG clock setup is part of system setup.
board-specific script might do things like setting up DRAM.
(@xref{Reset Command}.)
-@section SRST and TRST Signal Issues
+@section SRST and TRST Issues
Because SRST and TRST are hardware signals, they can have a
variety of system-specific constraints. Some of the most
signals to both levels (push/pull) to minimize rise times.
Use the @command{reset_config} @var{trst_type} and
@var{srst_type} parameters to say how to drive reset signals.
+
+@item @emph{Special initialization} ... Targets sometimes need
+special JTAG initialization sequences to handle chip-specific
+issues (not limited to errata).
+For example, certain JTAG commands might need to be issued while
+the system as a whole is in a reset state (SRST active)
+but the JTAG scan chain is usable (TRST inactive).
+(@xref{JTAG Commands}, where the @command{jtag_reset}
+command is presented.)
@end itemize
There can also be other issues.
@end deffn
-@node Tap Creation
-@chapter Tap Creation
-@cindex tap creation
-@cindex tap configuration
-
-In order for OpenOCD to control a target, a JTAG tap must be
-defined/created.
-
-Commands to create taps are normally found in a configuration file and
-are not normally typed by a human.
+@node TAP Creation
+@chapter TAP Creation
+@cindex TAP creation
+@cindex TAP configuration
-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.
+@emph{Test Access Ports} (TAPs) are the core of JTAG.
+TAPs serve many roles, including:
-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.
@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
@* 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
@anchor{Target Create}
@}
@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
has been locked. Halting the core is not required for the @option{str9xpec} driver
as mentioned above, just issue the commands above manually or from a telnet prompt.
-@subsubsection str9xpec driver options
-
-@b{flash bank str9xpec} <@var{base}> <@var{size}> 0 0 <@var{target}>
-@*Before using the flash commands the turbo mode must be enabled using str9xpec
-@option{enable_turbo} <@var{num>.}
-
+@deffn {Flash Driver} str9xpec
Only use this driver for locking/unlocking the device or configuring the option bytes.
Use the standard str9 driver for programming.
+Before using the flash commands the turbo mode must be enabled using the
+@command{str9xpec enable_turbo} command.
-@subsubsection str9xpec specific commands
-@cindex str9xpec specific commands
-These are flash specific commands when using the str9xpec driver.
+Several str9xpec-specific commands are defined:
-@itemize @bullet
-@item @b{str9xpec enable_turbo} <@var{num}>
-@cindex str9xpec enable_turbo
-@*enable turbo mode, will simply remove the str9 from the chain and talk
+@deffn Command {str9xpec disable_turbo} num
+Restore the str9 into JTAG chain.
+@end deffn
+
+@deffn Command {str9xpec enable_turbo} num
+Enable turbo mode, will simply remove the str9 from the chain and talk
directly to the embedded flash controller.
-@item @b{str9xpec disable_turbo} <@var{num}>
-@cindex str9xpec disable_turbo
-@*restore the str9 into JTAG chain.
-@item @b{str9xpec lock} <@var{num}>
-@cindex str9xpec lock
-@*lock str9 device. The str9 will only respond to an unlock command that will
+@end deffn
+
+@deffn Command {str9xpec lock} num
+Lock str9 device. The str9 will only respond to an unlock command that will
erase the device.
-@item @b{str9xpec unlock} <@var{num}>
-@cindex str9xpec unlock
-@*unlock str9 device.
-@item @b{str9xpec options_read} <@var{num}>
-@cindex str9xpec options_read
-@*read str9 option bytes.
-@item @b{str9xpec options_write} <@var{num}>
-@cindex str9xpec options_write
-@*write str9 option bytes.
-@end itemize
+@end deffn
-@subsubsection STR9 option byte configuration
-@cindex STR9 option byte configuration
+@deffn Command {str9xpec part_id} num
+Prints the part identifier for bank @var{num}.
+@end deffn
+
+@deffn Command {str9xpec options_cmap} num (@option{bank0}|@option{bank1})
+Configure str9 boot bank.
+@end deffn
+
+@deffn Command {str9xpec options_lvdsel} num (@option{vdd}|@option{vdd_vddq})
+Configure str9 lvd source.
+@end deffn
+
+@deffn Command {str9xpec options_lvdthd} num (@option{2.4v}|@option{2.7v})
+Configure str9 lvd threshold.
+@end deffn
+
+@deffn Command {str9xpec options_lvdwarn} bank (@option{vdd}|@option{vdd_vddq})
+Configure str9 lvd reset warning source.
+@end deffn
+
+@deffn Command {str9xpec options_read} num
+Read str9 option bytes.
+@end deffn
+
+@deffn Command {str9xpec options_write} num
+Write str9 option bytes.
+@end deffn
+
+@deffn Command {str9xpec unlock} num
+unlock str9 device.
+@end deffn
+
+@end deffn
-@itemize @bullet
-@item @b{str9xpec options_cmap} <@var{num}> <@option{bank0}|@option{bank1}>
-@cindex str9xpec options_cmap
-@*configure str9 boot bank.
-@item @b{str9xpec options_lvdthd} <@var{num}> <@option{2.4v}|@option{2.7v}>
-@cindex str9xpec options_lvdthd
-@*configure str9 lvd threshold.
-@item @b{str9xpec options_lvdsel} <@var{num}> <@option{vdd}|@option{vdd_vddq}>
-@cindex str9xpec options_lvdsel
-@*configure str9 lvd source.
-@item @b{str9xpec options_lvdwarn} <@var{bank}> <@option{vdd}|@option{vdd_vddq}>
-@cindex str9xpec options_lvdwarn
-@*configure str9 lvd reset warning source.
-@end itemize
@section mFlash
@subsection mFlash Configuration
@cindex mFlash Configuration
-@b{mflash bank} <@var{soc}> <@var{base}> <@var{RST pin}> <@var{target}>
-@cindex mflash bank
-@*Configures a mflash for <@var{soc}> host bank at
-<@var{base}>. Pin number format is dependent on host GPIO calling convention.
-Currently, mflash bank support s3c2440 and pxa270.
-(ex. of s3c2440) mflash <@var{RST pin}> is GPIO B1.
+@deffn {Config Command} {mflash bank} soc base RST_pin target
+Configures a mflash for @var{soc} host bank at
+address @var{base}.
+The pin number format depends on the host GPIO naming convention.
+Currently, the mflash driver supports s3c2440 and pxa270.
+
+Example for s3c2440 mflash where @var{RST pin} is GPIO B1:
@example
mflash bank s3c2440 0x10000000 1b 0
@end example
-(ex. of pxa270) mflash <@var{RST pin}> is GPIO 43.
+Example for pxa270 mflash where @var{RST pin} is GPIO 43:
@example
mflash bank pxa270 0x08000000 43 0
@end example
+@end deffn
@subsection mFlash commands
@cindex mFlash commands
-@itemize @bullet
-@item @b{mflash probe}
-@cindex mflash probe
-@*Probe mflash.
-@item @b{mflash write} <@var{num}> <@var{file}> <@var{offset}>
-@cindex mflash write
-@*Write the binary <@var{file}> to mflash bank <@var{num}>, starting at
-<@var{offset}> bytes from the beginning of the bank.
-@item @b{mflash dump} <@var{num}> <@var{file}> <@var{offset}> <@var{size}>
-@cindex mflash dump
-@*Dump <size> bytes, starting at <@var{offset}> bytes from the beginning of the <@var{num}> bank
-to a <@var{file}>.
-@item @b{mflash config pll} <@var{frequency}>
-@cindex mflash config pll
-@*Configure mflash pll. <@var{frequency}> is input frequency of mflash. The order is Hz.
+@deffn Command {mflash config pll} frequency
+Configure mflash PLL.
+The @var{frequency} is the mflash input frequency, in Hz.
Issuing this command will erase mflash's whole internal nand and write new pll.
After this command, mflash needs power-on-reset for normal operation.
If pll was newly configured, storage and boot(optional) info also need to be update.
-@item @b{mflash config boot}
-@cindex mflash config boot
-@*Configure bootable option. If bootable option is set, mflash offer the first 8 sectors
+@end deffn
+
+@deffn Command {mflash config boot}
+Configure bootable option.
+If bootable option is set, mflash offer the first 8 sectors
(4kB) for boot.
-@item @b{mflash config storage}
-@cindex mflash config storage
-@*Configure storage information. For the normal storage operation, this information must be
+@end deffn
+
+@deffn Command {mflash config storage}
+Configure storage information.
+For the normal storage operation, this information must be
written.
-@end itemize
+@end deffn
+
+@deffn Command {mflash dump} num filename offset size
+Dump @var{size} bytes, starting at @var{offset} bytes from the
+beginning of the bank @var{num}, to the file named @var{filename}.
+@end deffn
+
+@deffn Command {mflash probe}
+Probe mflash.
+@end deffn
+
+@deffn Command {mflash write} num filename offset
+Write the binary file @var{filename} to mflash bank @var{num}, starting at
+@var{offset} bytes from the beginning of the bank.
+@end deffn
@node NAND Flash Commands
@chapter NAND Flash Commands
@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}
-@subsection ARM Tracing
+@section ARM Tracing
@cindex ETM
@cindex ETB
shared with eventual Nexus-style trace module support.
@end quotation
-@subsubsection ETM Configuration
+@subsection ETM Configuration
ETM setup is coupled with the trace port driver configuration.
@deffn {Config Command} {etm config} target width mode clocking driver
@emph{Buggy and effectively a NOP ... @var{percent} from 2..100}
@end deffn
-@subsubsection ETM Trace Operation
+@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.
@end deffn
@anchor{Trace Port Drivers}
-@subsubsection Trace Port Drivers
+@subsection Trace Port Drivers
To use an ETM trace port it must be associated with a driver.
@end deffn
-@subsection ARMv4 and ARMv5 Architecture
+@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)
@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
@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
Code Review / openocd.git / blobdiff