6.1. Debug Transport Module (DTM) (non-ISA extension)
Debug Transport Modules provide access to the DM over one or more transports (e.g. JTAG or USB).
There may be multiple DTMs in a single hardware platform. Ideally every component that communicates with the outside world includes a DTM, allowing a hardware platform to be debugged through every transport it supports. For instance a USB component could include a DTM. This would trivially allow any hardware platform to be debugged over USB. All that is required is that the USB module already in use also has access to the Debug Module Interface.
Using multiple DTMs at the same time is not supported. It is left to the user to ensure this does not happen.
This specification defines a JTAG DTM in 6.1.1. JTAG Debug Transport Module. Additional DTMs may be added in future versions of this specification.
An implementation can be compatible with this specification without implementing any of this section. In that case it must be advertised as conforming to "RISC-V Debug Specification, with custom DTM." If the JTAG DTM described here is implemented, it must be advertised as conforming to the "RISC-V Debug Specification, with JTAG DTM.""
6.1.1. JTAG Debug Transport Module
This Debug Transport Module is based around a normal JTAG Test Access Port (TAP). The JTAG TAP allows access to arbitrary JTAG registers by first selecting one using the JTAG instruction register (IR), and then accessing it through the JTAG data register (DR).
6.1.1.1. JTAG Background
JTAG refers to IEEE Std 1149.1-2013. It is a standard that defines test logic that can be included in an integrated circuit to test the interconnections between integrated circuits, test the integrated circuit itself, and observe or modify circuit activity during the component’s normal operation. This specification uses the latter functionality. The JTAG standard defines a Test Access Port (TAP) that can be used to read and write a few custom registers, which can be used to communicate with debug hardware in a component.
6.1.1.2. JTAG DTM Registers
JTAG TAPs used as a DTM must have an IR of at least 5 bits. When the TAP is reset, IR must default to 00001, selecting the IDCODE instruction. A full list of JTAG registers along with their encoding is in Table 4. If the IR actually has more than 5 bits, then the encodings in Table 4 should be extended with 0’s in their most significant bits, except for the 0x1f encoding of BYPASS, which must be extended with 1’s in the most significant bits. The only regular JTAG registers a debugger might use are BYPASS and IDCODE, but this specification leaves IR space for many other standard JTAG instructions. Unimplemented instructions must select the BYPASS register.
| Address | Name | Description | Section |
|---|---|---|---|
0x00 |
JTAG recommends this encoding |
||
0x01 |
To identify a specific silicon version |
||
0x10 |
DTM Control and Status (dtmcs) |
For Debugging |
|
0x11 |
Debug Module Interface Access (dmi) |
For Debugging |
|
0x12 |
reserved (bypass) |
Reserved for future RISC-V debugging |
|
0x13 |
reserved (bypass) |
Reserved for future RISC-V debugging |
|
0x14 |
reserved (bypass) |
Reserved for future RISC-V debugging |
|
0x15 |
reserved (bypass) |
Reserved for future RISC-V standards |
|
0x16 |
reserved (bypass) |
Reserved for future RISC-V standards |
|
0x17 |
reserved (bypass) |
Reserved for future RISC-V standards |
|
0x1f |
JTAG requires this encoding |
IDCODE (at 0x01)
This register is selected (in IR) when the TAP state machine is reset. Its definition is exactly as defined in IEEE Std 1149.1-2013.
This entire register is read-only.
| Field | Description | Access | Reset |
|---|---|---|---|
Identifies the release version of this part. |
R |
Preset |
|
Identifies the designer’s part number of this part. |
R |
Preset |
|
Identifies the designer/manufacturer of this part. Bits 6:0 must be bits 6:0 of the designer/manufacturer’s Identification Code as assigned by JEDEC Standard JEP106. Bits 10:7 contain the modulo-16 count of the number of continuation characters (0x7f) in that same Identification Code. |
R |
Preset |
DTM Control and Status (dtmcs, at 0x10)
The size of this register will remain constant in future versions so that a debugger can always determine the version of the DTM.
| Field | Description | Access | Reset |
|---|---|---|---|
This optional field may provide additional detail about an error that occurred when communicating with a DM. It is updated whenever op is updated by the hardware or when 1 is written to dmireset. 0 (not implemented): This field is not implemented. 1 (dmi error): There was an error between the DTM and DMI. 2 (communication error): There was an error between the DMI and a DMI subordinate. 3 (device error): The DMI subordinate reported an error. 4 (unknown): There is no error to report, or no further information available about the error. This is the reset value if the field is implemented. Other values are reserved for future use by this specification. |
R |
4 |
|
Writing 1 to this bit does a hard reset of the DTM, causing the DTM to forget about any outstanding DMI transactions, and returning all registers and internal state to their reset value. In general this should only be used when the Debugger has reason to expect that the outstanding DMI transaction will never complete (e.g. a reset condition caused an inflight DMI transaction to be cancelled). |
W1 |
- |
|
Writing 1 to this bit clears the sticky error state and resets errinfo, but does not affect outstanding DMI transactions. |
W1 |
- |
|
This is a hint to the debugger of the minimum number of cycles a debugger should spend in Run-Test/Idle after every DMI scan to avoid a `busy' return code (dmistat of 3). A debugger must still check dmistat when necessary. 0: It is not necessary to enter Run-Test/Idle at all. 1: Enter Run-Test/Idle and leave it immediately. 2: Enter Run-Test/Idle and stay there for 1 cycle before leaving. And so on. |
R |
Preset |
|
Read-only alias of op. |
R |
0 |
|
R |
Preset |
||
0 (0.11): Version described in spec version 0.11. 1 (1.0): Version described in spec versions 0.13 and 1.0. 15 (custom): Version not described in any available version of this spec. |
R |
1 |
Debug Module Interface Access (dmi, at 0x11)
This register allows access to the Debug Module Interface (DMI).
In Update-DR, the DTM starts the operation specified in op unless the current status reported in op is sticky.
In Capture-DR, the DTM updates data with the result from that operation, updating op if the current op isn’t sticky.
See [dmiaccess] for examples of how this is used.
|
The still-in-progress status is sticky to accommodate debuggers that batch together a number of scans, which must all be executed or stop as soon as there’s a problem. For instance a series of scans may write a Debug Program and execute it. If one of the writes fails but the execution continues, then the Debug Program may hang or have other unexpected side effects. |
| Field | Description | Access | Reset |
|---|---|---|---|
Address used for DMI access. In Update-DR this value is used to access the DM over the DMI. op defines what this register contains after every possible operation. |
R/W |
0 |
|
The data to send to the DM over the DMI during Update-DR, and the data returned from the DM as a result of the previous operation. |
R/W |
0 |
|
When the debugger writes this field, it has the following meaning: Don’t send anything over the DMI during Update-DR. This operation should never affect DMI busy or error status. The address and data reported in the following Capture-DR are undefined. 1 (read): Read from address. When this operation succeeds, address contains the address that was read from, and data contains the value that was read. 3 (reserved): Reserved. When the debugger reads this field, it means the following: 0 (success): The previous operation completed successfully. 1 (reserved): Reserved. 2 (failed): A previous operation failed. The data scanned into dmi in this access will be ignored. This status is sticky and can be cleared by writing dmireset in dtmcs. This indicates that the DM itself or the DMI responded with an error. There are no specified cases in which the DM would respond with an error, and DMI is not required to support returning errors. If a debugger sees this status, there might be additional information in errinfo. 3 (busy): A DMI operation was attempted while a prior DMI operation was still in progress. The data scanned into dmi in this access will be ignored. This status is sticky and can be cleared by writing dmireset in dtmcs. If a debugger sees this status, it needs to give the target more TCK edges between Update-DR and Capture-DR. The simplest way to do that is to add extra transitions in Run-Test/Idle. |
R/W |
0 |
BYPASS (at 0x1f)
1-bit register that has no effect. It is used when a debugger does not want to communicate with this TAP.
This entire register is read-only.
6.1.1.3. JTAG Connector
6.1.1.3.1. Recommended JTAG Connector
To make it easy to acquire debug hardware, this spec recommends a connector that is compatible with the MIPI-10 .05 inch connector specification, as described in MIPI Debug & Trace Connector Recommendations, Version 1.20, 2 July 2021.
The connector has .05 inch spacing, gold-plated male header with .016 inch thick hardened copper or beryllium bronze square posts (SAMTEC FTSH or equivalent). Female connectors are compatible gold connectors.
Viewing the male header from above (the pins pointing at your eye), a target’s connector looks as it does in Table 2. The function of each pin is described in Table 5.
VREF DEBUG |
1 |
2 |
TMS |
GND |
3 |
4 |
TCK |
GND |
5 |
6 |
TDO |
GND or KEY |
7 |
8 |
TDI |
GND |
9 |
10 |
nRESET |
If a hardware platform requires nTRST then it is permissible to reuse
the nRESET pin as the nTRST signal, resulting in a MIPI 10-pin JTAG
nTRST connector.
6.1.1.3.2. Alternate JTAG Connector
The MIPI-10 connector should provide plenty of signals for all modern hardware. If a design does need legacy JTAG signals, then the MIPI-20 connector should be used. Pins whose functionality isn’t needed may be left unconnected.
Its physical connector is virtually identical to MIPI-10, except that it’s twice as long, supporting twice as many pins. Its pinout is shown in Table 6. The function of each pin is described in Table 5.
Essential |
GND |
Connected to ground. |
TCK |
JTAG TCK signal, driven by the debug adapter. |
|
TDI |
JTAG TDI signal, driven by the debug adapter. |
|
TDO |
JTAG TDO signal, driven by the target. |
|
TMS |
JTAG TMS signal, driven by the debug adapter. |
|
VREF DEBUG |
Reference voltage for logic high. |
|
Recommended |
nRESET |
Open drain active low reset signal, usually
driven by the debug adapter. The signal may be used bi-directional to
drive or sense the target reset signal. |
KEY |
This pin may be cut on the male and plugged on the female header to ensure the header is always plugged in correctly. It is, however, recommended to use this pin as an additional ground, to allow for fastest TCK speeds. A shrouded connector should be used to prevent the cable from being plugged in incorrectly. |
|
Advanced |
EXT |
Reserved for custom use. Could be an input or an output. |
TRIGIN |
Not used by this specification, to be driven by debug adapter. (Can be used for extended functions like UART or boot mode selection by some debug adapters). |
|
TRIGOUT |
Not used by this specification, driven by the target. |
|
Specialized |
nTRST |
Test reset, driven by the debug adapter. Asserting nTRST initializes the JTAG DTM asynchronously. It is used in systems where the JTAG DTM is not ready to be used after a normal power up. This signal is sometimes called TRST*. |
Legacy |
RTCK |
Return test clock, driven by the target. A target may
relay the TCK signal here once it has processed it, allowing a debugger
to adjust its TCK frequency in response. |
nTRST_PD |
Test reset pull-down, driven by the debug adapter. Same
function as nTRST, but with pull-down resistor on target. |
VREF DEBUG |
1 |
2 |
TMS |
GND |
3 |
4 |
TCK |
GND |
5 |
6 |
TDO |
GND or KEY |
7 |
8 |
TDI |
GND |
9 |
10 |
nRESET |
GND |
11 |
12 |
GND or RTCK |
GND |
13 |
14 |
NC or nTRST_PD |
GND |
15 |
16 |
nTRST or NC |
GND |
17 |
18 |
TRIGIN or NC |
GND |
19 |
20 |
TRIGOUT or GND |
6.1.1.4. cJTAG
This spec does not have specific recommendations on how to use the cJTAG protocol.
When implementing cJTAG access to a JTAG DTM, the MIPI 10-pin Narrow JTAG connector should be used. Pins whose functionality isn’t needed may be left unconnected.
Viewing the male header from above (the pins pointing at your eye), a target’s connector looks as it does in Table 7.
VREF DEBUG |
1 |
2 |
TMSC |
GND |
3 |
4 |
TCKC |
GND |
5 |
6 |
EXT or NC |
GND or KEY |
7 |
8 |
NC or nTRST_PD |
GND |
9 |
10 |
nRESET |