RISC-V Debug System Wrapper Technical Specification


This document specifies the RISC-V Debug System wrapper functionality.


The debug system follows the execution-based debug approach described in the RISC-V Debug Specification 0.13.2 and provides the following features.

  • JTAG Test Access Port (TAP)
  • Run-control debug features (in cooperation with the CPU core), including breakpoints, single-stepping through code, and reading core registers
  • System Bus Access (SBA): Access to arbitrary bus-attached peripherals through JTAG
  • Compatible with RISC-V Debug Specification 0.13-compliant debug software, including OpenOCD and GDB
  • TileLink Uncached Light (TL-UL) bus interfaces


This module provides a RISC-V Debug Specification-compliant debug system with TileLink Uncached Light bus interfaces. The main functionality is provided by the PULP RISC-V Debug System, which is instantiated by this module. All bus interfaces are converted into TL-UL.

See the PULP RISC-V Debug System Documentation for a full list of features and further design documentation. This document only describes the additional logic provided on top of the PULP RISC-V Debug System.


The debug system is compliant with the RISC-V Debug Specification 0.13.2.

Theory of Operations

Memory Maps

TL-UL device

The memory map accessible over the TL-UL device interface is documented in the Debug Memory section of the PULP RISC-V Debug System Documentation. Note this contains a mixture of read only and read-write regions and which is which isn’t documented. The read-write regions are:

  • 0x100 - 0x10c: Halted, Going, Resuming, Exception
  • 0x380 - 0x382: DataAddr (0x383 - 0x338 are not implemented and will read undefined data)

All other regions are read only.

Debug Module Registers

The Debug Module Registers are only accessible via the Debug Module Interface (DMI) accessed via JTAG. There is no access to these via the TL-UL device interface.

Hardware Interfaces

All hardware interfaces of the debug system are documented in the PULP RISC-V Debug System Documentation, with the exception of the bus interfaces, which are converted to TL-UL by this wrapper.


Referring to the Comportable guideline for peripheral device functionality, the module rv_dm has the following hardware interfaces defined.

Primary Clock: clk_i

Other Clocks: none

Bus Device Interfaces (TL-UL): regs_tl_d, mem_tl_d

Bus Host Interfaces (TL-UL): sba_tl_h

Peripheral Pins for Chip IO: none

Inter-Module Signals: Reference

Inter-Module Signals
Port Name Package::Struct Type Act Width Description
jtag jtag_pkg::jtag req_rsp rsp 1
lc_hw_debug_en lc_ctrl_pkg::lc_tx uni rcv 1
unavailable logic uni rcv 1
ndmreset_req logic uni req 1
dmactive logic uni req 1
debug_req logic [rv_dm_reg_pkg::NrHarts-1:0] uni req 1
sba_tl_h tlul_pkg::tl req_rsp req 1
regs_tl_d tlul_pkg::tl req_rsp rsp 1
mem_tl_d tlul_pkg::tl req_rsp rsp 1

Interrupts: none

Security Alerts:

Alert NameDescription

This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected.

Security Countermeasures:

Countermeasure IDDescription

End-to-end bus integrity scheme.


The life cycle hardware debug enable signal is multibit encoded.


The debug module is enabled with the LC_HW_DEBUG_EN signal. This enablement is implemented by gating / enabling critical blocks with separately buffered copies of the life cycle signal. This comprises the debug module interface (DMI) attached to the TAP, the reset request line, the system bus access module (SBA), the debug request output, the TL-UL adapter for the debug ROM, and the ifetch indicator being fed into the TL-UL adapter for the debug ROM.


The instruction fetch enable signal that is modulated with LC_HW_DEBUG_EN and that feeds into the TL-UL adapter is multibit encoded.

The table below lists other debug module signals.

Signal Direction Type Description
lc_hw_debug_en_i input lc_ctrl_pkg::lc_tx_t Multibit life cycle hardware debug enable signal coming from life cycle controller, asserted when the hardware debug mechanisms are enabled in the system.
ndmreset_req_o output logic Non-debug module reset request going to the system reset infrastructure.
dmactive_o output logic This signal indicates whether the debug module is active and can be used to prevent power down of the core and bus-attached peripherals.
debug_req_o output logic This is the debug request interrupt going to the main processor.
unavailable_i input logic This signal indicates to the debug module that the main processor is not available for debug (e.g. due to a low-power state).
jtag_i input jtag_pkg::jtag_req_t JTAG input signals
jtag_o output jtag_pkg::jtag_rsp_t JTAG output signals

Life Cycle Control

Debug system functionality is controlled by the HW_DEBUG_EN function of the life cycle controller.

input  lc_ctrl_pkg::lc_tx_t lc_hw_debug_en_i, // Debug module lifecycle enable/disable


The debug system provides a standard JTAG (IEEE Std 1149.1-2013) port for external debug access. All JTAG logic is clocked with an externally supplied test clock (tck). The protocol used for this JTAG port is specified in the RISC-V Debug Specification as JTAG Debug Transport Module (DTM).

input  logic               tck_i,           // JTAG test clock pad
input  logic               tms_i,           // JTAG test mode select pad
input  logic               trst_ni,         // JTAG test reset pad
input  logic               td_i,            // JTAG test data input pad
output logic               td_o,            // JTAG test data output pad
output logic               tdo_oe_o         // Data out output enable

System interface

The debug system is able to reset the system through its JTAG connection; the non-debug module reset (ndmreset_req_o) signals this intent. It is up to the larger system design to specify which parts of the system are actually reset by this signal.

The dmactive_o signals that some kind of debugging is ongoing. Use this signal to prevent the power down of the core and bus-attached peripherals, which might be accessed by the debug system.

output logic                  ndmreset_o,  // non-debug module reset
output logic                  dmactive_o,  // debug module is active

Core interface

Most communication between the core and the debug system is performed through the debug memory. To enter debug mode due to an external debug request, the debug system provides a debug_req_o interrupt. If the core is unavailable to the debug system, e.g. because it is powered down or in a locked-down state, the unavailable_i signal can signal this condition to the debug system.

output logic [NrHarts-1:0]    debug_req_o, // async debug request
input  logic [NrHarts-1:0]    unavailable_i, // communicate whether the hart is unavailable
                                             // (e.g.: power down)

TL-UL device for debug memory

The debug system implements execution-based debug according to the RISC-V Debug Specification. Most interactions between the core and the debug system are performed through the debug memory, a bus-exposed memory. The memory needs to be accessible from the core instruction and data interfaces. A full memory map is part of the PULP RISC-V Debug System Documentation.

input  tlul_pkg::tl_h2d_t tl_d_i,
output tlul_pkg::tl_d2h_t tl_d_o,

TL-UL host for System Bus Access (SBA)

Bus-attached peripherals can be accessed through the debug system, a functionality called System Bus Access (SBA) in the RISC-V Debug Specification. It is up to the interconnect fabric to decide which peripherals are actually accessible. The debug system wrapper provides a TL-UL host bus interface for SBA.

// bus host, for system bus accesses
output tlul_pkg::tl_h2d_t  tl_h_o,
input  tlul_pkg::tl_d2h_t  tl_h_i,