2 CSRs
CSR field specifications (such as WARL and WPRI) can be found in the RISC-V Instruction Set Manual vol. II (Privileged Architecture), section 2.3.
2.1 Machine Control Transfer Records Control Register (mctrctl)
The mctrctl register is a 64-bit read/write register that enables and configures the CTR capability.
Table 1. Machine Control Transfer Records Control Register Field Definitions
| Field | Description |
|---|---|
| M, S, U | Enable transfer recording in the selected privileged mode(s). |
| RASEMU | Enables RAS (Return Address Stack) Emulation Mode. See Section 6.4. |
| MTE | Enables recording of traps to M-mode when M=0. See Section 6.1.2. |
| STE | Enables recording of traps to S-mode when S=0. See Section 6.1.2. |
| BPFRZ | Set sctrstatus.FROZEN on a breakpoint exception that traps to M-mode or S-mode. See Section 6.5. |
| LCOFIFRZ | Set sctrstatus.FROZEN on local counter overflow interrupt (LCOFI) that traps to M-mode or S-mode. See Section 6.5. |
| EXCINH | Inhibit recording of exceptions. See Section 6.2. |
| INTRINH | Inhibit recording of interrupts. See Section 6.2. |
| TRETINH | Inhibit recording of trap returns. See Section 6.2. |
| NTBREN | Enable recording of not-taken branches. See Section 6.2. |
| TKBRINH | Inhibit recording of taken branches. See Section 6.2. |
| INDCALLINH | Inhibit recording of indirect calls. See Section 6.2. |
| DIRCALLINH | Inhibit recording of direct calls. See Section 6.2. |
| INDJMPINH | Inhibit recording of indirect jumps (without linkage). See Section 6.2. |
| DIRJMPINH | Inhibit recording of direct jumps (without linkage). See Section 6.2. |
| CORSWAPINH | Inhibit recording of co-routine swaps. See Section 6.2. |
| RETINH | Inhibit recording of function returns. See Section 6.2. |
| INDLJMPINH | Inhibit recording of other indirect jumps (with linkage). See Section 6.2. |
| DIRLJMPINH | Inhibit recording of other direct jumps (with linkage). See Section 6.2. |
| Custom[3:0] | WARL bits designated for custom use. The value 0 must correspond to standard behavior. See Section 7. |
All fields are optional except for M, S, U, and BPFRZ. All unimplemented fields are read-only 0, while all implemented fields are writable. If the Sscofpmf extension is implemented, LCOFIFRZ must be writable.
2.2 Supervisor Control Transfer Records Control Register (sctrctl)
The sctrctl register provides supervisor mode access to a subset of mctrctl.
Bits 2 and 9 in sctrctl are read-only 0. As a result, the M and MTE fields in mctrctl are not accessible through sctrctl. All other mctrctl fields are accessible through sctrctl.
2.3 Virtual Supervisor Control Transfer Records Control Register (vsctrctl)
If the H extension is implemented, the vsctrctl register is a 64-bit read/write register that is VS-mode’s version of supervisor register sctrctl. When V=1, vsctrctl substitutes for the usual sctrctl, so instructions that normally read or modify sctrctl actually access vsctrctl instead.
Table 2. Virtual Supervisor Control Transfer Records Control Register Field Definitions
| Field | Description |
|---|---|
| S | Enable transfer recording in VS-mode. |
| U | Enable transfer recording in VU-mode. |
| STE | Enables recording of traps to VS-mode when S=0. See Section 6.1.2. |
| BPFRZ | Set sctrstatus.FROZEN on a breakpoint exception that traps to VS-mode. See Section 6.5. |
| LCOFIFRZ | Set sctrstatus.FROZEN on local counter overflow interrupt (LCOFI) that traps to VS-mode. See Section 6.5. |
Other field definitions match those of sctrctl. The optional fields implemented in vsctrctl should match those implemented in sctrctl. | |
Unlike the CTR status register or the CTR entry registers, the CTR control register has a VS-mode version. This allows a guest to manage the CTR configuration directly, without requiring traps to HS-mode, while ensuring that the guest configuration (most notably the privilege mode enable bits) do not impact CTR behavior when V=0.
2.4 Supervisor Control Transfer Records Depth Register (sctrdepth)
The 32-bit sctrdepth register specifies the depth of the CTR buffer.
Table 3. Supervisor Control Transfer Records Depth Register Field Definitions
| Field | Description |
|---|---|
| DEPTH | WARL field that selects the depth of the CTR buffer. Encodings: ‘000 - 16 ‘001 - 32 ‘010 - 64 ‘011 - 128 ‘100 - 256 '11x - reserved The depth of the CTR buffer dictates the number of entries to which the hardware records transfers. For a depth of N, the hardware records transfers to entries 0..N-1. All Entry Registers read as '0' and are read-only when the selected entry is in the range N to 255. When the depth is increased, the newly accessible entries contain unspecified but legal values. It is implementation-specific which DEPTH value(s) are supported. |
Attempts to access sctrdepth from VS-mode or VU-mode raise a virtual-instruction exception, unless CTR state enable access restrictions apply. See Section 5.
It is expected that operating systems (OSs) will access sctrdepth only at boot, to select the maximum supported depth value. More frequent accesses may result in reduced performance in virtualization scenarios, as a result of traps from VS-mode incurred.
There may be scenarios where software chooses to operate on only a subset of the entries, to reduce overhead. In such cases tools may choose to read only the lower entries, and OSs may choose to save/restore only on the lower entries while using SCTRCLR to clear the others.
The value in configurable depth lies in supporting VM migration. It is expected that a platform spec may specify that one or more CTR depth values must be supported. A hypervisor may wish to restrict guests to using one of these required depths, in order to ensure that such guests can be migrated to any system that complies with the platform spec. The trapping behavior specified for VS-mode accesses to sctrdepth ensures that the hypervisor can impose such restrictions.
2.5 Supervisor Control Transfer Records Status Register (sctrstatus)
The 32-bit sctrstatus register grants access to CTR status information and is updated by the hardware whenever CTR is active. CTR is active when the current privilege mode is enabled for recording and CTR is not frozen.
Table 4. Supervisor Control Transfer Records Status Register Field Definitions
| Field | Description |
|---|---|
| WRPTR | WARL field that indicates the physical CTR buffer entry to be written next. It is incremented after new transfers are recorded (see Section 6), though there are exceptions when _x_ctrctl.RASEMU=1, see Section 6.4. For a given CTR depth (where depth = 2(DEPTH+4)), WRPTR wraps to 0 on an increment when the value matches depth-1, and to depth-1 on a decrement when the value is 0. Bits above those needed to represent depth-1 (e.g., bits 7:4 for a depth of 16) are read-only 0. On depth changes, WRPTR holds an unspecified but legal value. |
| FROZEN | Inhibit transfer recording. See Section 6.5. |
Undefined bits in sctrstatus are WPRI. Status fields may be added by future extensions,
and software should ignore but preserve any fields that it does not recognize. Undefined bits must be implemented as read-only 0, unless a custom extension is implemented and enabled (see Section 7).
Logical entry 0, accessed via sireg* when siselect=0x200, is always the physical buffer entry preceding the WRPTR entry. More generally, the physical buffer entry Y associated with logical entry X (X < depth) can be determined using the formula Y = (WRPTR - X - 1) % depth, where depth = 2(DEPTH+4). Logical entries >= depth are read-only 0.
Because the sctrstatus register is updated by hardware, writes should be performed with caution. If a multi-instruction read-modify-write to sctrstatus is performed while CTR is active, and between the read and write a qualified transfer or trap that causes CTR freeze completes, a hardware update could be lost. Software may wish to ensure that CTR is inactive before performing a read-modify-write, by ensuring that either sctrstatus.FROZEN=1, or that the current privilege mode is not enabled for recording.
When restoring CTR state, sctrstatus should be written before CTR entry state is restored. This ensures that the software writes to logical CTR entries modify the proper physical entries.
Exposing the WRPTR provides a more efficient means for synthesizing CTR entries. If a qualified control transfer is emulated, the emulator can simply increment the WRPTR, then write the synthesized record to logical entry 0. If a qualified function return is emulated while RASEMU=1, the emulator can clear ctrsource.V for logical entry 0, then decrement the WRPTR.
Exposing the WRPTR may also allow support for Linux perf’s stack stitching capability.
2.6 CSR Listing
Table 5. CTR CSR List
| CSR Number | Name | Description |
|---|---|---|
| 0x14E | sctrctl | Supervisor Control Transfer Records Control Register |
| 0x14F | sctrstatus | Supervisor Control Transfer Records Status Register |
| 0x15F | sctrdepth | Supervisor Control Transfer Records Depth Register |
| 0x24E | vsctrctl | Virtual Supervisor Control Transfer Records Control Register |
| 0x34E | mctrctl | Machine Control Transfer Records Control Register |
Because the ROI of CTR is perceived to be low for RV32 implementations, CTR does not fully support RV32. While control flow transfers in RV32 can be recorded, RV32 cannot access x_ctrctl_ bits 63:32. A future extension could add support for RV32 by adding 3 new CSRs (mctrctlh, sctrctlh, and vsctrctlh) to provide this access.
Smctr/Ssctr depends upon implementation of S-mode because much of CTR state is accessible only through S-mode CSRs. If, in the future, it becomes desirable to remove this dependency, an extension could add mctrdepth and mctrstatus CSRs that reflect the same state as sctrdepth and sctrstatus, respectively. Further, such an extension should make CTR entries accessible via miselect/mireg*. See Section 3.