This document is in the Stable state

Assume anything could still change, but limited change should be expected.

Copyright and license information

This specification is licensed under the Creative Commons Attribution 4.0 International License (CC-BY 4.0). The full license text is available at creativecommons.org/licenses/by/4.0/.

Copyright 2024 by RISC-V International.

Contributors

This RISC-V specification has been contributed to directly or indirectly by:

1. Introduction

This chapter is only included in the standalone CHERI spec and not part of the integrated document.

1.1. CHERI Concepts and Terminology

Current CPU architectures (including RISC-V) allow memory access solely by specifying and dereferencing a memory address stored as an integer value in a register or in memory. Any accidental or malicious action that modifies such an integer value can result in unrestricted access to the memory that it addresses. Unfortunately, this weak memory protection model has resulted in the majority of software security vulnerabilities present in software today.

CHERI enables software to efficiently implement fine-grained memory protection and scalable software compartmentalization by providing strong, efficient hardware mechanisms to support software execution and enable it to prevent and mitigate vulnerabilities.

Design goals include incremental adoptability from current ISAs and software stacks, low performance overhead for memory protection, significant performance improvements for software compartmentalization, formal grounding, and programmer-friendly underpinnings. It has been designed to provide strong, non-probabilistic protection rather than depending on short random numbers or truncated cryptographic hashes that can be leaked and reinjected, or that could be brute forced.

1.2. CHERI Extensions to RISC-V

This specification is based on publicly available documentation including CHERI v9 (Watson et al., 2023) and CHERI Concentrate (Woodruff et al., 2019). It defines the following extensions to support CHERI alongside RISC-V

1.2.1. Extensions to the unprivileged specification

RVY

Unprivileged specification for RVY to support CHERI.

Zys

Unprivileged extension for sentry support, for CFI.

Zyhybrid

Unprivileged extension to support switching CHERI Execution Mode.

The following extension is useful independently of CHERI:

Zabhlrsc

Addition of LR.B, LR.H, SC.B, SC.H for more accurate atomic locking as the memory ranges are restricted by using bounds, therefore precise locking is needed.

1.2.2. Privileged specifications

The following privileged specifications are updated for RVY:

Machine-Level ISA (RVY)

Machine-Level Privileged specification to support CHERI (implies, and required by, Machine-Level ISA).

Supervisor-Level ISA (RVY)

Supervisor-Level Privileged specification to support CHERI (implies, and required by, Supervisor-Level ISA).

Supervisor-Level ISA for Virtual Memory (RV64Y)

Privileged specification for integrating CHERI with virtual memory (implies, and required by, by Sv39).

"H" Extension for Hypervisor Support (RVY)

Privileged specification to integrate CHERI with the Hypervisor extensions (implies, and required by, H).

The following privileged extensions are added for RVY:

Svucrg1

CHERI extension for capability revocation on RISC-V harts supporting page-based virtual-memory (implies Supervisor-Level ISA for Virtual Memory (RV64Y)).

1 Svucrglct is available for improved software revocation performance if Svucrg is implemented.

1.2.3. Debug specifications (need to move to a separate document)

Sdext (RVY)

Debug specification for integrating CHERI with external debug mode (implies, and required by, Sdext).

Sdtrig (RVY)

Debug specification for integrating CHERI with debug triggers (implies, and required by, Sdtrig).

The extension names are provisional and subject to change.

1.2.4. Extension and specification status

Table 1. Unprivileged RVY extension and specification status and summary
Extension Status Comment

RVY

Stable

This extension is a candidate for freezing

Zys

Stable

This extension is a candidate for freezing

Zyhybrid

Stable

This extension is a candidate for freezing
Table 2. Other unprivileged extension status and summary (used by CHERI software), status and summary
Extension Status Comment

Zabhlrsc

Stable

This extension is a candidate for freezing
Table 3. Privileged extension and specification status and summary
Extension Status Comment

Machine-Level ISA (RVY)

Stable

This specification is a candidate for freezing

Supervisor-Level ISA (RVY)

Stable

This specification is a candidate for freezing

Zyhybrid for Privileged Architectures

Stable

This extension is a candidate for freezing

Supervisor-Level ISA for Virtual Memory (RV64Y)

Stable

This specification is a candidate for freezing

Sdext (RVY)

Stable

This specification is a candidate for freezing

Sdtrig (RVY)

Stable

This specification is a candidate for freezing

"H" Extension for Hypervisor Support (RVY)

Stabilizing

This specification is a candidate for freeze, software evaluation currently ongoing

Svucrg1

Stabilizing

This extension is a candidate for freeze, software evaluation currently ongoing

RVY is defined as the base ISA that all CHERI RISC-V implementations must support. Zyhybrid and Svucrg are examples of optional extensions in addition to RVY.

We refer to software as purecap if it utilizes CHERI capabilities for all memory accesses — including loads, stores and instruction fetches — rather than integer addresses. Purecap software requires the CHERI RISC-V hart to support RVY. We refer to software as hybrid if it uses integer addresses or CHERI capabilities for memory accesses. Hybrid software requires the CHERI RISC-V hart to support RVY and Zyhybrid.

See Appendix B for compatibility with other RISC-V extensions.

1.3. Risks and Known Uncertainty

  • All extensions could be divided up differently in the future, including after ratification

  • The RISC-V Architecture Review Committee (ARC) are likely to update all encodings

  • The ARC are likely to update all CSR addresses

  • Instruction mnemonics may be renamed

    • Any changes will affect assembly code, but assembler aliases can provide backwards compatibility

1.3.1. Partially Incompatible Extensions

There are RISC-V extensions in development that may duplicate some aspects of CHERI functionality or directly conflict with CHERI and should only be available in (Non-CHERI) Address Mode on a CHERI-enabled hart. These include:

  • RISC-V CFI specification

  • "J" Pointer Masking (see Chapter 10).

Chapters for the unprivileged specification

2. RV32Y and RV64Y Base Capability Instruction Sets, Version 1.0

This chapter will appear in the unpriv spec after the RV32I chapter.

This chapter describes the RV32Y and RV64Y base capability instruction sets, that extend the RV32I and RV64I (or RV32E/RV64E) integer instruction sets with CHERI. If the hart supports RV32E/RV64E instead of RV32I/RV64I, RVY the restrictions from RV32E and RV64E apply and 16 general purpose registers instead of 32 — but all other RVY changes are identical so the remainder of this chapter only refers to extending RV32I/RV64I behavior.

CHERI enhances the base ISA to add hardware memory access control. It has an additional memory access mechanism that protects references to code and data (pointers), rather than the location of code and data (integer addresses). This mechanism is implemented by providing a new primitive, called a capability, that software components can use to implement strongly protected pointers within an address space. Capabilities are unforgeable and delegatable tokens of authority that grant software the ability to perform a specific set of operations. In CHERI, integer-based pointers are replaced by capabilities to provide memory access control.

2.1. CHERI protection model

The CHERI model is motivated by the principle of least privilege, which argues that greater security can be obtained by minimizing the privileges accessible to running software. A second guiding principle is the principle of intentional use, which argues that, where many privileges are available to a piece of software, the privilege to use should be explicitly named rather than implicitly selected. While CHERI does not prevent the expression of vulnerable software designs, it provides strong vulnerability mitigation: attackers have a more limited vocabulary for attacks, and should a vulnerability be successfully exploited, they gain fewer rights, and have reduced access to further attack surfaces.

Protection properties for capabilities include the ISA ensuring that capabilities are always derived via valid manipulations of other capabilities (provenance), that corrupted1 in-memory capabilities cannot be dereferenced (integrity), and that rights associated with capabilities shall only ever be equal or less permissive (monotonicity). Tampering or modifying capabilities in an attempt to elevate their rights will yield an invalid capability. Attempting to dereference via an invalid capability will result in a hardware exception.

1 Not all possible corrupted states are detected, see Section A.2, “Integrity of Capabilities”.

CHERI capabilities may be held in registers or in memories, and are loaded, stored, and dereferenced using CHERI-aware instructions that expect capability operands rather than integer addresses. On system initialization, initial capabilities are made available to software by the execution environment via general purpose registers. All other capabilities will be derived from these initial valid capabilities through valid capability transformations.

Developers can use CHERI to build fine-grained spatial and temporal memory protection into their system software and applications and significantly improve their security.

2.2. Capability Registers and Format

RVY extends all registers that have to be able to hold addresses to 2*XLEN bits (hereafter referred to as YLEN), adding metadata to protect its integrity, limit how it is manipulated, and control its use. In addition to widening to YLEN, each register also gains one-bit capability tag which is defined below.

RVY specify the fields which the capability format supports, and how those fields behave for XLEN=32 and XLEN=64.

The exact encoding format of the capability is described in Default capability encoding.

Future extensions may redefine the capability format providing they follow the rules defined by the RVY base ISA.
Diagram
Figure 1. CHERI Capability structure

2.2.1. Address

The lower XLEN bits of a capability encode the address of where the capability points. This is also referred to as the integer part of the capability. For registers that are extended but currently hold non-capability data, all other fields are typically zero.

Future extensions may add 2*XLEN-bit operations to make use of the wide registers for efficient handling of 2*XLEN-bit non-capability data.

2.2.2. Capability Tag

The capability tag is an additional bit added to addressable memory and all YLEN-bit registers. It is stored separately and may be referred to as out of band or hidden, and is hardware managed. It indicates whether a YLEN-bit register or YLEN-aligned memory location contains a valid capability. If the capability tag is set, the capability is valid and can be dereferenced (contingent on checks such as permissions or bounds).

All registers or memory locations able to hold a capability are YLEN bits wide with an additional hidden capability tag bit. These are referred to as being YLEN-bit in this specification.

The capability tag cannot be directly set to one by software, it is not a conventionally accessible bit of state. If the capability tag is set then it shows that the capability has been derived correctly according to the principles listed above (provenance, integrity, monotonicity). If the rules are followed then the capability tag will propagate through the instructions that modify, load or store the capability.

Therefore, for capability manipulation in registers:

  • Any instruction that wrote the capability to a register had at least one capability tag set in its input operands.

    • This is the provenance check.

  • Any instruction that wrote the capability to a register requested a legal operation that does not increase bounds or permissions, and set the capability tag on the output.

    • This is the monotonicity check.

  • Any instruction that wrote the capability to a register detected corrupted values.

    • This is the integrity check.

Capability load/store require the provenance check:

  • Any store that wrote the capability to memory was correctly authorized

  • Any load that read the capability from memory was correctly authorized

When an operation fails a check, either due to software error or malicious intent, then the operation raises an exception or sets the resulting capability tag to zero.

Using an invalid capability to dereference memory or authorize any operation raises an exception. All capabilities derived from invalid capabilities are themselves invalid, i.e., their capability tags are zero.

When the capability tag is zero, the register or memory location may be used to store non-capability data.

2.2.3. Capability tags in registers

Every YLEN-bit register has a one-bit capability tag, indicating whether the capability in the register is valid to be dereferenced. This capability tag is cleared whenever an invalid capability operation is performed. Examples of such invalid operations include writing only the integer portion (the address field) of the register or attempting to increase bounds or permissions.

2.2.4. Capability tags in memory

Capability tags are tracked through the memory subsystem: every aligned YLEN-bit wide region has a non-addressable one-bit capability tag, which the hardware manages atomically with the data. The capability tag is set to zero if any byte in the YLEN/8 aligned memory region is ever written using an operation other than a store of a capability operand which is permitted to set the capability tag to one (see C-permission), and that the stored capability data has its capability tag set.

All system memory and caches that store capabilities must preserve this abstraction, handling the capability tags atomically with the data.

2.2.5. Capability Bounds

Capabilities encode memory bounds, i.e., the lowest and highest byte in memory that it is permitted to access when dereferenced for data memory access, or for instruction execution.

Checking is on a byte-by-byte basis, so that it is possible for a memory access to be fully in-bounds, partially out-of-bounds or fully out-of-bounds.

It is not permitted to make any partially or fully out-of-bounds memory accesses.

Every capability has two memory address bounds: base representing the lowest accessible byte, and top representing one byte above the highest accessible byte.

  • The base is XLEN bits and is inclusive.

  • The top is (XLEN+1)-bits and is exclusive.

    • The extra bit is required to allow the bounds to include the top byte of memory.

  • The length is (XLEN+1)-bits and is defined to be top - base.

Therefore a memory location A in the range base ≤ A < top is within bounds, and so valid to access.

Inclusive top, with XLEN bits, was considered but rejected in favor of the exclusive top.
Checking every byte of every executed instruction and every byte of every data memory access is fundamental to the memory safety which CHERI provides. In a typical load/store unit, the expansion of the bounds from rs1 and bounds checking is in parallel with the address calculation, the memory translation and/or the PMA/PMP checking.

A compressed format is used to encode the bounds with a scheme similar to floating-point using an exponent and a mantissa. Therefore small exponents can allow byte granularity on the bounds, but larger exponents give coarser granularity.

The RVY bounds encoding format is defined in Section A.1.4.

Future extensions may use alternative bounds encoding formats. Software can query the capability format by reading the uycfg CSR.

Software can query the capability bounds:

  • The base is returned by the YBASER instruction.

  • The length is returned by the YLENR instruction.

    • YLENR saturates the length to XLEN bits

  • The top can be calculated using a saturating addition of the YBASER and YLENR results.

A future extension may add an instruction to directly read the top if needed for performance.

2.2.6. Deriving New Bounds

On system initialization, one or more Root capabilities are available; typically, these have bounds which cover all of memory and the maximum permissions set. All smaller capabilities are derived from these.

The ISA does not allow the bounds (and permissions) of a capability with its capability tag set to be increased (monotonicity).

Bounds can be programmed using the YBNDSW, YBNDSWI and YBNDSRW instructions, which set the current address to be the base bound and the length to be the operand (rs2 or imm) value. The granularity constraints means that not all requested combinations of top and base bounds can be encoded exactly.

  • YBNDSW sets the base to rs1.address, and the length to rs2. Set the capability tag to zero if the bounds cannot be encoded exactly.

  • YBNDSWI sets the base to rs1.address, and the length to the immediate value. Set the capability tag to zero if the bounds cannot be encoded exactly.

  • YBNDSRW sets the base to rs1.address, and the length to rs2. The bounds may be rounded up if they cannot be encoded exactly.

    • If YBNDSRW rounds up the requested bounds, they must still be no larger than the initial bounds.

  • YAMASK can be used to calculate the nearest precisely encodable length and base values for a given size.

The bounds are encoded relative to the address field, sharing some upper bits of the address. The number of shared bits depends on the exponent, see Section A.1.4.

2.2.7. Representability and Updating the Address

Because the CHERI concentrate (Woodruff et al., 2019) encoding scheme for memory bounds shares the upper bits of the address with the bounds, not all out-of-bounds pointers can be represented.

The historic, uncompressed CHERI-MIPS 256-bit capability encoding had separate 64-bit values for the base and top memory bounds, and another for metadata fields. This scheme could represent all out-of-bounds pointers with a very high hardware cost.

The maximum range of address values that the pointer can take without changing the interpretation of bounds is defined by the representable region. Since deriving a new capability with a different address could change the meaning of the bounds, all such derived capabilities (e.g., deriving the next pc capability from the existing pc via control-flow instructions or sequential execution) and instructions that return valid derived capabilities, must check that the new address is within the representable region defined by the source capability. If the interpretation of bounds has changed, then the capability tag of the derived capability is set to zero, so that it is invalid for use.

Software can derive a capability with a new address using instructions such as YADDRW, ADDY and ADDIY.

YADDRW writes back a derived capability with a new address field and, if the capability tag was previously set, sets the capability tag of the derived capability to one if the resulting capability still has the same bounds interpretation.
Existing software sometimes temporarily moves pointers outside of arrays, and then only come back into the valid range on dereference, so the encoding was designed to allow valid capabilities to be out-of-bounds.
RVY implementations that use a different encoding scheme to the Default capability encoding (e.g., for accelerators or specific micro-controllers, see uycfg) may specify an alternative to the representable region check, and may never allow the address to be out of bounds. Therefore, the rest of the specification uses the phrase represented exactly for this check.

The bounds and representable region (or space) for the Default capability encoding are illustrated in Figure 2. E, MW and R in the figure are all introduced in Section A.1.4.2 along with the bounds decoding.

cap bounds map
Figure 2. Memory address bounds encoded within a capability

2.2.8. Capability Type (CT)

This metadata field indicates the type of the capability. The type determines which operations the capability authorizes. The following capability types are defined in RVY:

Table 4. Capability types in RVY
Type Hardware interpretation

0

Unsealed capability

1

Sealed entry (sentry) capability
Future extensions will add more types of sealed capabilities by extending the width of the CT-field. In the base ISA, sentries are the only type of sealed capability and the CT field is only 1-bit.
Unsealed capabilities

When CT=0, the capability authorizes access to a region of memory as defined by the permissions and bounds.

Sealed capabilities

Capabilities with CT≠0 are sealed against modification and cannot be dereferenced to access memory. Instructions that operate on capabilities will produce a result with a cleared capability tag if the source capability is sealed and the operation would alter its address, bounds, or permissions. Extensions that augment capability metadata must describe their interaction(s) with sealed capabilities.

When a sealed capability is used as a function pointer it is known as a sentry capability.

2.2.9. Sentry Capabilities

Sentries describe secure function entry points. They have a CT-field of 1.

They are used as the target of JALR (RVY), which must have a zero offset for the use of a sentry to be valid.

Sentry capabilities can establish a form of control-flow integrity between mutually distrusting code. JALR (RVY) with zero offset automatically unseals a sentry target capability and installs it in the program counter capability.

JALR (RVY) also seals the return register, so the callee can return to the caller but cannot access the memory pointed at by the return register, and cannot return elsewhere.

In addition to using sealed capabilities as sentries for secure entry points, sealed capabilities can also be useful to software as secure software tokens. They can be converted to an unsealed capability by extracting the metadata with YHIR, zeroing the CT field, reapplying it with YHIW and then rebuilding via a superset capability with the YBLD instruction. A future extension may add an unseal instruction for performance.

2.2.10. Architectural Permissions (AP)

This metadata field encodes architecturally defined permissions of the capability. Permissions grant access subject to the capability tag being set, the capability being unsealed, and bounds checks passing. Any operation is also contingent on requirements imposed by other RISC-V architectural features, such as virtual memory, PMP and PMAs, even if the capability grants sufficient permissions. The permissions currently defined in RVY are listed below.

Permissions can be cleared when deriving a new capability value (using YPERMC) but they can never be added.

The encoding of permissions varies with MXLEN and is described in AP-field encoding.
Table 5. AP-field summary
Permission Type Comment

R-permission

Data memory permission

Authorize data memory read access

W-permission

Data memory permission

Authorize data memory write access

X-permission

Instruction memory permission

Authorize instruction memory execute access

C-permission

Data memory permission

Authorize loading/storing of capability tags

LM-permission

Data memory permission

Used to restrict the permissions of loaded capabilities.

ASR-permission

Privileged state permission

Authorize privileged instructions and CSR accesses.
Read Permission (R)

Allow reading data from memory.

Write Permission (W)

Allow writing data to memory.

Execute Permission (X)

Allow instruction execution.

Capability Permission (C)

Allow reading capability tags from memory if R-permission is also granted.

Allow writing capability tags to memory if W-permission is also granted..

If C-permission is missing then the capability tags for capability loads and stores are read and written as zero.

Load Mutable Permission (LM)

Allow preserving the W-permission of capabilities loaded from memory. If a capability grants R-permission and C-permission, but no LM-permission, then a capability loaded via this authorizing capability will have W-permission and LM-permission removed.

The permission stripping behavior only applies to loaded capabilities that have their capability tag set and are not sealed. This ensures that capability loads of non-capability data do not modify the loaded value, and that sealed capabilities are not modified.

Clearing a capability’s LM-permission and W-permission allows sharing a read-only version of a data structure (e.g., a tree or linked list) without making a copy.
Access System Registers Permission (ASR, primarily used to authorize CSR accesses)

Allow read and write access to all privileged CSRs, some unprivileged CSRs and some privileged instructions. In RVY, the only affected CSR is the unprivileged utidc CSR, which requires ASR-permission for writing, but not for reading. ASR permission is used for additional permission checks by some instructions from other extensions such as Zicbom.

ASR-permission permission checks always use the permission in the pc.

This permission is important in privileged execution environments. Removing this permission allows constraining privileged software to a sandbox that cannot be subverted by changing privileged state.
Extensions may add additional non-privileged CSRs that require ASR-permission.
Permission Transitions

Not all capability permissions are orthogonal (that is, some permissions inherently depend on others). As such, using YPERMC to clear some permissions may have the effect of clearing others as well, such that a permission bit being set in the result of YPERMR implies that all bits for permissions upon which it depends will also be set.

For the base set of permissions just defined, the following rules apply. Extensions that define new permission bits (such as Zyhybrid and Zylevels1) may also introduce new dependency constraints. Capability encodings may impose additional constraints. to reduce the number of bits necessary to represent permissions.

Table 6. YPERMC base rules
YPERMC Rule Permission Valid only if

base-1

C-permission

R-permission or W-permission

base-2

LM-permission

C-permission and R-permission

base-3

ASR-permission

X-permission

2.2.11. Software-Defined Permissions (SDP)

The metadata also contains an encoding-dependent number of software-defined permission (SDP) bits. They can be inspected by the kernel or application programs to enforce restrictions on API calls (e.g., permit/deny system calls, memory allocation, etc.). They can be cleared by YPERMC but are not interpreted by the CPU otherwise.

While these bits are not used by the hardware as architectural permissions, modification follows the same rules: SDP bits can only be cleared and never set on valid capabilities.

This property is required to ensure restricted programs cannot forge capabilities that would pass the software-enforced checks.

2.2.12. Special Capabilities

Root Capabilities

Root (sometimes also primordial, initial) capabilities are those provided by the system at reset. In some systems (and capability encodings), there is a single "Infinite" capability value, which grants all permissions and has bounds covering the whole 2MXLEN address space; in such systems, root capabilities are often Infinite. More generally, the set of root capabilities often collectively grant all permissions to all addresses. By way of example, an encoding may prohibit one capability from authorizing both write and execute; a system using such an encoding would typically make available maximally permissive read-write and read-execute capabilities as part of their root set.

How unprivileged software receives its root capabilities is largely an ABI question; the privileged specification will detail requirements of capability registers' reset state (and so on the root capabilities held therein).

Because particular sets of requirements recur throughout the specification, we define some useful short-hand terminology.

Root Executable Capability

An unsealed capability that has bounds covering all addresses and grants at least all of X-permission, R-permission, C-permission, LM-permission, and ASR-permission. Extensions introducing new permissions may require these to be provided by root executable capabilities.

Root Data Capability

An unsealed capability that has bounds covering all addresses and grants at least all of R-permission, W-permission, C-permission, and LM-permission. Extensions introducing new permissions may require these to be provided by root data capabilities.

NULL Capability

A capability with all-zero metadata, a zero capability tag, and an address of zero is referred to as the NULL capability. This capability grants no permissions and any dereference results in raising an exception.

2.3. Extended State

As stated above, all state which can hold addresses are extended from XLEN to YLEN bits.

2.3.1. General Purpose Registers

The XLEN-wide integer registers (e.g., sp, a0) are all extended to YLEN bits.

Diagram
Figure 3. Extended registers in RVY

When referring to the extended registers, the x prefix is replaced with a y: i.e., the extended version of x1 becomes x1. The register can be referred to either way - as x1 accessing all YLEN bits or as x1 accessing only the address field (i.e., the lower XLEN bits). For the ABI register names the y prefix is added, e.g., sp to refer to all YLEN bits, and so the assembler can refer to either sp or sp depending on the instruction operand.

The zero register is extended with zero metadata and a zero capability tag: this is called the NULL capability.

2.3.2. The Program Counter Capability (pc)

The pc is extended to be a capability. Extending the pc allows the range of branches, jumps and linear execution for currently executing code to be restricted. The pc address field is the pc in the base RISC-V ISA so that the hardware automatically updates it as instructions are executed.

The hardware performs the following checks on pc for each instruction executed in addition to the checks already required by the base RISC-V ISA. A failing check raises a CHERI exception.

  • The capability tag must be set

  • The capability must not be sealed

  • The capability must grant execute permission

  • All bytes of the instruction must be in bounds

  • All integrity checks passed.

On system initialization the pc bounds and permissions must be set such that the program can run successfully (e.g., by setting it to a Root Executable capability to ensure all instructions are in bounds).

Future ISA extensions should respect these rules so that the checked bits do not need storing in all copies of the pc in the implementation.
Diagram
Figure 4. Program Counter Capability

2.3.3. Added CSRs

RV32Y and RV64Y add the YLEN-bit CSR shown in Table 7 and the XLEN-bit CSR shown in Table 8.

Table 7. Unprivileged capability CSRs added in RVY
YLEN CSR Permissions Description

utidc

RW, ASR-permission required for writes, not reads

User Thread ID Capability
Table 8. Unprivileged integer CSRs added in RVY
XLEN CSR Permissions Description

uycfg

RO; see section for details

Capability encoding version
User Thread Identifier Capability (utidc)

The utidc register is used to identify the current software thread in user mode. Any operation that modifies utidc raises an exception unless the ASR-permission is set in the current pc.

While the RISC-V ABI includes a thread pointer (tp) register, it is not usable for the purpose of reliably identifying the current software thread because the tp register is a general purpose register and can be changed arbitrarily by untrusted code. Therefore, this specification offers an additional CSR that facilitates a trusted source for identifying software threads.
Diagram
Figure 5. User thread identifier capability register

The following should probably move to a programmers guide

Compartmentalization seeks to separate the privileges between different protection units, e.g., two or more libraries. Code can be separated by sentries, which allow for giving out code capabilities to untrusted code where the untrusted code can only call the code capability, but not modify it. The utidc register supports a model where untrusted code is separated by trusted code and each call from one piece of untrusted code to another piece of untrusted piece of code goes through trusted code. Often, the trusted code is referred to as a trampoline. Sentries can be called from different software threads and thus there needs to be a way of identifying the current software thread. While identifying the current software thread can be done by privileged code, e.g., the kernel, the implied performance overhead of this is not bearable for CHERI systems with many compartments.

The utidc register is designed to hold a capability, which can only be used for memory accesses by trusted code. In a commonly used model on CHERI systems, the trusted code’s responsibility is only to switch between compartments, but not to switch threads. This responsibility is usually taken over by more privileged code, e.g., an operating system kernel running on a different privilege level. The privileged code switches software threads and writes the utidc register.

Every piece of code in the user space (and more privileged levels) can read the contents of the utidc register. However, the memory authorized by the capability in utidc must not be accessible to untrusted code, but only to trusted code. In order to protect this capability, it can be made a sentry (thus being sealed). The trusted code will be given a capability large enough so that it can recover the sentry stored in utidc. For the untrusted code, the sentry stored in utidc is inaccessible. The sentry itself is no secret, but the memory pointed to by the sentry is a secret and must not be accessed by any untrusted code.

Trusted code can use the sentry in utidc to implement secure compartment switches. Often, the sentry is used to implement a trusted stack. Whenever a compartment switch happens, the trusted code can pass arguments between the caller and callee compartment avoid capability leaks between the two compartments. The trusted code can store capabilities on the trusted stack when calling out of a compartment and can install them when returning to the same compartment.
CHERI Capability Encoding (uycfg)

The uycfg register is a read-only XLEN CSR used to identify which CHERI capability encoding is used by the platform. The capability encoding both determines the in-memory representation of a CHERI capability and entails a set of extensions present atop RVY.

Alternative capability encoding specifications, with, for example, new features and/or different bounds granularity, are possible and would not change how CHERI integrates with the RISC-V ISA, provided that said encodings still provide the primitives detailed in Section 2.2.
This CSR is read-only, but future extensions may provide a mechanism to modify the capability encoding currently in use.
Diagram
Figure 6. CHERI capability encoding CSR (uycfg) format

The following values for uycfg are defined:

Base Features Encoding

0x0

-

Reserved (unspecified capability encoding)

0x1

0x0

Default capability encoding capabilities, without Zylevels1 features

0x1

Default capability encoding capabilities, with Zylevels1 features

0x2

0x0

Reserved for CHERIoT’s (RV32-only) encoding

Future extensions that change capability encoding must define new values. Extensions that define encodings derived from Default capability encoding and are generally compatible with this encoding (e.g. they only assign meaning to previously reserved bits) must preserve the Base Encoding field (the bottom 8 bits) as 0x01.

We suggest that only low-level, system software query this value directly. Operating systems and/or runtime environments should provide a mechanism for software to determine if the platform’s capability encoding is backwards-compatible with a given, presumed encoding. Among other things, such a facility should be used as part of the platform executable loader to reject executables that expect unknown or known-incompatible CHERI features or capability encodings.

2.3.4. Extended CSRs

All CSRs that can hold addresses are extended to YLEN bits.

RVY has three classes of CSR

  • XLEN-bit CSRs, which do not contain addresses

    • e.g., fcsr from the "F" extension

  • XLEN-bit CSRs extended to YLEN bits, which are able to contain addresses (referred to as extended CSRs)

    • e.g., jvt from the "Zcmt" extension

  • YLEN-bit CSRs, which are added by RVY and contain addresses

When accessing CSRs these rules are followed:

  1. Accesses to XLEN-bit CSRs are as specified by Zicsr

  2. Accesses to YLEN-bit CSRs and extended CSRs, using CSRRW will:

    1. Read YLEN bits

    2. Write YLEN bits, and will write the capability tag to zero if:

      1. any integrity check fails

  3. Accesses to YLEN-bit CSRs and extended CSRs, using instructions other than CSRRW will:

    1. Read YLEN bits

    2. Write an XLEN-bit value to the address field, and use the semantics of the YADDRW instruction to determine the final written value

Any YLEN-bit or extended CSR may have additional rules defined to determine the final written value of the metadata and/or to write zero to the capability tag.

The assembler pseudoinstruction to read a capability CSR csrr rd, csr, is encoded as csrrs rd, csr, x0.

Table 9. YLEN-bit CSR and Extended CSR access summary for RVY
Instruction Read Width Write Width

CSRRW rd==x0

YLEN

CSRRW rd!=x0

YLEN

YLEN

CSRR[C|S] rs1==x0

YLEN

CSRR[C|S] rs1!=x0

YLEN

XLEN

CSRRWI rd==x0

XLEN

CSRRWI rd!=x0

YLEN

XLEN

CSRR[C|S]I uimm==x0

YLEN

CSRR[C|S]I uimm!=x0

YLEN

XLEN

In Table 9, when there is no read or write width shown, the CSR access is not made and there are no side-effects following standard Zicsr rules.

2.4. Capability checks

With RVY, every memory access performed by a CHERI core must be authorized by a capability.

Instruction fetches, branches, jumps, and data memory accesses may result in a fatal exception if the access is out of bounds, or if the authorizing capability is missing the required permissions. I.e.,:

See CHERI Exception handling in the privileged specification for further details on the exception reporting mechanism.

Instruction fetch is also authorized by a capability: the program counter capability (pc) which extends the PC. This allows code fetch to be bounded, preventing a wide range of attacks that subvert control flow with non-capability data.

The authorizing capability is either named explicitly (the base register of a load/store operation) or implicitly (when executing a branch, pc is used for authorization).

E.g., lw t0, 16(sp) loads a word from memory, getting the address, bounds, and permissions from the sp (capability stack pointer) register.

No other exception paths are added by RVY: in particular, capability manipulations do not raise an exception, but may set capability tag of the resulting capability to zero if the operation is not permitted.

2.5. Added Instructions

RVY adds new instructions to operate on capabilities.

2.6. Instructions to Update The Capability Pointer

Creating a new capability with a different address (i.e., updating the pointer) requires specific instructions instead of integer ADD/ADDI. These instructions all include a check that the resulting address can be represented exactly within the new capability.

Table 10. Instructions which update the address field summary in RVY
Mnemonic Description

ADDIY

Increment capability address by immediate, represented exactly check

ADDY

Increment capability address by register, represented exactly check

YADDRW

Replace capability address, represented exactly check

2.6.1. ADDIY

See ADDY.

2.6.2. ADDY

Synopsis

Capability pointer increment

Mnemonic

addy rd, rs1, rs2
addiy rd, rs1, imm

Suggested assembly syntax

add rd, rs1, rs2
addi rd, rs1, imm

The suggested assembly syntax distinguishes from integer add/addi by operand type.
Encoding
Diagram
Diagram
ADDY with rs2=x0 is decoded as YMV instead, the key difference being that capabilities cannot have their capability tag cleared by YMV.
Description

Copy the capability in register rs1 to register rd.

For ADDY, increment rd.address by the value in rs2[XLEN-1:0] .
For ADDIY, increment rd.address by the immediate value imm.

Set rd.tag=0 if rs1 is sealed.

Set rd.tag=0 if the resulting capability cannot be represented exactly.

Set rd.tag=0 if rs1 fails any integrity checks.

Included in

RVY

Operation for ADDY
  let cs1_val = C(cs1);
  let rs2_val = X(rs2);

  let newCap = incCapAddrChecked(cs1_val, rs2_val);

  C(cd) = newCap;
  RETIRE_SUCCESS
Operation for ADDIY
  let cs1_val = C(cs1);
  let immBits : xlenbits = sign_extend(imm);

  let newCap = incCapAddrChecked(cs1_val, immBits);

  C(cd) = newCap;
  RETIRE_SUCCESS

2.6.3. YADDRW

Synopsis

Write capability address

Mnemonic

yaddrw rd, rs1, rs2

Encoding
Diagram
Description

Copy the capability rs1 to rd.

Set rd.address to rs2[XLEN-1:0].

Set rd.tag=0 if rs1 is sealed.

Set rd.tag=0 if the resulting capability cannot be represented exactly.

Set rd.tag=0 if rs1 fails any integrity checks.

Included in

RVY

Operation
C(cd) = setCapAddrChecked(C(cs1), X(rs2));
RETIRE_SUCCESS

2.7. Instructions to Manipulate Capabilities

For security, capabilities can only be modified in restricted ways. Special instructions are provided to copy capabilities or derive a new capability using manipulations such as shrinking the bounds (YBNDSW), reducing the permissions (YPERMC) or authorizing a capability with another one which has a superset (or identical) bounds and permissions (YBLD).

Table 11. Summary of RVY instructions that create a modified capability
Mnemonic Description

YPERMC

AND capability permissions (expand to 1-bit per permission before ANDing)

YMV

Move capability register

YHIW1

Set metadata and clear capability tag

YBNDSWI

Set immediate bounds on capability with rounding, clear capability tag if rounding is required

YBNDSW

Set register bounds on capability with rounding, clear capability tag if rounding is required

YBNDSRW

Set bounds on capability with rounding up as required

YBLD

Set rd to rs2 with its capability tag set after checking that rs2 is a subset of rs1

1 YHIW is a pseudoinstruction for PACKY

2.7.1. YPERMC

Synopsis

Clear capability permissions

Mnemonics

ypermc rd, rs1, rs2

Encoding
Diagram
Description

YPERMC performs the following operations:

  1. Convert the AP-field, SDP-field, and any other extension-defined permission-like fields of capability rs1 into a bit field with the format shown in Figure 7.

  2. The initial value in register rs2[XLEN-1:0] is treated as a bit mask that specifies bit positions to be cleared in the bit field. Any bit that is high in rs2 will cause the corresponding bit to be cleared in the bit field.

    Future extensions may include hardwired permission bits, in which case they are not cleared by set bits in rs2.

  3. Encode the resulting architectural permissions as specified by the encoding in use. This may involve iterating over the rules in Section 2.2.10.1, as well as any rules added by extensions or the capability encoding, to a fixed point (that is, a set of permissions not further reduced by any rule); encodings may, however, specify other encoding procedures.

    Depending on the base ISA and supported extensions, some combinations of permissions cannot be encoded or are not useful. In these cases, YPERMC will return a minimal sets of permissions, which may be no permissions. Therefore, it is possible that requesting to clear a permission also clears others, but YPERMC will never add new permissions.

  4. Copy rs1 to rd, and update the AP-field, SDP-field, and any others therein with the newly calculated versions.

  5. Set rd.tag=0 if rs1 is sealed and any bits in the AP-field or SDP-field were affected by YPERMC; extensions must describe whether such changes to their bits also necessitate capability tag clearing.

  6. Set rd.tag=0 if any integrity checks fail.

Diagram
Figure 7. Capability permissions bit field
If a future extension adds a new permission that overlaps with an existing permission (e.g., finer-grained ASR-permission), then clearing the original must also clear the new permission. This ensures software forward-compatibility: for example, a kernel that does not know about finer-grained ASR-permission subsets must still be able to prevent all access to privileged instructions and CSRs by clearing ASR-permission.
Any future extension that defines new permissions that are a refinement of existing permissions (e.g., finer-grained ASR-permission or those of Zylevels1) must be allocated to the bits that are currently reported as 1 to ensure forward-compatibility. Completely new permissions (e.g., sealing) should use the bits that are reported as zero in the current specification.

Extensions like Zylevels1 introduce bits that are, conceptually, labels on a capability rather than a permission granted by the capability. These bits are, nevertheless, still adjusted using the YPERMC instruction. This avoids the need for a dedicated instruction and allows simultaneous changes of these labels and permissions.
Included in

RVY

Operation
  let cs1_val = C(cs1);
  let rs2_val = X(rs2);

  let cond = capIsSealed(cs1_val) | not(capReservedValid(cs1_val));
  let inCap = clearTagIf(cs1_val, cond);

  let old_perms = packPerms(getArchPermsLegalized(inCap), inCap.sd_perms).bits;

  let new_perms = old_perms & rs2_val;

  let (new_arch_perms, new_sd_perms) = unpackPerms(struct {bits = new_perms});
  let newCap = { setArchPerms(inCap, new_arch_perms) with sd_perms = new_sd_perms };

  C(cd) = newCap;
  RETIRE_SUCCESS

2.7.2. YMV

Synopsis

Capability register copy

Mnemonic

ymv rd, rs1

Suggested assembly syntax

ymv rd, rs1

Encoding
Diagram
YMV is encoded as ADDY with rs2=x0.
Description

The contents of capability register rs1 are written to capability register rd. YMV unconditionally does a bit-wise copy from rs1 to rd .

This instruction can propagate valid capabilities which fail integrity checks.

Included in

RVY

Operation
C(cd) = C(cs1);
RETIRE_SUCCESS

2.7.3. PACKY

Synopsis

Pack Y register

Mnemonic

packy rd, rs1, rs2

Encoding
Diagram
Description

The PACKY instruction packs the least-significant XLEN-bits of rs1 and rs2 into rd, and sets rd.tag=0.

Included in

RVY

2.7.4. YHIW

Synopsis

Capability set metadata

Mnemonic

yhiw rd, rs1, rs2

Encoding

YHIW is a pseudoinstruction for PACKY

Description

Copy rs1 to rd.

Replace the capability metadata of rs1 (i.e., bits [YLEN-1:XLEN]) with rs2 and set rd.tag to 0.

The value of rs1.tag does not affect the result.
Included in

RVY

Operation
let capVal = C(cs1);
let intVal = X(rs2);
let newCap = bitsToCap(false, intVal @ capVal.address);
C(cd) = newCap;
RETIRE_SUCCESS

2.7.5. YBNDSWI

See YBNDSW.

2.7.6. YBNDSW

Synopsis

Write capability bounds

Mnemonics

ybndsw rd, rs1, rs2
ybndswi rd, rs1, uimm

Encoding
Diagram
Diagram
Description

Copy the capability from register rs1 to register rd. Set the base address of its bounds to the value of `rs1.address and set the length of its bounds to rs2[XLEN-1:0] for YBNDSW, or imm for YBNDSWI.

Set rd.tag=0 if rs1.tag=0, rs1 is sealed or if rd 's bounds exceed rs1 's bounds.

Set rd.tag=0 if the requested bounds cannot be encoded exactly.

Set rd.tag=0 if rs1 fails any integrity checks.

YBNDSWI uses the s bit to scale the immediate by 4 places

immediate = ZeroExtend(s ? uimm<<4 : uimm)

The YBNDSWI encoding with s=1 and uimm ≤ 1 is RESERVED since these immediates can also be encoded with s=0.
Included in

RVY

Operation for YBNDSW
let cs1_val = C(cs1);
let length = X(rs2);
let newBase = cs1_val.address;
let newTop : CapLenBits = zero_extend(newBase) + zero_extend(length);
// inCapBoundsNoWrap returns false if the input bounds are malformed.
let inBounds = inCapBoundsNoWrap(cs1_val, newBase, unsigned(length));
let (exact, newCap) : (bool, Capability) = setCapBounds(cs1_val, newBase, newTop);
let cond = not(inBounds & exact) |
           boundsMalformed(newCap) |
           not(capReservedValid(newCap)) |
           capIsSealed(newCap);
C(cd) = clearTagIf(newCap, cond);
RETIRE_SUCCESS
Operation for YBNDSWI
let cs1_val = C(cs1);
let length = if s == 0b1 then uimm5 @ 0b0000 else 0b0000 @ uimm5;
let newBase = cs1_val.address;
let newTop : CapLenBits = zero_extend(newBase) + zero_extend(length);
// inCapBoundsNoWrap returns false if the input bounds are malformed.
let inBounds = inCapBoundsNoWrap(cs1_val, newBase, unsigned(length));
let (exact, newCap) : (bool, Capability) = setCapBounds(cs1_val, newBase, newTop);
assert(exact, "SCBNDSI immediate too small for non-exact lengths");
let cond = not(inBounds) |
           boundsMalformed(newCap) |
           not(capReservedValid(newCap)) |
           capIsSealed(newCap);
C(cd) = clearTagIf(newCap, cond);
RETIRE_SUCCESS

2.7.7. YBNDSRW

Synopsis

Write capability bounds, rounding up if required

Mnemonic

ybndsrw rd, rs1, rs2

Encoding
Diagram
Description

Copy the capability from register rs1 to register rd. Set the base address of its bounds to the value of `rs1.address and set the length of its bounds to rs2[XLEN-1:0].

The base is rounded down and the top is rounded up by the smallest amounts needed to form a capability covering the requested base and top.

Set rd.tag=0 if rs1.tag=0, rs1 is sealed or if rd 's bounds exceed rs1 's bounds.

Set rd.tag=0 if the requested bounds cannot be encoded exactly.

Set rd.tag=0 if rs1 fails any integrity checks.

Included in

RVY

Operation
let cs1_val = C(cs1);
let length = X(rs2);
let newBase = cs1_val.address;
let newTop : CapLenBits = zero_extend(newBase) + zero_extend(length);
// inCapBoundsNoWrap returns false if the input bounds are malformed.
let inBounds = inCapBoundsNoWrap(cs1_val, newBase, unsigned(length));
let (_, newCap) : (bool, Capability) = setCapBounds(cs1_val, newBase, newTop);
let cond = not(inBounds) |
           boundsMalformed(newCap) |
           not(capReservedValid(newCap)) |
           capIsSealed(newCap);
C(cd) = clearTagIf(newCap, cond);
RETIRE_SUCCESS

2.7.8. YBLD

Synopsis

Build capability

Mnemonic

ybld rd, rs1, rs2

Encoding
Diagram
Description

Copy rs2 to rd.

Set rd.tag=1 if:

  1. rs1.tag is set, and

  2. rs1 passes all integrity checks, and

  3. rs1 is not sealed, and

  4. rs2 's permissions and bounds are equal to or a subset of rs1 's, and

  5. rs2 passes all integrity checks, and

  6. any extension-specific constraints on YBLD hold.

    Otherwise, set rd.tag=0

YBLD is typically used alongside YHIW to build capabilities from integer values.
When rs1 is x0 YBLD will copy rs2 to rd and clear rd.tag. However future extensions may add additional behavior to update currently reserved fields, and so software should not assume rs1==0 to be a pseudo-instruction for capability tag clearing.
Included in

RVY

Operation
  let cs1_val = C(cs1);
  let cs2_val = C(cs2);

  let tag = cs1_val.tag &
            not(capIsSealed(cs1_val)) &
            capIsSubset(cs2_val, cs1_val); /* Subset checks for malformed bounds,
                                              perms, and reserved bits */

  C(cd) = { cs2_val with tag = tag };
  RETIRE_SUCCESS

2.8. Instructions to Decode Capability Bounds

The bounds describing the range of addresses the capability gives access to are stored in a compressed format. These instructions query the bounds and related information.

Table 12. Instructions which decode capability bounds summary in RVY
Mnemonic Description

YBASER

Get capability base

YLENR

Get capability length

2.8.1. YBASER

Synopsis

Read capability base address

Mnemonic

ybaser rd, rs1

Encoding
Diagram
Description

Decode the base integer address from rs1 's bounds and write the result to rd.

If rs1 's bounds can’t be decoded, or rs1 fails any integrity checks, then return zero.

The value of rs1.tag does not affect the result.
Included in

RVY

Operation
let capVal = C(cs1);
X(rd) = match getCapBoundsBits(capVal) {
  None() => zeros(),
  Some(base, _) => base
};
RETIRE_SUCCESS

2.8.2. YLENR

Synopsis

Read capability length

Mnemonic

ylenr rd, rs1

Encoding
Diagram
Description

Calculate the length of rs1 's bounds and write the result in rd.

The length is defined as the difference between the decoded bounds' top and base addresses, i.e., top - base.

Return the maximum length, 2MXLEN-1, if the length of rs1 is 2MXLEN.

If rs1 's bounds can’t be decoded, or rs1 fails any integrity checks, then return zero.

The value of rs1.tag does not affect the result.
Included in

RVY

Operation
let capVal = C(cs1);
// getCapLength returns 0 if the bounds are malformed
let len = getCapLength(capVal);
X(rd) = to_bits(xlen, if len > cap_max_addr then cap_max_addr else len);
RETIRE_SUCCESS

2.9. Instructions to Extract Capability Fields

These instructions either directly read bit fields from the metadata or capability tag, or only apply simple transformations on the metadata.

Table 13. Instructions which extract capability fields summary in RVY
Mnemonic Description

YTAGR

Get capability tag

YPERMR

Get capability architectural and software permissions

YTYPER

Get capability type

YHIR1

Get capability metadata

1 YHIR is a pseudoinstruction for SRLIY

2.9.1. YTAGR

Synopsis

Read capability tag

Mnemonic

ytagr rd, rs1

Encoding
Diagram
Description

Zero extend the value of rs1.tag and write the result to rd.

Included in

RVY

Operation
let capVal = C(cs1);
X(rd) = zero_extend(bool_to_bits(capVal.tag));
RETIRE_SUCCESS

2.9.2. YPERMR

Synopsis

Read capability permissions

Mnemonic

ypermr rd, rs1

Encoding
Diagram
Description

Convert the unpacked AP-field, SDP-field, and any other extension-defined permission-like fields of capability rs1 into a bit field, with the same format as used by YPERMC (see Figure 7), and write the result to rd.

All bits in the [23:0] range that are reserved or assigned to extensions that are not implemented by the current hart always report 1.

All architectural permission bits in rd are set to 0 if any integrity checks failed.

Diagram
Figure 8. Capability permissions bit field
The value of rs1.tag does not affect the result.
Included in

RVY

Operation
let capVal = C(cs1);
X(rd) = packPerms(getArchPermsLegalized(capVal), capVal.sd_perms).bits;
RETIRE_SUCCESS

2.9.3. YTYPER

Synopsis

Read capability type

Mnemonic

ytyper rd, rs1

Encoding
Diagram
Description

Decode the architectural capability type (CT-field) from rs1 and write the result to rd.

The value of rs1.tag does not affect the result.
Included in

RVY

Operation
let capVal = C(cs1);
X(rd) = zero_extend(bool_to_bits(capVal.sealed));
RETIRE_SUCCESS

2.9.4. SRLIY

Synopsis

Logical right shift of Y register

Mnemonic

srliy rd, rs1, shamt

Encoding
Diagram
Description

Logical right shift of Y register rs1 to rd, zero-filling the upper bits of the result.

Currently the only valid shift distance is XLEN places, a future extension may add an arbitrary shift distance.
For RV32Y, srliy rd, rs1, 32 has an identical encoding and operation to the RV64 instruction srli rd, rs1, 32.
Included in

RVY

Operation

TODO

2.9.5. YHIR

Synopsis

Read capability metadata (pseudo)

Mnemonic

yhir rd, rs1

Encoding

yhir rd, rs1 is a pseudoinstruction for srliy rd, rs1, XLEN

Description

Copy the metadata (bits [YLEN-1:XLEN]) of capability rs1 into rd.

The value of rs1.tag does not affect the result.
Included in

RVY

Operation
let capVal = C(cs1);
X(rd) = capToMetadataBits(capVal).bits;
RETIRE_SUCCESS

2.10. Miscellaneous Instructions to Handle Capability Data

Table 14. Miscellaneous capability instruction summary in RVY
Mnemonic Description

SYEQ

Full capability bitwise compare, set result true if all bits (including the capability tag) are equal

YLT

Set result true if rs1 and rs1 capability tags match and rs2 bounds and permissions are a subset of rs1

YAMASK

Representable Alignment Mask: Return mask to apply to address to get the requested bounds

2.10.1. SYEQ

Synopsis

Capability equality comparison including capability tag

Mnemonic

syeq rd, rs1, rs2

Encoding
Diagram
Description

Set rd to 1 if all bits (i.e., YLEN bits and the capability tag) of capabilities rs1 and rs2 are equal, otherwise set rd to 0.

Included in

RVY

Operation
let cs1_val = C(cs1);
let cs2_val = C(cs2);
X(rd) = zero_extend(bool_to_bits(cs1_val == cs2_val));
RETIRE_SUCCESS

2.10.2. YLT

Synopsis

Set Capability Subset

Mnemonic

ylt rd, rs1, rs2

Encoding
Diagram
Description

rd is set to 1 if:

  1. the capability tag of capabilities rs1 and rs2 are equal, and

  2. the bounds and permissions of rs2 are a subset of those of rs1, and

  3. neither rs1 nor rs2 fail any integrity checks

  4. any extension-specific constraints capability subset relationships hold.

Otherwise set rd to 0. Extensions may further impose constraints on when rd is set to 1.

The implementation of this instruction is similar to YBLD, although YLT does not include the sealed bit in the check.
Included in

RVY

Operation
  let cs1_val = C(cs1);
  let cs2_val = C(cs2);

  X(rd) = zero_extend(bool_bits(
    (cs1_val.tag == cs2_val.tag) &
    capIsSubset(cs2_val, cs1_val) /* capIsSubset returns false if either input
                                     has malformed bounds, perms, or non-zero
                                     reserved bits */
  ));
  RETIRE_SUCCESS

2.10.3. YAMASK

Synopsis

Capability alignment mask

Mnemonic

yamask rd, rs1

Encoding
Diagram
Description

rd[XLEN-1:0] is set to a mask that can be used to round addresses down to a value that is sufficiently aligned to set exact bounds for the nearest representable length of rs1[XLEN-1:0]. The upper bits of rd are zero extended. See Section A.1.4 for the algorithm used to compute the next representable length.

Included in

RVY

Operation
let len = X(rs1);
X(rd) = getRepresentableAlignmentMask(len);
RETIRE_SUCCESS

2.11. Instructions to Load and Store Capability Data

New loads and stores are introduced to handle capability data, LY and SY. They atomically access YLEN bits of data and the associated capability tag.

All capability memory accesses check for C-permission in the authorizing capability in rs1.

If C-permission is granted then:

  • LY reads YLEN bits of data from memory, and returns the associated capability tag.

  • SY writes YLEN bits of data to memory, and writes the associated capability tag.

If C-permission is not granted then:

  • LY reads YLEN bits from memory, but does not return the associated capability tag, instead zero is returned.

  • SY writes YLEN bits to memory, and writes zero to the associated capability tag.

All capability data memory access instructions require YLEN-aligned addresses, and will take an access fault exception if this requirement is not met. They cannot be emulated.

An access fault is raised instead of a misaligned exception since these instructions cannot be emulated since there is one hidden capability tag per YLEN-aligned memory region.

All memory accesses, of any type, require permission from the authorizing capability in rs1.

  • All loads require R-permission, otherwise they raise an exception

  • All stores require W-permission, otherwise they raise an exception

Under some circumstances LY will modify the data loaded from memory before writing it back to the destination register. See LY for details.

Table 15. Capability load/store instruction summary in RVY
Mnemonic Description

LY

Load capability

SY

Store capability

2.11.1. LY

Synopsis

Load capability

Mnemonic

ly rd, offset(rs1)

Encoding
Diagram
Any instance of this instruction with a rs1=x0 will raise an exception, as x0 is defined to always hold a NULL capability. As such, the encodings with a rs1=x0 are RESERVED for use by future extensions.
Description

Calculate the effective address of the memory access by adding rs1.address to the sign-extended 12-bit offset.

Authorize the memory access with the capability in rs1.

Load a naturally aligned YLEN-bit data value from memory.

If the PMA is CHERI Capability Tag then load the associated capability tag, otherwise set the capability tag to zero.

Use the YLEN-bit data and the capability tag to determine the value of rd as specified below.

This instruction can propagate valid capabilities which fail integrity checks.

Determining the final value of rd

If the capability tag is zero, or the authorizing capability (rs1) does not grant C-permission then set rd.tag=0. In this case the steps below do not apply.

If rd.tag=1, rd is not sealed and rs1 does not grant LM-permission, then an implicit YPERMC is performed to clear W-permission and LM-permission from rd.

Extensions may define further circumstances under which implict YPERMC-s or other mutation of loaded capabilities may take place.

While the implicit YPERMC introduces a dependency on the loaded data, implementations can avoid this by deferring the actual masking of permissions until the loaded capability is dereferenced or the metadata bits are inspected using YPERMR or YHIR. Additionally, metadata modifications are on naturally aligned data, and so on the read path from a data cache, the modification typically happens in parallel with data alignment multiplexers.

When sending load data to a trace interface, implementations trace the final value written to rd which may not match the value in memory.

Exceptions

Load access fault exception when the effective address is not aligned to YLEN/8.

CHERI fault exception when one of the checks below fail (see CHERI Exception handling in the privileged specification for further details):

Kind Reason

CHERI Load Access Fault

Authorizing capability tag is set to 0.

CHERI Load Access Fault

Authorizing capability is sealed.

CHERI Load Access Fault

Authorizing capability does not grant the necessary permissions.

CHERI Load Access Fault

At least one byte accessed is outside the authorizing capability bounds, or the bounds could not be decoded.

CHERI Load Access Fault

Authorizing capability failed any integrity check.
Included in

RVY

Operation
  let offset : xlenbits = sign_extend(imm);
  let (auth_val, vaddr) = get_cheri_mode_cap_addr(rs1_cs1, offset);
  let aq : bool = false;
  let rl : bool = false;

  match check_and_handle_load_vaddr_for_triggers(vaddr, get_arch_pc()) {
    Some (ret) => return ret,
    None () => ()
  };
  if not(capTaggedAndReservedValid(auth_val)) then {
    handle_cheri_exception(CapCheckType_Data, CapEx_TagViolation);
    RETIRE_FAIL
  } else if capIsSealed(auth_val) then {
    handle_cheri_exception(CapCheckType_Data, CapEx_SealViolation);
    RETIRE_FAIL
  } else if not(canR(auth_val)) then {
    handle_cheri_exception(CapCheckType_Data, CapEx_PermissionViolation);
    RETIRE_FAIL
  } else if not(validAddrRange(vaddr, cap_size) | capBoundsInfinite(auth_val)) then {
    handle_cheri_exception(CapCheckType_Data, CapEx_InvalidAddressViolation);
    RETIRE_FAIL
  } else if not(inCapBounds(auth_val, vaddr, cap_size)) then {
    handle_cheri_exception(CapCheckType_Data, CapEx_LengthViolation);
    RETIRE_FAIL
  } else if not(is_aligned_addr(vaddr, cap_size)) then {
    handle_mem_exception(vaddr, E_Load_Addr_Align());
    RETIRE_FAIL
  } else match translateAddr(vaddr, Read(Cap)) {
    TR_Failure(E_Extension(_)) => { internal_error(__FILE__, __LINE__, "unexpected cheri exception for cap load") },
    TR_Failure(e) => { handle_mem_exception(vaddr, e); RETIRE_FAIL },
    TR_Address(addr, pbmt, ptw_info) => {
      let c = mem_read_cap(addr, pbmt, aq, aq & rl, false);
      match c {
        MemValue(v) => {
          let cr = clearTagIf(v, ptw_info.ptw_lc == PTW_LC_CLEAR | not(canC(auth_val)));
          C(cd) = legalizeLM(cr, auth_val);
          RETIRE_SUCCESS
        },
        MemException(e) => {handle_mem_exception(vaddr, e); RETIRE_FAIL }
      }
    }
  }

2.11.2. SY

Synopsis

Store capability

Mnemonic

sy rs2, offset(rs1)

Encoding
Diagram
Any instance of this instruction with a rs1=x0 will raise an exception, as x0 is defined to always hold a NULL capability. As such, the encodings with a rs1=x0 are RESERVED for use by future extensions.
Description

Calculate the effective address of the memory access by adding rs1.address to the sign-extended 12-bit offset.

Authorize the memory access with the capability in rs1.

Store a naturally aligned YLEN-bit data value in rs2 to memory and the associated capability tag in rs2.

This instruction can propagate valid capabilities which fail integrity checks.

Stored Capability Tag Value

The stored capability tag is set to zero if:

  1. rs2.tag=0, or

  2. rs1 does not grant C-permission, or

  3. The PMA is CHERI Capability Tag Strip

    Extensions may define further circumstances under which stored capabilities may have their capability tags cleared.

Exceptions

Store/AMO access fault exception when the effective address is not aligned to YLEN/8.

Store/AMO access fault if the stored capability tag is set to one and the PMA is CHERI Capability Tag Fault.

Kind Reason

CHERI Store/AMO Access Fault

Authorizing capability tag is set to 0.

CHERI Store/AMO Access Fault

Authorizing capability is sealed.

CHERI Store/AMO Access Fault

Authorizing capability does not grant the necessary permissions.

CHERI Store/AMO Access Fault

At least one byte accessed is outside the authorizing capability bounds, or the bounds could not be decoded.

CHERI Store/AMO Access Fault

Authorizing capability failed any integrity check.
Included in

RVY

Operation
  let offset : xlenbits = sign_extend(imm);
  let (auth_val, vaddr) = get_cheri_mode_cap_addr(rs1_cs1, offset);
  let cs2_val = C(cs2);
  let aq : bool = false;
  let rl : bool = false;
  let cs2_val = clearTagIf(cs2_val, not(canC(auth_val)));

  match check_and_handle_store_vaddr_for_triggers(vaddr, get_arch_pc()) {
    Some (ret) => return ret,
    None () => ()
  };
  if not(capTaggedAndReservedValid(auth_val)) then {
    handle_cheri_exception(CapCheckType_Data, CapEx_TagViolation);
    RETIRE_FAIL
  } else if capIsSealed(auth_val) then {
    handle_cheri_exception(CapCheckType_Data, CapEx_SealViolation);
    RETIRE_FAIL
  } else if not(canW(auth_val)) then {
    handle_cheri_exception(CapCheckType_Data, CapEx_PermissionViolation);
    RETIRE_FAIL
  } else if not(validAddrRange(vaddr, cap_size) | capBoundsInfinite(auth_val)) then {
    handle_cheri_exception(CapCheckType_Data, CapEx_InvalidAddressViolation);
    RETIRE_FAIL
  } else if not(inCapBounds(auth_val, vaddr, cap_size)) then {
    handle_cheri_exception(CapCheckType_Data, CapEx_LengthViolation);
    RETIRE_FAIL
  } else if not(is_aligned_addr(vaddr, cap_size)) then {
    handle_mem_exception(vaddr, E_SAMO_Addr_Align());
    RETIRE_FAIL
  } else match translateAddr(vaddr, Write(if cs2_val.tag then Cap else Data)) {
    TR_Failure(e) => { handle_mem_exception(vaddr, e); RETIRE_FAIL },
    TR_Address(addr, pbmt, _) => {
      let eares : MemoryOpResult(unit) = mem_write_ea_cap(addr, aq & rl, rl, false);
      match (eares) {
        MemException(e) => { handle_mem_exception(vaddr, e); RETIRE_FAIL },
        MemValue(_) => {
          let res : MemoryOpResult(bool) = mem_write_cap(addr, pbmt, cs2_val, aq & rl, rl, false);
          match (res) {
            MemValue(true)  => RETIRE_SUCCESS,
            MemValue(false) => internal_error(__FILE__, __LINE__, "store got false from mem_write_value"),
            MemException(e) => { handle_mem_exception(vaddr, e); RETIRE_FAIL }
          }
        }
      }
    }
  }

2.12. Changes to Existing RISC-V Base ISA Instructions

RVY extend existing instructions that are used for handling addresses so that they manipulate a whole capability.

  • Whenever an input operand is used as an address (e.g., the load/store base address), all capability bits are fed into the instruction instead of just XLEN bits.

  • Any instruction that writes back an address (e.g., AUIPC (RVY) or CSRRW (RVY)) to the destination register, writes a full capability register instead of just XLEN bits. For all other results the high bits of the register are zeroed.

  • Whenever a capability with a new address is returned, the result is always created using the semantics of the YADDRW instruction.

ADD and ADDI are not affected by the rule above. Even though they are used for handling addresses, they also have other uses. New encodings are used for capability addition: ADDY and ADDIY. They must be used for all address incrementing.

Integer add (ADD) and capability add (ADDY) have separate encodings. Using a single encoding for both is undesirable:

  1. Integer ADD is most commonly used for purposes other than address calculations.

  2. For high performance implementations which can issue multiple ADDs, it means that the integer ADD units don’t need the upper halves of the operands, and don’t need the capability check logic on the result.

  3. The compiler and/or programmer would have to execute another metadata clearing instruction after each ADD to ensure that compartments don’t leak capabilities.

The rules above apply to the base ISA instructions listed in the following subsections, but also apply to instructions added by other extensions. Any change to instruction semantics (or remapping of opcodes) for RVY is called out in the chapter defining the extension.

2.12.1. Changes to load/stores

All load and store instructions behave as described in Load and Store Instructions with one fundamental difference:

  • Any memory instruction that has rs1 as a base address register reads the full capability register instead. The base address is unchanged, i.e., using the value from rs1. The metadata and capability tag are used to authorize the access.

  • For a load instruction, the lower XLEN bits of the result written to the destination register is the same as in the RV32I/RV64I specification.

All load and store instructions authorized by rs1 raise exceptions if any of these checks fail:

  • rs1 must not be x01

  • The capability tag (rs1.tag) must be set

  • rs1 must be unsealed

  • For loads, read permission must be set in rs1

  • For stores, write permission must be set in rs1

  • All integrity checks on rs1 must pass

1 All load/store encodings are reserved if rs1=x0 (since dereferencing NULL always faults).

All load instructions, except for the RVY LY, always zero the capability tag and metadata of the result register.

All store instructions, except for the RVY SY, always write zero to the capability tag or capability tags associated with the memory locations that are written to.

Therefore, misaligned stores may clear up to two associated capability tag bits.

The changed interpretation of the base register also applies to all loads, stores and all other memory operations defined in later chapters of this specification with a base operand of rs1 unless stated otherwise.

Under RVY all loads and stores are authorized by rs1.

These rules affect the following base ISA instructions listed in Table 17, and also apply to instructions added by other extensions, e.g.,:

Table 16. Changed RISC-V base ISA load/store instructions summary in RVY
Mnemonic Description

LD, LW[U], LH[U], LB[U]

Integer loads (authorized by the capability in rs1)

SD, SW, SH, SB

Integer stores (authorized by the capability in rs1)

2.12.2. Changes to PC

  • Whenever the address field of the pc is modified, it is always updated using the semantics of the YADDRW instruction. This includes adding an offset to the pc from direct jumps and branches for both the target address and the link register. In this case, e.g., new_pc = YADDRW(old_pc, offset)

  • JALR (RVY) copies rs1 into the pc, and increments the address field with the offset. In this case, e.g., new_pc = YADDRW(rs1, offset)

These rules affect the following base ISA instructions listed in Table 17, and also apply to instructions added by other extensions, e.g.,:

Table 17. Changed RISC-V base ISA PC relative instructions summary in RVY
Mnemonic Description

AUIPC (RVY)

Add immediate to pc address, return capability.

JAL (RVY)

Jump to pc+offset, link and seal capability to rd.

JALR (RVY)

Indirect jump, link and seal capability to rd.

2.12.3. AUIPC (RVY)

Synopsis

Add upper immediate to pc

Mnemonic

auipc rd, imm

Encoding
Diagram
This instruction is extended from the version in the base ISA.
Description

Form a 32-bit offset from the 20-bit immediate filling the lowest 12 bits with zeros. Take the value of the AUIPC instruction’s pc, increment its address by the 32-bit offset using the semantics of the YADDRW instruction and write the result to rd.

Set rd.tag=0 if the resulting capability cannot be represented exactly.

Included in

RVI (RVY modified behavior)

Operation
let off : xlenbits = sign_extend(imm @ 0x000);
let (representable, newCap) = setCapAddr(PCC, PC + off);
C(cd) = clearTagIf(newCap, not(representable));
RETIRE_SUCCESS

2.12.4. JAL (RVY)

Synopsis

Immediate offset jump, and link and seal to capability register

Mnemonic

jal rd, offset

Encoding
Diagram
Description

Jump to the target pc.

Increment pc.address by the sign-extended offset to form the target pc. The pc of the next instruction is sealed and written to rd.

Both address increments use the semantics of the YADDRW instruction to determine the result.

A future extension may raise an exception on the branch instruction itself if fetching a minimum sized instruction at the target pc will raise a CHERI Instruction Access Fault. Performing the pc bounds check at the branch source instead of on instruction fetch is helpful for debugging and can simplify the implementation of CPUs with very short pipelines.
Included in

RVI (RVY modified behavior)

Operation

TODO

2.12.5. JALR (RVY)

Synopsis

Jump to capability register, and link and seal to capability register

Mnemonic

jalr rd, rs1, offset

Encoding
Diagram
This instruction is extended from the version in the base ISA.
Description

Indirect jump to the target capability in rs1 with an address offset.

Copy rs1 to the target pc

  1. If the target pc is a sentry, and the offset is zero, then unseal the target pc. Otherwise, increment the address of the target pc by the sign-extended 12-bit offset.

  2. Set bit zero of the target address to zero and update pc with the new target address using the semantics of the YADDRW instruction

  3. Jump to the target pc

    The pc of the next instruction is calculated using the semantics of the YADDRW instruction, and written to rd as a sentry.

    Because of the unsealing and YADDRW behavior, it is not possible for the target pc to be sealed.
    A future extension may raise an exception on the JALR instruction itself if the target pc will raise a CHERI exception at the target.
Included in

RVI (RVY modified behavior)

Operation

TODO

2.12.6. Changes to BEQ, BNE

For beq and bne only, if rs1≥rs2 then the encoding is RESERVED. These encodings are redundant and may be used by future extensions.

Future behavior for these reserved branch encodings may include branching on capability tag values only, or YLEN-bit compares.

If the target of a taken branch lies outside the bounds of pc, the next instruction fetch will raise an exception.

A future extension may raise an exception on the branch instruction itself if fetching a minimum sized instruction at the target pc will raise a CHERI Instruction Access Fault.

3. "Zys" Extension for Creation of Sentry Capabilities

In the RVY base ISA the only way to create a sentry capability is through the JALR (RVY) instruction as that writes back a sentry capability to the link register. The Zys extension adds the YSENTRY instruction to allow sealing arbitrary capabilities as a sentry capability (CT-field=1).

Future extensions to RVY (such as CHERIoT, see uycfg) support additional CT-field values as alternatives to the sentry capability (CT-field=1), so this instruction is part of an optional extension instead of the RVY base ISA.

3.1. Added instructions

3.1.1. YSENTRY

Synopsis

Seal capability as a sentry

Mnemonic

ysentry rd, rs1

Encoding
Diagram
Description

Copy rs1 to rd. Set the capability type of rd to sentry capability.

Set rd.tag=0 if rs1 is sealed.

The YSENTRY instruction may give rise to an illegal instruction fault when the implementation does not support capability type 1 (unrestricted sentry; see CT-field). This is not the case when the implementation supports the capability encoding described in Default capability encoding.
Included in

Zys

Operation
let cs1_val = C(cs1);
let inCap = clearTagIf(cs1_val, capIsSealed(cs1_val));
C(cd) = sealCap(inCap);
RETIRE_SUCCESS

4. "Zyhybrid" Extension for CHERI Execution Modes

This chapter will appear in the unpriv spec somewhere after the Zicsr chapter (since it depends on Zicsr).

Zyhybrid is an optional extension to RVY which adds the ability to dynamically change the base architecture of the hart between CHERI (RVY) and standard RISC-V (RVI/RVE).

The ability to choose between these two behaviors is referred to as switching between CHERI Execution Modes. The mode is controlled by a new bit (the M-bit) allocated in the pc.

Zyhybrid adds the instructions shown in Zyhybrid which add the ability to query and update the current mode.

Zyhybrid also adds a new unprivileged CSR: the default data capability, ddc. ddc is used to authorize all data memory accesses when executing RVI/RVE code.

Together with pc, ddc allows confining code runs to a compartment (also called a sandbox), where all data memory and instruction memory accesses are bounded to fixed memory regions. These compartments have full binary compatibility with all existing ratified RISC-V base architectures and extensions, i.e. non-CHERI aware programs which execute unmodified. Providing that the privileged execution environment has set up ddc and pc appropriately, non-CHERI aware programs will execute unmodified providing they don’t attempt to access memory out of the defined bounds.

RVY implementations which support Zyhybrid are typically referred to as CHERI Hybrid, whereas implementations which do not support Zyhybrid are typically referred to as CHERI purecap.

4.1. CHERI Execution Modes

The two execution modes are:

(Non-CHERI) Address Mode

Executing with the RVI (or RVE) base ISA.

If RVC encodings are supported, load/store encodings will revert back to their non-CHERI encodings, such as C.LYSP reverting to C.FLWSP for RV32F. This behavior is summarized in Table 50, Table 51, Table 52 and Table 53.
Instructions which are modified on an RVY architecture (RVY) revert to their standard behavior.

All RVY instructions, and associated CSRs, are available in addition to RVI/RVE and all supported non-CHERI extensions.

All memory accesses are implicitly authorized by ddc, including PREFETCH.W (RVY) and PREFETCH.R (RVY). PREFETCH.I (RVY) is authorized by pc instead.

ddc is also used to authorize RVY specific memory instructions such as LY and SY.

All CSR accesses to YLEN CSRs only access the lower XLEN bits, and, if writing, update the CSR using the semantics of the YADDRW instruction (see Section 4.4).

(CHERI) Capability Mode

Executing with the RVY base ISA.

The CHERI Execution Mode is key in providing backwards compatibility with the base RV32I/RV64I ISA. RISC-V software is able to execute unchanged in implementations supporting Zyhybrid provided that the privileged environment sets up ddc and pc appropriately.

The CHERI execution mode is always (CHERI) Capability Mode on implementations that support RVY, but not Zyhybrid.

4.1.1. CHERI Execution Mode Encoding

The CHERI Execution Mode is determined by a bit in the metadata of the pc called the M-bit. Zyhybrid adds a new CHERI Execution Mode field (M) to the capability format. Although always present, it only takes effect in code capabilities, i.e., when the X-permission is set. The exact location of the M-bit in the capability format for XLEN=32 and XLEN=64 is described in Default capability encoding.

  • Mode (M)=0 indicates (CHERI) Capability Mode.

  • Mode (M)=1 indicates (Non-CHERI) Address Mode.

While the M-bit only has an effect when installed in pc, it needs to be encoded in all capabilities. Since indirect jumps copy the full target capability into pc, it allows indirect jumps to change between modes (see Section 4.1.2).

4.1.2. Changing CHERI Execution Mode

The M-bit of pc can be updated by the instructions listed in Table 18:

Table 18. Zyhybrid instructions that can perform mode changes
Mnemonic From mode Description

JALR (RVY)

(CHERI) Capability Mode

Jump to capability register, and link and seal to capability register

YMODESWI

(CHERI) Capability Mode

Switch execution to (Non-CHERI) Address Mode

YMODESWY

(Non-CHERI) Address Mode

Switch execution to (CHERI) Capability Mode

The M-bit of a X-permission-granting capability can be read and written by the instructions listed in Table 19:

Table 19. Zyhybrid instructions to observe and update the mode in a capability
Mnemonic Description

YMODEW

Set capability execution mode

YMODER

Read capability mode
In addition to the mode switching instructions, the current mode can also be updated by setting the M-bit of a target capability using YMODEW followed by a JALR (RVY).

For capabilities that do not grant X-permission, M-bit must always be interpreted and reported as 0.

While this is not phrased as an additional rule for YPERMC to follow, beyond those of Section 2.2.10.1, capability encodings may nevertheless take advantage of this implication in their representation of architectural CHERI capabilities.

4.1.3. Observing the CHERI Execution Mode

The effective CHERI execution mode cannot be determined just by reading the M-bit from pc since it also depends on the execution environment. The following code sequence demonstrates how a program can observe the current, effective CHERI execution mode. It will write 0 for (CHERI) Capability Mode and 1 for (Non-CHERI) Address Mode to x1:

auipc x1, 0
ytagr x1, x1
Implementations that support Zyhybrid will typically boot into (Non-CHERI) Address Mode so that non-CHERI aware software can run unmodified. CHERI aware software can observe and switch the mode as required.

4.2. Added instructions

4.2.1. YMODEW

Synopsis

Set capability execution mode

Mnemonic

ymodew rd, rs1, rs2

Encoding
Diagram
Description

Copy rs1 to rd.

Clear rd.tag if rs1 is sealed.

If rs1 grants X-permission and rs1 's AP-field could have been produced by YPERMC, then update the M-bit of rd to:

  1. (CHERI) Capability Mode if the least significant bit of rs2 is 0, or,

  2. (Non-CHERI) Address Mode if the least significant bit of rs2 is 1

    Otherwise do not update the M-bit.

    The value of rs1.tag does not affect the result.
Included in

Zyhybrid

Operation 
  let cap = C(cs1);
  let mode = execution_mode_encdec(X(rs2)[0 .. 0]);

  let cap = clearTagIf(cap, capIsSealed(cap));
  let hasMode = not(permsMalformed(cap)) & canX(cap);
  let newCap = if hasMode then setCapMode(cap, mode) else cap;

  C(cd) = newCap;
  RETIRE_SUCCESS

4.2.2. YMODER

Synopsis

Read capability mode

Mnemonic

ymoder rd, rs1

Encoding
Diagram
Description

Decode the CHERI execution mode from the capability in rs1 and write the result to rd.

Set rd to 0 if rs1 does not grant X-permission

Set rd to 0 if any integrity checks failed.

Otherwise set rd according to rs1 's CHERI execution mode (M-bit):

  1. Set rd to 0 for (CHERI) Capability Mode, or,

  2. Set rd to 1 for (Non-CHERI) Address Mode.

    The value of rs1.tag does not affect the result.
Included in

Zyhybrid

Operation
let capVal = C(cs1);
X(rd) = zero_extend(execution_mode_encdec(getCapMode(capVal)));
RETIRE_SUCCESS

4.2.3. YMODESWI

See YMODESWY.

4.2.4. YMODESWY

Synopsis

Switch execution mode to (CHERI) Capability Mode (YMODESWY), or (Non-CHERI) Address Mode (YMODESWI), 32-bit encodings

Mnemonic

ymodeswy
ymodeswi

Encoding
Diagram
Description

Set the current CHERI execution mode in pc.

  • YMODESWY: If the current mode in pc is (Non-CHERI) Address Mode (1), then the M-bit in pc is set to (CHERI) Capability Mode (0). Otherwise no effect.

  • YMODESWI: If the current mode in pc is (CHERI) Capability Mode (0), then the M-bit in pc is set to (Non-CHERI) Address Mode (1). Otherwise no effect.

Included in

Zyhybrid

Operation
let mode : ExecutionMode = match effective_cheri_mode() {
  IntPtrMode => CapPtrMode,
  CapPtrMode => IntPtrMode,
};
if debug_mode_active then dinfc = setCapMode(infinite_cap, mode);
set_next_pcc(setCapMode(PCC, mode));
RETIRE_SUCCESS

4.3. Added State

Zyhybrid adds the YLEN-wide CSR shown in Table 20.

Table 20. Unprivileged YLEN-wide CSRs added in Zyhybrid
YLEN CSR Permissions Description

ddc

URW

User Default Data Capability

4.3.1. Default Data Capability CSR (ddc)

ddc is a read-write, user mode accessible capability CSR. It does not require ASR-permission in pc for writes or reads. Similarly to pc authorizing all control flow and instruction fetches, this capability register is implicitly checked to authorize all data memory accesses when the current CHERI mode is (Non-CHERI) Address Mode. On startup ddc bounds and permissions must be set such that the program can run successfully (e.g., by setting it to have sufficiently broad bounds and permissions, possibly a Root Data capability).

Diagram
Figure 9. Unprivileged default data capability register

4.4. Changes to Zicsr Instructions

When in (Non-CHERI) Address Mode, there is a special rule for updating extended CSRs (e.g., jvt (RVY)). These are CSRs that are XLEN-wide for RVI/RVE but YLEN-wide for RVY.

  • Writing an extended CSR writes the address field (XLEN bits) only, and the full CSR is updated using the semantics of the YADDRW instruction.

  • Reading an extended CSR reads the address field (XLEN bits) only

Accesses to extended CSRs in (Non-CHERI) Address Mode must only access XLEN bits for compatibility, and so use the semantics of the YADDRW instruction to determine the final written value.

YLEN-wide CSRs are accessed identically in either CHERI Execution Mode.

Table 21. YLEN-bit CSR and Extended CSR access summary for Zyhybrid
YLEN-bit CSR1 Extended CSR2

Instruction

Read Width

Write Width

Read Width

Write Width

CSRRW rd==x0

YLEN

XLEN

CSRRW rd!=x0

YLEN

YLEN

XLEN

XLEN

CSRR[C|S] rs1==x0

YLEN

XLEN

CSRR[C|S] rs1!=x0

YLEN

XLEN

XLEN

XLEN

CSRRWI rd==x0

XLEN

XLEN

CSRRWI rd!=x0

YLEN

XLEN

XLEN

XLEN

CSRR[C|S]I uimm==x0

YLEN

XLEN

CSRR[C|S]I uimm!=x0

YLEN

XLEN

XLEN

XLEN

1 e.g., utidc

2 e.g., jvt (RVY)

4.4.1. CSRRWI (RVY)

See CSRRCI (RVY).

4.4.2. CSRRS (RVY)

See CSRRCI (RVY).

4.4.3. CSRRSI (RVY)

See CSRRCI (RVY).

4.4.4. CSRRC (RVY)

See CSRRCI (RVY).

4.4.5. CSRRCI (RVY)

Synopsis

CSR access (CSRRWI, CSRRS, CSRRSI, CSRRC, CSRRCI) 32-bit encodings for RVY

Mnemonics

csrrs rd, csr, rs1
csrrc rd, csr, rs1
csrrwi rd, csr, imm
csrrsi rd, csr, imm
csrrci rd, csr, imm

Encoding
Diagram
Description

These CSR instructions have extended functionality for accessing YLEN bit CSRs, and XLEN bit CSRs extended to YLEN bits (Extended CSRs).

Access to XLEN bit CSRs is as defined in Zicsr.

Zicsr rules are followed when determining whether to read or write the CSR.

Suppressed read or write actions have no side-effects on the CSR.

All writes are XLEN bits only, as determined by Zicsr, and use the semantics of the YADDRW instruction to determine the final write data.

Read data from extended CSRs is YLEN bits in (CHERI) Capability Mode or, if Zyhybrid is supported, XLEN bits in (Non-CHERI) Address Mode.

Read data from YLEN bit CSRs is always YLEN bits.

In all cases, when writing YLEN bits of rs1, if any integrity check fails then set the capability tag to zero before writing to the CSR.

Permissions

Accessing CSRs may require ASR-permission.

Prerequisites

RVY, Zicsr

Included in

RVI (RVY modified behavior)

Operation
TBD

4.4.6. CSRRW (RVY)

Synopsis

CSR access (CSRRW) 32-bit encodings for (RVY)

Mnemonic

csrrw rd, csr, rs1

Encoding
Diagram
Description

CSRRW has extended functionality for accessing YLEN-bit CSRs, and XLEN-bit CSRs extended to YLEN bits (Extended CSRs).

Access to XLEN bit CSRs is as defined in Zicsr.

CSRRW accesses to YLEN bit CSRs read YLEN bits into rd and write YLEN bits of rs1 into the CSR.

CSRRW accesses to extended CSRs read YLEN bits into rd and write YLEN bits of rs1 into the CSR, or if Zyhybrid is supported, XLEN bit accesses are made in (Non-CHERI) Address Mode. The final write data is determined using semantics of the YADDRW instruction.

In all cases, when writing YLEN bits of rs1, if any integrity check fails then set the capability tag to zero before writing to the CSR.

Permissions

Accessing CSRs may require ASR-permission.

Prerequisites

RVY, Zicsr

Included in

RVI (RVY modified behavior)

Operation
TBD

5. "Zabhlrsc" Extension for Byte and Halfword Load Reserved/Store Conditional, Version 0.9

The Zalrsc extension offers LR/SC (load reserved/store conditional) instructions for words and doublewords. Zabhlrsc extends this by adding byte and halfword versions.

The absence of LR/SC operations for subword data types is problematic for CHERI software (RVY base architectures). Non-CHERI RISC-V software can use LR/SC on larger data types than are strictly required for the memory access to register the reservation set. RVY check memory bounds and so it not possible to round a subword access up to a word or larger to gain the reservation set.

5.1. Byte and Halfword Atomic Load Reserved/Store Conditional Instructions

The Zabhlrsc extension provides the LR.[B|H] and SC.[B|H] instructions.

zabhlrsc lr ext wavedrom reg
zabhlrsc sc ext wavedrom reg

LR.[B|H] behave analogously to LR.[W|D].

SC.[B|H] behave analogously to SC.[W|D].

All Zabhlrsc instructions sign extend the result and write it to rd.

5.2. Vector with RVY

This chapter should appear as a section in the vector chapter. Exact location TBD.

The Vector extension is orthogonal to RVY because the vector registers do not support capability tags.

A future extension may allow capability tags to be stored in vector registers. Until that time, vector load and store instructions must not be used to implement generic memory copying in software, such as the memcpy() standard C library function, because the vector registers do not hold capabilities, so the capability tags of any copied capabilities will be set to 0 in the destination memory.

Under RVY, vector loads and stores follow the standard rules for active elements:

  • Only active elements are subject to CHERI exception checks.

  • If there are no active elements then no CHERI exceptions will be raised.

  • CHERI exceptions are only raised on fault-only-first loads if element 0 is both active and fails any exception checks.

Indexed loads check the bounds of every access against the authorizing capability in rs1. Therefore the approach of having a zero base register and treating every element as an absolute address may not work well in this mode.

6. "Zylevels1" Extension for CHERI 2-Level Information Flow Control

Zylevels1 introduces a simple Information Flow Control (IFC) mechanism to CHERI.

In this simple IFC system, capabilities are said to be either global or local. While the distinction between global and local is not one of authority (that is, the distinction is not one of permission), global capabilities may attenuate into local capabilities. The distinction refines the behavior of capability store and load instructions:

  • Capability-write-permissive capabilities are refined to authorize stores of any capability or global capabilities only. The former may attenuate into the latter. Attempting to store a local capability through an insufficiently permissive authority clears the capability tag of the value written to memory, if any.

  • Capability-load-permissive capabilities are refined to authorize loads of any capabilities or local capabilities only. Again, the former may attenuate to the latter. Attempting to load a global capability through an insufficiently permissive authority instead attenuates the load result as described below.

6.1. Added Architectural Permissions (AP) Bits

Permission Type Comment

SL-permission

Data memory permission

Used to filter the permissions of loaded capabilities.

LG-permission

Data memory permission

Used to filter the permissions of loaded capabilities.
Store Local Permission (SL)

This field allows limiting the propagation of local capabilities.

A capability without GL(obal) Flag set stored through an authorizing capability lacking SL-permission will be stored with a zero capability tag.

SL-permission is a refinement of C-permission and W-permission. That is, if either of the latter are clear, then SL-permission has no effect.

Load Global Permission (LG)

This field allows limiting the propagation of global capabilities.

When a capability is loaded through an authorizing capability that lacks LG-permission, the resulting capability value has its GL(obal) Flag bit cleared. Additionally, if the loaded capability value is unsealed, its LG-permission is also cleared in the result.

This permission is similar to the base LM-permission and its effects on loaded capabilities' W-permission and LM-permission (but note the difference in interaction with seals).

LG-permission is a refinement of C-permission and R-permission. That is, if either of the latter are clear, then LG-permission has no effect.

6.2. The Capability Global (GL) Flag

The Capability Global (GL) flag is a permission-like single-bit field which allows enforcing invariants on capability propagation in combination with the LG-permission and SL-permission bits described above.

For example, the software TCB may enforce that software has access to capabilities with SL-permission only to (subsets of) its runtime stack, and may ensure that all stack pointers lack GL(obal) Flag. In such a system, capabilities without GL(obal) Flag, including all those derived from the stack, are confined to registers and stack memory. Global capabilities, say, into heap memory, may be attenuated to being local before being passed across a call; the callee will be unable to capture this pointer outside its stack. This specification defines only the architectural mechanics of this feature, for further information on how this can be used by software please refer to (Watson et al., 2023).

The Capability Global flag holds one of two values:

  • 1: the capability is global.

  • 0: the capability is local.

As with permissions, the Capability Global flag can be cleared when creating a new capability value from an existing one, but it can never be set (without deriving it from a global superset capability).

6.3. Interaction with Root Capabilities

The Root capabilities used in the system are extended thus:

6.4. Interaction with YPERMC and YPERMR

Diagram
Figure 10. Extended capability permissions bit field (see Figure 7)

The GL(obal) Flag, SL-permission, and LG-permission fields are mapped into the capability permissions bitfield (Figure 7), used by YPERMC and YPERMR, as shown in Figure 10.

6.4.1. YPERMC and the Capability Global (GL) Flag

YPERMC can produce a new capability value with the Capability Global flag cleared, even if the source capability is sealed. This is unlike architectural and software permissions. This applies to both "implicit YPERMCs" in loads from memory and explicit YPERMC instructions.

Implementations are permitted but not mandated to require that an explicit YPERMC instruction wishing to clear GL(obal) Flag has an input mask that is entirely 0s except for GL(obal) Flag (or else clear the capability tag of the resulting capability).

6.4.2. Additional YPERMC rules

As mentioned, the SL-permission and LG-permission permissions are dependent on (refinements of) base permissions. YPERMC (including "implicit YPERMC" operations) and/or the capability encoding therefore clear these permissions when their dependencies clear. Specifically, we add the following rules to those of Section 2.2.10.1:

YPERMC Rule Permission Valid only if

Zylevels1-1

LG-permission

C-permission and R-permission

Zylevels1-2

SL-permission

C-permission and W-permission

6.5. Interaction with LY

As outlined above, Zylevels1 introduces two new constraints on capabilities loaded from memory, as part of a LY instruction (ly rd, offset(rs1)). Analogous requirements apply for other instructions that inherit semantics from LY. These may be phrased as "implicit YPERMC-s" performed on the loaded capability thus:

Missing LG-permission also affects the GL(obal) Flag of sealed capabilities, since notionally the latter is not a permission but rather a data flow label attached to the loaded value.
Because SL-permission is relevant only to capabilities granting W-permission, the attenuation performed by a load whose authority (rs1) does not grant LM-permission will necessarily also clear SL-permission.

6.6. Interaction with SY

As outlined above, Zylevels1 introduces a new constraint on capabilities stored to memory, as part of a SY instruction (sy rs2, offset(rs1)). Analogous requirements apply for other instructions that inherit semantics from SY. The written capability tag may be set only if either

While LG-permission attenuates by reducing GL(obal) Flag and LG-permission, SL-permission attenuates by clearing capability tags.

6.7. Interaction with YLT

Implementations of Zylevels1 must ensure that a YLT instruction ylt rd, rs1, rs2 indicates that rs1 is a subset of rs2 (that is, sets rd to 1) only if either

The existing permission subset logic applies to the new SL-permission and LG-permission.

6.8. Interaction with YBLD

A YBLD instruction ybld rd, rs1, rs2 may yield rd.tag=1 only if either

The existing permission subset logic applies to the new SL-permission and LG-permission.

6.9. Summary Of System Behavior

Table 22. SL-permission effects for stored capabilities
Auth cap field Data cap field

W

C

SL

GL

Notes

1

1

1

X

Store data capability unmodified

0

0

Store data capability unmodified

1

Store data capability with capability tag cleared
SL-permission is relevant only to capabilities granting both W-permission and C-permission.
Table 23. GL(obal) Flag effects for loading capabilities
Auth cap field Data cap field

R

C

LG

Tag

Sealed

Action

1

1

0

1

Yes

Load data capability with its GL(obal) Flag cleared

No

Load data capability with both its GL(obal) Flag and LG-permission cleared

All other cases

Load data capability with both its GL(obal) Flag and LG-permission unmodified
LG-permission is relevant only to capabilities granting both R-permission and C-permission.

Appendix A: Default Capability Encoding in RVY

This chapter describes the default capability encoding for both RV64Y and RV32Y. It covers the following configurations:

No levels support is specified as an option to allow flexibility for future extensions to reuse the architectural permissions allocated to Zylevels1 in RV32Y. It is not recommended to exclude Zylevels1 until a better alternative exists.

If no capability encoding format extension is specified then the selected format is always uycfg.base=0, uycfg.features=1. The explicit name for this is Zydefaultcap.

If Zyhybrid is implemented, the specification includes encoding the CHERI Execution Mode in the capability format.

This chapter will appear as an appendix in the unpriv specification.

A.1. Capability Encoding

The components of a capability, except the capability tag, are encoded as shown in Figure 11 for RV32Y and Figure 12 for RV64Y. Each memory location or register able to hold a capability must also store the capability tag as out of band or hidden information that software cannot directly set or clear. The capability metadata is held in the most significant bits and the address is held in the least significant bits.

Diagram
Figure 11. Capability encoding for RV32Y
Diagram
Figure 12. Capability encoding for RV64Y

Reserved bits are available for future extensions to RVY.

Reserved bits must be 0 in valid capabilities.

The encoding of capabilities depends on the extensions supported by the current environment. The following extensions affect the capability encoding:

Zyhybrid

When Zyhybrid is supported, capabilities include an M-bit which is included in the specification below. If not supported the M-bit is reserved and reads as zero.

Zylevels1

The base definition of capabilities in RVY does not have capability-mediated Information Flow Control (IFC) mechanisms. Zylevels1 is available for this and other schemes are likely in the future to add more levels.

A.1.1. Architectural Permissions (AP) Encoding

The bit width of the permissions field depends on the value of MXLEN as shown in Table 24. A 5-bit vector encodes the permissions when RV32Y. For this case, the legal encodings of permissions are listed in Table 26. Certain combinations of permissions are impractical. For example, C-permission is superfluous when the capability does not grant either R-permission or W-permission. Therefore, it is only possible to encode a subset of all combinations.

Table 24. Permissions widths depending on MXLEN
MXLEN AP-field width Comment

32

5

Encodes some combinations of 8 permission bits, including the M-bit if Zyhybrid is supported.

64

8

Separate bits for each architectural permission.

For RV32Y, the permissions encoding is split into four quadrants. The quadrant is taken from bits [4:3] of the permissions encoding. The meaning for bits [2:0] are shown in Table 26 for each quadrant.

Quadrants 2 and 3 are arranged to implicitly grant future permissions which may be added with the existing allocated encodings. Quadrant 0 does the opposite - the encodings are allocated not to implicitly add future permissions, and so granting future permissions will require new encodings. Quadrant 1 encodes permissions for executable capabilities and the M-bit.

Table 25. Encoding of architectural permissions for RV32Y without Zylevels1
Field[2:0] R W C LM X ASR Mode1 Notes

Quadrant 0: Non-capability data read/write

bit[2] - write, bit[1] - reserved (0), bit[0] - read

Reserved bits for future extensions are 0 so new permissions are not implicitly granted

0

N/A

No permissions

1

✔

N/A

Data RO

2-3

reserved

4

✔

N/A

Data WO

5

✔

✔

N/A

Data RW

6-7

reserved

Quadrant 1: Executable capabilities

bit[0] - M-bit (0-(CHERI) Capability Mode, 1-(Non-CHERI) Address Mode)

0-1

✔

✔

✔

✔

✔

✔

Mode1

Execute + Data & Cap RW + ASR

2-3

✔

✔

✔

✔

Mode1

Execute + Data & Cap RO

4-5

✔

✔

✔

✔

✔

Mode1

Execute + Data & Cap RW

6-7

✔

✔

✔

Mode1

Execute + Data RW

Quadrant 2: Restricted capability data read/write

R and C implicitly granted, LM dependent on W permission.

Reserved bits for future extensions must be 1 so they are implicitly granted

bit[2] is reserved to mean write for future encodings

0-2

reserved

3

✔

✔

N/A

Data & Cap RO (no LM)

4-7

reserved

Quadrant 3: Capability data read/write

bit[2] - write, R and C implicitly granted.

Reserved bits for future extensions must be 1 so they are implicitly granted

0-2

reserved

3

✔

✔

✔

N/A

Data & Cap RO

4-6

reserved

7

✔

✔

✔

✔

N/A

Data & Cap RW

1 Mode (M-bit) can only be set on a valid capability when Zyhybrid is supported. Despite being encoded here it is not an architectural permission.

When RV32Y there are many reserved permission encodings (see Table 26). It is not possible for a valid capability to have one of these values since YPERMC will never create it. It is possible for invalid capabilities to have reserved values. YPERMR will interpret reserved values as if they were 0b00000 (no permissions). Future extensions may assign meanings to the reserved bit patterns, in which case YPERMR is allowed to report a non-zero value.
Mode is encoded with permissions for RV32Y, but is not a permission. It is orthogonal to permissions as it can vary arbitrarily using YMODEW.
Table 26. Encoding of architectural permissions for RV32Y with Zylevels1
Field[2:0] R W C LM LG SL X ASR Mode1 Notes

Quadrant 0: Non-capability data read/write

bit[2] - write, bit[1] - reserved (0), bit[0] - read

Reserved bits for future extensions are 0 so new permissions are not implicitly granted

0

N/A

No permissions

1

✔

N/A

Data RO

2-3

reserved

4

✔

N/A

Data WO

5

✔

✔

N/A

Data RW

6-7

reserved

Quadrant 1: Executable capabilities

bit[0] - M-bit (0-(CHERI) Capability Mode, 1-(Non-CHERI) Address Mode)

0-1

✔

✔

✔

✔

✔

✔

✔

✔

Mode1

Execute + Data & Cap RW + ASR

2-3

✔

✔

✔

✔

✔

Mode1

Execute + Data & Cap RO

4-5

✔

✔

✔

✔

✔

✔

✔

Mode1

Execute + Data & Cap RW

6-7

✔

✔

✔

Mode1

Execute + Data RW

Quadrant 2: Restricted capability data read/write

bit[2] = write, bit[1] reserved, bit[0] = !SL. R and C implicitly granted, LM dependent on W permission.

0-2

reserved

3

✔

✔

N/A

Data & Cap R0 (without LM-permission)

4-5

reserved

6

✔

✔

✔

✔

✔

N/A

Data & Cap RW (with SL-permission, no LG-permission)

7

✔

✔

✔

✔

N/A

Data & Cap RW (no SL-permission, no LG-permission)

Quadrant 3: Capability data read/write

bit[2] = write, bit[1] reserved, bit[0] = !SL. R and C implicitly granted.

Reserved bits for future extensions must be 1 so they are implicitly granted

0-2

reserved

3

✔

✔

✔

✔

N/A

Data & Cap R0

4-6

reserved

6

✔

✔

✔

✔

✔

✔

N/A

Data & Cap RW (with SL-permission)

7

✔

✔

✔

✔

✔

N/A

Data & Cap RW (no SL-permission)

1 Mode (M-bit) can only be set on a valid capability when Zyhybrid is supported, otherwise such encodings are reserved. Despite being encoded here it is not an architectural permission.

When RV32Y, this encoding’s compressed permission format specifies a particular procedure for encoding architectural permissions, which is used instead of YPERMC's default fixed-pointing procedure. If Zylevels1 is absent, the following rules are run in order:

YPERMC Rule Permission Valid only if

RV32-base-1

C-permission

R-permission (supersedes base-1)

RV32-base-2

X-permission

R-permission

RV32-base-3

W-permission

not(C-permission) or LM-permission

RV32-base-4

X-permission

W-permission or C-permission

RV32-base-5

LM-permission

C-permission (supersedes base-2)

RV32-base-6

X-permission

(C-permission and LM-permission) or not (C-permission or LM-permission)

RV32-base-7

ASR-permission

W-permission and C-permission and X-permission (supersedes base-3)

RV32-base-8

M-bit

X-permission and Zyhybrid is implemented

If Zylevels1 is present, the following rules are run in order:

YPERMC Rule Permission Valid only if

RV32-l1-1

C-permission

R-permission (supersedes base-1)

RV32-l1-2

X-permission

R-permission

RV32-l1-3

W-permission

not(C-permission) or LM-permission

RV32-l1-4

X-permission

W-permission or C-permission

RV32-l1-5

LM-permission

C-permission (supersedes base-2)

RV32-l1-6

LM-permission

W-permission or LG-permission

RV32-l1-7

LG-permission

LM-permission (supersedes Zylevels1-1)

RV32-l1-8

SL-permission

LM-permission and W-permission (supersedes Zylevels1-2)

RV32-l1-9

X-permission

(C-permission and LM-permission and LG-permission and SL-permission) or
(C-permission and LM-permission and LG-permission and not W-permission) or
not (C-permission or LM-permission or LG-permission or SL-permission)

RV32-l1-10

ASR-permission

W-permission and C-permission and X-permission (supersedes base-3)

RV32-l1-11

M-bit

X-permission and Zyhybrid is implemented

For RV32, the encodings which have the M-bit set to 1 for (Non-CHERI) Address Mode are only valid if Zyhybrid is implemented. Otherwise those encodings represent invalid permissions.

When RV64Y, there is a bit per permission as shown in Table 27. A permission is granted if its corresponding bit, and those of any dependent permissions, are set; otherwise, the capability does not grant that permission.

Table 27. Encoding of architectural permissions for RV64Y
Bit Encoded permission

0

C-permission

1

W-permission

2

R-permission

3

X-permission

4

ASR-permission

5

LM-permission

6

LG-permission if Zylevels1 is implemented; reserved otherwise.

7

SL-permission if Zylevels1 is implemented; reserved otherwise.

The M-bit is only assigned meaning when the implementation supports Zyhybrid and X-permission is set.

  1. For RV64Y, the bit assigned to the M-bit must be zero if X-permission isn’t set.

  2. For RV32Y, the M-bit is only encoded in quadrant 1 and does not exist in the other quadrants.

Future extensions may allow more combinations of permissions, especially for RV64Y.
Future extensions may define new dependent permissions and, if so, must augment the above table.

A.1.2. Software-Defined Permissions (SDP) Encoding

The width of the SDP-field depends on the underlying base architecture. The value of the SDP-field bits of the YPERMR result maps 1:1 to the SDP-field in the capability.

Table 28. SDP widths depending on MXLEN
MXLEN SDPLEN

32

2

64

4
Software is completely free to define the usage of these bits.

A.1.3. Capability Type (CT) Encoding

For RVY the CT field is one bit wide and maps 1:1 to the capability types listed in Table 4: it is a sentry capability if the bit is 1 or unsealed if it is 0.

A.1.4. Bounds (EF, T, TE, B, BE) Encoding

Concept

The bounds encode the base and top addresses that constrain memory accesses. The capability can be used to access any memory location A in the range base ≤ A < top. The bounds are encoded in a compressed format, so it is not possible to encode any arbitrary combination of base and top addresses. An invalid capability with capability tag cleared is produced when attempting to construct a capability that is not representable because its bounds cannot be correctly encoded. The bounds are decoded as described in Section A.1.

The bounds field has the following components:

  • T: Value substituted into the capability’s address to decode the top address

  • B: Value substituted into the capability’s address to decode the base address

  • E: Exponent that determines the position at which B and T are substituted into the capability’s address

  • EF: Exponent format flag indicating the encoding for T, B and E

    • The exponent is stored in T and B if EF=0, so it is 'internal'

    • The exponent is zero if EF=1

The bit width of T and B are defined in terms of the mantissa width (MW) which is set depending on the value of MXLEN as shown in Table 29.

Table 29. Mantissa width (MW) values depending on MXLEN
MXLEN MW

32

10

64

14

The exponent E indicates the position of T and B within the capability’s address as described in Section A.1. The bit width of the exponent (EW) is set depending on the value of MXLEN. The maximum value of the exponent is calculated as follows:

CAP_MAX_E = MXLEN - MW + 2

The possible values for EW and CAP_MAX_E are shown in Table 30.

Table 30. Exponent widths and CAP_MAX_E depending on MXLEN
MXLEN EW CAP_MAX_E

32

5

24

64

6

52
The address and bounds must be representable in valid capabilities i.e., when the capability tag is set (see Section A.1.4.4).
Decoding

The metadata is encoded in a compressed format termed CHERI Concentrate (Woodruff et al., 2019). It uses a floating point representation to encode the bounds relative to the capability address. The base and top addresses from the bounds are decoded as shown below.

The pseudocode below does not have a formal notation. It is a place-holder until the sail implementation has been integrated in the specification. In this notation, / means "integer division", [] are the bit-select operators, and arithmetic is signed. 
EW        = (MXLEN == 32) ? 5 : 6
CAP_MAX_E = MXLEN - MW + 2

If EF = 1:
    E               = 0
    T[EW / 2 - 1:0] = TE
    B[EW / 2 - 1:0] = BE
    LCout           = (T[MW - 3:0] < B[MW - 3:0]) ? 1 : 0
    LMSB            = (MXLEN == 32) ? L8 : 0
else:
    E               = CAP_MAX_E - ( (MXLEN == 32) ? { L8, TE, BE } : { TE, BE } )
    T[EW / 2 - 1:0] = 0
    B[EW / 2 - 1:0] = 0
    LCout           = (T[MW - 3:EW / 2] < B[MW - 3:EW / 2]) ? 1 : 0
    LMSB            = 1

Reconstituting the top two bits of T:

T[MW - 1:MW - 2] = B[MW - 1:MW - 2] + LCout + LMSB

The bounds are decoded as shown in Figure 13 and Figure 14.

Diagram
Figure 13. Decoding of the MXLEN+1 wide top (t) bound
Diagram
Figure 14. Decoding of the MXLEN wide base (b) bound

Figure 13 and Figure 14 include ranges which may not be present when the bounds are decoded:

  • If E = 0 the lower section does not exist.

  • If E+MW=MXLEN then the top section is only the least signification bit of ct for the top bound, and top section doesn’t exist for the bottom bound.

  • If E+MW>MXLEN then neither top section exists, and so the bounds are calculated with no depending on the address field a.

The corrections ct and cb are calculated as as shown below using the definitions in Table 31 and Table 32.

A = a[E + MW - 1:E]
R = B - 2MW-2
The comparisons in Table 31 and Table 32 are unsigned.
Table 31. Calculation of top address correction
A < R T < R ct

false

false

0

false

true

+1

true

false

-1

true

true

0
Table 32. Calculation of base address correction
A < R B < R cb

false

false

0

false

true

+1

true

false

-1

true

true

0

The base, b, and top, t, addresses are derived from the address by substituting a[E + MW - 1:E] with B and T respectively and clearing the lower E bits. The most significant bits of a may be adjusted up or down by 1 using corrections cb and ct to allow encoding memory regions that span alignment boundaries.

The EF bit selects between two cases:

  1. EF = 1: The exponent is 0. When RV32Y, L8 encodes the MSB of the length, which can be used to derive T[MW-1:MW-2], forming a full MW-wide T field.

  2. EF = 0: The exponent is internal with E stored in the lower bits of T and B, with L8 used for the MSB of E when RV32Y. E is chosen so that the most significant non-zero bit of the length of the region aligns with T[MW - 2] such that this bit is implied by E.

The most significant two bits of T can be derived from B using the equality T = B + L, where L[MW - 2] is known from the values of EF and E (as well as L8 when RV32Y). A carry out is implied if T[MW - 3:0] < B[MW - 3:0] since it is guaranteed that the top is larger than the base.

The compressed bounds encoding allows the address to roam over a large representable region while maintaining the original bounds. This is enabled by defining a lower boundary R from the out-of-bounds values that allows us to disambiguate the location of the bounds with respect to an out-of-bounds address. R is calculated relative to the base by subtracting 2MW-2 from B. If B, T or a[E + MW - 1:E] is less than R, it is inferred that they lie in the 2E+MW aligned region above R labeled spaceU in Figure 2 and the corrections ct and cb are computed accordingly. The overall effect is that the address can roam 2E+MW/4 bytes below the base address and at least 2E+MW/4 bytes above the top address while still allowing the bounds to be correctly decoded.

Top bound MSB correction

A capability has infinite bounds if its bounds cover the entire address space such that the base address b=0 and the top address t≥2MXLEN, i.e., t is an MXLEN + 1 bit value. However, b is an MXLEN-bit value and the size mismatch introduces additional complications when decoding, so the following condition is required to correct t for capabilities whose Representable Range wraps the edge of the address space:D

if ( (E < (CAP_MAX_E - 1)) & (t[MXLEN: MXLEN - 1] - b[MXLEN - 1] > 1) )
    t[MXLEN] = !t[MXLEN]
The comparison is unsigned.

That is, invert the most significant bit of t if the decoded length of the capability is larger than E.

A capability has infinite bounds if E=CAP_MAX_E and it is not malformed (see Section A.1.4.4); this check is equivalent to b=0 and t≥2MXLEN.
Malformed Capability Bounds

A capability is malformed if its bounds cannot be correctly decoded. The following check indicates whether a capability is malformed. enableL8 is true when RV32Y and false otherwise, indicating whether the L8 bit is available for extra precision when EF=1.

malformedMSB =  (E == CAP_MAX_E     && B         != 0)
             || (E == CAP_MAX_E - 1 && B[MW - 1] != 0)
malformedLSB =  (E  < 0) || (E == 0 && enableL8)
malformed    =  !EF && (malformedMSB || malformedLSB)

Capabilities with malformed bounds:

  1. Return both base and top bounds as zero, which affects instructions like YBASER.

  2. Cause certain manipulation instructions like ADDIY to always set the capability tag of the result to zero.

A.2. Integrity of Capabilities

CHERI enforces the following rules for all valid capabilities:

  1. The bounds are not malformed.

  2. No reserved bit in the capability encoding is set.

  3. The permissions can be legally produced by YPERMC.

In all cases the capability could not have been legally created, and so either:

  • There has been a corruption of capability state due to memory or logic faults

  • There is an incompatible or faulty CHERI IP within the system

These checks are much less rigorous than parity or ECC protection, and are only used to detect simple problems with the capability metadata.
Even though valid capabilities which fail the integrity check could not have been legally generated by the local hart, defining the handling in the architecture allows the behavior to be precisely specified for all 2(YLEN+1) input values.

Implementing these checks is optional, as integrity failures are most likely due to IP compatibility issues.

A.3. Encoding of Special Capabilities

A.3.1. NULL Capability Encoding

The NULL capability is represented with 0 in all fields. This implies that it has no permissions and its exponent E is CAP_MAX_E (52 for RV64Y, 24 for RV32Y), so its bounds cover the entire address space such that the expanded base is 0 and top is 2MXLEN.

Table 33. Field values of the NULL capability
Field Value Comment

Capability Tag

zero

Capability is not valid

SDP

zeros

Grants no permissions

AP

zeros

Grants no permissions

M

zero

No meaning since non-executable (RV64Y and Zyhybrid only)

CT

zero

Unsealed

EF

zero

Internal exponent format

L8

zero

Top address reconstruction bit (RV32Y only)

T

zeros

Top address bits

TE

zeros

Exponent bits

B

zeros

Base address bits

BE

zeros

Exponent bits

Address

zeros

Capability address

Reserved

zeros

All reserved fields

Permissions added by extensions (such as those of Zylevels1) are presumed absent in NULL capabilities.

A.3.2. Infinite Capability Encoding

This encoding is for an Infinite capability value, which grants all permissions while its bounds also cover the whole address space. It includes X-permission and so includes the M-bit if Zyhybrid is supported. This infinite capability is both a Root Executable and a Root Data capability.

This capability format has a single encoding for the Infinite capability. The CHERIoT encoding format has separate roots for code and for data, and will be included in a future version of this specification.
Table 34. Field values of the Infinite capability
Field Value Comment

Capability Tag

one

Capability is valid

SDP

ones

Grants all permissions

AP (RV32Y)

0x8/0x91 (see Table 26)

Grants all permissions

AP (RV64Y)

0xFF (see Table 27)

Grants all permissions

CT

zero

Unsealed

EF

zero

Internal exponent format

L8

zero

Top address reconstruction bit (RV32Y only)

T

zeros

Top address bits

TE

zeros

Exponent bits

B

zeros

Base address bits

BE

zeros

Exponent bits

Address

zeros2

Capability address

Reserved

zeros

All reserved fields

1If Zyhybrid is supported, then the infinite capability must represent (Non-CHERI) Address Mode for compatibility with standard RISC-V code. Therefore:

  • For RV32Y, the M-bit is set to 1 in the AP-field, giving the value 0x9

  • For RV64Y, the M-bit is set to 1 in a separate M field which is not shown in the table above.

2If an infinite capability is used as a constant in either hardware or software, then the address field will typically be set to zero. If the address field is non-zero then it is still referred to as an infinite capability, and it still has the authority to authorize all memory accesses.

Permissions added by extensions (such as those of Zylevels1) are presumed present in Infinite capabilities.

A.4. Memory space

A hart supporting RVY has a single byte-addressable address space of 2XLEN bytes for all memory accesses. Each memory region capable of holding a capability also stores a capability tag bit for each naturally aligned YLEN bits (e.g., 16 bytes in RV64), so that capabilities with their capability tag set can only be stored in naturally aligned addresses. Capability tags must be atomically bound to the data they protect.

The memory address space is circular, so the byte at address 2XLEN - 1 is adjacent to the byte at address zero. A capability’s Representable Range described in Section A.1 is also circular, so address 0 is within the Representable Range of a capability where address 2MXLEN - 1 is within the bounds. However, the decoded top address of a capability is MXLEN + 1 bits wide and does not wrap, so a capability with base 2MXLEN - 1 and top 2MXLEN + 1 is not a subset of the infinite capability and does not authorize access to the byte at address 0. Like malformed bounds (see Section A.1.4.4), it is impossible for a CHERI core to generate a valid capability with top > 2MXLEN. If such a capability exists then it must have been caused by a logic or memory fault. Unlike malformed bounds, the top overflowing is not treated as a special case in the architecture: normal bounds check rules should be followed.

A.5. Representable Range Check

The concept of the representability check was introduced in Section 2.2.7.

The definition of the check is:

  • A source capability with address a, metadata m that decodes to give the bounds b and t.

  • A derived capability with arbitrary address a' with the same metadata m that decodes to give the bounds b' and t'.

The address a' is within the source capability’s representable range if b == b' && t == t'.

If the address a' is outside the representable range, then the derived capability has the capability tag set to zero.

A.5.1. Practical Information

An artifact of the bounds encoding is that if the new address causes t != t', then it is also the case that b != b'.

The inverse is also true, if b != b' then t != t'.

Therefore, for representable range checking, it is acceptable to either check t == t' or b == b'.

The top and bottom capability bounds are formed of two or three sections:

  • Upper bits from the address

    • This is only if the other sections do not fill the available bits (E + MW < MXLEN)

  • Middle bits from T and B decoded from the metadata

  • Lower bits are set to zero

    • This is only if there is an internal exponent (EF=0)

Table 35. Composition of the decoded top address bound
Configuration Upper Section (if E + MW < MXLEN) Middle Section Lower Section

EF=0

address[MXLEN-1:E + MW] + ct

T[MW - 1:0]

{E{1’b0}}

EF=1, i.e., E=0

address[MXLEN-1:MW] + ct

T[MW - 1:0]

The representable range defines the range of addresses which do not corrupt the bounds encoding. The encoding was first introduced in Section A.1, and is repeated in a different form in Table 35 to aid this description.

For the address to be valid for the current bounds encoding, the value in the Upper Section of Table 35 must not change as this will change the meaning of the bounds. This is because T, B and E will be unchanged for the source and destination capabilities. Therefore, the Middle and Lower sections of the bounds calculation are also unchanged for source and destination capabilities.

When E > CAP_MAX_E - 2, the calculation of the top bound is entirely derived from T and E which will be identical for both the source and destination capabilities, thus guaranteeing that t == t'. Likewise, with such values of E, the base bound is entirely derived from B and E and therefore b == b'.

The calculation of the MSB of the top bound maybe inverted as specified Section A.1.4.3. Assuming (E < (CAP_MAX_E - 1)), the truth-table for this inversion is as follows:

Table 36. Top bound MSB inversion truth table
input_t[MXLEN:MXLEN-1] b[MXLEN-1] output_t[MXLEN:MXLEN-1]

00

0

00

01

0

01

10

0

00

11

0

01

00

1

10

01

1

01

10

1

10

11

1

01

Inspection of Table 36 shows that output_t[MXLEN] does not depend on input_t[MXLEN] as:

  • output_t[MXLEN] = {input_t[MXLEN-1], b[MXLEN-1]} == 2’b01.

This leads to the conclusions:

  • If t[MXLEN-1] == t'[MXLEN-1] and b[MXLEN-1] == b'[MXLEN-1], then it is guaranteed t[MXLEN] == t'[MXLEN].

  • If t[MXLEN-1] != t'[MXLEN-1] or b[MXLEN-1] != b'[MXLEN-1], then the representable check will fail regardless of checking t[MXLEN] == t'[MXLEN].

Therefore, for the purpose of representable range checking, it is not required to check that t[MXLEN]==t'[MXLEN].

Given that t[MXLEN] is not part of the representable range check:

  • when E == CAP_MAX_E - 2, t[MXLEN-1:E] == T[MW-1:0] and b[MXLEN-1:E] == B[MW-1:0].

Therefore, T and B are both derived from the capabilities metadata and are therefore constant. Which means that in this case too, the representable range check always passes.

As a result:

  • If E > CAP_MAX_E - 3, then the representability check always passes, even though the bounds are only infinite if E = CAP_MAX_E

This gives a range of s=2E+MW, as shown in Figure 2.

The gap between the object bounds and the bound of the representable range is always guaranteed to be at least 1/4 of s. This is represented by R = B - 2MW-2 in Section A.1. This gives useful guarantees, such that if an executed instruction is in pc bounds, then it is also guaranteed that the next linear instruction is representable.

Chapters for the privileged specification

7. "Machine/Supervisor-Level ISA (RVY)" Extensions, Version 1.0

This chapter will appear in the priv spec. Exact location TBD.

This chapter describes integration of RVY with the RISC-V privileged architecture.

7.1. Machine-Level CSRs added or extended by RVY

RVY extends some M-mode CSRs to hold capabilities or otherwise add new functions. ASR-permission in the pc is always required for access to privileged CSRs.

7.1.1. Machine Trap Vector Base Address Capability Register (mtvec)

The mtvec register is extended to hold a code capability. Its reset value is nominally a Root Executable capability.

mtvec (RVY) exists in all CHERI implementations, and so may be used as a source of a Root Executable capability after reset.
Diagram
Figure 15. Machine-mode trap-vector base-capability register

The fields in the metadata are WARL as many fields can be implemented as constants.

Examples of WARL behavior include always setting X-permission to 1 and setting the reserved fields to zero, otherwise the capability is unusable. Another example is to partially or fully restrict the bounds to constant values.
Care must be taken however that suitable root capabilities are available to software after reset if this CSR does not represent one.

When traps are taken into machine mode, the pc is updated following the standard mtvec behavior. The capability tag and metadata from mtvec (RVY) are also written to the pc.

Following the standard mtvec behavior, the value of mtvec.address can be viewed with a range of different addresses:

  1. The MODE field is included in mtvec.address[1:0] but it does not form part of the trap vector address.

  2. When MODE=Vectored, the trap vector address is incremented by four times the interrupt number.

  3. CSR reads include MODE in mtvec.address[1:0].

HICAUSE is defined to be the largest interrupt cause value that the implementation can write to xcause when an interrupt is taken.

Therefore the minimum observable address is mtvec.address & ~3 and the maximum is (mtvec.address & ~3) + 4 x HICAUSE.

All possible observable values must be in the Representable Range. Software must ensure this is true when writing to mtvec (RVY), and the hardware sets the capability tag to zero if any values are out of the Representable Range.

Modifying the address of any capability outside of the Representable Range without clearing the capability tag causes a security hole as the interpretation of the bounds changes. Therefore requiring that all possible observable addresses are representable but not necessary in bounds is the minimum security requirement.

mtvec (RVY) is always updated using the semantics of the YADDRW instruction and so writing a sealed capability will cause the capability tag to be set to zero.

The capability in mtvec (RVY) is not unsealed when it is written to pc, unlike other executing from other CSRs such as mepc (RVY).

mtvec (RVY) follows the rule from mtvec about not needing to be able to hold all possible invalid addresses (see Invalid address conversion).

7.1.2. Machine Scratch Capability Register (mscratch)

The mscratch register is extended to hold a capability.

The reset value of the capability tag of this CSR is zero, the reset values of the metadata and address fields are UNSPECIFIED.

It is not WARL, all capability fields must be implemented.

Diagram
Figure 16. Machine-mode scratch capability register

7.1.3. Machine Exception Program Counter Capability (mepc)

The mepc is extended to hold a capability. Its reset value is nominally a Root Executable capability.

Diagram
Figure 17. Machine exception program counter capability register

mepc.address is the mepc CSR, and so the follows the standard rules meaning that:

  1. mepc.address[0]=0, and

  2. mepc.address[1]=0 when IALIGN is fixed to 32

  3. mepc.address[1] reads as zero when IALIGN is programmable and is set to 32

As listed above for mtvec (RVY), this means that mepc.address can represent multiple different values. Therefore software must ensure that all possible values are in the Representable Range on writing, otherwise the hardware sets the written capability tag to zero.

Sealed capabilities may be written to mepc (RVY). The capability tag is set to zero on writing if:

  1. mepc.address[0]=1, or

  2. mepc.address[1]=1 when IALIGN=32

In the following case the value of the capability tag observable in the CSR depends on the value of IALIGN:

  1. mepc (RVY) is sealed, the capability tag is set, and

  2. mepc.address[1]=1 and IALIGN=16 when writing the CSR

The capability tag is zero then IALIGN=32 when reading the CSR, or executing MRET (RVY), and the capability tag is one when IALIGN=16.

When a trap is taken into M-mode, the pc is written to mepc.address following the standard behavior. The capability tag and metadata of the pc are also written to mepc (RVY).

On execution of an MRET (RVY) instruction, the capability value from mepc (RVY) is unsealed and written to pc.

mepc (RVY) follows the rule from mepc about not needing to be able to hold all possible invalid addresses (see Invalid address conversion).

7.1.4. Machine Thread Identifier Capability (mtidc)

The mtidc register is used to identify the current software thread in machine mode, using the method defined in the section for the unprivileged utidc CSR. On reset the capability tag of mtidc will be set to zero and the remainder of the data is UNSPECIFIED.

Diagram
Figure 18. Machine thread identifier capability register

7.1.5. Machine CHERI Capability Encoding (mycfg)

The mycfg register is used to identify which CHERI capability encoding is used by the platform. The capability encoding both determines the in-memory representation of a CHERI capability and entails a set of extensions present atop RVY. The CSR exists in the writable namespace and all bits are defined to be WARL, but, absent any future extensions, it is expected that each implementation has exactly one legal value. For the meaning of the individual fields, refer to the uycfg register in the unprivileged specification.

Diagram
Figure 19. Machine CHERI capability encoding CSR (mycfg) format

7.2. Machine-Level CSRs modified by RVY

7.2.1. Machine Status Registers (mstatus and mstatush)

The mstatus and mstatush registers operate as described in mstatus with two restrictions:

  • The MXL, SXL and UXL fields that control the value of XLEN for S-mode and U-mode must be read-only and equal to MXL in RVY implementations. Only 1 and 2 are supported values.

  • The MBE, SBE, and UBE fields that control the memory system endianness for M-mode, S-mode, and U-mode must be read-only in RVY implementations. SBE and UBE must be read only and equal to MBE, if S-mode or U-mode, respectively, is implemented, or read-only zero otherwise.

Changing XLEN or endianness would change the interpretation of all in-memory capabilities, so allowing these fields to change at runtime is prohibited.

These restrictions may be relaxed by a future extension. Such an extension is likely to enforce the constraint that any privilege level with XLEN less than MXLEN has CHERI disabled.

MXR has no effect on the CHERI permission checking.

CHERI does not need to make use execute only memory for security reasons, and so MXR has no relevance. Additionally the 32-bit encoding format does not allow X-permission to be encoded without R-permission.

7.2.2. Machine Cause Register (mcause)

RVY adds new exception codes for CHERI exceptions that mcause must be able to represent. The new exception codes and priorities are listed in Machine cause (mcause) register values after trap and Table 37 respectively.

Table 37. Synchronous exception priority in decreasing priority order. Entries added in RVY are in bold
Priority Exc.Code Description

Highest

3

Instruction address breakpoint

32

Prior to instruction address translation:
CHERI Instruction Access Fault due to pc checks (capability tag, execute permission, bounds1)

12, 1

During instruction address translation:
First encountered page fault or access fault

1

With physical address for instruction:
Instruction access fault

2
32
0
8,9,11
3
3

Illegal instruction
CHERI Instruction Access Fault due to pc ASR-permission clear
Instruction address misaligned
Environment call
Environment break
Load/store/AMO address breakpoint

33,34

Prior to address translation for an explicit memory access:
CHERI fault due to capability checks (capability tag, sealed, permissions, bounds)

4,6

Load/store/AMO capability address misaligned
Optionally:
Load/store/AMO address misaligned

35, 36, 13, 15, 5, 7

During address translation for an explicit memory access:
First encountered CHERI Load Page Fault2, CHERI Store/AMO Page Fault, 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

35

If not higher priority:
CHERI Load Page Fault3

1 pc bounds are checked against all bytes of fetched instructions. If the instructions could not be decoded to determine the length, then the pc bounds check is made against the minimum sized instruction supported by the implementation which can be executed, when prioritizing against Instruction Access Faults.

2 The higher priority CHERI Load Page Fault covers capability loads or atomics where the loaded capability tag is not checked (Svucrg is implemented) .

3 The lower priority CHERI Load Page Fault covers capability loads or atomics where the loaded capability tag is checked (Svucrglct is implemented).

The full details of the CHERI exceptions are in Table 38.

7.2.3. Machine Trap Delegation Register (medeleg)

Bits 32,33,34,35,36 of medeleg refer to a valid CHERI exception and so can be used to delegate CHERI exceptions to supervisor mode.

7.2.4. Machine Trap Value Register (mtval)

For all CHERI faults, mtval is written with the MXLEN-bit effective address which caused the fault.

Diagram
Figure 20. Machine trap value register

7.2.5. "Smstateen/Ssstateen" Integration

The TID bit in mstateen0 controls access to the stidc CSR.

Diagram
Figure 21. Machine State Enable 0 Register (mstateen0)

7.3. Supervisor-Level CSRs added or extended by RVY

RVY extends some of the existing RISC-V CSRs to be able to hold capabilities or with other new functions. ASR-permission in the pc is required for access to all privileged CSRs.

7.3.1. Supervisor Trap Vector Base Address Capability Register (stvec)

The stvec register is extended to hold a capability.

When the S-mode execution environment starts, the value is nominally the Root Executable capability.

Diagram
Figure 22. Supervisor trap-vector base-capability register

The handling of stvec (RVY) is otherwise identical to mtvec (RVY), but in supervisor mode.

7.3.2. Supervisor Scratch Capability Register (sscratch)

The sscratch register is extended to hold a capability.

At the start of the S-mode execution environment, the value of the capability tag of this CSR is zero and the values of the metadata and address fields are UNSPECIFIED.

It is not WARL, all capability fields must be implemented.

Diagram
Figure 23. Supervisor scratch capability register

7.3.3. Supervisor Exception Program Counter Capability (sepc)

The sepc register is extended to hold a capability.

When the S-mode execution environment starts, the value is nominally the Root Executable capability.

As shown in Table 66, sepc (RVY) is a code capability, so it does not need to be able to hold all possible invalid addresses (see Invalid address conversion). Additionally, the capability in sepc (RVY) is unsealed when it is written to pc on execution of an SRET (RVY) instruction. The handling of sepc (RVY) is otherwise identical to mepc (RVY), but in supervisor mode.

Diagram
Figure 24. Supervisor exception program counter capability register

7.3.4. Supervisor Thread Identifier Capability (stidc)

The stidc register is used to identify the current software thread in supervisor mode, using the method defined in the section for the unprivileged utidc CSR.

At the start of the S-mode execution environment, the value of the capability tag of this CSR is zero and the values of the metadata and address fields are UNSPECIFIED.

Diagram
Figure 25. Supervisor thread identifier capability register

7.3.5. Supervisor CHERI Capability Encoding (sycfg)

The sycfg register is used to identify which CHERI capability encoding is used by the platform. The capability encoding both determines the in-memory representation of a CHERI capability and entails a set of extensions present atop RVY. The CSR exists in the writable namespace and all bits are defined to be WARL, but, absent any future extensions, it is expected that each implementation has exactly one legal value. For the meaning of the individual fields, refer to the uycfg register in the unprivileged specification.

Diagram
Figure 26. Supervisor CHERI capability encoding CSR (sycfg) format

7.4. Supervisor-Level CSRs modified by RVY

7.4.1. Supervisor Cause Register (scause)

RVY adds a new exception code for CHERI exceptions that scause must be able to represent. The new exception code is listed in .Supervisor cause (scause) register values after trap. The behavior and usage of scause otherwise remains as described in scause.

See Section 7.2.2 for the new exceptions priorities when RVY is implemented.

7.4.2. Supervisor Trap Value Register (stval)

stval is updated following the same rules as Section 7.2.4 for CHERI exceptions and CHERI page faults which are delegated to HS-mode or S-mode.

7.4.3. "Smstateen/Ssstateen" Integration

The TID (thread ID) bit in sstateen0 controls access to the utidc CSR. See utidc for a description of the usage.

Diagram
Figure 27. Supervisor State Enable 0 Register (sstateen0)

7.5. CHERI Exception handling

CHERI faults are typically higher priority than standard RISC-V faults. E.g., CHERI faults on the pc are higher priority than any other fault effecting the program counter such as instruction access fault.

auth_cap is rs1, unless in (Non-CHERI) Address Mode when it is ddc (if Zyhybrid is implemented).
Table 38. Valid CHERI exception combination description
Instructions Xcause Description Check

All instructions have these exception checks first

All

32

CHERI Instruction Access Fault

pc capability tag is zero

All

32

CHERI Instruction Access Fault

pc is sealed

All

32

CHERI Instruction Access Fault

pc does not have X-permission

All

32

CHERI Instruction Access Fault

Any byte of current instruction out of pc bounds1

All

32

CHERI Instruction Access Fault

pc failed any integrity check.

CSR/Xret additional exception check

CSR*, MRET (RVY), SRET (RVY), CBO.INVAL (RVY)

Illegal instruction

CHERI Instruction Access Fault

pc does not have ASR-permission when required for CSR access or execution of MRET (RVY), SRET (RVY) or CBO.INVAL (RVY)

Load additional exception checks

All loads

33

CHERI Load Access Fault

auth_cap capability tag is zero

All loads

33

CHERI Load Access Fault

auth_cap is sealed

All loads

33

CHERI Load Access Fault

auth_cap does not have R-permission

All loads

33

CHERI Load Access Fault

Any byte of load access out of auth_cap bounds1

All loads

33

CHERI Load Access Fault

auth_cap failed any integrity check.

Capability loads

52

Load access fault

Misaligned capability load

Store/atomic/cache-block-operation additional exception checks

All stores, all atomics, all CBOs

34

CHERI Store/AMO Access Fault

auth_cap capability tag is zero

All stores, all atomics, all CBOs

34

CHERI Store/AMO Access Fault

auth_cap is sealed

All stores, CBO.ZERO

34

CHERI Store/AMO Access Fault

auth_cap does not have W-permission

All atomics, CBO.CLEAN, CBO.FLUSH, CBO.INVAL

34

CHERI Store/AMO Access Fault

auth_cap does not have both R-permission and W-permission

All stores, all atomics

34

CHERI Store/AMO Access Fault

any byte of access out of auth_cap bounds1

CBO.ZERO, CBO.INVAL

34

CHERI Store/AMO Access Fault

any byte of cache block out of auth_cap bounds1

CBO.CLEAN, CBO.FLUSH

34

CHERI Store/AMO Access Fault

all bytes of cache block out of auth_cap bounds1

All stores, all atomics, all CBOs

34

CHERI Store/AMO Access Fault

auth_cap failed any integrity check.

Capability stores

72

Store access fault

Misaligned capability store

1 The bounds checks include the cases where the bounds could not be decoded.

2 Misaligned capability accesses raise access faults instead of misaligned faults since they cannot be emulated in software.

CBO.ZERO (RVY) is performed as a cache block wide store. All CMOs operate on the cache block which contains the address. Prefetch instructions check that the authorizing capability is has its capability tag set, is not sealed, has the required permission (R-permission, W-permission, X-permission) corresponding to the instruction, and has bounds which include at least one byte of the cache block; if any check fails, the prefetch is not performed but no exception is generated.

7.6. CHERI Exceptions and speculative execution

should be non-normative - and needs more details - move to appendix?

CHERI adds architectural guarantees that can prove to be microarchitecturally useful. Speculative-execution attacks can — among other factors — rely on instructions that fail CHERI permission checks not to take effect. When implementing any of the extensions proposed here, microarchitects need to carefully consider the interaction of late-exception raising and side-channel attacks.

7.7. Physical Memory Attributes (PMA)

Typically, only parts of the entire memory space need to support CHERI capability tags. Therefore, it is desirable that harts supporting RVY extend PMAs with Physical Memory Attributes indicating whether a memory region allows storing CHERI capability tags. If they are not supported, then what the behavior is when attempting to access them.

There are three levels of support:

Table 39. CHERI PMAs
PMA Load Behavior Store Behavior Comment

CHERI Capability Tag

Load capability tag

Store capability tag

Tagged memory supporting capability tags

CHERI Capability Tag Strip

Load zero capability tag

Ignore stored capability tag

No support for capability tags, ignore them

CHERI Capability Tag Fault

Load zero capability tag

Store/AMO Access Fault on capability tag1

No support for capability tags, trap on storing one

1 The access fault is triggered on all capability stores or atomics such as SY or AMOSWAP.Y when C-permission and W-permission are granted and the capability tag is set to one.

Memory regions that do not have the CHERI Capability Tag PMA do not require storage for capability tags.

7.8. Virtual Memory

CHERI checks are made on the effective address according to the current translation scheme. I.e., on the virtual address if translation is enabled or the physical address if translation is disabled.

Implicit memory accesses made by the page table walker are not subject to CHERI checks.

A future extension may add CHERI checks to the page table walker.

7.9. Modified Trap-Return Instructions Behavior

When the RVY base ISA is implemented, the trap-return instructions (MRET and SRET) read the full YLEN bits of the mepc (RVY)/sepc (RVY) register and unseal it prior to exception return if it is a sentry capability.

7.9.1. SRET (RVY)

See MRET (RVY).

7.9.2. MRET (RVY)

Synopsis

Trap Return (MRET, SRET)

Mnemonics

mret
sret

Encoding
Diagram
Description

Return from machine mode (MRET (RVY)) or supervisor mode (SRET (RVY)) trap handler. MRET unseals mepc (RVY) and writes the result into pc. SRET unseals sepc (RVY) and writes the result into pc.

Exceptions

An illegal instruction fault is raised when pc does not grant ASR-permission because MRET (RVY) and SRET (RVY) require access to privileged CSRs.

Prerequisites (MRET)

Machine-Level ISA, RVY

Prerequisites (SRET)

Supervisor-Level ISA, RVY

Operation
TBD

8. "Zyhybrid for Privileged Architectures" Extension, Version 1.0

When using a system with Zyhybrid, it may be desirable to disable CHERI register and instruction access to some (or all) privilege levels such that they operate as a RV32I/RV64I system without any observable presence of CHERI features. Zyhybrid includes functions to disable explicit access to CHERI registers and instructions (hereafter referred to disabling CHERI).

When CHERI is disabled for a specific privilege level, pc and ddc bounds are still enforced.

The Zyhybrid extension makes the Y bit of misa, menvcfg, and senvcfg writable to allow CHERI to be disabled.

The effective CHERI-enable for the current privilege is:

On reset CHERI is always disabled for backwards compatibility (misa.Y resets to zero, ddc and pc bounds are nominally root capabilities (see Root).

The following occurs when executing code in a privilege mode that has CHERI disabled:

  • Instructions from RVY and Zyhybrid cause illegal instruction exceptions.

  • Executing CSR instructions accessing any natively YLEN CSR causes an illegal instruction exception.

  • Executing CSR instructions accessing any CSR extended to YLEN only allows XLEN access (this is identical to (Non-CHERI) Address Mode access).

Disabling CHERI has no effect on implicit accesses or security checks. The last capability written to pc and ddc before disabling CHERI will be used to authorize instruction execution and data memory accesses.

Disabling CHERI prevents low-privileged (Non-CHERI) Address Mode software from interfering with the correct operation of higher-privileged (Non-CHERI) Address Mode software that do not perform ddc switches on trap entry and return.

Disabling CHERI allows harts supporting CHERI to be fully compatible with standard RISC-V, so CHERI instructions, such as YAMASK, that do not change any CHERI state, raise exceptions. This is the default behavior on reset.

Table 40 summarizes the behavior of a hart in connection with the effective CHERI enable and the CHERI Execution Mode while in a privilege other than debug mode.

Table 40. Hart’s behavior depending on the effective CHERI enable and CHERI Execution Mode
Y1=0 Y=1, M-bit=1 Y=1, M-bit=0

Authorizing capability for data memory accesses

ddc

ddc

capability in rs1

natively YLEN CSR Access Width

✘

YLEN

YLEN

Extended YLEN CSR Access Width

XLEN

XLEN

YLEN

CHERI Instructions Allowed

✘

✔

✔

Summary

Fully RISC-V compatible2

(Non-CHERI) Address Mode

(CHERI) Capability Mode

1 Y represents the effective CHERI enable for the current privilege mode.

2 The hart is fully compatible with standard RISC-V when Y=0 provided that pc, mtvec (RVY), mepc (RVY), stvec (RVY), sepc (RVY), vstvec (RVY), vsepc (RVY) and ddc have not been changed from the default reset state (i.e., hold Root Executable and Root Data capabilities).

9. "Supervisor-Level ISA for Virtual Memory (RV64Y)" Extension, Version 1.0 for RV64Y

Virtual memory support for RV64Y requires at least one additional bit to be allocated in the page table entries, to control access to capabilities in virtual memory pages.

9.1. Capability Read-Write (CRW) Bit

Supervisor-Level ISA for Virtual Memory (RV64Y) defines the Capability Read-Write (CRW) bit in Page Table Entries (PTEs) for Sv39, Sv48, and Sv57 virtual memory systems on RV64Y harts. The CRW bit controls whether capabilities with their capability tag set can be written to and loaded from a virtual page.

Sv32 does not have any spare PTE bits, and so this bit does not exist for RV32.
Any RV64Y hart that supports Sv39 must also implement the PTE.CRW bit.

9.1.1. Limiting Capability Propagation

Page table enforcement can allow the operating system to limit the flow of capabilities between processes. It is highly desirable that a process should only possess capabilities that have been issued for that address space by the operating system. Unix processes may share memory for efficient communication, but capability pointers must not be shared across these channels into a foreign address space. An operating system might defend against this by only issuing a capability to the shared region that does not grant the load/store capability permission. However, there are circumstances where portions of general-purpose, mmapped* memory become shared, and the operating system must prevent future capability communication through those pages. This is not possible without restructuring software, as the capability for the original allocation, which spans both shared memory and private memory, would need to be deleted and replaced with a list of distinct capabilities with appropriate permissions for each range. Such a change would not be transparent to the program. Such sharing through virtual memory is on the page granularity, so preventing capability writes with a PTE permission is a natural solution.

* allocated using mmap

9.2. CHERI page faults

CHERI adds the concept of CHERI page faults. They are split into :

  • CHERI Load Page Fault (cause value 35), and

  • CHERI Store/AMO Page Fault (cause value 36)

They are prioritized against other fault types as shown in Table 37.

The PTE.CRW bit allows CHERI Store/AMO Page Faults to be raised.

CHERI harts which implement Sv39 must also implement a revocation scheme to prevent use-after-free attacks.

The current revocation scheme (Svucrg) also allows CHERI Load Page Faults to be raised.

A future extension may define an improved scheme.

9.2.1. Extending the Page Table Entry Format

The page table entry format remains unchanged for Sv32. However, a new bit, Capability Read-Write (CRW), is added to leaf PTEs in Sv39, Sv48 and Sv57 as shown in Figure 28, Figure 29 and Figure 30 respectively. For non-leaf PTEs this bit remains reserved and must be cleared by software for forward compatibility, or else a page-fault exception is raised. Additionally, if the hypervisor extension is enabled this bit remains reserved for leaf and non-leaf PTEs used in guest address translation.

Diagram
Figure 28. Sv39 page table entry
Diagram
Figure 29. Sv48 page table entry
Diagram
Figure 30. Sv57 page table entry

The CRW bit indicates whether reading or writing capabilities with the capability tag set to the virtual page is permitted. When the CRW bit is set, capabilities are written as usual.

If the CRW bit is clear then:

  • When a capability load or AMO instruction is executed, the capability tag bit of the loaded capability is cleared before it is written to the destination register.

  • A CHERI Store/AMO Page Fault exception is raised when a capability store or AMO instruction is executed and the capability tag bit of the to-be-stored capability is set.

Table 41. Summary of memory access behavior depending on CRW in the PTEs
PTE.CRW Instruction Behavior

0

Capability load

Set loaded capability tag to zero

0

Capability store/AMO

Raise a CHERI Store/AMO Page Fault if the capability tag of the to-be-stored capability is set

1

Any

Normal operation.

The capability tag bit of the stored capability is checked after it is potentially cleared due to missing permissions. Therefore, the behavior in this section isn’t relevant if:

  • The authorizing capability doesn’t have C-permission.

  • Any extension-specific mediation has already cleared the capability tag of the to-be-stored capability.

9.3. Invalid Address Handling

When address translation is in effect for RV64Y, the upper bits of virtual memory addresses must match for the address to be valid.

The CSRs shown in Table 66, as well as the pc, need not hold all possible invalid addresses. Implementations may convert an invalid address into some other invalid address that the register is capable of holding.

However, the bounds encoding of capabilities depends on the address value if the bounds are not infinite.

Therefore implementations must not convert invalid addresses to other arbitrary invalid addresses in an unrestricted manner if the bounds are not infinite.

If the bounds could not be decoded due to the address being invalid, then a CHERI Instruction Access Fault, CHERI Load Access Fault or CHERI Store/AMO Access Fault exception is raised as appropriate.

In all cases, if the authorizing capability has bounds that cover all addresses, then the behavior is identical to the normal RISC-V behavior without CHERI.
Not requiring to the implementation to decode the bounds for invalid addresses reduces the size of bounds comparators from 64-bits to the supported virtual address width.

9.3.1. Updating CSRs

A CSR may be updated to hold a capability with an invalid address, due to:

To ensure that the bounds of a valid capability cannot be corrupted:

  • If the new address is invalid and the capability bounds do not cover all addresses, then set the capability tag to zero before writing to the CSR.

When the capability’s address is invalid and happens to match an invalid address which the CSR can hold, then it is implementation defined whether to set the capability tag to zero.

9.3.2. Branches and Jumps

If the effective target address of the jump or branch is invalid, and the authorizing capability’s bounds do not cover all addresses, then set the capability tag of the target pc to zero. This will cause a CHERI Instruction Access Fault exception when executing the target instruction.

RISC-V harts that do not support RVY normally raise an instruction access fault or page fault after jumping or branching to an invalid address. Therefore, RVY aims to preserve that behavior to ensure that harts supporting RVY and Zyhybrid are fully compatible with RISC-V harts provided that pc and ddc are set to Root Executable and Root Data capabilities, respectively.

9.3.3. Memory Accesses

If the effective address of the memory access is invalid, and the authorizing capability’s bounds do not cover all addresses, then raise a CHERI Load Access Fault or CHERI Store/AMO Access Fault exception because the bounds cannot be reliably decoded.

9.4. Integrating RVY with Sdext

This chapter will appear in the priv spec. Exact location TBD.

This section describes changes to integrate the Sdext ISA and RVY. It must be implemented to make external debug compatible with RVY. Modifications to Sdext are kept to a minimum.

The following features, which are optional in Sdext, must be implemented for use with RVY:

  • The hartinfo register must be implemented.

  • All harts which support RVY must provide hartinfo.nscratch of at least 1 and implement the dscratch0 (RVY) register.

  • All harts which support RVY must provide hartinfo.datasize of at least 1 and hartinfo.dataaccess of 0.

  • The program buffer must be implemented, with abstractcs.progbufsize of at least 4 if dmstatus.impebreak is 1, or at least 5 if dmstatus.impebreak is 0.

These requirements allow a debugger to read and write capabilities in integer registers without disturbing other registers. These requirements may be relaxed if some other means of accessing capabilities in integer registers, such as an extension of the Access Register abstract command, is added. The following sequences demonstrate how a debugger can read and write a capability in x1 if MXLEN is 64, hartinfo.dataaccess is 0, hartinfo.dataaddr is 0xBF0, hartinfo.datasize is 1, dmstatus.impebreak is 0, and abstractcs.progbufsize is 5:

# Read the high MXLEN bits into data0-data1
csrrw  x2, dscratch0, x2
yhir   x2, x1
csrw   0xBF0, x2
csrrw  x2, dscratch0, x2
ebreak

# Read the capability tag into data0
csrrw  x2, dscratch0, x2
ytagr  x2, x1
csrw   0xBF0, x2
csrrw  x2, dscratch0, x2
ebreak

# Write the high MXLEN bits from data0-data1
csrrw  x2, dscratch0, x2
csrr   x2, 0xBF0
yhiw   x1, x1, x2
csrrw  x2, dscratch0, x2
ebreak

# Write the capability tag (if nonzero)
csrrw   x2, dscratch0, x2
csrr    x2, drootc
ybld    x1, x2, x1
csrrw   x2, dscratch0, x2
ebreak

The low MXLEN bits of a capability are read and written using normal Access Register abstract commands. If dscratch0 (RVY) were known to be preserved between abstract commands, it would be possible to remove the requirements on hartinfo.datasize, hartinfo.dataaccess, and abstractcs.progbufsize, however there is no way to discover the former property.

9.4.1. Debug Mode

When executing code due to an abstract command, the hart stays in debug mode and the rules outlined in Section 4.1 of the RISC-V Debug Specification apply.

9.4.2. Core Debug Registers

RVY renames and extends debug CSRs that are designated to hold addresses to be able to hold capabilities. The renamed debug CSRs are listed in Table 69.

The pc must grant ASR-permission to access debug CSRs. This permission is automatically provided when the hart enters debug mode as described in the dpc (RVY) section. The pc metadata can only be changed if the implementation supports executing control transfer instructions from the program buffer — this is an optional feature according to the RISC-V Debug Specification.

This specification extends the following registers from the RISC-V Debug Specification.

Debug Program Counter (dpc)

dpc is a DXLEN-bit register used as the PC saved when entering debug mode.

Diagram
Figure 31. Debug program counter
Debug Scratch Register 1 (dscratch1)

dscratch1 is an optional DXLEN-bit scratch register that can be used by implementations which need it.

Diagram
Figure 32. Debug scratch 0 register
Debug Scratch Register 1 (dscratch1)

dscratch1 is an optional DXLEN-bit scratch register that can be used by implementations which need it.

Diagram
Figure 33. Debug scratch 1 register

9.4.3. Debug Program Counter Capability (dpc)

The dpc register is extended to hold a capability.

The reset value of the capability tag of this CSR is zero, the reset values of the metadata and address fields are UNSPECIFIED.

Diagram
Figure 34. Debug program counter capability

Upon entry to debug mode, the RISC-V Debug Specification, does not specify how to update the PC, and says PC relative instructions may be illegal. This concept is extended to include any instruction which reads or updates pc, which refers to all jumps, conditional branches and AUIPC (RVY). The exceptions are YMODESWY and YMODESWI which are supported if Zyhybrid is implemented, see drootc for details.

As a result, the value of pc is UNSPECIFIED in debug mode according to this specification. The pc metadata has no architectural effect in debug mode. Therefore ASR-permission is implicitly granted for access to all CSRs for instruction execution.

On debug mode entry dpc (RVY) is updated with the capability in pc whose address field is set to the address of the next instruction to be executed upon debug mode exit as described in the RISC-V Debug Specification.

When leaving debug mode, a unsealed capability value is copied from the value in dpc (RVY) and written into pc. A debugger may write dpc (RVY) to change where the hart resumes and its mode, permissions, sealing or bounds.

The legalization of dpc (RVY) follows the same rules described for mepc (RVY).

9.4.4. Debug Scratch Register 0 (dscratch0)

The dscratch1 register is extended to hold a capability.

The reset value of the capability tag of this CSR is zero, the reset values of the metadata and address fields are UNSPECIFIED.

Diagram
Figure 35. Debug scratch 0 capability register

9.4.5. Debug Scratch Register 1 (dscratch1)

The dscratch1 register is extended to hold a capability.

The reset value of the capability tag of this CSR is zero, the reset values of the metadata and address fields are UNSPECIFIED.

Diagram
Figure 36. Debug scratch 1 capability register

9.4.6. Debug Root Capability Selector (drootcsel)

drootcsel is a debug mode accessible integer CSR. The address and access details are shown in Table 20.

It selects which Root capability is exposed through drootc. The reset value is 0, which must cause drootcsel to expose a Root Executable capability.

Other capability values may be defined for exposure through drootc by the capability encoding, and may be selected by having the debugger write to this register. Writes are WARL, so the debugger may confirm that its selection has been applied.

Diagram
Figure 37. Debug root capability register

9.4.7. Debug Root Capability Register (drootc)

drootc is a debug mode accessible capability CSR. The address and access details are shown in Table 20. It exposes the capability selected by drootcsel.

If Zyhybrid is implemented, the Root Executable exposed when drootcsel is 0 is further specified thus:

  • The M-bit is reset to (Non-CHERI) Address Mode (1).

  • The debugger can set the M-bit to (CHERI) Capability Mode (0) by executing YMODESWY from the program buffer.

    • Executing YMODESWY causes subsequent instructions execution from the program buffer, starting from the next instruction, to be executed in (CHERI) Capability Mode. It also sets the CHERI execution mode to (CHERI) Capability Mode on future entry into debug mode.

    • Therefore to enable use of a CHERI debugger, a single YMODESWY only needs to be executed once from the program buffer after resetting the core.

    • The debugger can also execute YMODESWI to change the mode back to (Non-CHERI) Address Mode, which also affects the execution of the next instruction in the program buffer, updates the M-bit of this capability and controls which CHERI execution mode to enter on the next entry into debug mode.

The M-bit of this capability is only updated by executing YMODESWY or YMODESWI from the program buffer.

Diagram
Figure 38. Debug root capability register

9.5. Modified Trap-Return Instruction Behavior

The DRET instruction reads the full YLEN bits of the mepc (RVY)/sepc (RVY) register and unseals it prior to exception return if it is a sentry capability.

9.5.1. DRET (RVY)

Synopsis

Debug Return (DRET)

Mnemonic

dret

Encoding
Diagram
Description

DRET (RVY) returns from debug mode. It unseals dpc (RVY) and writes the result into pc.

The DRET (RVY) instruction is the recommended way to exit debug mode. However, it is a pseudoinstruction to return that technically does not execute from the program buffer or memory. It currently does not require the pc to grant ASR-permission so it never raises an exception.
Prerequisites

Sdext, RVY

Operation
TBD

9.6. Integrating Zyhybrid with Sdext

A new debug default data capability (dddc) CSR is added at the CSR number shown in Table 20.

Zyhybrid allows YMODESWY and YMODESWI to execute in debug mode.

When entering debug mode, whether the core enters (Non-CHERI) Address Mode or (CHERI) Capability Mode is controlled by the M-bit in the drootc capability selected by drootcsel value 0.

The current mode can be read by setting drootcsel to 0 and then reading drootc.

The following sequence executed from the program buffer will write 0 for (CHERI) Capability Mode and 1 for (Non-CHERI) Address Mode to x1:

csrr   x1, drootc
ymoder x1, x1
There is no CHERI enable/disable bit for debug mode, so CHERI register and instruction access is always permitted in debug mode.

9.6.1. Debug Default Data Capability CSR (dddc)

dddc is a debug mode accessible capability CSR. The address is shown in Table 20.

The reset value of the capability tag of this CSR is zero, the reset values of the metadata and address fields are UNSPECIFIED.

This CSR is only implemented if Zyhybrid is implemented.

Diagram
Figure 39. Debug default data capability

Upon entry to debug mode, ddc is saved in dddc. ddc is set to a Root Data capability such that ddc's address remains unchanged.

When debug mode is exited by executing DRET (RVY), the hart’s ddc is updated to the capability stored in dddc. A debugger may write dddc to change the hart’s context.

As shown in Table 66, dddc is a data pointer, so it does not need to be able to hold all possible invalid addresses (see Invalid address conversion).

9.7. "Sdtrig (RVY)", Integrating RVY with Sdtrig

This chapter will appear in the priv spec. Exact location TBD.

The Sdtrig extension is orthogonal to RVY. However, the priority of synchronous exceptions and where triggers fit is adjusted as shown in Table 42.

Debug triggers are higher priority than CHERI exceptions to allow debug.

Table 42. Synchronous exception priority (including triggers) in decreasing priority order. Entries added in RVY are in bold
Priority Exc. Code Description Trigger

Highest

3
3
3
3

etrigger
icount
itrigger
mcontrol/mcontrol6 after (on previous instruction)

3

Instruction address breakpoint

mcontrol/mcontrol6 execute address before

32

Prior to instruction address translation:
CHERI fault due to pc checks (tag, execute permission, and bounds)

12, 1

During instruction address translation:
First encountered page fault or access fault

1

With physical address for instruction:
Instruction access fault

3

mcontrol/mcontrol6 execute data before

2
0
8,9,11
3

Illegal instruction
Instruction address misaligned
Environment call
Environment break

3

Load/store/AMO address breakpoint

mcontrol/mcontrol6 load/store address before

3

mcontrol/mcontrol6 store data before

33,34

Prior to address translation for an explicit memory access:
Load/store/AMO capability address misaligned
CHERI fault due to capability checks (tag, sealed, permissions and bounds)

4,6

Optionally:
Load/store/AMO address misaligned

13, 15, 5, 7

During address translation for an explicit memory access:
First encountered CHERI Load Page Fault, CHERI Store/AMO Page Fault, 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

13

If not higher priority:
CHERI Load Page Fault 3

Lowest

3

mcontrol/mcontrol6 load data before
See the notes beneath Synchronous exception priority in decreasing priority order for details about CHERI load page fault priority.

10. Integrating RVY and Zyhybrid with Pointer Masking

This chapter should appear as a section in the pointermasking chapter. Exact location TBD.

The pointer masking extensions Smmpm, Smnpm, SSnpm, Sspm and Supm are compatible with both RVY and Zyhybrid. Whenever pointer masking is enabled, all bounds decoding and bounds checks are affected.

The suggestion in this section is based on the pointer masking approach from Morello but with changes to sign extension and to address the dynamic nature of bit masking. Further evaluation on RISCV, especially for (CHERI) Capability Mode, is still required.

When bounds are encoded or decoded, a masked but not sign extended address is used. Changing how many bits are masked can therefore change the interpretation of the bounds of a capability, both for the purpose of implicit accesses via bounds checks and any instructions that report the bounds of a capability. Apart from treating high address bits as 0, there are no other changes to bounds decode, which are still based on MXLEN, not the new effectively addressable space. That is, the maximum length of a capability does not change, and it is not invalid to have a capability that covers a longer range than could be actually be addressed with pointer masking enabled (such as one that covers the entire MXLEN address space). For the representable range check, both the original and new address are masked. Bounds setting instructions also mask the address in the same way.

Because dynamically changing the number of masked bits changes the interpretation of a capability, software must take the same care when sharing capabilities between address spaces with differing pointer masking as it generally must when sharing capabilities between address spaces with different page mappings.

Any address that is checked against a capability (whether via loads/stores in (Non-CHERI) Address Mode or (CHERI) Capability Mode), is also first subject to the same masking as bounds decode (masking without extension). After any CHERI operations, the final access address is still subject to as much sign extension as the masking extensions mandate.

11. "Svucrg" Extension, Version 1.0 for RV64Y

This chapter will appear in the priv spec. Exact location TBD.
Sv32 (for RV32) does not have any spare PTE bits, and so no features from this chapter can be implemented.

The Svucrg extension adds the ability to perform capability revocation of user mode pages (see Section 11.1) by adding the PTE.CRG, PTE.CD and sstatus.UCRG bits as described below.

Svucrg depends on Supervisor-Level ISA and RV64Y also being supported.
Svucrg is strongly recommended but not mandatory as a future version of this specification may specify an improved method.
There is no explicit mechanism for enabling or disabling Svucrg.
If software ignores the new PTE bits then there is no change in functionality unless capabilities are accessed.
A future version of this specification may include kernel revocation which may require an sstatus.SCRG bit.

The minimum level of PTE support is to set CRW and CD to 1 in all PTEs intended for storing capabilities (i.e., private anonymous mappings) and leave sstatus.UCRG and CRG in all PTEs set to 0, which will allow capabilities with their tags set to be loaded and stored successfully.

Hardware initiated memory accesses from the page-table walker are not checked by a capability.

11.1. Capability Revocation

Page table enforcement can accelerate concurrent capability revocation for temporal safety. Without page table capability protection, a concurrent capability revocation sweep must begin by visiting all PTEs to mark them unreadable, henceforth trapping on any read to a new page to sweep it clean before proceeding. With a page-granularity generational capability read permission, we can eliminate the initial permission change of all PTEs. In addition, a page-granularity capability write control can eliminate many pages from the sweep that are known to not contain capabilities. Page-granularity capability-dirty tracking accelerates the detection of capability-clean pages, which enables the revocation sweep to skip them during the visit.

11.2. Extending the Page Table Entry Format

Two new bits, Capability Read Generation (CRG) and Capability Dirty (CD), are added to leaf PTEs in Sv39, Sv48 and Sv57 as shown in Figure 40, Figure 41 and Figure 42 respectively. For non-leaf PTEs these bits remain reserved and must be cleared by software for forward compatibility, or else a page-fault exception is raised. Additionally, if the hypervisor extension is enabled these bits remain reserved for leaf and non-leaf PTEs used in guest address translation.

Diagram
Figure 40. Sv39 page table entry
Diagram
Figure 41. Sv48 page table entry
Diagram
Figure 42. Sv57 page table entry
The behavior in this section isn’t relevant if:

  1. The authorizing capability doesn’t have C-permission, for loads, stores and AMO.

  2. Any extension-specific mediation has already cleared the stored tag, for stores and AMOs.

The CRW bit (defined by Supervisor-Level ISA for Virtual Memory (RV64Y)) indicates whether reading or writing capabilities with the capability tag set to the virtual page is permitted. When the CRW bit is set, capabilities are written as usual, and capability reads are controlled by the CRG bit.

The capability tag bit of the stored capability is checked after it is potentially cleared due to lack of C-permission.

If the CRW bit is clear, the "no capability state", then the existing rules from Chapter 9 are followed:

  • When a capability load or AMO instruction is executed, the capability tag bit of the loaded capability is cleared before it is written to the destination register.

  • When a capability store or AMO instruction is executed and the capability tag bit of the capability being written is set, the implementation raises a CHERI Store/AMO Page Fault.

When the CRW bit is set, the "capability state", then the behavior of capability loads is controlled by CRG and the behavior of capability stores is controlled by CD.

When CRW is set, the CRG bit indicates the current generation of the virtual memory page with regards to the ongoing capability revocation cycle. The implementation raises CHERI Load Page Fault when a capability load or AMO instruction is executed and:

  • the authorizing capability grants C-permission,

  • the virtual page’s CRG bit does not equal sstatus.UCRG, and

  • the virtual page’s PTE.U is set.

When the Svucrglct extension is implemented, the CHERI Load Page Fault is raised when capability load or AMO instruction satisfies the conditions above and the capability read from memory has its capability tag set.

Svucrglct implies Svucrg.

When CRW is set, the CD bit indicates that a capability was stored to the virtual page since the last time the CD bit was cleared. When a capability store or AMO instruction is executed, the capability tag bit of the capability being written is set and the CD bit is clear, two schemes are permitted (also see Section 11.3):

  • The same behavior as when CRW is clear, allowing software interpretation of this state.

  • The implementation sets the CD bit. The PTE update behaves in the same way as the D bit update described by the Svadu extension.

When CRW, CD and CRG are all clear, the implementation is required to clear loaded tags and raise CHERI Store/AMO Page Fault when the stored capability tag is set.

Other CD and CRG combinations when CRW=0 are reserved for future extensions. The reserved PTE states behave as the CRW=0, CD=0, CRG=0, unless a future extension defines an alternative function.
Table 43. Summary of Load CRW and CRG behavior in the PTEs
PTE.CRW PTE.CD PTE.CRG PTE.U Load/AMO

0

0

0

X

Clear loaded tag

0

0

1

X

Reserved

0

1

X

X

Reserved

1

X

≠ sstatus.UCRG

1

CHERI Load Page Fault, or CHERI Load Page Fault if tag is set for Svucrglct1

1

X

= sstatus.UCRG

1

Normal operation

1

X

X

0

Normal operation2

1 The choice here is whether to take data dependent exceptions on load data for loads or atomic operations. The default is to take the trap without checking the value of the loaded capability tag. Taking a trap when the capability tag is not set will introduce additional traps during revocation sweeps. If Svucrglct is implemented then the trap is only taken if the loaded capability tag is set, to reduce software overhead from revocation sweeps. Checking the loaded tag affects the exception priority, see Synchronous exception priority in decreasing priority order.

Svucrglct is an optimization for software, and as such implementations are allowed to conservatively fault under certain conditions even if the capability tag is not set.
Implementations which already take synchronous traps on loaded data, such as ECC faults, should implement Svucrglct instead of Svucrg.

Svucrglct implies Svucrg.

2 A future version of this specification may check an SCRG bit in sstatus for kernel revocation.

Table 44. Summary of Store CRW and CD behavior in the PTEs
PTE.CRW PTE.CD PTE.CRG Store/AMO

0

0

0

CHERI Store/AMO Page Fault if stored tag is set

0

1

X

Reserved

1

0

X

CHERI Store/AMO Page Fault if stored tag is set, or hardware CD update

1

1

X

Normal operation

11.3. Enabling Software or Hardware PTE updates

The decision about whether to take exceptions on capability stores with the capability tag set to a page with PTE.CRW=1 and PTE.CD=0 is determined by whether the Svade and Svadu extensions are enabled. These cause PTE Accessed and Dirty updates to be done in software, via the exception handler, or by a hardware mechanism respectively.

  • If only Svade is implemented, or enabled through henvcfg.ADUE or menvcfg.ADUE, then take a CHERI Store/AMO Page Fault.

  • If only Svadu is implemented, or enabled through henvcfg.ADUE or menvcfg.ADUE, then do the hardware update of setting PTE.CD=1 as described in Section 11.2.

11.4. Extending the Supervisor (sstatus) and Virtual Supervisor (vsstatus) Status Registers

The sstatus and vsstatus CSRs are extended to include the new Capability Read Generation (CRG) bit as shown.

When V=1 vsstatus.UCRG is in effect.

mstatus.UCRG also exists. Reading or writing it is equivalent to reading or writing sstatus.UCRG.

Diagram
Figure 43. Machine-mode status (mstatus) register for RV64Y
Diagram
Figure 44. Supervisor-mode status (sstatus) register when SXLEN=64
Diagram
Figure 45. Virtual Supervisor-mode status (vsstatus) register when VSXLEN=64

12. Integrating RVY and Zyhybrid with the "H" Extension

This chapter will appear in the priv spec. Exact location TBD.

The RISC-V hypervisor (H) extension virtualizes the supervisor-level architecture to support the efficient hosting of guest operating systems atop a type-1 or type-2 hypervisor (RISC-V, 2023).

The hypervisor extension is generally orthogonal to CHERI; the main requirements, when integrating with RVY and Zyhybrid, is that address CSRs added for hypervisors are extended to YLEN size. The remainder of this chapter describes these changes in detail.

12.1. Hypervisor Status Register (hstatus)

The hstatus register operates as described above except for the VSXL field that controls the value of XLEN for VS-mode (known as VSXLEN).

The encoding of the VSXL field is the same as the MXL field of misa. Only 1 and 2 are supported values for VSXL. When the implementation supports RVY (but not Zyhybrid), then hstatus's VSXL must be read-only as described in mstatus for mstatus.SXL. When the implementation supports both RVY and Zyhybrid, then VSXL behaves as described in mstatus for mstatus.SXL.

The VSBE field determines controls the endianness of explicit memory accesses from VS-mode and implicit memory accesses to VS-level memory management data structures. VSBE=0 indicates little endian and VSBE=1 is big endian. VSBE must be read-only and equal to MBE when the implementation only supports RVY. VSBE is optionally writable when Zyhybrid is also supported.

12.2. Hypervisor Environment Configuration Register (henvcfg)

The henvcfg(RVY) register operates as described in the RISC-V Privileged Specification. A new enable bit is added to henvcfg(RVY) when the implementation supports Zyhybrid as shown in Figure 46.

Diagram
Figure 46. Hypervisor environment configuration register (henvcfg)

The Y bit controls whether explicit access to CHERI registers is permitted when V=1. When henvcfg(RVY).Y=1 and menvcfg.Y=1 and misa.Y=1, CHERI can be enabled by VS-mode and VU-mode. When henvcfg(RVY).Y=0, CHERI is disabled in VS-mode and VU-mode as described in Chapter 8.

The reset value is 0.

12.3. Hypervisor Exception Delegation Register (hedeleg)

Bits 32,33,34,35,36 of hedeleg refer to a valid CHERI exceptions and so can be used to delegate CHERI exceptions to supervisor mode.

12.4. Virtual Supervisor Status Register (vsstatus)

The vsstatus register operates as described above except for the UXL field that controls the value of XLEN for VU-mode.

The encoding of the UXL field is the same as the MXL field of misa. Only 1 and 2 are supported values for UXL. When the implementation supports RVY (but not Zyhybrid), then vsstatus.UXL must be read-only as described in mstatus for mstatus.UXL. When the implementation supports both RVY and Zyhybrid, then UXL behaves as described in mstatus for mstatus.UXL.

12.5. Virtual Supervisor Trap Vector Base Address Capability Register (vstvec)

The vstvec register is extended to hold a capability. Its reset value is a Root Executable capability.

Diagram
Figure 47. Virtual supervisor trap vector base address capability register

The handling of vstvec (RVY) is otherwise identical to mtvec (RVY), but in virtual supervisor mode.

12.6. Virtual Supervisor Scratch Register (vsscratch)

The vsscratch register is extended to hold a capability.

At the start of the S-mode execution environment, the value of the capability tag of this CSR is zero and the values of the metadata and address fields are UNSPECIFIED.

It is not WARL, all capability fields must be implemented.

Diagram
Figure 48. Virtual supervisor scratch capability register

12.7. Virtual Supervisor Exception Program Counter Capability (vsepc)

The vsepc register is extended to hold a capability. Its reset value is a Root Executable capability.

As shown in Table 66, vsepc (RVY) is a code capability, so it does not need to be able to hold all possible invalid addresses (see Invalid address conversion). Additionally, the capability in vsepc (RVY) is unsealed when it is written to pc on execution of an SRET (RVY) instruction when V=1. The handling of vsepc (RVY) is otherwise identical to mepc (RVY), but in VS-mode.

Diagram
Figure 49. Virtual supervisor exception program counter capability

12.8. Virtual Supervisor Trap Value Register (vstval)

The vstval register is a VSXLEN-bit read-write register.

vstval is updated following the same rules as mtval for CHERI exceptions and CHERI page faults which are delegated to VS-mode.

Diagram
Figure 50. Virtual supervisor trap value register

12.9. Virtual Supervisor Thread Identifier Capability (vstidc)

The vstidc register is used to identify the current software thread in virtual supervisor mode. It is used to identify the current software thread in As other Virtual Supervisor registers when V=1, vstidc substitutes for stidc, so that instructions that normally read or modify stidc actually access vstidc instead. When V=0, vstidc does not directly affect the behavior of the machine. On reset the capability tag of vstidc will be set to 0 and the remainder of the data is UNSPECIFIED.

Diagram
Figure 51. Virtual supervisor thread identifier capability register

12.10. Virtual Supervisor CHERI Capability Encoding (vsycfg)

The vsycfg register is used to identify which CHERI capability encoding is used by the platform. The capability encoding both determines the in-memory representation of a CHERI capability and entails a set of extensions present atop RVY. The CSR exists in the writable namespace and all bits are defined to be WARL, but, absent any future extensions, it is expected that each implementation has exactly one legal value. For the meaning of the individual fields, refer to the uycfg register in the unprivileged specification.

Diagram
Figure 52. Virtual Supervisor CHERI capability encoding CSR (vsycfg) format

12.11. "Smstateen/Ssstateen" Integration

The new TID bit controls access to the vstidc CSR.

Diagram
Figure 53. Hypervisor State Enable 0 Register (hstateen0)

12.12. Hypervisor Load and Store Instructions For Capability Data

Hypervisor virtual-machine load (HLV.Y) and store (HSV.Y) instructions read or write YLEN bits from memory as though V=1. These instructions change behavior depending on the CHERI execution mode although the instruction’s encoding remains unchanged.

When in (CHERI) Capability Mode, the hypervisor load and store capability instructions behave as described in Section 2.12. In (Non-CHERI) Address Mode, the instructions use the low XLEN bits of the base register as the effective address for the memory access and the capability authorizing the memory access is ddc.

12.12.1. HLV.Y

Synopsis

Hypervisor virtual-machine load capability

Mnemonic

hlv.y rd, rs1

Encoding
Diagram
Any instance of this instruction with a rs1=x0 will raise an exception, as x0 is defined to always hold a NULL capability. As such, the encodings with a rs1=x0 are RESERVED for use by future extensions.
Description

Execute LY as though V=1, following the same pattern as HLV.W but with capability data.

Prerequisites

RVY, H

Operation

TBD

12.12.2. HSV.Y

Synopsis

Hypervisor virtual-machine store capability

Mnemonic

hsv.y rs2, rs1

Encoding
Diagram
Any instance of this instruction with a rs1=x0 will raise an exception, as x0 is defined to always hold a NULL capability. As such, the encodings with a rs1=x0 are RESERVED for use by future extensions.
Description

Execute SY as though V=1; following the same pattern as HSV.W but with capability data.

Prerequisites for (CHERI) Capability Mode

RVY, H

Operation

TBD

Appendix B: RVY ISA Extension Summary

Appendix C: RVY Extensions Summary

An RVY core imports all instructions from RVI and adds new instructions for CHERI functionality. Additionally, some RVI instruction (as well as instructions defined in other extensions) have modified behavior. The following sections detail the list of added/modified instructions per extension.

C.1. RVY added instructions

Table 45. RVY added instructions
Mnemonic RV32Y RV64Y Function

LY

✔

✔

Load capability

SY

✔

✔

Store capability

ADDY

✔

✔

Capability pointer increment

ADDIY

✔

✔

Capability pointer increment by immediate

YADDRW

✔

✔

Write capability address

YTAGR

✔

✔

Read capability tag

YPERMR

✔

✔

Read capability permissions

YMV

✔

✔

Capability register copy

YPERMC

✔

✔

Clear capability permissions

SRLIY

✔

✔

Logical right shift of Y register

YHIR

✔

✔

Read capability metadata (pseudo)

PACKY

✔

✔

Pack Y register

YHIW

✔

✔

Write capability metadata and clear capability tag (pseudo)

SYEQ

✔

✔

Capability equality comparison including capability tag

YLT

✔

✔

Capability less than comparison including capability tag

YBLD

✔

✔

Build capability

YBNDSW

✔

✔

Write capability bounds

YBNDSWI

✔

✔

Write capability bounds by immediate

YBNDSRW

✔

✔

Write capability bounds, rounding up if required

YAMASK

✔

✔

Capability alignment mask

YBASER

✔

✔

Read capability base address

YLENR

✔

✔

Read capability length

YTYPER

✔

✔

Read capability type

C.2. RVI (RVY modified behavior)

The following RVI instructions have modified behavior due to adding CHERI functionality. In general, this is restricted to changing whether input/output operands read/write XLEN or YLEN bits.

Table 46. RVI (RVY modified behavior) instructions
Mnemonic RV32Y RV64Y Function

AUIPC (RVY)

✔

✔

Add upper immediate to pc

JAL (RVY)

✔

✔

Immediate offset jump, and link and seal to capability register

JALR (RVY)

✔

✔

Jump to capability register, and link and seal to capability register

C.3. Zicsr (RVY modified behavior)

The following RVI instructions have modified behavior due to adding CHERI functionality. In general, this is restricted to changing whether input/output operands read/write XLEN or YLEN bits.

Table 47. Zicsr (RVY modified behavior) instructions
Mnemonic RV32Y RV64Y Function

CSRRW (RVY)

✔

✔

CSR write

CSRRS (RVY)

✔

✔

CSR set

CSRRC (RVY)

✔

✔

CSR clear

CSRRWI (RVY)

✔

✔

CSR write (immediate form)

CSRRSI (RVY)

✔

✔

CSR set (immediate form)

CSRRCI (RVY)

✔

✔

CSR clear (immediate form)

C.4. Zys

Zys adds the sentry capability type.

Table 48. Zys instruction extension
Mnemonic RV32Y RV64Y Function

YSENTRY

✔

✔

Seal capability as a sentry

C.5. C (RVY added instructions)

An RVY core which supports C also supports C (RVY added instructions).

C (RVY added instructions) is incompatible with Zcf (RV32) and Zcd (RV64).

Table 49. C (RVY added instructions) instruction extension
Mnemonic RV32Y RV64Y Function

C.LYSP

✔

✔

Load capability stack pointer relative, 16-bit encoding

C.SYSP

✔

✔

Store capability stack pointer relative, 16-bit encoding

C.LY

✔

✔

Load capability, 16-bit encoding

C.SY

✔

✔

Store capability, 16-bit encoding

C.6. RV32 / RV32Y RVC load/store mapping summary

Table 50. 16-bit load/store instruction mapping in RV32I
Encoding Supported Extensions

[15:13]

[1:0]

Zca

Zcf

Zcd

Zcmp/ Zcmt

Zclsd

111

00

N/A

C.FSW

N/A

N/A

C.SD

011

00

N/A

C.FLW

N/A

N/A

C.LD

111

10

N/A

C.FSWSP

N/A

N/A

C.SDSP

011

10

N/A

C.FLWSP

N/A

N/A

C.LDSP

101

00

N/A

N/A

C.FSD

reserved

N/A

001

00

N/A

N/A

C.FLD

reserved

N/A

101

10

N/A

N/A

C.FSDSP

Zcmp/ Zcmt

N/A

001

10

N/A

N/A

C.FLDSP

reserved

N/A
Table 51. 16-bit load/store instruction mapping in RV32Y
Encoding Supported Extensions

[15:13]

[1:0]

Zca

Zcd

Zcmp/ Zcmt

111

00

C.SY

111

10

C.SYSP

011

10

C.LYSP

011

00

C.LY

101

00

N/A

C.FSD

reserved

001

00

N/A

C.FLD

reserved

101

10

N/A

C.FSDSP

Zcmp (RV32Y)/ Zcmt (RV32Y)

001

10

N/A

C.FLDSP

reserved
Zcf and Zclsd are incompatible with RV32Y.

C.7. RV64 / RV64Y RVC load/store mapping summary

Table 52. 16-bit load/store instruction mapping in RV64I
Encoding Supported Extensions

[15:13]

[1:0]

Zca

Zcd

Zcmp/ Zcmt

111

00

C.SD

N/A

N/A

011

00

C.LD

N/A

N/A

111

10

C.SDSP

N/A

N/A

011

10

C.LDSP

N/A

N/A

101

00

N/A

C.FSD

reserved

001

00

N/A

C.FLD

reserved

101

10

N/A

C.FSDSP

Zcmp/ Zcmt

001

10

N/A

C.FLDSP

reserved
Table 53. 16-bit load/store instruction mapping in RV64Y
Encoding Supported Extensions

[15:13]

[1:0]

Zca

111

00

C.SD

011

00

C.LD

111

10

C.SDSP

011

10

C.LDSP

101

00

C.SY

001

00

C.LY

101

10

C.SYSP

001

10

C.LYSP
Zcd, Zcmp and Zcmt are incompatible with RV64Y.

C.7.1. C.LY

see C.LYSP.

C.7.2. C.LYSP

Synopsis

Capability loads (C.LY, C.LYSP), 16-bit encodings

These instructions have different encodings for RV64 and RV32.
Mnemonics

c.ly rd', offset(rs1')
c.lysp rd', offset(sp)

Expansions

ly rd', offset(rs1')
ly rd', offset(sp)

Encoding
Diagram
Diagram
(CHERI) Capability Mode Description

Load capability instruction, authorized by the capability in rs1. Take a load address misaligned exception if not naturally aligned.

Exceptions

CHERI fault exception when one of the checks below fail (see CHERI Exception handling in the privileged specification for further details):

Kind Reason

CHERI Load Access Fault

Authorizing capability tag is set to 0.

CHERI Load Access Fault

Authorizing capability is sealed.

CHERI Load Access Fault

Authorizing capability does not grant the necessary permissions. Only R-permission is required.

CHERI Load Access Fault

At least one byte accessed is outside the authorizing capability bounds, or the bounds could not be decoded.

CHERI Load Access Fault

Authorizing capability failed any integrity check.
Prerequisites

C or Zca, RVY

Included in

C (RVY added instructions)

Operation (after expansion to 32-bit encodings)

See LY

C.7.3. C.SY

see C.SYSP.

C.7.4. C.SYSP

Synopsis

Capability stores (C.SY, C.SYSP), 16-bit encodings

These instructions have different encodings for RV64 and RV32.
Mnemonics

c.sy rs2', offset(rs1')
c.sysp rs2', offset(sp)

Expansions

sy rs2', offset(rs1')
sy rs2', offset(sp)

Encoding
Diagram
Diagram
(CHERI) Capability Mode Description

Store the YLEN-bit value in rs2' to memory. The capability in sp authorizes the operation. The effective address of the memory access is obtained by adding the address of sp to the zero-extended offset.

Capability Tag of the written capability value

The capability written to memory has the capability tag set to 0 if the capability tag of rs2' is 0 or if the authorizing capability (sp) does not grant C-permission.

Extensions may define further circumstances under which stored capabilities may have their capability tags cleared.

This instruction can propagate valid capabilities which fail integrity checks.

Exceptions

Store/AMO access fault exception when the effective address is not aligned to YLEN/8.

Store/AMO access fault if the stored capability tag is set to one and the PMA is CHERI Capability Tag Fault.

Kind Reason

CHERI Store/AMO Access Fault

Authorizing capability tag is set to 0.

CHERI Store/AMO Access Fault

Authorizing capability is sealed.

CHERI Store/AMO Access Fault

Authorizing capability does not grant the necessary permissions.

CHERI Store/AMO Access Fault

At least one byte accessed is outside the authorizing capability bounds, or the bounds could not be decoded.

CHERI Store/AMO Access Fault

Authorizing capability failed any integrity check.
Prerequisites

C or Zca, RVY

Included in

C (RVY added instructions)

Operation (after expansion to 32-bit encodings)

See SY

C.8. C (RVY modified behavior)

An RVY core which supports C also supports C (RVY modified behavior) which modifies the behavior of some instructions.

c.ymv is renamed from c.mv to avoid ambiguity in disassembly.
Table 54. C (RVY modified behavior) instruction extension
Mnemonic RV32Y RV64Y Function

C.ADDI16SP (RVY)

✔

✔

Stack pointer increment in blocks of 16, 16-bit encoding

C.ADDI4SPN (RVY)

✔

✔

Stack pointer increment in blocks of 4, 16-bit encoding

C.YMV

✔

✔

Capability register copy, 16-bit encoding

C.JALR (RVY)

✔

✔

Jump to capability register, and link and seal to capability register, 16-bit encoding

C.JR (RVY)

✔

✔

Jump to capability register, 16-bit encoding

C.8.1. C.ADDI16SP (RVY)

Synopsis

Stack pointer increment in blocks of 16, 16-bit encoding

Mnemonic

c.addi16sp nzimm

Expansion

addiy sp, sp, nzimm

Encoding
Diagram
For implementations that support Zyhybrid, the behavior of this instruction is CHERI Execution Mode dependent.
Description

Add the non-zero sign-extended 6-bit immediate to the value in the stack pointer (sp=x2), where the immediate is scaled to represent multiples of 16 in the range (-512,496).

Set sp.tag=0 if sp is sealed.

Set rd.tag=0 if the resulting capability cannot be represented exactly.

Set rd.tag=0 if sp fails any integrity checks.

Prerequisites

C or Zca, RVY

Included in

C (RVY modified behavior)

Operation
execute(CADDI(sp, sp, sign_extend(nzimm)))

C.8.2. C.ADDI4SPN (RVY)

Synopsis

Stack pointer increment in blocks of 4, 16-bit encoding

Mnemonic

c.addi4spn rd', nzuimm

Expansion

addiy rd', sp, nzuimm

Encoding
Diagram
For implementations that support Zyhybrid, the behavior of this instruction is CHERI Execution Mode dependent.
Description

Copy sp to rd'. Add a zero-extended non-zero immediate, scaled by 4, to rd'.address.

Set rd'.tag=0 if sp is sealed.

Set rd'.tag=0 if the resulting capability cannot be represented exactly.

Set rd'.tag=0 if sp 's bounds are malformed, or if any of the reserved fields are set.

Prerequisites

C or Zca, Zyhybrid

Included in

C (RVY modified behavior)

Operation
let cd = creg2reg_idx(cdc) in
execute(CADDI(cd, sp, zero_extend(nzuimm)))

C.8.3. C.YMV

Synopsis

Capability register copy, 16-bit encoding

Mnemonic

c.ymv rd, rs2

Expansion

ymv rd, rs2

Suggested assembly syntax

ymv rd, rs2

c.mv is remapped to copy YLEN-bit registers for RVY. The mnemonic is changed to avoid ambiguity about whether the copy is XLEN or YLEN-bits.
Encoding
Diagram
For implementations that support Zyhybrid, the behavior of this instruction is CHERI Execution Mode dependent.
Description

Capability register rd is replaced with the contents of rs2.

This instruction can propagate valid capabilities which fail integrity checks.

Prerequisites

C or Zca, RVY

Included in

C (RVY modified behavior)

Operation (after expansion to 32-bit encoding)

See YMV

C.8.4. C.JR (RVY)

Synopsis

Jump to capability register, 16-bit encoding

Mnemonic

c.jr rs1

Expansion

jalr x0, 0(rs1)

Encoding
Diagram
(CHERI) Capability Mode Description

See JALR (RVY) for execution of the expanded instruction as shown above. Note that the offset is zero in the expansion.

Prerequisites

C or Zca, RVY

Included in

C (RVY modified behavior)

Operation (after expansion to 32-bit encodings)

See JALR (RVY)

C.8.5. C.JAL (RV32Y)

Synopsis

Immediate offset jump, and link and seal to capability register, 16-bit encoding

Mnemonic (RV32Y)

c.jal x1, offset

Expansion (RV32Y)

jal x1, offset

Encoding (RV32Y)
Diagram
Description

Link the next linear pc to rd and seal. Jump to pc.address+offset.

Prerequisites

C or Zca, RVY

Included in

C (RVY modified behavior)

Operation (after expansion to 32-bit encodings)

See JAL (RVY)

C.8.6. C.JALR (RVY)

Synopsis

Jump to capability register, and link and seal to capability register, 16-bit encoding

Mnemonic

c.jalr x1, rs1

Expansion

jalr x1, 0(rs1)

Encoding
Diagram
Description

See JALR (RVY) for execution of the expanded instruction as shown above. Note that the offset is zero in the expansion.

Exceptions

See JALR (RVY)

Prerequisites

C or Zca, RVY

Included in

C (RVY modified behavior)

Operation (after expansion to 32-bit encodings)

See JALR (RVY)

C.9. Zalrsc (RVY added instructions)

Specifying RVY and Zalrsc adds atomic capability load and store instructions.

Table 55. Zalrsc (RVY added instructions) instruction extension
Mnemonic RV32Y RV64Y Function

LR.Y

✔

✔

Load Reserved capability

SC.Y

✔

✔

Store Conditional capability

C.9.1. LR.Y

Synopsis

Load Reserved capability

Mnemonic

lr.y rd, 0(rs1)

Encoding
Diagram
Any instance of this instruction with a rs1=x0 will raise an exception, as x0 is defined to always hold a NULL capability. As such, the encodings with a rs1=x0 are RESERVED for use by future extensions.
Description

Calculate the effective address of the memory access by adding rs1.address to the sign-extended 12-bit offset.

Authorize the memory access with the capability in rs1.

Load a naturally aligned YLEN-bit data value from memory.

If the PMA is CHERI Capability Tag then load the associated capability tag, otherwise set the capability tag to zero.

Set the reservation as for LR.W/D.

Use the YLEN-bit data and the capability tag to determine the value of rd as specified by the LY instruction.

This instruction can propagate valid capabilities which fail integrity checks.

Exceptions

All misaligned load reservations cause a load address misaligned exception to allow software emulation (if the Zam extension is supported), otherwise they take a load access fault exception.

CHERI fault exception when one of the checks below fail (see CHERI Exception handling in the privileged specification for further details):

Kind Reason

CHERI Load Access Fault

Authorizing capability tag is set to 0.

CHERI Load Access Fault

Authorizing capability is sealed.

CHERI Load Access Fault

Authorizing capability does not grant the necessary permissions. Only R-permission is required.

CHERI Load Access Fault

At least one byte accessed is outside the authorizing capability bounds, or the bounds could not be decoded.

CHERI Load Access Fault

Authorizing capability failed any integrity check.
Prerequisites

RVY, and A or Zalrsc

Included in

Zalrsc (RVY added instructions)

Operation
TBD

C.9.2. SC.Y

Synopsis

Store Conditional capability

Any instance of this instruction with a rs1=x0 will raise an exception, as x0 is defined to always hold a NULL capability. As such, the encodings with a rs1=x0 are RESERVED for use by future extensions.
Mnemonic

sc.y rd, rs2, 0(rs1)

Encoding
Diagram
Description

Calculate the effective address of the memory access by adding rs1.address to the sign-extended 12-bit offset.

Authorize the memory access with the capability in rs1.

Conditionally store, following the same rules as SC.W, a naturally aligned YLEN-bit data value in rs2 to memory and the associated capability tag in rs2.

Set rd to 1 for success or 0 for failure.

The written capability capability tag may be cleared following the same modification rules as SY.

This instruction can propagate valid capabilities which fail integrity checks.

Exceptions

Store/AMO access fault exception when the effective address is not aligned to YLEN/8.

Store/AMO access fault if the stored capability tag is set to one and the PMA is CHERI Capability Tag Fault.

Kind Reason

CHERI Store/AMO Access Fault

Authorizing capability tag is set to 0.

CHERI Store/AMO Access Fault

Authorizing capability is sealed.

CHERI Store/AMO Access Fault

Authorizing capability does not grant the necessary permissions.

CHERI Store/AMO Access Fault

At least one byte accessed is outside the authorizing capability bounds, or the bounds could not be decoded.

CHERI Store/AMO Access Fault

Authorizing capability failed any integrity check.
Prerequisites

RVY, and A or Zalrsc

Included in

Zalrsc (RVY added instructions)

Operation
TBD

C.10. Zaamo (RVY added instructions)

Specifying RVY and Zaamo gives Zaamo (RVY added instructions) functionality, which adds atomic capability swap.

Table 56. Zaamo (RVY added instructions) instruction extension
Mnemonic RV32Y RV64Y Function

AMOSWAP.Y

✔

✔

Atomic swap of capabilities

C.10.1. AMOSWAP.Y

Synopsis

Atomic swap of capabilities

Mnemonic

amoswap.y rd, rs2, 0(rs1)

Encoding
Diagram
Any instance of this instruction with a rs1=x0 will raise an exception, as x0 is defined to always hold a NULL capability. As such, the encodings with a rs1=x0 are RESERVED for use by future extensions.
Description

Atomic swap of capability type, authorized by the capability in rs1.

The operation is equivalent to an atomically executed sequence of:

ly rd, 0(rs1)

sy rs2, 0(rs1)

With the proviso that rd is only updated if no exceptions are raised.

Permissions

Requires R-permission and W-permission in the authorizing capability.

Requires all bytes of the access to be in capability bounds.

Exceptions

If the address is not naturally aligned raise a Store/AMO address misaligned exception or a Store/AMO access fault exception. See "Zaamo" for details on which one is raised.

CHERI data fault exceptions occur when the authorizing capability fails one of the checks listed below (see CHERI Exception handling in the privileged specification for further details):

Kind Reason

CHERI Store/AMO Access Fault

Authorizing capability tag is set to 0.

CHERI Store/AMO Access Fault

Authorizing capability is sealed.

CHERI Store/AMO Access Fault

Authorizing capability does not grant the necessary permissions. W-permission and R-permission are both required.

CHERI Store/AMO Access Fault

At least one byte accessed is outside the authorizing capability bounds, or the bounds could not be decoded.
Prerequisites

RVY, and A or Zaamo

Included in

Zaamo (RVY added instructions)

Operation

TODO

C.11. H Extension (RVY added instructions)

Specifying RVY and "H" gives H Extension (RVY added instructions) functionality, which adds virtualized capability load and store instructions.

While HLVX.* only requires execute permission in the PTE, the authorizing CHERI capability must grant R-permission.

Table 57. H Extension (RVY added instructions) instruction extension
Mnemonic RV32Y RV64Y Function

HLV.Y

✔

✔

Hypervisor virtual machine load capability

HSV.Y

✔

✔

Hypervisor virtual machine store capability

C.12. Zba (RVY added instructions)

Specifying RVY and Zba gives Zba (RVY added instructions) functionality, which adds more instructions.

Table 58. Zba (RVY added instructions) instruction extension
Mnemonic RV32Y RV64Y Function

SH1ADDY

✔

✔

shift and add, representability check

SH2ADDY

✔

✔

shift and add, representability check

SH3ADDY

✔

✔

shift and add, representability check

SH4ADDY (RV64Y)

✔

shift and add, representability check

SH1ADDY.UW (RV64Y)

✔

shift and add unsigned word, representability check

SH2ADDY.UW (RV64Y)

✔

shift and add unsigned word, representability check

SH3ADDY.UW (RV64Y)

✔

shift and add unsigned word, representability check

SH4ADDY.UW (RV64Y)

✔

shift and add unsigned word, representability check
There is no RVY equivalent for add.uw as only having the integer version is sufficient.

C.12.1. SH1ADDY

See SH4ADDY (RV64Y).

C.12.2. SH2ADDY

See SH4ADDY (RV64Y).

C.12.3. SH3ADDY

See SH4ADDY (RV64Y).

C.12.4. SH4ADDY (RV64Y)

Synopsis

Shift by n and add for address generation (SH1ADDY, SH2ADDY, SH3ADDY, SH4ADDY)

Mnemonics (RVY)

sh1addy rd, rs1, rs2
sh2addy rd, rs1, rs2
sh3addy rd, rs1, rs2

Mnemonics (RV64Y)

sh4addy rd, rs1, rs2

Encoding
Diagram
Description

Copy the capability in rs2 to rd.

Increment rd.address by rs1 shifted left by n bit positions.

Set rd.tag=0 if rs2 is sealed.

Set rd.tag=0 if the resulting capability cannot be represented exactly.

Set rd.tag=0 if rs2 fails any integrity checks.

Included in

Zba (RVY added instructions)

Operation
let rs1_val = X(rs1);
let cs2_val = C(cs2);
let shamt : range(0,3) = match op {
  RISCV_SH1ADD => 1,
  RISCV_SH2ADD => 2,
  RISCV_SH3ADD => 3,
};
let result = incCapAddrChecked(cs2_val, rs1_val << shamt);
C(cd) = result;
RETIRE_SUCCESS

C.12.5. SH1ADDY.UW (RV64Y)

See SH4ADDY.UW (RV64Y).

C.12.6. SH2ADDY.UW (RV64Y)

See SH4ADDY.UW (RV64Y).

C.12.7. SH3ADDY.UW (RV64Y)

See SH4ADDY.UW (RV64Y).

C.12.8. SH4ADDY.UW (RV64Y)

Synopsis

Shift by n and add unsigned words for address generation (SH1ADDY.UW, SH2ADDY.UW, SH3ADDY.UW, SH4ADDY.UW)

Mnemonics (RV64Y)

sh1addy.uw rd, rs1, rs2
sh2addy.uw rd, rs1, rs2
sh3addy.uw rd, rs1, rs2
sh4addy.uw rd, rs1, rs2

Encoding
Diagram
Description

Copy the capability in rs2 to rd.

Increment rd.address by the unsigned word rs1 shifted left by n bit positions.

Set rd.tag=0 if rs2 is sealed.

Set rd.tag=0 if the resulting capability cannot be represented exactly.

Set rd.tag=0 if rs2 fails any integrity checks.

Included in

Zba (RVY added instructions)

Operation
let rs1_val = X(rs1);
let cs2_val = C(cs2);
let shamt : range(0,3) = match op {
  RISCV_ADDUW    => 0,
  RISCV_SH1ADDUW => 1,
  RISCV_SH2ADDUW => 2,
  RISCV_SH3ADDUW => 3,
};
let result = incCapAddrChecked(cs2_val, zero_extend(rs1_val[31..0]) << shamt);
C(cd) = result;
RETIRE_SUCCESS

C.13. Zicbom (RVY modified behavior)

Specifying RVY and Zicbom gives Zicbom (RVY modified behavior) functionality, which extends the checking.

Table 59. Zicbom (RVY modified behavior) instruction extension
Mnemonic RV32Y RV64Y Function

CBO.INVAL (RVY)

✔

✔

Cache block invalidate (implemented as clean)

CBO.CLEAN (RVY)

✔

✔

Cache block clean

CBO.FLUSH (RVY)

✔

✔

Cache block flush

C.13.1. CBO.CLEAN (RVY)

Synopsis

Perform a clean operation on a cache block

Mnemonic

cbo.clean 0(rs1)

Encoding
Diagram
Description

A CBO.CLEAN instruction performs a clean operation on the cache block whose effective address is the base address specified in rs1. The authorizing capability for this operation is rs1.

Exceptions
Kind Reason

CHERI Store/AMO Access Fault

Authorizing capability tag is set to 0.

CHERI Store/AMO Access Fault

Authorizing capability is sealed.

CHERI Store/AMO Access Fault

Authorizing capability does not grant the necessary permissions. W-permission and R-permission are both required.

CHERI Store/AMO Access Fault

None of the bytes accessed are within the bounds, or the bounds could not be decoded.

CHERI Store/AMO Access Fault

Authorizing capability failed any integrity check.
Prerequisites

Zicbom, RVY

Included in

Zicbom (RVY modified behavior)

Operation
TBD

C.13.2. CBO.FLUSH (RVY)

Synopsis

Perform a flush operation on a cache block

Mnemonic

cbo.flush 0(rs1)

Encoding
Diagram
Description

A CBO.FLUSH instruction performs a flush operation on the cache block whose effective address is the base address specified in rs1. The authorizing capability for this operation is rs1.

Exceptions
Kind Reason

CHERI Store/AMO Access Fault

Authorizing capability tag is set to 0.

CHERI Store/AMO Access Fault

Authorizing capability is sealed.

CHERI Store/AMO Access Fault

Authorizing capability does not grant the necessary permissions. W-permission and R-permission are both required.

CHERI Store/AMO Access Fault

None of the bytes accessed are within the bounds, or the bounds could not be decoded.

CHERI Store/AMO Access Fault

Authorizing capability failed any integrity check.
Prerequisites

Zicbom, RVY

Included in

Zicbom (RVY modified behavior)

Operation
TBD

C.13.3. CBO.INVAL (RVY)

Synopsis

Perform an invalidate operation on a cache block

Mnemonic

cbo.inval 0(rs1)

Encoding
Diagram
Description

A CBO.INVAL instruction performs an invalidate operation on the cache block whose effective address is the base address specified in rs1. The authorizing capability for this instruction is rs1.

Exceptions
Kind Reason

Illegal instruction

pc does not grant ASR-permission.

CHERI Store/AMO Access Fault

Authorizing capability tag is set to 0.

CHERI Store/AMO Access Fault

Authorizing capability is sealed.

CHERI Store/AMO Access Fault

Authorizing capability does not grant the necessary permissions. W-permission, R-permission are both required.

CHERI Store/AMO Access Fault

At least one byte accessed is outside the authorizing capability bounds, or the bounds could not be decoded.

CHERI Store/AMO Access Fault

Authorizing capability failed any integrity check.

CSR state controls whether CBO.INVAL performs cache block flushes instead of invalidations for less privileged modes.

Invalidating a cache block can re-expose capabilities previously stored to it after the most recent flush, not just secret values. As such, CBO.INVAL has stricter checks on its use than CBO.FLUSH, and should only be made available to, and used by, sufficiently-trusted software.

Untrusted software should use CBO.FLUSH instead as a minimum, and a sensible implementation choice for CHERI systems is to always execute CBO.INVAL as CBO.FLUSH.
Prerequisites

Zicbom, RVY

Included in

Zicbom (RVY modified behavior)

Operation
TBD

C.14. Zicboz (RVY modified behavior)

Specifying RVY and Zicboz gives Zicboz (RVY modified behavior) functionality, which extends the checking.

Table 60. Zicboz (RVY modified behavior) instruction extension
Mnemonic RV32Y RV64Y Function

CBO.ZERO (RVY)

✔

✔

Cache block zero

C.14.1. CBO.ZERO (RVY)

Synopsis

Store zeros to the full set of bytes corresponding to a cache block

Mnemonic

cbo.zero 0(rs1)

Encoding
Diagram
Description

A cbo.zero instruction performs stores of zeros to the full set of bytes corresponding to the cache block whose effective address is the base address specified in rs1. An implementation may or may not update the entire set of bytes atomically although each individual write must atomically clear the capability tag bit of the corresponding aligned YLEN-bit location. The authorizing capability for this instruction is rs1.

Exceptions

Store/AMO access fault exception when the effective address is not aligned to YLEN/8.

Store/AMO access fault if the stored capability tag is set to one and the PMA is CHERI Capability Tag Fault.

Kind Reason

CHERI Store/AMO Access Fault

Authorizing capability tag is set to 0.

CHERI Store/AMO Access Fault

Authorizing capability is sealed.

CHERI Store/AMO Access Fault

Authorizing capability does not grant the necessary permissions.

CHERI Store/AMO Access Fault

At least one byte accessed is outside the authorizing capability bounds, or the bounds could not be decoded.

CHERI Store/AMO Access Fault

Authorizing capability failed any integrity check.
Prerequisites

Zicboz, RVY

Included in

Zicboz (RVY modified behavior)

Operation
TBD

C.15. Zicbop (RVY modified behavior)

Specifying RVY and Zicbop gives Zicbop (RVY modified behavior) functionality, which extends the checking.

Table 61. Zicbop (RVY modified behavior) instruction extension
Mnemonic RV32Y RV64Y Function

PREFETCH.R (RVY)

✔

✔

Prefetch instruction cache line, always valid

PREFETCH.W (RVY)

✔

✔

Prefetch read-only data cache line

PREFETCH.I (RVY)

✔

✔

Prefetch writable data cache line

C.15.1. PREFETCH.I (RVY)

Synopsis

Provide a HINT to hardware that a cache block is likely to be accessed by an instruction fetch in the near future

Mnemonic

prefetch.i offset(rs1)

Encoding
Diagram
Description

A PREFETCH.I instruction indicates to hardware that the cache block whose effective address is the sum of the base address specified in rs1 and the sign-extended offset encoded in imm[11:0], where imm[4:0] equals 0b00000, is likely to be accessed by an instruction fetch in the near future. The encoding is only valid if imm[4:0]=0. The authorizing capability for this operation is rs1. This instruction does not throw any exceptions. However, following the rules from Chapter 2, this instruction does not perform a prefetch if it is not authorized by rs1.

PREFETCH.I does not perform a memory access if one or more of the following conditions of the authorizing capability are met:

  • The capability tag is not set

  • The sealed bit is set

  • No bytes of the cache line requested is in bounds

  • X-permission is not set

  • Any integrity check fails

Prerequisites

Zicbop, RVY

Included in

Zicbop (RVY modified behavior)

Operation
TODO

C.15.2. PREFETCH.R (RVY)

Synopsis

Provide a HINT to hardware that a cache block is likely to be accessed by a data read in the near future

Mnemonic

prefetch.r offset(rs1)

Encoding
Diagram
Description

A PREFETCH.R instruction indicates to hardware that the cache block whose effective address is the sum of the base address specified in rs1 and the sign-extended offset encoded in imm[11:0], where imm[4:0] equals 0b00000, is likely to be accessed by a data read (i.e., load) in the near future. The encoding is only valid if imm[4:0]=0. The authorizing capability for this operation is rs1. This instruction does not throw any exceptions. However, following the rules from Chapter 2, this instruction does not perform a prefetch if it is not authorized by rs1.

PREFETCH.R does not perform a memory access if one or more of the following conditions of the authorizing capability are met:

  • The capability tag is not set

  • The sealed bit is set

  • No bytes of the cache line requested is in bounds

  • R-permission is not set

  • Any integrity check fails

Prerequisites

Zicbop, RVY

Included in

Zicbop (RVY modified behavior)

Operation
TODO

C.15.3. PREFETCH.W (RVY)

Synopsis

Provide a HINT to hardware that a cache block is likely to be accessed by a data write in the near future

Mnemonic

prefetch.w offset(rs1)

Encoding
Diagram
Description

A PREFETCH.W instruction indicates to hardware that the cache block whose effective address is the sum of the base address specified in rs1 and the sign-extended offset encoded in imm[11:0], where imm[4:0] equals 0b00000, is likely to be accessed by a data write (i.e., store) in the near future. The encoding is only valid if imm[4:0]=0. The authorizing capability for this operation is rs1. This instruction does not throw any exceptions. However, following the rules from Chapter 2, this instruction does not perform a prefetch if it is not authorized by rs1.

PREFETCH.W does not perform a memory access if one or more of the following conditions of the authorizing capability are met:

  • The capability tag is not set

  • The sealed bit is set

  • No bytes of the cache line requested is in bounds

  • W-permission is not set

  • Any integrity check fails

Prerequisites

Zicbop, RVY

Included in

Zicbop (RVY modified behavior)

Operation
TODO

C.16. Zyhybrid

An RVY core which supports Zyhybrid adds the instructions in Table 62.

Table 62. Zyhybrid instruction extension
Mnemonic RV32Y RV64Y Function

YMODEW

✔

✔

Set capability execution mode

YMODER

✔

✔

Read capability mode

YMODESWY

✔

✔

Switch execution to (CHERI) Capability Mode

YMODESWI

✔

✔

Switch execution to (Non-CHERI) Address Mode

C.JAL (RV32Y)

✔

Immediate offset jump, and link and seal to capability register, 16-bit encoding

Appendix D: Capability Width CSR Summary

Table 63. CSRs aliased and extended to capability width
YLEN CSR Alias Prerequisites

dpc (RVY)

dpc

Sdext

dscratch0 (RVY)

dscratch1

Sdext

dscratch1 (RVY)

dscratch1

Sdext

mtvec (RVY)

mtvec

M-mode

mscratch (RVY)

mscratch

M-mode

mepc (RVY)

mepc

M-mode

stvec (RVY)

stvec

S-mode

sscratch (RVY)

sscratch

S-mode

sepc (RVY)

sepc

S-mode

vstvec (RVY)

vstvec

H

vsscratch (RVY)

vsscratch

H

vsepc (RVY)

vsepc

H

jvt (RVY)

jvt

Zcmt
Table 64. Action taken on writing to extended CSRs
YLEN CSR Action on XLEN write Action on YLEN write

dpc (RVY)

Apply Invalid address conversion. Always update the CSR with YADDRW even if the address didn’t change.

Apply Invalid address conversion and update the CSR with the result if the address changed, direct write if address didn’t change

dscratch0 (RVY)

Update the CSR using YADDRW.

direct write

dscratch1 (RVY)

Update the CSR using YADDRW.

direct write

mtvec (RVY)

Apply Invalid address conversion. Always update the CSR with YADDRW even if the address didn’t change, including the MODE field in the address for simplicity. Vector range check * if vectored mode is programmed.

Apply Invalid address conversion. Always update the CSR with YADDRW even if the address didn’t change, including the MODE field in the address for simplicity. Vector range check * if vectored mode is programmed.

mscratch (RVY)

Update the CSR using YADDRW.

direct write

mepc (RVY)

Apply Invalid address conversion. Always update the CSR with YADDRW even if the address didn’t change.

Apply Invalid address conversion and update the CSR with the result if the address changed, direct write if address didn’t change

stvec (RVY)

Apply Invalid address conversion. Always update the CSR with YADDRW even if the address didn’t change, including the MODE field in the address for simplicity. Vector range check * if vectored mode is programmed.

Apply Invalid address conversion. Always update the CSR with YADDRW even if the address didn’t change, including the MODE field in the address for simplicity. Vector range check * if vectored mode is programmed.

sscratch (RVY)

Update the CSR using YADDRW.

direct write

sepc (RVY)

Apply Invalid address conversion. Always update the CSR with YADDRW even if the address didn’t change.

Apply Invalid address conversion and update the CSR with the result if the address changed, direct write if address didn’t change

vstvec (RVY)

Apply Invalid address conversion. Always update the CSR with YADDRW even if the address didn’t change, including the MODE field in the address for simplicity. Vector range check * if vectored mode is programmed.

Apply Invalid address conversion. Always update the CSR with YADDRW even if the address didn’t change, including the MODE field in the address for simplicity. Vector range check * if vectored mode is programmed.

vsscratch (RVY)

Update the CSR using YADDRW.

direct write

vsepc (RVY)

Apply Invalid address conversion. Always update the CSR with YADDRW even if the address didn’t change.

Apply Invalid address conversion and update the CSR with the result if the address changed, direct write if address didn’t change

jvt (RVY)

Apply Invalid address conversion. Always update the CSR with YADDRW even if the address didn’t change.

Apply Invalid address conversion and update the CSR with the result if the address changed, direct write if address didn’t change

* The vector range check is to ensure that vectored entry to the handler is within bounds of the capability written to xtvec. The check on writing must include the lowest (0 offset) and highest possible offset (e.g., 64 * MXLEN bits where HICAUSE=16).

XLEN bits of extended YLEN-wide CSRs are written when executing CSRRWI (RVY), CSRRC (RVY), CSRRS (RVY), CSRRCI (RVY) or CSRRSI (RVY) regardless of the CHERI execution mode. When using CSRRW (RVY), YLEN bits are written when the CHERI execution mode is (CHERI) Capability Mode and XLEN bits are written when the mode is (Non-CHERI) Address Mode; therefore, writing XLEN bits with CSRRW (RVY) is only possible when Zyhybrid is implemented.

Table 65. Action taken on writing to YLEN-wide CSRs
YLEN CSR Action on XLEN write Action on YLEN write

dddc

Apply Invalid address conversion. Always update the CSR with YADDRW even if the address didn’t change.

Apply Invalid address conversion and update the CSR with the result if the address changed, direct write if address didn’t change

ddc

Apply Invalid address conversion. Always update the CSR with YADDRW even if the address didn’t change.

Apply Invalid address conversion and update the CSR with the result if the address changed, direct write if address didn’t change

drootcsel

Ignore

Ignore

drootc

Ignore

Ignore

utidc

Update the CSR using YADDRW.

direct write

stidc

Update the CSR using YADDRW.

direct write

vstidc

Update the CSR using YADDRW.

direct write

mtidc

Update the CSR using YADDRW.

direct write

XLEN bits of YLEN-wide CSRs added in Zyhybrid are written when executing CSRRWI (RVY), CSRRC (RVY), CSRRS (RVY), CSRRCI (RVY) or CSRRSI (RVY) regardless of the CHERI execution mode. YLEN bits are always written when using CSRRW (RVY) regardless of the CHERI execution mode.

Implementations which allow misa.C to be writable need to legalize xepc on reading if the misa.C value has changed since the value was written as this can cause the read value of bit [1] to change state.
Table 66. YLEN-wide CSRs storing code pointers or data pointers
YLEN CSR Code Pointer Data Pointer Unseal On Execution

dpc (RVY)

✔

✔

mtvec (RVY)

✔

mepc (RVY)

✔

✔

stvec (RVY)

✔

sepc (RVY)

✔

✔

vstvec (RVY)

✔

vsepc (RVY)

✔

✔

jvt (RVY)

✔

dddc

✔

ddc

✔

Some CSRs store code pointers or data pointers as shown in Table 66. These are WARL CSRs that do not need to store full 64-bit addresses on RV64, and so need not be capable of holding all possible invalid addresses. Prior to writing an invalid address to these CSRs, the address must be converted to another invalid address that the CSR is capable of holding. CSRs that store fewer address bits are also subject to the invalid address check in Invalid address conversion on writing.

Table 67 shows all YLEN-wide CSRs.

Table 67. All YLEN-wide CSRs.
YLEN CSR Prerequisites Address Permissions Reset Value Description

dpc (RVY)

Sdext

0x7b1

DRW

tag=0, otherwise undefined

Debug Program Counter Capability

dscratch0 (RVY)

Sdext

0x7b2

DRW

tag=0, otherwise undefined

Debug Scratch Capability 0

dscratch1 (RVY)

Sdext

0x7b3

DRW

tag=0, otherwise undefined

Debug Scratch Capability 1

mtvec (RVY)

M-mode

0x305

MRW, ASR-permission

Root Executable

Machine Trap-Vector Base-Address Capability

mscratch (RVY)

M-mode

0x340

MRW, ASR-permission

tag=0, otherwise undefined

Machine Scratch Capability

mepc (RVY)

M-mode

0x341

MRW, ASR-permission

Root Executable

Machine Exception Program Counter Capability

stvec (RVY)

S-mode

0x105

SRW, ASR-permission

Root Executable

Supervisor Trap-Vector Base-Address Capability

sscratch (RVY)

S-mode

0x140

SRW, ASR-permission

tag=0, otherwise undefined

Supervisor Scratch Capability

sepc (RVY)

S-mode

0x141

SRW, ASR-permission

Root Executable

Supervisor Exception Program Counter Capability

vstvec (RVY)

H

0x205

HRW, ASR-permission

Root Executable

Virtual Supervisor Trap-Vector Base-Address Capability

vsscratch (RVY)

H

0x240

HRW, ASR-permission

tag=0, otherwise undefined

Virtual Supervisor Scratch Capability

vsepc (RVY)

H

0x241

HRW, ASR-permission

Root Executable

Virtual Supervisor Exception Program Counter Capability

jvt (RVY)

Zcmt

0x017

URW

tag=0, otherwise undefined

Jump Vector Table Capability

dddc

Zyhybrid, Sdext

0x7bc

DRW

tag=0, otherwise undefined

Debug Default Data Capability (saved/restored on debug mode entry/exit)

ddc

Zyhybrid

0x416

URW

Root Data

User Default Data Capability

drootcsel

Sdext

0x7ba

DRW

0

Multiplexing selector for drootc

drootc

Sdext

0x7bd

DRW

Root Executable

Source of authority in debug mode, writes are ignored

utidc

RVY

0x480

Read: U, Write: U, ASR-permission

tag=0, otherwise undefined

User thread ID

stidc

RVY

0x580

Read: S, Write: S, ASR-permission

tag=0, otherwise undefined

Supervisor thread ID

vstidc

RVY

0xA80

Read: VS, Write: VS, ASR-permission

tag=0, otherwise undefined

Virtual supervisor thread ID

mtidc

RVY

0x780

Read: M, Write: M, ASR-permission

tag=0, otherwise undefined

Machine thread ID

13. "Zcmp" and "Zcmt" Integration with RVY

13.1. "Zcmp" Standard Extension For Code-Size Reduction

The push (CM.PUSH (RV32Y)) and pop (CM.POP (RV32Y), CM.POPRET (RV32Y), CM.POPRETZ (RV32Y)) instructions are redefined in (CHERI) Capability Mode to save/restore capability data.

The double move instructions (CM.MVSA01 (RV32Y), CM.MVA01S (RV32Y)) are redefined in (CHERI) Capability Mode to move capability data between registers. The saved register mapping is as shown in Table 68.

Table 68. saved register mapping for Zcmp
saved register specifier xreg integer ABI CHERI ABI

0

x8

s0

s0

1

x9

s1

s1

2

x18

s2

s2

3

x19

s3

s3

4

x20

s4

s4

5

x21

s5

s5

6

x22

s6

s6

7

x23

s7

s7

13.1.1. CM.PUSH (RV32Y)

Synopsis

Create stack frame (CM.PUSH): store the return address register and 0 to 12 saved registers to the stack frame, optionally allocate additional stack space. 16-bit encoding.

Mnemonic

cm.push {creg_list}, -stack_adj

Encoding
Diagram
NOTE: For implementations that support Zyhybrid, the behavior of this instruction is CHERI Execution Mode dependent.

rlist values 0 to 3 are reserved for a future EABI variant

Description

Create stack frame, store capability registers as specified in creg_list using SY semantics.

Optionally allocate additional multiples of 16-byte stack space in sp.

All accesses are authorized against sp.

This encoding is not available in RV64Y, it is remapped to C.SYSP

If Zcherihybrid is implemented and the CHERI execution mode is (Non-CHERI) Address Mode then the table access is checked against pc bounds.

Prerequisites

C or Zca, RVY, Zcmp

Operation
TBD

13.1.2. CM.POP (RV32Y)

Synopsis

Destroy stack frame (CM.POP): load the return address register and 0 to 12 saved registers from the stack frame, deallocate the stack frame. 16-bit encodings.

Mnemonic

cm.pop {creg_list}, -stack_adj

Encoding
Diagram
rlist values 0 to 3 are reserved for a future EABI variant
For implementations that support Zyhybrid, the behavior of this instruction is CHERI Execution Mode dependent.
Description

Load capability registers as specified in creg_list using LY semantics.

Deallocate stack frame.

All accesses are authorized by sp.

This encoding is not available in RV64Y, it is remapped to C.SYSP

If Zcherihybrid is implemented and the CHERI execution mode is (Non-CHERI) Address Mode then the table access is checked against pc bounds.

Prerequisites

C or Zca, RVY, Zcmp

Operation
TBD

13.1.3. CM.POPRET (RV32Y)

Synopsis

Destroy stack frame (CM.POPRET): load the return address register and 0 to 12 saved registers from the stack frame, deallocate the stack frame. Return through the return address register. 16-bit encodings.

Mnemonic

cm.popret {creg_list}, -stack_adj

Encoding
Diagram
rlist values 0 to 3 are reserved for a future EABI variant
For implementations that support Zyhybrid, the behavior of this instruction is CHERI Execution Mode dependent.
Description

Load capability registers as specified in creg_list using LY semantics.

Deallocate stack frame.

Return by calling JALR (RVY) to cra.

All data accesses are authorized by sp.

The return destination is authorized by cra.

This encoding is not available in RV64Y, it is remapped to C.SYSP

If Zcherihybrid is implemented and the CHERI execution mode is (Non-CHERI) Address Mode then the table access is checked against pc bounds.

Prerequisites

C or Zca, RVY, Zcmp

Operation
TBD

13.1.4. CM.POPRETZ (RV32Y)

Synopsis

Destroy stack frame (CM.POPRETZ): load the return address register and register 0 to 12 saved registers from the stack frame, deallocate the stack frame. Move zero into argument register zero. Return through the return address register. 16-bit encoding.

Mnemonic

cm.popretz {creg_list}, -stack_adj

Encoding
Diagram
rlist values 0 to 3 are reserved for a future EABI variant
For implementations that support Zyhybrid, the behavior of this instruction is CHERI Execution Mode dependent.
Description

Load capability registers as specified in creg_list using LY semantics.

Deallocate stack frame.

Move zero into a0.

Return by calling JALR (RVY) to ra.

All data accesses are authorized by sp.

The return destination is authorized by ra.

This encoding is not available in RV64Y, it is remapped to C.SYSP

If Zcherihybrid is implemented and the CHERI execution mode is (Non-CHERI) Address Mode then the table access is checked against pc bounds.

Prerequisites

C or Zca, RVY, Zcmp for (CHERI) Capability Mode

Operation
TBD

13.1.5. CM.MVSA01 (RV32Y)

Synopsis

CM.MVSA01: Move argument registers 0 and 1 into two saved registers. 16-bit encoding.

Mnemonic

cm.mvsa01 c1s', c2s'

Encoding
Diagram
The encoding uses sreg number specifiers instead of xreg number specifiers to save encoding space. The saved register encoding is shown in Table 68.
For implementations that support Zyhybrid, the behavior of this instruction is CHERI Execution Mode dependent.
Description

Atomically move two saved capability registers s0-s7 into a0 and a1.

This encoding is not available in RV64Y, it is remapped to C.SYSP

If Zcherihybrid is implemented and the CHERI execution mode is (Non-CHERI) Address Mode then the table access is checked against pc bounds.

Prerequisites

C or Zca, RVY, Zcmp

Operation
TBD

13.1.6. CM.MVA01S (RV32Y)

Synopsis

Move two saved registers into argument registers 0 and 1. 16-bit encoding.

Mnemonic

cm.mva01s c1s', c2s'

Encoding
Diagram
The encoding uses sreg number specifiers instead of xreg number specifiers to save encoding space. The saved register encoding is shown in Table 68.
For implementations that support Zyhybrid, the behavior of this instruction is CHERI Execution Mode dependent.
Description

Atomically move two capability registers a0 and a1 into s0-s7.

This encoding is not available in RV64Y, it is remapped to C.SYSP

If Zcherihybrid is implemented and the CHERI execution mode is (Non-CHERI) Address Mode then the table access is checked against pc bounds.

Prerequisites

C or Zca, RVY, Zcmp

Operation
TBD

13.2. "Zcmt" Standard Extension For Code-Size Reduction

The table jump instructions (CM.JT (RV32Y), CM.JALT (RV32Y)) are not redefined in (CHERI) Capability Mode to have capabilities in the jump table. This is to prevent the code-size growth caused by doubling the size of the jump table.

In the future, new jump table modes or new encodings can be added to have capabilities in the jump table.

The jump vector table CSR jvt (RVY) is a full capability so that it can only be configured to point to accessible memory. All accesses to the jump table are checked against jvt (RVY) in (CHERI) Capability Mode, and against pc bounds in (Non-CHERI) Address Mode. This allows the jump table to be accessed when the pc bounds are set narrowly to the local function only in (CHERI) Capability Mode.

In (CHERI) Capability Mode the instruction fetch bounds check is authorized by two different capabilities - jvt (RVY) for the table access and pc for the CM.JALT (RV32Y)/CM.JT (RV32Y) instruction, and target instruction.
In (CHERI) Capability Mode the implementation doesn’t need to expand and bounds check against jvt (RVY) on every access, it is sufficient to decode the valid accessible range of entries after every write to jvt (RVY), and then check that the accessed entry is in that range.

13.2.1. Jump Vector Table CSR (jvt)

The Zcmt jvt CSR is extended to be a full capability.

Diagram
Figure 54. Jump Vector Table Capability register

All instruction fetches from the jump vector table are checked against jvt (RVY) in (CHERI) Capability Mode. In (Non-CHERI) Address Mode the address field gives the base address of the table, and the access is checked against pc bounds.

See CM.JALT (RV32Y), CM.JT (RV32Y).

If the access to the jump table succeeds, then the instructions execute as follows:

As a result the capability metadata is retained in pc during execution.

13.2.2. CM.JALT (RV32Y)

Synopsis

Jump via table with link (CM.JALT), 16-bit encodings

Mnemonic (RV32)

cm.jalt index

Encoding
Diagram
For this encoding to decode as CM.JALT (RV32Y), index≥32, otherwise it decodes as CM.JT (RV32Y).
For implementations that support Zyhybrid, the behavior of this instruction is CHERI Execution Mode dependent.
Description (RV32Y)

Redirect instruction fetch via the jump table defined by the indexing via jvt.address+ index*XLEN/8, checking every byte of the jump table access against jvt (RVY) bounds (not against pc) and requiring X-permission. Link to cra.

The target pc is calculated by replacing the current pc address with the value read from the jump table, and is updated using the semantics of the YADDRW instruction.

If the jvt (RVY) check fails, then clear the capability tag of the target pc.

This encoding is not available in RV64Y, it is remapped to C.SYSP

If Zcherihybrid is implemented and the CHERI execution mode is (Non-CHERI) Address Mode then the table access is checked against pc bounds.

Permissions (RV32Y)

Requires jvt (RVY) to have its capability tag set, not be sealed, have X-permission and for the full XLEN-wide table access to be in jvt (RVY) bounds.

Prerequisites for (RV32Y)

C or Zca, RVY, Zcmt

Operation
TBD

13.2.3. CM.JT (RV32Y)

Synopsis

Jump via table with link (CM.JT), 16-bit encodings

Mnemonic (RV32)

cm.jt index

Encoding
Diagram
For this encoding to decode as CM.JT (RV32Y), index<32, otherwise it decodes as CM.JALT (RV32Y).
For implementations that support Zyhybrid, the behavior of this instruction is CHERI Execution Mode dependent.
Description (RV32Y)

Redirect instruction fetch via the jump table defined by the indexing via jvt.address+ index*XLEN/8, checking every byte of the jump table access against jvt (RVY) bounds (not against pc) and requiring X-permission.

The target pc is calculated by replacing the current pc address with the value read from the jump table, and is updated using the semantics of the YADDRW instruction.

If the jvt (RVY) check fails, then clear the capability tag of the target pc.

This encoding is not available in RV64Y, it is remapped to C.SYSP

If Zcherihybrid is implemented and the CHERI execution mode is (Non-CHERI) Address Mode then the table access is checked against pc bounds.

Permissions (RV32Y)

Requires jvt (RVY) to have its capability tag set, not be sealed, have X-permission and for the full XLEN-wide table access to be in jvt (RVY) bounds.

Prerequisites for (RV32Y)

C or Zca, RVY, Zcmt

Operation
TBD

Appendix E: Control and Status Registers (CSRs) overview

Machine-Level ISA (RVY) and Supervisor-Level ISA (RVY) extend the CSRs listed in Table 69, Table 70, Table 71, Table 72 and Table 73 from the base RISC-V ISA and its extensions.

If Zyhybrid is supported then the CHERI Execution Mode determines whether YLEN or XLEN bits are returned (see CSRRW (RVY)).
Table 69. Extended debug-mode CSRs in RVY
RVY CSR Address Extended CSR Prerequisites Permissions Description

dpc (RVY)

0x7b1

dpc

Sdext

DRW

Debug Program Counter Capability

dscratch0 (RVY)

0x7b2

dscratch1

Sdext

DRW

Debug Scratch Capability 0

dscratch1 (RVY)

0x7b3

dscratch1

Sdext

DRW

Debug Scratch Capability 1
Table 70. Extended machine-mode CSRs in RVY
RVY CSR Address Extended CSR Prerequisites Permissions Description

mtvec (RVY)

0x305

mtvec

M-mode

MRW, ASR-permission

Machine Trap-Vector Base-Address Capability

mscratch (RVY)

0x340

mscratch

M-mode

MRW, ASR-permission

Machine Scratch Capability

mepc (RVY)

0x341

mepc

M-mode

MRW, ASR-permission

Machine Exception Program Counter Capability
Table 71. Extended supervisor-mode CSRs in RVY
RVY CSR Address Extended CSR Prerequisites Permissions Description

stvec (RVY)

0x105

stvec

S-mode

SRW, ASR-permission

Supervisor Trap-Vector Base-Address Capability

sscratch (RVY)

0x140

sscratch

S-mode

SRW, ASR-permission

Supervisor Scratch Capability

sepc (RVY)

0x141

sepc

S-mode

SRW, ASR-permission

Supervisor Exception Program Counter Capability
Table 72. Extended virtual supervisor-mode CSRs in RVY
RVY CSR Address Extended CSR Prerequisites Permissions Description

vstvec (RVY)

0x205

vstvec

H

HRW, ASR-permission

Virtual Supervisor Trap-Vector Base-Address Capability

vsscratch (RVY)

0x240

vsscratch

H

HRW, ASR-permission

Virtual Supervisor Scratch Capability

vsepc (RVY)

0x241

vsepc

H

HRW, ASR-permission

Virtual Supervisor Exception Program Counter Capability
Table 73. Extended user-mode CSRs in RVY
RVY CSR Address Extended CSR Prerequisites Permissions Description

jvt (RVY)

0x017

jvt

Zcmt

URW

Jump Vector Table Capability

Appendix F: CHERI System Implications

Unclear if this chapter will appear in the priv spec. May just be in the standalone spec.

CHERI processors need memory systems which support the capability tags in memory.

There are, or will soon be, a wide range of CHERI systems in existence from tiny IoT devices up to server chips.

There are two types of bus connections used in SoCs which contain CHERI CPUs:

  1. Tag-aware busses, where the bus protocol is extended to carry the capability tag along with the data. This is typically done using user defined bits in the protocol.

    1. These busses will read capability tags from memory (if capability tags are present in the target memory) and return them to the requestor.

    2. These busses will write the capability tag to memory as an extension of the data write.

  2. Non-capability tag aware busses, i.e., current non-CHERI aware busses.

    1. Reads of tagged memory will not read the capability tag.

    2. Writes to tagged memory will set the capability tag to zero of any YLEN-aligned YLEN-wide memory location where any byte matches the memory write.

The fundamental rule for any CHERI system is that the capability tag and data are always accessed atomically. For every naturally aligned YLEN-wide memory location, it must never be possible to:

  1. Update any data bytes without also writing the capability tag

    1. This implies setting the capability tag to zero if a non-CHERI aware bus master overwrites a capability in memory

  2. Read a capability tag value with mismatched (stale or newer) data

  3. Set the capability tag without also writing the data.

Clearing capability tags in memory does not necessarily require updating the associated data.

F.1. Small CHERI system example

small cheri system.drawio
Figure 55. Example small CHERI system with local capability tag storage

This example shows a minimum sized system where only the local memory is extended to support capability tags. The capability tag-aware region is highlighted. All capability tags are created by the CHERI CPU, and only stored locally. The memory is shared with the system, probably via a secure DMA, which is not capability tag aware.

Therefore the connection between CPU and memory is tag-aware, and the connection to the system is not capability tag aware.

All writes from the system port to the memory must clear any memory capability tags to follow the rules from above.

F.2. Large CHERI system example

large cheri system.drawio
Figure 56. Example large CHERI system with capability tag cache

In the case of a large CHERI SoC with caches, all the cached memory visible to the CHERI CPUs must support capability tags. All memory is backed up by DRAM, and standard DRAM does not offer the extra bit required for CHERI capability tag storage and so a typical system will have a capability tag cache IP.

A region of DRAM is typically reserved for CHERI capability tag storage.

The capability tag cache sits on the boundary of the capability tag-aware and non-tag-aware memory domains, and it provides the bridge between the two. It stores capability tags locally in its cache, and if there is a miss, it will create an extra bus request to access the region of DRAM reserved for capability tag storage. Therefore in the case of a miss a single access is split into two - one to access the data and one to access the capability tag.

The key property of the capability tag cache is to preserve the atomic access of data and capability tags in the memory system so that all CPUs have a consistent view of capability tags and data.

The region of DRAM reserved for capability tag storage must be only accessible by the capability tag cache, therefore no bus initiators should be able to write to the DRAM without the transactions passing through the capability tag cache.

Therefore the GPUs and peripherals cannot write to the capability tag storage in the DRAM, or the capability tagged memory data storage region. These constraints will be part of the design of the network-on-chip. It is possible for the GPU and peripherals to read the capability tagged memory data storage region of the DRAM, if required.

It would be possible to allow a DMA to access the capability tagged memory region of the DRAM directly to allow swap to/from DRAM and external devices such as flash. This will require the highest level of security in the SoC, as the CHERI protection model relies on the integrity of the capability tags, and so the root-of-trust will need to authenticate and encrypt the transfer, with anti-rollback protection.

For further information on the capability tag cache see (Efficient Tagged Memory, 2017).

F.3. Large CHERI pure-capability system example

large cheri purecap system.drawio
Figure 57. Example large CHERI system with only tag-aware bus masters

In this example every DRAM access passes through the capability tag cache, and so all bus masters are capability tag-aware and can access the capability tags associated with memory if permitted by the network-on-chip.

The system topology is simpler than in Figure 56.

There is likely to be a performance difference between the two systems. The main motivation for Figure 56 is to avoid the GPU DRAM traffic needing to look-up every capability tag in the capability tag cache, potentially adding overhead to every transaction.

Appendix G: Placeholder references to unprivileged spec

To allow building this document both as an extension to the RISC-V ISA documents and standalone, the following references point to the appropriate chapter in the (un)privileged specification:

RV32I

See Chapter RV32I Base Integer Instruction Set in (RISC-V, 2023).

RV32E and RV64E

See Chapter RV32E and RV64E Base Integer Instruction Sets in

General purpose registers

See Chapter RV32I Base Integer Instruction Set in (RISC-V, 2023).

Load and Store Instructions

See Chapter RV32I Base Integer Instruction Set in (RISC-V, 2023).

Integer Register-Immediate Instructions

See Chapter RV32I Base Integer Instruction Set in (RISC-V, 2023).

Control Transfer Instructions

See Chapter RV32I Base Integer Instruction Set in (RISC-V, 2023).

Atomics

See Chapter "A" Extension for Atomic Instructions in (RISC-V, 2023).

Zba

See Chapter "B" Extension for Bit Manipulation in (RISC-V, 2023).

Zicbom

See Chapter "CMO" Extensions for Base Cache Management Operation ISA in (RISC-V, 2023).

Zcmt

See Chapter "Zc*" Extension for Code Size Reduction in (RISC-V, 2023).

Zcmp

See Chapter "Zc*" Extension for Code Size Reduction in (RISC-V, 2023).

jvt

See Chapter "Zc*" Extension for Code Size Reduction in (RISC-V, 2023).

Zaamo

See Chapter "A" Extension for Atomic Instructions in (RISC-V, 2023).

"Zalrsc" for RVY

See Chapter "A" Extension for Atomic Instructions in (RISC-V, 2023).

"Zaamo" for RVY

See Chapter "A" Extension for Atomic Instructions in (RISC-V, 2023).

Appendix H: Placeholder references to privileged spec

This chapter only exists for the standalone document to allow references to resolve.
Control and Status Registers (CSRs) overview

See Chapter Control and Status Registers (CSRs) in (RISC-V, 2023).

Machine Status Registers (mstatus and mstatush)
Base ISA Control in mstatus Register
Endianness Control in mstatus and mstatush Registers

See mtatus in Chapter Machine-Level ISA, Version 1.13 in (RISC-V, 2023).

Machine Scratch Register (mscratch)

See mscratch in Chapter Machine-Level ISA, Version 1.13 in (RISC-V, 2023).

Diagram
Figure 58. Machine-mode scratch register
Machine Cause (mcause) Register
Synchronous exception priority in decreasing priority order
Machine cause (mcause) register values after trap

See mcause in Chapter Machine-Level ISA, Version 1.13 in (RISC-V, 2023).

Diagram
Figure 59. Machine Cause (mcause) register.
Machine Trap-Vector Base-Address (mtvec) Register

See mtvec in Chapter Machine-Level ISA, Version 1.13 in (RISC-V, 2023).

Diagram
Figure 60. Machine-mode trap-vector base-address register
Machine Exception Program Counter (mepc)

See mepc in Chapter Machine-Level ISA, Version 1.13 in (RISC-V, 2023).

Diagram
Figure 61. Machine exception program counter register
Machine Trap Delegation Register (medeleg)

See medeleg in Chapter Machine-Level ISA, Version 1.13 in (RISC-V, 2023).

Machine Trap Value Register (mtval)

See mtval in Chapter Machine-Level ISA, Version 1.13 in (RISC-V, 2023).

Diagram
Figure 62. Machine trap value register
Machine ISA (misa) Register

See misa in Chapter Machine-Level ISA, Version 1.13 in (RISC-V, 2023). RVY sets the Y bit to be 1, and also I or E are set to show how many X registers are present.

If Zyhybrid is implemented, then Y is writable.

Machine Environment Configuration (menvcfg) Register

See menvcfg in Chapter Machine-Level ISA, Version 1.13 in (RISC-V, 2023). Zyhybrid adds a new Y bit.

Diagram
Figure 63. Machine environment configuration register (menvcfg)
Trap-Return Instructions

See Trap-Return Instructions in Chapter Supervisor-Level ISA, Version 1.13 in (RISC-V, 2023).

Supervisor Trap Vector Base Address (stvec) Register

See stvec in Chapter Supervisor-Level ISA, Version 1.13 in (RISC-V, 2023).

Diagram
Figure 64. Supervisor trap vector base address (stvec) register.
Supervisor Scratch (sscratch) Register

See sscratch in Chapter Supervisor-Level ISA, Version 1.13 in (RISC-V, 2023).

Diagram
Figure 65. Supervisor-mode scratch register
Supervisor Exception Program Counter (sepc) Register

See sepc in Chapter Supervisor-Level ISA, Version 1.13 in (RISC-V, 2023).

Diagram
Figure 66. Supervisor exception program counter register
Supervisor Trap Value (stval) Register

See stval in Chapter Supervisor-Level ISA, Version 1.13 in (RISC-V, 2023).

Diagram
Figure 67. Supervisor trap value register
Supervisor Cause (scause) Register
.Supervisor cause (scause) register values after trap

See scause in Chapter Supervisor-Level ISA, Version 1.13 in (RISC-V, 2023).

Diagram
Figure 68. Supervisor Cause (scause) register.
Supervisor Environment Configuration (senvcfg) Register

See senvcfg in Chapter Supervisor-Level ISA, Version 1.13 in (RISC-V, 2023). Zyhybrid adds a new Y bit.

Diagram
Figure 69. Supervisor environment configuration register (senvcfg)
Supervisor Status (sstatus) Register

See sstatus in Chapter Supervisor-Level ISA, Version 1.13 in (RISC-V, 2023).

Virtual Supervisor Trap Vector Base Address (vstvec) Register

See vstvec in Chapter "H" Extension for Hypervisor Support in (RISC-V, 2023).

Diagram
Virtual Supervisor Scratch (vsscratch) Register

See vsscratch in Chapter "H" Extension for Hypervisor Support in (RISC-V, 2023).

Diagram
Figure 70. Virtual Supervisor-mode scratch register
Virtual Supervisor Exception Program Counter (sepc) Register

See vsepc in Chapter "H" Extension for Hypervisor Support in (RISC-V, 2023).

Diagram
Figure 71. Virtual Supervisor exception program counter register

Index

Bibliography

Efficient Tagged Memory. (2017). www.cl.cam.ac.uk/research/security/ctsrd/pdfs/201711-iccd2017-efficient-tags.pdf

RISC-V. (2023). RISC-V Privileged Specification. github.com/riscv/riscv-isa-manual/releases/download/riscv-isa-release-056b6ff-2023-10-02/priv-isa-asciidoc.pdf

RISC-V. (2023). RISC-V Unprivileged Specification. github.com/riscv/riscv-isa-manual/releases/download/riscv-isa-release-056b6ff-2023-10-02/unpriv-isa-asciidoc.pdf

Watson, R. N. M., Neumann, P. G., Woodruff, J., Roe, M., Almatary, H., Anderson, J., Baldwin, J., Barnes, G., Chisnall, D., Clarke, J., Davis, B., Eisen, L., Filardo, N. W., Fuchs, F. A., Grisenthwaite, R., Joannou, A., Laurie, B., Markettos, A. T., Moore, S. W., … Xia, H. (2023). Capability Hardware Enhanced RISC Instructions: CHERI Instruction-Set Architecture (Version 9) (UCAM-CL-TR-987; Issue UCAM-CL-TR-987). University of Cambridge, Computer Laboratory. doi.org/10.48456/tr-987

Woodruff, J., Joannou, A., Xia, H., Fox, A., Norton, R. M., Chisnall, D., Davis, B., Gudka, K., Filardo, N. W., Markettos, A. T., & others. (2019). Cheri concentrate: Practical compressed capabilities. IEEE Transactions on Computers, 68(10), 1455–1469. doi.org/10.1109/TC.2019.2914037