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 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.
-
Halting the hart to enter Debug Mode
-
Executing Program buffer
-
Serving abstract commands (Access Register, Access Memory)
When external debug is disallowed in running privilege level, the hart behaves as the following:
-
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. -
Abstract commands without halting will be dropped and set
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 can be configured to any legal privilege level
-
The debug operations are permitted when the hart executes in all modes
-
Abstract commands without halting the hart carries M-mode privilege if supported
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. The sdedbgalw along with mdbgen determines the debug allowed privilege levels, as illustrated in External debug allowed privilege levels per debug controls. The debug access privilege can only be configured to debug allowed levels.
| mdbgen | sdedbgalw | Debug allowed privilege levels |
|---|---|---|
1 |
Don’t care |
All |
0 |
1 |
All except M |
0 |
0 |
None |
When debug is allowed in supervisor domain, debug operations are allowed when hart executes in supervisor domain. The abstract commands without halting the hart carries supervisor mode privilege if supported.
The debug access privilege is defined as the privilege level granted to the external debugger to access hardware resources with abstract commands or program buffers. Memory and register accesses from Debug Mode also carry debug access privilege instead of always with M-mode. The debug access privilege is represented by the prv and v fields in dcsr or sdcsr. The legal privilege levels programmable to the fields in Debug Mode are elaborated in Configuring External Debugger Access Privileges. Debugger accesses to registers and memory will be checked by permission check mechanisms against debug access privilege, and trap if they violate corresponding rules.
The prv and v fields have been modified to authorize privilege for external debug accesses. Upon transitioning into Debug Mode, the prv and v fields are updated to the privilege level the hart was previously operating in. The maximum debug privilege level that can be configured in prv and v is determined in Determining maximum debug access privilege with mdbgen and sdedbgalw. The fields retain legal values when the prv and v are configured with an illegal privilege level. Illegal privilege levels include unsupported levels and any level higher than the maximum allowed debug privilege. When the hart resumes from Debug Mode, the current privilege mode and virtualization mode are changed to that specified by prv and v.
| mdbgen | sdedbgalw | Maximum debug privilege allowed |
|---|---|---|
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, those instructions including mret, sret, uret, ecall, must either act as NOP or trigger an exception (stopping execution and setting cmderr to 3) in Program Buffer. Notably, these instructions retain their normal functionality during single stepping.
The interrupt can be disabled by stepie in dcsr during single stepping. When mdbgen is 1, stepie disables interrupts in all privilege modes for the hart. When mdbgen is 0 and sdedbgalw is 1, only interrupts delegated to the supervisor domain 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 disables trace output 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, the trace output is allowed when the hart runs in the supervisor domain.
When both sdetrcalw and mtrcen are set to 0, trace output is inhibited at all privilege levels.
Triggers configured to enter Debug Mode can only fire or match when external debug is allowed, as outlined in External debug allowed privilege levels per debug controls.
|
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
|
The dmode being read/write allows M-mode to switch trigger context. The trigger can form a side-channel to debug disallowed supervisor domains from a debug allowed supervisor domain if the trigger context is not switched. Although the trigger cannot fire or match in disallowed supervisor domain to enter Debug Mode, the malicious debugger can exploit it by setting a trigger to raise breakpoint exception (action = 0) when it is in debug allowed supervisor domain. If the trigger hits in debug disallowed supervisor domain, the external debugger can indirectly observe the executed PC, accessed memory address or read/write data in debug disallowed supervisor domain by the checking value in hit0/hit1. As the dmode is accessible when mdbgen is 0, such 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 allowed privilege levels per debug controls.
The external trigger input can be driven by any input signals, e.g. the external trigger output from another hart or 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 module in the system are managed by the individual module. When the module is not allowed to debug, 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 scratch registers do not have supervisor access, and external debuggers with S-mode privilege cannot not use them as scratch memory.
|
{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 contol knobs for supervisor domain are specified in Smsdedbg and Smsdetrc extension respectively in RISC-V Supervisor Domains Access Protection cite:[smmtt]. The Smsdedbg and/or Smsdetrc extension must be implemented to support security control for debugging and/or tracing in supervisor domain.