This chapter introduces the Sdsec ISA extension, which enhances the Sdext extension defined in The RISC-V Debug Specification cite:[dbgspec]. The Sdsec extension provides privilege based protection for debug operations, and for triggers in Sdtrig cite:[dbgspec]. Furthermore, it constrains trace functionality cite:[etrace] according to RISC-V privilege levels.
Chapter 3 of The RISC-V Debug Specification cite:[dbgspec] outlines all mandatory and optional debug operations. The operations listed below are affected by the Sdsec extension, other operations remain unaffected. In the context of this chapter, debug operations refer to those listed below.
Debug operations affected by Sdsec: * Halting the hart to enter Debug Mode * Executing the Program Buffer * Serving abstract commands (Access Register, Access Memory)
When external debug is disallowed in the current privilege level, the hart behaves as follows:
-
The hart will not enter Debug Mode. Halt requests will remain pending until debug is allowed.
-
Triggers with
action=1 will not match or fire. -
"Quick Access" Abstract Commands, which do not require the hart to be in the halted state, will be dropped and set
abstractcs.cmderrto 6.
The subsequent subsections describe how external debug is authorized by M-mode debug control and supervisor domain debug control.
|
Note
|
A pending request to enter Debug Mode can dynamically change from a disallowed state to an allowed state due to updates in debug controls. For example, once the software completes executing confidential code, it can grant debuggability for an external debugger. Afterwards, the software can enter a while(1) loop, waiting for the debugger to take control and break out of the loop. |
A state element in each hart, named mdbgen, is introduced to control the debuggability of M-mode for each hart as depicted in [extdbg]. When mdbgen is set to 1, the following rules apply:
-
The debug access privilege for the hart is M-mode
-
The debug operations are permitted when the hart executes in any privilege mode
-
Abstract Commands, including "Quick Access", and Program Buffer execution operate with M-mode privilege
When mdbgen is set to 0, the debug operations are disallowed and the behaviors applies when the hart runs in M-mode.
|
Note
|
mdbgen may be controlled through various methods, such as a new input port to the hart, a handshake with the system Root of Trust (RoT), or other methods. The implementation can choose to group several harts together and use one signal to drive their mdbgen state or assign each hart its own dedicated state. For example, a homogeneous computing system can use a signal to drive all mdbgen state to enforce a unified debug policy across all harts.
|
The Smsdedbg extension cite:[smmtt] introduces sdedbgalw field (bit 7) in CSR msdcfg, to control the debuggability of supervisor domains. When mdbgen=0, the sdedbgalw field determines both the debug allowed privilege modes and the debug access privilege, as illustrated in External Debug Configuration and Privilege.
| mdbgen | sdedbgalw | Debug allowed privilege modes | Debug access privilege |
|---|---|---|---|
1 |
Don’t care |
All |
M-mode |
0 |
1 |
All except M |
S-mode |
0 |
0 |
None |
N/A |
The debug access privilege is defined as the privilege level granted to the external debugger when performing state accesses via the hart, such as Abstract Commands and Program Buffer execution. Any attempt by the debugger to access state inaccessible to debug access privilege will return an error.
The prv and v fields in dcsr are updated with the current privilege mode on Debug Mode entry, and are used to set the new privilege mode on resume from Debug Mode. The debugger may modify the prv and v fields, to alter the mode of execution upon resume, but the allowed values are constrained by the debugger privilege.
The maximum debug privilege level that can be configured in prv and v is shown in Maximum Allowed Resume Privilege Mode. On a write that attempts to write an illegal value to prv and/or v, the fields retain legal values. Illegal privilege levels include values higher than the maximum allowed debug privilege.
| mdbgen | sdedbgalw | Maximum privilege allowed on resume |
|---|---|---|
1 |
Don’t care |
M |
0 |
1 |
S(HS) |
0 |
0 |
None |
|
Note
|
As the prv and v fields are Write Any Read Legal (WARL) fields, the external debugger is able to read back the written value to determine the maximum debug privilege level.
|
The RISC-V Debug Specification cite:[dbgspec] defines that the instructions that change the privilege mode have UNSPECIFIED behavior when executed within the Program Buffer, with exception of the EBREAK instruction. In Sdsec, privilege changing instructions (other than EBREAK) executed in the Program Buffer must either act as a NOP or raise an exception (stopping execution and setting abstractcs.cmderr to 3).
Interrupts during single-step can be disabled by setting dcsr.stepie=1. When mdbgen is 1, stepie disables interrupts in all privilege modes for the hart. When mdbgen is 0 and sdedbgalw is 1, only delegated interrupts are disabled, while interrupts that trap to M-mode are not affected.
|
Note
|
When debugging is only allowed for the supervisor domain, M-mode interrupts must not be disabled. Otherwise, debugging might impact the behavior of other parts of the system. For example, if a context switch for the supervisor domain triggered by a timer interrupt is suppressed, some real-time workloads might not be completed on time, resulting in unexpected errors. |
When Sdsec is supported, trace, as a non-intrusive debug method, will be constrained based on RISC-V privilege level. The availability of trace output is indicated through the interface defined in <[_reference to the trace interface doc_]> to trace module.
Each hart must add a new state element, mtrcen, which controls the availability of M-mode tracing. Setting mtrcen to 1 enables trace for both M-mode and the supervisor domain; setting mtrcen to 0 inhibits trace when the hart is running in M-mode.
|
Note
|
Similar to M-mode debug control, mtrcen may be controlled through various methods, such as a new input port to the hart, a handshake with the system Root of Trust (RoT), or other methods. The implementation may group several harts together and use one signal to drive their mtrcen state or assign each hart its own dedicated state.
|
The Smsdetrc extension introduces sdetrcalw field (bit 8) in CSR msdcfg within a hart. The trace availability for a hart in supervisor domain is determined by the sdetrcalw field and mtrcen. If either sdetrcalw or mtrcen is set to 1, trace can be allowed when the hart runs in the supervisor domain.
When both sdetrcalw and mtrcen are set to 0, trace is inhibited in all privilege levels.
Triggers configured to enter Debug Mode can only fire or match when external debug is allowed, as outlined in External Debug Configuration and Privilege.
|
Note
|
Implementations must ensure that pending triggers intending to enter Debug Mode match or fire only when the hart is in a state where debug is allowed. For example, if an interrupt traps the hart to a debug-disallowed privilege mode, the trigger can only take effect either before the privilege is updated and control flow is transferred to the trap handler, or after the interrupt is completely handled and returns from the trap handler. The implementation must prevent Debug Mode from being entered in an intermediate state where privilege is changed or the PC is updated. This also applies to scenarios where a trigger is configured to enter Debug Mode before instruction execution and an interrupt occurs simultaneously. |
When Sdsec extension is implemented, dmode is read/write for both M-mode and Debug Mode when mdbgen is 0, and remains only accessible to Debug Mode when mdbgen is 1.
|
Note
|
M-mode is given write access to dmode to allow it to save/restore trigger context on behalf of a supervisor debugger. Otherwise a trigger could serve as a side-channel to debug disallowed supervisor domains. The trigger may raise a breakpoint exception in a supervisor domain where debugging is disallowed. This could allow the external debugger to indirectly observe the state from the debug disallowed supervisor domain (PC, data address, etc) and may even result in a Denial of Service (DoS). By making dmode M-mode accessible when mdbgen is 0, such an attack can be mitigated by having M-mode firmware switch the trigger context at supervisor domain boundary.
|
The external trigger outputs (with action = 8/9) will not fire or match when the privilege level of the hart exceeds debug allowed privilege as specified in External Debug Configuration and Privilege.
The external trigger input can be driven by any input signals, e.g. the external trigger output from another hart, interrupt signals, etc. The input signals cause the trigger (with action = 1) to fire only when the hart is allowed to debug. The initiators of these signals are responsible for determining whether the signal is allowed to assert. For example, if the external trigger input of hart i is connected to external trigger output of hart j, the assertion of output signal from hart j is determined by its own allowed privilege level for debug. The output signal of hart j must not assert when debug is disallowed. Similarly, signals from other modules in the system are managed by the individual module. When the module is not debug allowed, the signal connected to external trigger input must not be asserted.
|
Note
|
This represents a balance between usability and hardware complexity. There may be instances where the triggers are linked across different privilege levels (e.g., from S-mode to M-mode), while the external debugger may only have access with S-mode privilege. The external debugger should not modify the chain, because it could be suppressed or incorrectly match or fire in M-mode. |
The sdcsr and sdpc registers provide supervisor read/write access to the dcsr and dpc registers respectively. They are only accessible in Debug Mode.
| Number | Name | Descirption |
|---|---|---|
0xaaa |
sdcsr |
Supervisor debug control and status register. |
0xaaa |
sdpc |
Supervisor debug program counter. |
The sdcsr register exposes a subset of dcsr, formatted as shown in Register 1, while the sdpc register provides full access to dpc.
|
Note
|
Unlike dcsr and dpc, the dscratch* registers do not have a supervisor access mechanism, and external debuggers with S-mode privilege cannot not use them.
|
{reg: [
{bits: 1, name: 'prv'},
{bits: 1, name: '0'},
{bits: 1, name: 'step'},
{bits: 1, name: '0'},
{bits: 1, name: '0'},
{bits: 1, name: 'v'},
{bits: 3, name: 'cause'},
{bits: 1, name: '0'},
{bits: 1, name: '0'},
{bits: 1, name: 'stepie'},
{bits: 1, name: 'ebreaku'},
{bits: 1, name: 'ebreaks'},
{bits: 1, name: '0'},
{bits: 1, name: '0'},
{bits: 1, name: 'ebreakvu'},
{bits: 1, name: 'ebreakvs'},
{bits: 6, name: '0'},
{bits: 3, name: 'extcause'},
{bits: 1, name: '0'},
{bits: 4, name: 'debugver'}
], config:{lanes: 3, hspace:1024}}
|
Note
|
The nmip, mprven, stoptime, stopcount, ebreakm and cetrig fields in dcsr are configurable only by M-mode, masked from sdcsr, while the prv field is constrained to 1 bit.
|
(defattrs :plain [:plain { :font-size 24}])
(def row-height 40 )
(def row-header-fn nil)
(def left-margin 30)
(def right-margin 30)
(def boxes-per-row 32)
(draw-column-headers {:height 24 :font-size 24 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "DXLEN-1" ""])})
(draw-box "sdpc" {:span 32:text-anchor "middle" :borders {:left :border-unrelated :top :border-unrelated :bottom :border-unrelated :right :border-unrelated}})
(draw-box "DXLEN" {:font-size 24 :span 32 :borders {}})
The Smtdeleg and Sstcfg extensions define the process for delegating triggers to modes with lower privilege than M-mode. The Sdsec requires both extensions to securely delegate Sdtrig triggers to supervisor domain.
|
Note
|
When M-mode enables debugging for supervisor domain, it can optionally delegate the triggers to the supervisor domain, allowing an external debugger with S-mode privilege to configure these triggers. |
The CSR holding the debug and trace control knobs for supervisor domain are specified in the Smsdedbg and Smsdetrc extensions, respectively, defined in RISC-V Supervisor Domains Access Protection cite:[smmtt]. The Smsdedbg and/or Smsdetrc extensions must be implemented to support security control for debugging and/or tracing in supervisor domains.