5.1. Sdtrig (ISA Extension)
This chapter describes the Sdtrig ISA extension, which can be implemented independently of functionality described in the other chapters. It consists exclusively of the Trigger Module (TM).
Triggers can cause a breakpoint exception, entry into Debug Mode, or a trace action without having to execute a special instruction. This makes them invaluable when debugging code from ROM. They can trigger on execution of instructions at a given memory address, or on the address/data in loads/stores.
If Sdtrig is implemented, the Trigger Module must support at least one trigger. Accessing trigger CSRs that are not used by any of the implemented triggers must result in an illegal instruction exception. M-Mode and Debug Mode accesses to trigger CSRs that are used by any of the implemented triggers must succeed, regardless of the current type of the currently selected trigger.
A trigger matches when the conditions that it specifies (e.g. a load from a specific address) are met. A trigger fires when a trigger that matches performs the action configured for that trigger.
Triggers do not fire while in Debug Mode.
5.1.1. Enumeration
Each trigger may support a variety of features. A debugger can build a list of all triggers and their features as follows:
-
Write 0 to tselect. If this results in an illegal instruction exception, then there are no triggers implemented.
-
Read back tselect and check that it contains the written value. If not, exit the loop.
-
Read tinfo.
-
If that caused an exception, the debugger must read tdata1 to discover the type. (If type is 0, this trigger doesn’t exist. Exit the loop.)
-
If info is 1, this trigger doesn’t exist. Exit the loop.
-
Otherwise, the selected trigger supports the types discovered in info.
-
Repeat, incrementing the value in tselect.
5.1.2. Actions
Triggers can be configured to take one of several actions when they fire. Table 1 lists all options.
| Value | Description |
|---|---|
0 |
Raise a breakpoint exception. (Used when software wants to use the trigger module without an external debugger attached.) |
1 |
Enter Debug Mode. dpc must contain the virtual address of the next instruction that must be executed to preserve the program flow. |
2 |
Trace on, described in the trace specification. |
3 |
Trace off, described in the trace specification. |
4 |
Trace notify, described in the trace specification. |
5 |
Reserved for use by the trace specification. |
8 - 9 |
Send a signal to TM external trigger output 0 or 1 (respectively). |
other |
Reserved for future use. |
|
Actions 8 and 9 are intended to increment custom event counters, but these signals could also be brought to outputs for use by external logic. |
5.1.3. Priority
Table 2 lists the synchronous exceptions from the Privileged Spec, and where the various types of triggers fit in. The first 3 columns come from the Privileged Spec, and the final column shows where triggers fit in. Priorities in the table are separated by horizontal lines, so e.g. etrigger and itrigger have the same priority. If this table contradicts the table in the Privileged Spec, then the latter takes precedence.
This table only applies if triggers are precise. Otherwise triggers will fire some indeterminate time after the event, and the priority is irrelevant. When triggers are chained, the priority is the lowest priority of the triggers in the chain.
| Priority | Exception Code | Description | Trigger |
|---|---|---|---|
Highest |
3 |
etrigger |
|
3 |
Instruction address breakpoint |
mcontrol/mcontrol6 execute address before |
|
12, 20, 1 |
During instruction address translation: First encountered page fault, guest-page fault, or access fault |
||
1 |
With physical address for instruction: Instruction access fault |
||
3 |
mcontrol/mcontrol6 execute data before |
||
2 |
Illegal instruction |
mcontrol/mcontrol6 load/store address before, store data before |
|
4, 6 |
Optionally: Load/Store/AMO address misaligned |
||
13, 15, 21, 23, 5, 7 |
During address translation for an explicit memory access: First encountered page fault, guest-page fault, or access fault |
||
5, 7 |
With physical address for an explicit memory access: Load/store/AMO access fault |
||
4, 6 |
If not higher priority: Load/store/AMO address misaligned |
||
Lowest |
3 |
mcontrol/mcontrol6 load data before |
When multiple triggers in the same priority fire at once, hit (if
implemented) is set for all of them. If more than one of these triggers
has action=0 then tval is updated in accordance with one of them, but which one is UNSPECIFIED . If one of these triggers has the "enter Debug Mode" action (1)
and another trigger has the "raise a breakpoint exception" action (0),
the preferred behavior is to have both actions take place. It is
implementation-dependent which of the two happens first. This ensures
both that the presence of an external debugger doesn’t affect execution
and that a trigger set by user code doesn’t affect the external
debugger. If this is not implemented, then the hart must enter Debug
Mode and ignore the breakpoint exception. In the latter case, hit of the
trigger whose action is 0 must still be set, giving a debugger an
opportunity to handle this case.
Since triggers that have an action other than 0 or 1 don’t affect the execution
of the hart, they are not mentioned in the priority table. Such triggers fire
independently from those that have an action of 0 or 1.
5.1.4. Native Triggers
Triggers can be used for native debugging when action=0. If supported by the hart and desired by the debugger, triggers will often be programmed to have m=0 so that when they fire they cause a breakpoint exception to trap to a more privileged mode. That breakpoint exception can either be taken in M-mode or it can be delegated to a less privileged mode. However, it is possible for triggers to fire in the same mode that the resulting exception will be handled in.
In these cases such a trigger may cause a breakpoint exception while
already in a trap handler. This might leave the hart unable to resume
normal execution because state such as mcause and mepc would be overwritten.
|
In particular, when action=0:
|
Harts that support triggers with action=0 should implement one of the following two solutions to solve the problem of reentrancy:
-
The hardware prevents triggers with action=0 from matching or firing while in M-mode and while
MIEinmstatusis 0. Ifmedeleg[3]=1 then it prevents triggers with action=0 from matching or firing while in S-mode and whileSIEinsstatusis 0. Ifmedeleg[3]=1 andhedeleg[3]=1 then it prevents triggers with action=0 from matching or firing while in VS-mode and whileSIEinvstatusis 0. -
mte and mpte in tcontrol is implemented.
medeleg[3] is hard-wired to 0.
|
The first option has the limitation that interrupts might be disabled at times when a user still might want triggers to fire. It has the benefit that breakpoints are not required to be handled in M-mode. The second option has the benefit that it only disables triggers during the trap handler, though it requires specific software support for this debug feature in the M-mode trap handlers. It can only work if breakpoints are not delegated to less privileged modes and therefore targets primarily implementations without S-mode. Because tcontrol is not accessible to S-mode, the second option can not be extended to accommodate delegation without adding additional S-mode and VS-mode CSRs. Both options prevent etrigger and itrigger from having any effect on
exceptions and interrupts that are handled in M-mode. They also prevent
triggering during some initial portion of each handler. Debuggers should
use other mechanisms to debug these cases, such as patching the handler
or setting a breakpoint on the instruction after |
5.1.5. Memory Access Triggers
mcontrol and mcontrol6 both enable triggers on memory accesses. This section describes for both of them how certain corner cases are treated.
5.1.5.1. A Extension
If the A extension is supported, then triggers on loads/stores treat them as follows:
-
lrinstructions are loads. -
Successful
scinstructions are stores. -
It is UNSPECIFIED whether failing
scinstructions are stores or not. -
Each AMO instruction is a load for the read portion of the operation. The address is always available to trigger on, although the value loaded might not be, depending on the hardware implementation.
-
Each AMO instruction is a store for the write portion of the operation. The address is always available to trigger on. Whether data store triggers match on AMOs is UNSPECIFIED.
-
If the destination register of any load or AMO is
zerothen it is UNSPECIFIED whether a data load trigger will match.
5.1.5.2. Combined Accesses
Some instructions lead a hart to perform multiple memory accesses. This
includes vector loads and stores, as well as cm.push and cm.pop
instructions. The Trigger Module should match such accesses as if they
all happened individually. E.g. a vector load should be treated as if it
performed multiple loads of size SEW (selected element width), and
cm.push should be treated as if it performed multiple stores of size
XLEN.
5.1.5.3. Cache Operations
Cache operations are infrequently performed, and code that uses them can have hard-to-find bugs. For the purposes of debug triggers, two classes of cache operations must match as stores:
-
Cache operations that enable software to maintain coherence between otherwise non-coherent implicit and explicit memory accesses.
-
Cache operations that perform block writes of constant data.
Only triggers with size=0 and select=0 will match. Since cache operations affect multiple addresses, there are multiple possible values to compare against. Implementations must implement one of the following options. From most desirable to least desirable, they are:
-
Every address from the effective address rounded down to the nearest cache block boundary (inclusive) to the effective address rounded up to the nearest cache block boundary (exclusive) is a compare value.
-
The effective address rounded down to the nearest cache block boundary is a compare value.
-
The effective address of the instruction is a compare value.
Cache operations encoded as HINTs do not match debug triggers.
|
The above language intends to capture the trigger behavior with respect to the cache operations to be introduced in a forthcoming I/D consistency extension. For RISC-V Base Cache Management Operation ISA Extensions 1.0.1, this means the following:
|
5.1.5.4. Address Matches
For address matches without a mask, tdata2 must be able to hold all valid addresses in all supported translation modes. That means that after writing any of these valid addresses, the exact same value XLEN-wide value is read back, including any high bits. An implementation may be able to optimize the storage required, depending on the widest addresses it supports.
|
If physical addresses are less than XLEN bits wide, they are zero-extended. If virtual addresses are less than XLEN bits wide, they are sign-extended. tdata2 must be implemented with enough bits of storage to represent the full range of supported physical and virtual address values when read by software and used by hardware. |
5.1.5.4.1. Invalid Addresses
If tdata2 can hold any invalid addresses, then writes of an invalid address that can not be represented as-is should be converted to a different invalid address that can be represented.
For invalid instruction fetch addresses and load and store effective addresses, the compare value may be changed to a different invalid address.
In addition, an implementation may choose to inhibit all trigger matching against invalid addresses, especially if there is no support for storage of any invalid address values in tdata2.
5.1.6. Multiple State Change Instructions
An instruction that performs multiple architectural state changes (e.g., register updates and/or memory accesses) might cause a trigger to fire at an intermediate point in its execution. As a result, architectural state changes up to that point might have been performed, while subsequent state changes, starting from the event that activated the trigger, might not have been. The definition of such an instruction will specify the order in which architectural state changes take place. Alternatively, it may state that partial execution is not allowed, implying that a mid-execution trigger must prevent any architectural state changes from occurring.
Debuggers won’t be aware if an instruction has been partially executed. When they resume execution, they will execute the same instruction once more. Therefore, it’s crucial that partially executing the instruction and then executing it again leaves the hart in a state closely resembling the state it would have been in if the instruction had only been executed once.
5.1.7. Trigger Module Registers
These registers are CSRs, accessible using the RISC-V csr opcodes and
optionally also using abstract debug commands. They are the only mechanism
to access the triggers.
Almost all trigger functionality is optional. All tdata registers
follow write-any-read-legal semantics. If a debugger writes an
unsupported configuration, the register will read back a value that is
supported (which may simply be a disabled trigger). This means that a
debugger must always read back values it writes to tdata registers,
unless it already knows what is supported. Writes to one tdata
register must not modify the contents of other tdata registers, nor
the configuration of any trigger besides the one that is currently
selected.
The combination of these rules means that a debugger cannot simply set a trigger by writing tdata1, then tdata2, etc. The current value of tdata2 might not be legal with the new value of tdata1. To help with this situation, it is guaranteed that writing 0 to tdata1 disables the trigger, and leaves it in a state where tdata2 and tdata3 can be written with any value that makes sense for any trigger type supported by this trigger.
As a result, a debugger can write any supported trigger as follows:
Code that restores CSR context of triggers that might be configured to fire in the current privilege mode must use this same sequence to restore the triggers. This avoids the problem of a partially written trigger firing at a different time than is expected.
Attempts to access an unimplemented Trigger Module Register raise an illegal instruction exception.
The Trigger Module registers, except mscontext, scontext, and hcontext, are only accessible in machine and Debug Mode to prevent untrusted user code from causing entry into Debug Mode without the OS’s permission.
In this section XLEN refers to the effective XLEN in the current execution mode. On systems where XLEN values can differ between modes, this is handled as follows. Fields retain their values regardless of XLEN, which only affects where in the register these fields appear (e.g. type). Some fields are wider when XLEN is 64 than when it is 32 (e.g. svalue). The high bits in such fields retain their value but are not readable when XLEN is 32. A modification of a register when XLEN is 32 clears any inaccessible bits in that register.
| Address | Name | Section |
|---|---|---|
0x5a8 |
Supervisor Context (scontext) |
|
0x6a8 |
Hypervisor Context (hcontext) |
|
0x7a0 |
Trigger Select (tselect) |
|
0x7a1 |
Trigger Data 1 (tdata1) |
|
0x7a1 |
Match Control (mcontrol) |
|
0x7a1 |
Match Control Type 6 (mcontrol6) |
|
0x7a1 |
Instruction Count (icount) |
|
0x7a1 |
Interrupt Trigger (itrigger) |
|
0x7a1 |
Exception Trigger (etrigger) |
|
0x7a1 |
External Trigger (tmexttrigger) |
|
0x7a2 |
Trigger Data 2 (tdata2) |
|
0x7a3 |
Trigger Data 3 (tdata3) |
|
0x7a3 |
Trigger Extra (RV32) (textra32) |
|
0x7a3 |
Trigger Extra (RV64) (textra64) |
|
0x7a4 |
Trigger Info (tinfo) |
|
0x7a5 |
Trigger Control (tcontrol) |
|
0x7a8 |
Machine Context (mcontext) |
|
0x7aa |
Machine Supervisor Context (mscontext) |
Trigger Select (tselect, at 0x7a0)
This register determines which trigger is accessible through the other Trigger Module registers. It is optional if no triggers are implemented. The set of accessible triggers must start at 0, and be contiguous.
This register is WARL. Writes of values greater than or equal to the number of supported triggers may result in a different value in this register than what was written or may point to a trigger where type=0. To verify that what they wrote is a valid index, debuggers can read back the value and check that tselect holds what they wrote and read tdata1 to see that type is non-zero.
Since triggers can be used both by Debug Mode and M-mode, the external debugger must restore this register if it modifies it.
This CSR is read/write.
Trigger Data 1 (tdata1, at 0x7a1)
This register provides access to the trigger selected by tselect. The reset values listed here apply to every underlying trigger.
This register is optional if no triggers are implemented.
Writing 0 to this register must result in a trigger that is disabled. If this trigger supports multiple types, then the hardware should disable it by changing type to 15.
This CSR is read/write.
| Field | Description | Access | Reset |
|---|---|---|---|
0 (none): There is no trigger at this tselect. 1 (legacy): The trigger is a legacy SiFive address match trigger. These should not be implemented and aren’t further documented here. 2 (mcontrol): The trigger is an address/data match trigger. The remaining bits in this register act as described in mcontrol. 3 (icount): The trigger is an instruction count trigger. The remaining bits in this register act as described in icount. 4 (itrigger): The trigger is an interrupt trigger. The remaining bits in this register act as described in itrigger. 5 (etrigger): The trigger is an exception trigger. The remaining bits in this register act as described in etrigger. 6 (mcontrol6): The trigger is an address/data match trigger. The remaining bits in this register act as described in mcontrol6. This is similar to a type 2 trigger, but provides additional functionality and should be used instead of type 2 in newer implementations. 7 (tmexttrigger): The trigger is a trigger source external to the TM. The remaining bits in this register act as described in tmexttrigger. 12—14 (custom): These trigger types are available for non-standard use. 15 (disabled): This trigger is disabled. In this state, tdata2 and tdata3 can be written with any value that is supported for any of the types this trigger implements. The remaining bits in this register, except for dmode, are ignored. Other values are reserved for future use. |
WARL |
Preset |
|
If type is 0, then this bit is hard-wired to 0. 0 (both): Both Debug and M-mode can write the 1 (dmode): Only Debug Mode can write the This bit is only writable from Debug Mode. In ordinary use, external debuggers will always set this bit when configuring a trigger. When clearing this bit, debuggers should also set the action field (whose location depends on type) to something other than 1. |
WARL |
0 |
|
If type is 0, then this field is hard-wired to 0. Trigger-specific data. |
WARL |
Preset |
Trigger Data 2 (tdata2, at 0x7a2)
This register provides access to the trigger selected by tselect. The reset values listed here apply to every underlying trigger.
Trigger-specific data. It is optional if no implemented triggers use it.
If the trigger is disabled, then this register can be written with any value supported by any of the trigger types supported by this trigger.
If XLEN is less than DXLEN, writes to this register are sign-extended.
This CSR is read/write.
Trigger Data 3 (tdata3, at 0x7a3)
This register provides access to the trigger selected by tselect. The reset values listed here apply to every underlying trigger.
Trigger-specific data. It is optional if no implemented triggers use it.
If the trigger is disabled, then this register can be written with any value supported by any of the trigger types supported by this trigger.
If XLEN is less than DXLEN, writes to this register are sign-extended.
This CSR is read/write.
Trigger Info (tinfo, at 0x7a4)
This register provides access to the trigger selected by tselect. The reset values listed here apply to every underlying trigger.
This register is optional if no triggers are implemented, or if type is not writable and version would be 0. In this case the debugger can read the only supported type from tdata1.
Writing this read/write CSR has no effect.
| Field | Description | Access | Reset |
|---|---|---|---|
Contains the version of the Sdtrig extension implemented. 0 (0): Supports triggers as described in this spec at commit 5a5c078, made on February 2, 2023. In these older versions: 1 (1): Supports triggers as described in the ratified version 1.0 of this document. |
R |
Preset |
|
R |
Preset |
Trigger Control (tcontrol, at 0x7a5)
This optional register is only accessible in M-mode and Debug Mode and provides various control bits related to triggers.
This CSR is read/write.
| Field | Description | Access | Reset |
|---|---|---|---|
M-mode previous trigger enable field. mpte and mte provide one solution to a problem regarding triggers with action=0 firing in M-mode trap handlers. See 5.1.4. Native Triggers for more details. |
WARL |
0 |
|
WARL |
0 |
Hypervisor Context (hcontext, at 0x6a8)
This optional register may be implemented only if the H extension is implemented. If it is implemented, mcontext must also be implemented.
This register is only accessible in HS-Mode, M-mode and Debug Mode. If
Smstateen is implemented, then accessibility of in HS-Mode is
controlled by mstateenzero[57].
Supervisor Context (scontext, at 0x5a8)
This optional register is only accessible in S/HS-mode, VS-mode, M-mode and Debug Mode.
Accessibility of this CSR is controlled by mstateenzero[57] and
hstateenzero[57] in the Smstateen extension. Enabling scontext
can be a security risk in a virtualized system with a hypervisor that
does not swap scontext.
This CSR is read/write.
| Field | Description | Access | Reset |
|---|---|---|---|
Supervisor mode software can write a context number to this register, which can be used to set triggers that only fire in that specific context. An implementation may tie any number of high bits in this field to 0. It’s recommended to implement 16 bits on RV32 and 32 bits on RV64. |
WARL |
0 |
Machine Context (mcontext, at 0x7a8)
This register must be implemented if hcontext is implemented, and is optional otherwise. It is only accessible in M-mode and Debug mode.
|
hcontext is primarily useful to set triggers on hypervisor systems that only fire when a given VM is executing. It is also useful in systems where M-Mode implements something like a hypervisor directly. |
This CSR is read/write.
| Field | Description | Access | Reset |
|---|---|---|---|
M-Mode or HS-Mode (using hcontext) software can write a context number to this register, which can be used to set triggers that only fire in that specific context. An implementation may tie any number of upper bits in this field to 0. If the H extension is not implemented, it’s recommended to implement 6 bits on RV32 and 13 bits on RV64 (as visible through the mcontext register). If the H extension is implemented, it’s recommended to implement 7 bits on RV32 and 14 bits on RV64. |
WARL |
0 |
Machine Supervisor Context (mscontext, at 0x7aa)
This optional register is an alias for scontext. It is only accessible in S/HS-mode, M-mode and Debug Mode. It is included for backward compatibility with version 0.13.
|
The encoding of this CSR does not conform to the CSR Address Mapping Convention in the Privileged Spec. It is expected that new implementations will not support this encoding and that new debuggers will not use this CSR if scontext is available. |
Match Control (mcontrol, at 0x7a1)
This register provides access to the trigger selected by tselect. The reset values listed here apply to every underlying trigger.
This register is accessible as tdata1 when type is 2. This trigger type is deprecated. It is included for backward compatibility with version 0.13.
Address and data trigger implementation are heavily dependent on how the processor core is implemented. To accommodate various implementations, execute, load, and store address/data triggers may fire at whatever point in time is most convenient for the implementation. The debugger may request specific timings as described in timing. Table 4 suggests timings for the best user experience.
A chain of triggers that don’t all have the same timing value will never fire. That means to implement the suggestions in Table 4, both timings should be supported on load address triggers that can be chained with a load data trigger.
The Privileged Spec says that breakpoint exceptions that occur on
instruction fetches, loads, or stores update the tval CSR
with either zero or the faulting virtual address. The faulting
virtual address for an mcontrol trigger with action=0 is the
address being accessed and which caused that trigger to fire.
If multiple mcontrol triggers are chained then the faulting
virtual address is the address which caused any of the chained
triggers to fire.
If textra32 or textra64 are implemented for this trigger, it only matches when the conditions set there are satisfied.
This CSR is read/write.
| Field | Description | Access | Reset |
|---|---|---|---|
Specifies the largest naturally aligned powers-of-two (NAPOT) range supported by the hardware when match is 1. The value is the logarithm base 2 of the number of bytes in that range. A value of 0 indicates match 1 is not supported. A value of 63 corresponds to the maximum NAPOT range, which is 263 bytes in size. |
R |
Preset |
|
WARL |
0 |
||
If this bit is implemented then it must become set when this trigger fires and may become set when this trigger matches. The trigger’s user can set or clear it at any time. It is used to determine which trigger(s) matched. If the bit is not implemented, it is always 0 and writing it has no effect. |
WARL |
0 |
|
This bit determines the contents of the XLEN-bit compare values. 0 (address): There is at least one compare value and it contains the lowest virtual address of the access. It is recommended that there are additional compare values for the other accessed virtual addresses. (E.g. on a 32-bit read from 0x4000, the lowest address is 0x4000 and the other addresses are 0x4001, 0x4002, and 0x4003.) 1 (data): There is exactly one compare value and it contains the data value loaded or stored, or the instruction executed. Any bits beyond the size of the data access will contain 0. |
WARL |
0 |
|
0 (before): The action for this trigger will be taken just before the
instruction that triggered it is retired, but after all preceding
instructions are retired. If this is combined with load and select=1 then a memory access will be performed (including any side effects of performing such an access) even though the load will not update its destination register. Debuggers should consider this when setting such breakpoints on, for example, memory-mapped I/O addresses. If an instruction matches this trigger and the instruction performs multiple memory accesses, it is UNSPECIFIED which memory accesses have completed before the trigger fires. 1 (after): The action for this trigger will be taken after the instruction
that triggered it is retired. It should be taken before the next
instruction is retired, but it is better to implement triggers imprecisely
than to not implement them at all. Most hardware will only implement one timing or the other, possibly dependent on select, execute, load, and store. This bit primarily exists for the hardware to communicate to the debugger what will happen. Hardware may implement the bit fully writable, in which case the debugger has a little more control. |
WARL |
0 |
|
This field contains the 2 low bits of the access size. The high bits come from sizehi. The combined value is interpreted as follows: 0 (any): The trigger will attempt to match against an access of any size. The behavior is only well-defined if select=0, or if the access size is XLEN. 1 (8bit): The trigger will only match against 8-bit memory accesses. 2 (16bit): The trigger will only match against 16-bit memory accesses or execution of 16-bit instructions. 3 (32bit): The trigger will only match against 32-bit memory accesses or execution of 32-bit instructions. 4 (48bit): The trigger will only match against execution of 48-bit instructions. 5 (64bit): The trigger will only match against 64-bit memory accesses or execution of 64-bit instructions. 6 (80bit): The trigger will only match against execution of 80-bit instructions. 7 (96bit): The trigger will only match against execution of 96-bit instructions. 8 (112bit): The trigger will only match against execution of 112-bit instructions. 9 (128bit): The trigger will only match against 128-bit memory accesses or execution of 128-bit instructions. An implementation must support the value of 0, but all other values are optional. When an implementation supports address triggers (select=0), it is recommended that those triggers support every access size that the hart supports, as well as for every instruction size that the hart supports. Implementations such as RV32D or RV64V are able to perform loads and stores that are wider than XLEN. Custom extensions may also support instructions that are wider than XLEN. Because tdata2 is of size XLEN, there is a known limitation that data value triggers (select=1) can only be supported for access sizes up to XLEN bits. When an implementation supports data value triggers (select=1), it is recommended that those triggers support every access size up to XLEN that the hart supports, as well as for every instruction length up to XLEN that the hart supports. |
WARL |
0 |
|
The action to take when the trigger fires. The values are explained in Table 1. |
WARL |
0 |
|
0 (disabled): When this trigger matches, the configured action is taken. 1 (enabled): While this trigger does not match, it prevents the trigger with the next index from matching. A trigger chain starts on the first trigger with Debuggers should not terminate a chain with a trigger with a different type. It is undefined when exactly such a chain fires. Because chain affects the next trigger, hardware must zero it in writes to mcontrol that set dmode to 0 if the next trigger has dmode of 1. In addition hardware should ignore writes to mcontrol that set dmode to 1 if the previous trigger has both dmode of 0 and chain of 1. Debuggers must avoid the latter case by checking chain on the previous trigger if they’re writing mcontrol. |
WARL |
0 |
|
0 (equal): Matches when any compare value equals tdata2. 1 (napot): Matches when the top 2 (ge): Matches when any compare value is greater than (unsigned) or equal to tdata2. 3 (lt): Matches when any compare value is less than (unsigned) tdata2. 4 (mask low): Matches when of any compare value
equals of tdata2 after
of the compare value is ANDed with
5 (mask high): Matches when 8 (not equal): Matches when match=0 would not match. 9 (not napot): Matches when match=1 would not match. 12 (not mask low): Matches when match=4 would not match. 13 (not mask high): Matches when match=5 would not match. Other values are reserved for future use. |
WARL |
0 |
|
When set, enable this trigger in M-mode. |
WARL |
0 |
|
When set, enable this trigger in S/HS-mode. This bit is hard-wired to 0 if the hart does not support S-mode. |
WARL |
0 |
|
When set, enable this trigger in U-mode. This bit is hard-wired to 0 if the hart does not support U-mode. |
WARL |
0 |
|
When set, the trigger fires on the virtual address or opcode of an instruction that is executed. |
WARL |
0 |
|
When set, the trigger fires on the virtual address or data of any store. |
WARL |
0 |
|
When set, the trigger fires on the virtual address or data of any load. |
WARL |
0 |
Match Control Type 6 (mcontrol6, at 0x7a1)
This register provides access to the trigger selected by tselect. The reset values listed here apply to every underlying trigger.
Implementing this trigger as described here requires that version is 1 or higher, which in turn means tinfo must be implemented.
This replaces mcontrol in newer implementations and serves to provide additional functionality.
Address and data trigger implementation are heavily dependent on how the processor core is implemented. To accommodate various implementations, execute, load, and store address/data triggers may fire at whatever point in time is most convenient for the implementation.
Table 4 suggests timings for the best user experience. The underlying principle is that firing just before the instruction gives a user more insight, so is preferable. However, depending on the instruction and conditions, it might not be possible to evaluate the trigger until the instruction has partially executed. In that case it is better to let the instruction retire before the trigger fires, to avoid extra memory accesses which might affect the state of the system.
| Match Type | Suggested Trigger Timing |
|---|---|
Execute Address |
Before |
Execute Instruction |
Before |
Execute Address+Instruction |
Before |
Load Address |
Before |
Load Data |
After |
Load Address+Data |
After |
Store Address |
Before |
Store Data |
Before |
Store Address+Data |
Before |
A chain of triggers must only fire if every trigger in the chain was matched by the same instruction.
The Privileged Spec says that breakpoint exceptions that occur on
instruction fetches, loads, or stores update the tval CSR
with either zero or the faulting virtual address. The faulting
virtual address for an mcontrol6 trigger with action=0 is the
address being accessed and which caused that trigger to fire.
If multiple mcontrol6 triggers are chained then the faulting
virtual address is the address which caused any of the chained
triggers to fire.
In implementations that support match mode 1 (NAPOT), not all NAPOT ranges may be supported. All NAPOT ranges between and are supported where . The value of maskmax6 can be determined by the debugger via the following sequence:
-
Write tdata1=0, in case the current tdata2 value is not supported with mcontrol6 triggers.
-
Write tdata2=0, which is always supported with mcontrol6 triggers.
-
Read match. If it is not 1 then NAPOT matching is not supported.
-
Write all ones to tdata2.
-
Read tdata2. The value of maskmax6 is the index of the most significant 0 bit plus 1.
If textra32 or textra64 are implemented for this trigger, it only matches when the conditions set there are satisfied.
|
uncertain and uncertainen exist to accommodate systems where not every memory access is fully observed by the Trigger Module. Possible examples include data values in far AMOs, and the address/data/size of accesses by instructions that perform multiple memory accesses, such as vector, push, and pop instructions. While the uncertain mechanism exists to deal with these situations, it can lead to an unusable number of false positives. Users will get a much better debug experience if the TM does have perfect visibility into the details of every memory access. |
This CSR is read/write.
| Field | Description | Access | Reset |
|---|---|---|---|
If implemented, the TM updates this field every time the trigger fires. 0 (certain): The trigger that fired satisfied the configured conditions, or this bit is not implemented. 1 (uncertain): The trigger that fired might not have perfectly satisfied the configured conditions. Due to the implementation the hardware cannot be certain. |
WARL |
0 |
|
When set, enable this trigger in VS-mode. This bit is hard-wired to 0 if the hart does not support virtualization mode. |
WARL |
0 |
|
When set, enable this trigger in VU-mode. This bit is hard-wired to 0 if the hart does not support virtualization mode. |
WARL |
0 |
|
If they are implemented, hit1 (MSB) and hit0 (LSB) combine into a single 2-bit field. The TM updates this field when the trigger fires. After the debugger has seen the update, it will normally write 0 to this field to so it can see future changes. If either of the bits is not implemented, the unimplemented bits will be read-only 0. 0 (false): The trigger did not fire. 1 (before): The trigger fired before the instruction that matched it was retired, but after all preceding instructions are retired. This explicitly allows for instructions to be partially executed, as described in 5.1.6. Multiple State Change Instructions.
2 (after): The trigger fired after the instruction that triggered and at least
one additional instruction were retired.
3 (immediately after): The trigger fired just after the instruction that triggered it was
retired, but before any subsequent instructions were executed.
If the instruction performed multiple memory accesses, all of them have been completed. |
WARL |
0 |
|
This bit determines the contents of the XLEN-bit compare values. 0 (address): There is at least one compare value and it contains the lowest virtual address of the access. In addition, it is recommended that there are additional compare values for the other accessed virtual addresses match. (E.g. on a 32-bit read from 0x4000, the lowest address is 0x4000 and the other addresses are 0x4001, 0x4002, and 0x4003.) 1 (data): There is exactly one compare value and it contains the data value loaded or stored, or the instruction executed. Any bits beyond the size of the data access will contain 0. |
WARL |
0 |
|
0 (any): The trigger will attempt to match against an access of any size. The behavior is only well-defined if select=0, or if the access size is XLEN. 1 (8bit): The trigger will only match against 8-bit memory accesses. 2 (16bit): The trigger will only match against 16-bit memory accesses or execution of 16-bit instructions. 3 (32bit): The trigger will only match against 32-bit memory accesses or execution of 32-bit instructions. 4 (48bit): The trigger will only match against execution of 48-bit instructions. 5 (64bit): The trigger will only match against 64-bit memory accesses or execution of 64-bit instructions. 6 (128bit): The trigger will only match against 128-bit memory accesses or execution of 128-bit instructions. An implementation must support the value of 0, but all other values are optional. When an implementation supports address triggers (select=0), it is recommended that those triggers support every access size that the hart supports, as well as for every instruction size that the hart supports. Implementations such as RV32D or RV64V are able to perform loads and stores that are wider than XLEN. Custom extensions may also support instructions that are wider than XLEN. Because tdata2 is of size XLEN, there is a known limitation that data value triggers (select=1) can only be supported for access sizes up to XLEN bits. When an implementation supports data value triggers (select=1), it is recommended that those triggers support every access size up to XLEN that the hart supports, as well as for every instruction length up to XLEN that the hart supports. |
WARL |
0 |
|
The action to take when the trigger fires. The values are explained in Table 1. |
WARL |
0 |
|
0 (disabled): When this trigger matches, the configured action is taken. 1 (enabled): While this trigger does not match, it prevents the trigger with the next index from matching. A trigger chain starts on the first trigger with Debuggers should not terminate a chain with a trigger with a different type. It is undefined when exactly such a chain fires. Because chain affects the next trigger, hardware must zero it in writes to mcontrol6 that set dmode to 0 if the next trigger has dmode of 1. In addition hardware should ignore writes to mcontrol6 that set dmode to 1 if the previous trigger has both dmode of 0 and chain of 1. Debuggers must avoid the latter case by checking chain on the previous trigger if they’re writing mcontrol6. |
WARL |
0 |
|
0 (equal): Matches when any compare value equals tdata2. 1 (napot): Matches when the top 2 (ge): Matches when any compare value is greater than (unsigned) or equal to tdata2. 3 (lt): Matches when any compare value is less than (unsigned) tdata2. 4 (mask low): Matches when of any compare value
equals of tdata2 after
of the compare value is ANDed with
5 (mask high): Matches when 8 (not equal): Matches when match 9 (not napot): Matches when match 12 (not mask low): Matches when match 13 (not mask high): Matches when match Other values are reserved for future use. |
WARL |
0 |
|
When set, enable this trigger in M-mode. |
WARL |
0 |
|
0 (disabled): This trigger will only match if the hardware can perfectly evaluate it. 1 (enabled): This trigger will match if it’s possible that it would match if the Trigger Module had perfect information about the operations being performed. |
WARL |
0 |
|
When set, enable this trigger in S/HS-mode. This bit is hard-wired to 0 if the hart does not support S-mode. |
WARL |
0 |
|
When set, enable this trigger in U-mode. This bit is hard-wired to 0 if the hart does not support U-mode. |
WARL |
0 |
|
When set, the trigger fires on the virtual address or opcode of an instruction that is executed. |
WARL |
0 |
|
When set, the trigger fires on the virtual address or data of any store. |
WARL |
0 |
|
When set, the trigger fires on the virtual address or data of any load. |
WARL |
0 |
Instruction Count (icount, at 0x7a1)
This register provides access to the trigger selected by tselect. The reset values listed here apply to every underlying trigger.
This trigger matches when:
-
An instruction retires after having been fetched in a privilege mode where the trigger is enabled. This explicitly includes all RET instructions from various modes.
-
A trap is taken from a privilege mode where the trigger is enabled. This explicitly includes traps taken due to interrupts.
If more than one of the above events occur during a single instruction execution, the trigger still only matches once for that instruction.
|
For use in single step, icount must match for traps where the instruction will not be reexecuted after the handler, such as illegal instructions that are emulated by privileged software and the instruction being emulated never retires. Ideally, icount would not match for traps where the instruction will later be retried by the handler, such as page faults where privileged software modifies the page tables and returns to the faulting instruction which ultimately retires. Trying to distinguish the two cases leads to complex rules, so instead the rule is simply that all traps match. See also [stepicount]. |
When count is 1 and the trigger matches, then pending becomes set. In addition count will become 0 unless it is hard-wired to 1.
The only exception to the above is when the instruction the trigger matched on is a write to the icount trigger. In that case pending might or might not become set if count was 1. Afterwards count contains the newly written value.
When count is 0 it stays at 0 until explicitly written.
When pending is set, the trigger fires just before any further instructions are executed in a mode where the trigger is enabled. As the trigger fires, pending is cleared. In addition, if count is hard-wired to 1 then m, s, u, vs, and vu are all cleared.
If the trigger fires with action=0 then zero is written to the
tval CSR on the breakpoint trap.
|
This trigger type is intended to be used as a single step for software monitor programs or native debug. Systems that support multiple privilege modes that want to debug software running in lower privilege modes don’t need to support count greater than 1. |
If textra32 or textra64 are implemented for this trigger, it only matches when the conditions set there are satisfied.
This CSR is read/write.
| Field | Description | Access | Reset |
|---|---|---|---|
When set, enable this trigger in VS-mode. This bit is hard-wired to 0 if the hart does not support virtualization mode. |
WARL |
0 |
|
When set, enable this trigger in VU-mode. This bit is hard-wired to 0 if the hart does not support virtualization mode. |
WARL |
0 |
|
If this bit is implemented, the hardware sets it when this trigger fires. The trigger’s user can set or clear it at any time. It is used to determine which trigger(s) fires. If the bit is not implemented, it is always 0 and writing it has no effect. |
WARL |
0 |
|
The trigger will generally fire after count instructions in enabled modes have been executed. See above for the precise behavior. |
WARL |
1 |
|
When set, enable this trigger in M-mode. |
WARL |
0 |
|
This bit becomes set when count is decremented from 1 to 0. It is cleared when the trigger fires, which will happen just before executing the next instruction in one of the enabled modes. |
R/W |
0 |
|
When set, enable this trigger in S/HS-mode. This bit is hard-wired to 0 if the hart does not support S-mode. |
WARL |
0 |
|
When set, enable this trigger in U-mode. This bit is hard-wired to 0 if the hart does not support U-mode. |
WARL |
0 |
|
The action to take when the trigger fires. The values are explained in Table 1. |
WARL |
0 |
Interrupt Trigger (itrigger, at 0x7a1)
This register provides access to the trigger selected by tselect. The reset values listed here apply to every underlying trigger.
This trigger can fire when an interrupt trap is taken.
It can be enabled for individual interrupt numbers by setting the bit corresponding to the interrupt number in tdata2. The interrupt number is interpreted in the mode that the trap handler executes in. (E.g. virtualized interrupt numbers are not the same in every mode.) In addition the trigger can be enabled for non-maskable interrupts using nmi.
|
If XLEN is 32, then it is not possible to set a trigger for interrupts with Exception Code larger than 31. A future version of the RISC-V Privileged Spec will likely define interrupt Exception Codes 32 through 47. Some of those numbers are already being used by the RISC-V Advanced Interrupt Architecture. |
Hardware may only support a subset of interrupts for this trigger. A debugger must read back tdata2 after writing it to confirm the requested functionality is actually supported.
When the trigger matches, it fires after the trap occurs, just before
the first instruction of the trap handler is executed. If
action=0, the standard CSRs are updated for taking the
breakpoint trap, and zero is written to the relevant tval CSR. If
the breakpoint trap does not go to a higher privilege mode, this will
lose CSR information for the original trap. See
5.1.4. Native Triggers for more information about this case.
If textra32 or textra64 are implemented for this trigger, it only matches when the conditions set there are satisfied.
This CSR is read/write.
| Field | Description | Access | Reset |
|---|---|---|---|
If this bit is implemented, the hardware sets it when this trigger matches. The trigger’s user can set or clear it at any time. It is used to determine which trigger(s) matched. If the bit is not implemented, it is always 0 and writing it has no effect. |
WARL |
0 |
|
When set, enable this trigger for interrupts that are taken from VS mode. This bit is hard-wired to 0 if the hart does not support virtualization mode. |
WARL |
0 |
|
When set, enable this trigger for interrupts that are taken from VU mode. This bit is hard-wired to 0 if the hart does not support virtualization mode. |
WARL |
0 |
|
When set, non-maskable interrupts cause this trigger to fire if the trigger is enabled for the current mode. |
WARL |
0 |
|
When set, enable this trigger for interrupts that are taken from M mode. |
WARL |
0 |
|
When set, enable this trigger for interrupts that are taken from S/HS mode. This bit is hard-wired to 0 if the hart does not support S-mode. |
WARL |
0 |
|
When set, enable this trigger for interrupts that are taken from U mode. This bit is hard-wired to 0 if the hart does not support U-mode. |
WARL |
0 |
|
The action to take when the trigger fires. The values are explained in Table 1. |
WARL |
0 |
Exception Trigger (etrigger, at 0x7a1)
This register provides access to the trigger selected by tselect. The reset values listed here apply to every underlying trigger.
This trigger may fire on up to XLEN of the Exception Codes defined in
mcause (described in the Privileged Spec, with Interrupt=0). Those
causes are configured by writing the corresponding bit in tdata2.
(E.g. to trap on an illegal instruction, the debugger sets bit 2 in
tdata2.)
|
If XLEN is 32, then it is not possible to set a trigger on Exception Codes higher than 31. A future version of the RISC-V Privileged Spec will likely define Exception Codes 32 through 47. |
Hardware may support only a subset of exceptions. A debugger must read back tdata2 after writing it to confirm the requested functionality is actually supported.
When the trigger matches, it fires after the trap occurs, just before
the first instruction of the trap handler is executed. If
action=0, the standard CSRs are updated for taking the
breakpoint trap, and zero is written to the relevant tval CSR. If
the breakpoint trap does not go to a higher privilege mode, this will
lose CSR information for the original trap. See
5.1.4. Native Triggers for more information about this case.
If textra32 or textra64 are implemented for this trigger, it only matches when the conditions set there are satisfied.
This CSR is read/write.
| Field | Description | Access | Reset |
|---|---|---|---|
If this bit is implemented, the hardware sets it when this trigger matches. The trigger’s user can set or clear it at any time. It is used to determine which trigger(s) matched. If the bit is not implemented, it is always 0 and writing it has no effect. |
WARL |
0 |
|
When set, enable this trigger for exceptions that are taken from VS mode. This bit is hard-wired to 0 if the hart does not support virtualization mode. |
WARL |
0 |
|
When set, enable this trigger for exceptions that are taken from VU mode. This bit is hard-wired to 0 if the hart does not support virtualization mode. |
WARL |
0 |
|
When set, enable this trigger for exceptions that are taken from M mode. |
WARL |
0 |
|
When set, enable this trigger for exceptions that are taken from S/HS mode. This bit is hard-wired to 0 if the hart does not support S-mode. |
WARL |
0 |
|
When set, enable this trigger for exceptions that are taken from U mode. This bit is hard-wired to 0 if the hart does not support U-mode. |
WARL |
0 |
|
The action to take when the trigger fires. The values are explained in Table 1. |
WARL |
0 |
External Trigger (tmexttrigger, at 0x7a1)
This register provides access to the trigger selected by tselect. The reset values listed here apply to every underlying trigger.
This trigger fires when any selected TM external trigger input signals. Up to 16 TM external trigger inputs coming from other blocks outside the TM, (e.g. signaling an hpmcounter overflow) can be selected. Hardware may support none or just a few TM external trigger inputs (starting with TM external trigger input 0 and continuing sequentially). Unsupported inputs are hardwired to be inactive.
If the trigger fires with action=0 then zero is written to the
tval CSR on the breakpoint trap. This trigger fires
asynchronously but it is subject to delegation by medeleg[3] like
the other triggers.
The TM external trigger input can signal when the trigger is prevented from firing due to one of the mechanisms in 5.1.4. Native Triggers. An implementation may either ignore the signal altogether when it cannot fire (dropping the trigger event) or it may hold the action as pending and fire the trigger once it is legal to do so.
|
intctl is intended to be used by the |
This CSR is read/write.
| Field | Description | Access | Reset |
|---|---|---|---|
If this bit is implemented, the hardware sets it when this trigger matches. The trigger’s user can set or clear it at any time. It is used to determine which trigger(s) matched. If the bit is not implemented, it is always 0 and writing it has no effect. |
WARL |
0 |
|
This optional bit, when set, causes this trigger to fire whenever an attached interrupt controller signals a trigger. |
WARL |
0 |
|
Selects any combination of up to 16 TM external trigger inputs that cause this trigger to fire. |
WARL |
0 |
|
The action to take when the trigger fires. The values are explained in Table 1. |
WARL |
0 |
Trigger Extra (RV32) (textra32, at 0x7a3)
This register provides access to the trigger selected by tselect. The reset values listed here apply to every underlying trigger.
If DXLEN >= 64, then this register provides access to the low bits of each field defined in textra64. Writes to this register will clear the high bits of the corresponding fields in textra64.
All functionality in this register is optional. Any number of upper bits of mhvalue and svalue may be tied to 0. mhselect and sselect may only support 0 (ignore).
Byte-granular comparison of scontext to svalue allows scontext to be defined to include more than one element of comparison. For example, software instrumentation can program the scontext value to be the concatenation of different ID contexts such as process ID and thread ID. The user can then program byte compares based on sbytemask to include one or more of the contexts in the compare.
|
Note that sselect and mhselect filtering apply in all modes, including M-mode and S-mode. If desired, debuggers can use a trigger’s mode filtering bits to restrict the matching to modes where it considers ASID/VMID/scontext/hcontext to be active. |
This CSR is read/write.
| Field | Description | Access | Reset |
|---|---|---|---|
Data used together with mhselect. |
WARL |
0 |
|
0 (ignore): Ignore mhvalue. 4 (mcontext): This trigger will only match or fire if the low bits of mcontext/hcontext equal mhvalue. 1, 5 (mcontext_select): This trigger will only match or fire if the low bits of mcontext/hcontext equal {mhvalue, mhselect[2]}. 2, 6 (vmid_select): This trigger will only match or fire if VMID in hgatp equals the lower VMIDMAX (defined in the Privileged Spec) bits of {mhvalue, mhselect[2]}. 3, 7 (reserved): Reserved. If the H extension is not supported, the only legal values are 0 and 4. |
WARL |
0 |
|
WARL |
0 |
||
Data used together with sselect. This field should be tied to 0 when S-mode is not supported. |
WARL |
0 |
|
0 (ignore): Ignore svalue. 2 (asid): This trigger will only match or fire if: This field should be tied to 0 when S-mode is not supported. |
WARL |
0 |
Trigger Extra (RV64) (textra64, at 0x7a3)
This register provides access to the trigger selected by tselect. The reset values listed here apply to every underlying trigger.
This register is accessible as tdata3 when type is 2, 3, 4, 5, or 6 and XLEN=64. The function of the fields are defined above, in textra32. This register retains its value when XLEN changes. When XLEN=32 some of the bits can be accessed through textra32.
Byte-granular comparison of scontext to svalue in textra64 allows scontext to be defined to include more than one element of comparison. For example, software instrumentation can program the scontext value to be the concatenation of different ID contexts such as process ID and thread ID. The user can then program byte compares based on sbytemask to include one or more of the contexts in the compare.
This CSR is read/write.
| Field | Description | Access | Reset |
|---|---|---|---|
When the least significant bit of this field is 1, it causes bits 7:0 in the comparison to be ignored, when sselect=1. Likewise, the second bit controls the comparison of bits 15:8, third bit controls the comparison of bits 23:16, and fourth bit controls the comparison of bits 31:24. |
WARL |
0 |