Test Access Ports (TAPs) are the core of JTAG. TAPs serve many roles, including:
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.
TAPs are part of a hardware scan chain, which is daisy chain of TAPs. They also need to be added to OpenOCD's software mirror of that hardware list, giving each member a name and associating other data with it. Simple scan chains, with a single TAP, are common in systems with a single microcontroller or microprocessor. More complex chips may have several TAPs internally. Very complex scan chains 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.
You can display the list with the scan_chain command. (Don't confuse this with the list displayed by the targets command, presented in the next chapter. That only displays TAPs for CPUs which are configured as debugging targets.) Here's what the scan chain might look like for a chip more than one TAP:
TapName Enabled IdCode Expected IrLen IrCap IrMask Instr -- ------------------ ------- ---------- ---------- ----- ----- ------ ----- 0 omap5912.dsp Y 0x03df1d81 0x03df1d81 38 0 0 0x... 1 omap5912.arm Y 0x0692602f 0x0692602f 4 0x1 0 0xc 2 omap5912.unknown Y 0x00000000 0x00000000 8 0 0 0xff
Unfortunately those TAPs can't always be autoconfigured, because not all devices provide good support for that. JTAG doesn't require supporting IDCODE instructions, and chips with JTAG routers may not link TAPs into the chain until they are told to do so.
The configuration mechanism currently supported by OpenOCD
requires explicit configuration of all TAP devices using
jtag newtap commands, as detailed later in this chapter.
A command like this would declare one tap and name it chip1.cpu
:
jtag newtap chip1 cpu -irlen 7 -ircapture 0x01 -irmask 0x55
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 the order in which TAPs are declared is very important. It must match the order in the JTAG scan chain, both inside a single chip and between them. See FAQ TAP Order.
For example, the ST Microsystems STR912 chip has three separate TAPs1. To configure those taps, target/str912.cfg includes commands something like this:
jtag newtap str912 flash ... params ... jtag newtap str912 cpu ... params ... jtag newtap str912 bs ... params ...
Actual config files use a variable instead of literals like str912, to support more than one chip of each type. See Config File Guidelines.
At this writing there is only a single command to work with scan chains, and there is no support for enumerating TAPs or examining their attributes.
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.
When TAP objects are declared with jtag newtap,
a dotted.name is created for the TAP, combining the
name of a module (usually a chip) and a label for the TAP.
For example: xilinx.tap
, str912.flash
,
omap3530.jrc
, dm6446.dsp
, or 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.
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 those scripts on boards with multiple targets.
Declares a new TAP with the dotted name chipname.tapname, and configured according to the various configparams.
The chipname is a symbolic name for the chip. Conventionally target config files use
$_CHIPNAME
, defaulting to the model name given by the chip vendor but overridable.The tapname reflects the role of that TAP, and should follow this convention:
bs
– For boundary scan if this is a seperate TAP;cpu
– The main CPU of the chip, alternativelyarm
anddsp
on chips with both ARM and DSP CPUs,arm1
andarm2
on chips two ARMs, and so forth;etb
– For an embedded trace buffer (example: an ARM ETB11);flash
– If the chip has a flash TAP, like the str912;jrc
– For JTAG route controller (example: the ICEpick modules on many Texas Instruments chips, like the OMAP3530 on Beagleboards);tap
– Should be used only FPGA or CPLD like devices with a single TAP;unknownN
– If you have no idea what the TAP is for (N is a number);- 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
sdma
.Every TAP requires at least the following configparams:
-ircapture
NUMBER
The IDCODE capture command, such as 0x01.-irlen
NUMBER
The length in bits of the instruction register, such as 4 or 5 bits.-irmask
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.A TAP may also provide optional configparams:
-disable
(or-enable
)
Use the-disable
parameter to flag a TAP which is not linked in to the scan chain after a reset using either TRST or the JTAG state machine's reset state. You may use-enable
to highlight the default state (the TAP is linked in). See Enabling and Disabling TAPs.-expected-id
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. Repeat the option as many times as required if more than one ID code could appear (for example, multiple versions).
In some systems, a 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.
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:
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.
At this writing this mechanism is used only for event handling, and the only two events relate to TAP enabling and disabling.
The
configure
subcommand assigns an event handler, a TCL string which is evaluated when the event is triggered. Thecget
subcommand returns that handler. The two possible values for an event name are tap-disable and tap-enable.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:
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 }
These three commands all return the string "1" if the tap specified by dotted.name is enabled, and "0" if it is disbabled. The tapenable variant first enables the tap by sending it a tap-enable event. The tapdisable variant first disables the tap by sending it a tap-disable event.
Note: Humans will find the scan_chain command more helpful than the script-oriented tapisenabled for querying the state of the JTAG taps.
[1] See the ST document titled: STR91xFAxxx, Section 3.15 Jtag Interface, Page: 28/102, Figure 3: JTAG chaining inside the STR91xFA. http://eu.st.com/stonline/products/literature/ds/13495.pdf