1 Introduction
When a design progresses from simulation to hardware implementation, a user’s control and understanding of the system’s current state drops dramatically. To help bring up and debug low level software and hardware, it is critical to have good debugging support built into the hardware. When a robust OS is running on a core, software can handle many debugging tasks. However, in many scenarios, hardware support is essential.
This document outlines a standard architecture for external debug support on RISC-V platforms. This architecture allows a variety of implementations and tradeoffs, which is complementary to the wide range of RISC-V implementations. At the same time, this specification defines common interfaces to allow debugging tools and components to target a variety of platforms based on the RISC-V ISA.
System designers may choose to add additional hardware debug support, but this specification defines a standard interface for common functionality.
1.1 Terminology
A platform is a single integrated circuit consisting of one or more components. Some components may be RISC-V cores, while others may have a different function. Typically they will all be connected to a single system bus. A single RISC-V core contains one or more hardware threads, called harts.
DXLEN of a hart is its widest supported XLEN, ignoring the current value
of MXLin misa.
1.1.1 Context
This document is written to work with:
The RISC-V Instruction Set Manual, Volume I: User-Level ISA, Document Version 2.2 (the ISA Spec)
The RISC-V Instruction Set Manual, Volume II: Privileged Architecture, Version 1.10 (the Privileged Spec)
1.1.2 Versions
Version 0.13 of this document was ratified by the RISC-V Foundation’s board. Versions 0.13.x are bug fix releases to that ratified specification.
Version 0.14 will be forwards and backwards compatible with Version 0.13.
1.2 About This Document
1.2.1 Structure
This document contains two parts. The main part of the document is the specification, which is given in the numbered sections. The second part of the document is a set of appendices. The information in the appendices is intended to clarify and provide examples, but is not part of the actual specification.
1.2.2 Register Definition Format
All register definitions in this document follow the format shown below. A simple graphic shows which fields are in the register. The upper and lower bit indices are shown to the top left and top right of each field. The total number of bits in the field are shown below it.
After the graphic follows a table which for each field lists its name, description, allowed accesses, and reset value. The allowed accesses are listed in Table 1.1. The reset value is either a constant or “Preset.” The latter means it is an implementation-specific legal value.
Names of registers and their fields are hyperlinks to their definition, and are also listed in the index on page .
1.3 Background
There are several use cases for dedicated debugging hardware, both internal to a CPU core and with an external connection. This specification addresses the use cases listed below. Implementations can choose not to implement every feature, which means some use cases might not be supported.
Debugging low-level software in the absence of an OS or other software.
Debugging issues in the OS itself.
Bootstrapping a system to test, configure, and program components before there is any executable code path in the system.
Accessing hardware on a system without a working CPU.
In addition, even without a hardware debugging interface, architectural support in a RISC-V CPU can aid software debugging and performance analysis by allowing hardware triggers and breakpoints.
1.4 Supported Features
The debug interface described in this specification supports the following features:
All hart registers (including CSRs) can be read/written.
Memory can be accessed either from the hart’s point of view, through the system bus directly, or both.
RV32, RV64, and future RV128 are all supported.
Any hart in the platform can be independently debugged.
A debugger can discover almost1 everything it needs to know itself, without user configuration.
Each hart can be debugged from the very first instruction executed.
A RISC-V hart can be halted when a software breakpoint instruction is executed.
Hardware single-step can execute one instruction at a time.
Debug functionality is independent of the debug transport used.
The debugger does not need to know anything about the microarchitecture of the harts it is debugging.
Arbitrary subsets of harts can be halted and resumed simultaneously. (Optional)
Arbitrary instructions can be executed on a halted hart. That means no new debug functionality is needed when a core has additional or custom instructions or state, as long as there exist programs that can move that state into GPRs. (Optional)
Registers can be accessed without halting. (Optional)
A running hart can be directed to execute a short sequence of instructions, with little overhead. (Optional)
A system bus master allows memory access without involving any hart. (Optional)
A RISC-V hart can be halted when a trigger matches the PC, read/write address/data, or an instruction opcode. (Optional)
This document does not suggest a strategy or implementation for hardware test, debugging or error detection techniqes. Scan, BIST, etc. are out of scope of this specification, but this specification does not intend to limit their use in RISC-V systems.
It is possible to debug code that uses software threads, but there is no special debug support for it.
Notable exceptions include information about the memory map and peripherals.↩︎