5 RISC-V Debug
Modifications to the RISC-V core to support debug are kept to a minimum. There is a special execution mode (Debug Mode) and a few extra CSRs. The DM takes care of the rest.
In order to be compliant with this specification an implementation must implement everything described in this section that is not explicitly listed as optional.
5.1 Debug Mode
Debug Mode is a special processor mode used only when a hart is halted for external debugging. How Debug Mode is implemented is not specified here.
When executing code from the optional Program Buffer, the hart stays in Debug Mode and the following apply:
All operations are executed at machine mode privilege level, except that
mstatusmay be ignored according to
All interrupts (including NMI) are masked.
Exceptions don’t update any registers. That includes
mstatus. They do end execution of the
No action is taken if a trigger matches.
Counters may be stopped, depending on
Timers may be stopped, depending on
wfi instruction acts as a
Almost all instructions that change the privilege level have undefined
behavior. This includes
uret. (To change the privilege level, the debugger can write
dcsr). The only exception is
ebreak. When that is executed
in Debug Mode, it halts the hart again but without updating
[fence] Completing Program Buffer execution is considered output for the purpose
All control transfer instructions may act as illegal instructions if their destination is in the Program Buffer. If one such instruction acts as an illegal instruction, all such instructions must act as an illegal instruction.
All control transfer instructions may act as illegal instructions if their destination is outside the Program Buffer. If one such instruction acts as an illegal instruction, all such instructions must act as an illegal instruction.
Instructions that depend on the value of the PC (e.g.
auipc) may act
as illegal instructions.
Effective XLEN is DXLEN.
5.2 Load-Reserved/Store-Conditional Instructions
The reservation registered by an
lr instruction on a memory address may
be lost when entering Debug Mode or while in Debug Mode. This means that there
may be no forward progress if Debug Mode is entered between
5.3 Wait for Interrupt Instruction
If halt is requested while
wfi is executing, then the hart must leave the
stalled state, completing this instruction’s execution, and then enter Debug
5.4 Single Step
A debugger can cause a halted hart to execute a single instruction and then
re-enter Debug Mode by setting
If executing or fetching that instruction causes an exception, Debug Mode is
re-entered immediately after the PC is changed to the exception handler and the
cause registers are updated.
If executing or fetching the instruction causes a trigger to fire, Debug Mode
is re-entered immediately after that trigger has fired. In that case
set to 2 (trigger) instead of 4 (single step). Whether the instruction is
executed or not depends on the specific configuration of the trigger.
If the instruction that is executed causes the PC to change to an address where an instruction fetch causes an exception, that exception does not occurr until the next time the hart is resumed. Similarly, a trigger at the new address does not fire until the hart actually attempts to execute that instruction.
If the instruction being stepped over is
wfi and would normally stall the
hart, then instead the instruction is treated as
If the halt signal (driven by the hart’s halt request bit in the Debug Module)
resethaltreqare asserted when a hart comes out of reset, the hart must
enter Debug Mode before executing any instructions, but after performing any
initialization that would usually happen before the first instruction is
To return from Debug Mode, a new instruction is defined:
dret. It has an
encoding of 0x7b200073. On harts which support this instruction,
dret in Debug Mode changes
pcto the value
dpc. The current privilege level is changed to that specified by
dcsr. The hart is no longer in debug mode.
dret outside of Debug Mode causes an illegal instruction exception.
It is not necessary for the debugger to know whether an implementation supports
dret, as the Debug Module will ensure that it is executed if necessary.
It is defined in this specification only to reserve the opcode and
allow for reusable Debug Module implementations.
While in Debug Mode, XLEN is DXLEN. It is up to the debugger to determine the
XLEN during normal program execution (by looking at
misa) and to clearly
communicate this to the user.
5.8 Core Debug Registers
The supported Core Debug Registers must be implemented for each hart that can
be debugged. They are CSRs, accessible using the RISC-V
csr opcodes and
optionally also using abstract debug commands.