Tap Creation - Open On-Chip Debugger (OpenOCD)

Next: Target Configuration, Previous: Reset Configuration, Up: Top

11 Tap Creation

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.

When a tap is created a dotted.name is created for the tap. Other commands use that dotted.name to manipulate or refer to the tap.

Tap Uses:

Debug Target A tap can be used by a GDB debug target
Flash Programing Some chips program the flash via JTAG
Boundry Scan Some chips support boundry scan.

11.1 jtag newtap

jtag newtap CHIPNAME TAPNAME configparams ....

CHIPNAME
is a symbolic name of the chip.
TAPNAME
is a symbol name of a tap present on the chip.
Required configparams
Every tap has 3 required configparams, and several “optional parameters”, the required parameters are:
- -irlen NUMBER - the length in bits of the instruction register
- -ircapture NUMBER - the ID code capture command.
- -irmask NUMBER - the corresponding mask for the ir register.
An example of a FOOBAR Tap
```
          jtag newtap foobar tap -irlen 7 -ircapture 0x42 -irmask 0x55
```
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.
Optional configparams
- -expected-id NUMBER
  By default it is zero. If non-zero represents the expected tap ID used when the Jtag Chain is examined. See below.
- -disable
- -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 jtag tapenable DOTTED.NAME or jtag tapdisable DOTTED.NAME

Notes:

Technically
newtap is a sub command of the “jtag” command
Big Picture Background
GDB Talks to OpenOCD using the GDB protocol via tcpip. 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 daisy chain configuration. Each chip may have one or more jtag taps. GDB ends up talking via OpenOCD to one of the taps.
NAME Rules
Names follow “C” symbol name rules (start with alpha ...)
TAPNAME - Conventions
- tap - should be used only FPGA or CPLD like devices with a single tap.
- cpu - the main cpu of the chip, alternatively foo.arm and foo.dsp
- flash - if the chip has a flash tap, example: str912.flash
- bs - for boundary scan if this is a seperate tap.
- jrc - for jtag route controller (example: OMAP3530 found on Beagleboards)
- unknownN - where N is a number if you have no idea what the tap is for
- Other names - Freescale IMX31 has a SDMA (smart dma) with a JTAG tap, that tap should be called the “sdma” tap.
- When in doubt - use the chip makers name in their data sheet.
DOTTED.NAME
CHIPNAME.TAPNAME creates the tap name, aka: the Dotted.Name is the CHIPNAME and TAPNAME combined with a dot (period); for example: xilinx.tap, str912.flash, omap3530.jrc, or stm32.cpu The dotted.name is used in numerous other places to refer to various taps.
ORDER
The order this command appears via the config files is important.
Multi Tap Example
This example is based on the ST Microsystems STR912. 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
checked: 28/nov/2008
The diagram shows 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.
```
             # 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 ...
```
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.
Multiple chips
If your board has multiple chips, you should be able to source two configuration files, in the proper order, and have the taps created in the proper order.

11.2 jtag_device - REMOVED

     jtag_device <IR length> <IR capture> <IR mask> <IDCODE instruction>

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, ie: 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 jtag newtap command for details.

     OLD: jtag_device 8 0x01 0xe3 0xfe
     NEW: jtag newtap CHIPNAME TAPNAME -irlen 8 -ircapture 0x01 -irmask 0xe3

11.3 Enable/Disable Taps

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.

By default, all taps are enabled

jtag tapenable DOTTED.NAME
jtag tapdisable DOTTED.NAME
jtag tapisenabled DOTTED.NAME

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 “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 syncronization problems one must face. To solve that problem, the JTAG Route controller was introduced. Rather then “bypass” the tap, the tap is completely removed from the circuit and skipped.

From OpenOCD's view point, a JTAG TAP is in one of 3 states:

Enabled - Not In ByPass and has a variable bit length
Enabled - In ByPass and has a length of exactly 1 bit.
Disabled and has a length of ZERO and is removed from the circuit.

The IEEE JTAG definition has no concept of a “disabled” tap. Historical note: this feature was added 28/nov/2008

jtag tapisenabled DOTTED.NAME

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.