The Capstone-RISC-V Instruction Set Reference

The ultimate goal of Capstone is to provide a unified architectural abstraction for multiple security goals. This goal requires Capstone to support the following properties.

The Capstone architecture design is based on the idea of capabilities, which are unforgeable tokens that represent authority to perform memory accesses and control flow transfers, among other operations. Capstone extends the basic capability model with new capability types including the following.

While Capstone does not assume any specific modern ISA, we choose to propose a Capstone variant to RISC-V due to its open nature and the availability of toolchains and simulators.

The Capstone-RISC-V ISA is an RV64IZicsr variant that makes the following types of changes to the base architecture:

This document describes a version of Capstone-RISC-V with the Caplifive extension, which enables Capstone to support guest machines with traditional access control abstractions. This is achieved through the idea of caplification: it allows exposing capability-backed physical memory regions to lower privilege levels through a modified PMP (Physical Memory Protection) structure which requires valid capabilities in its entries instead of arbitrary ranges and permissions.

Compared to vanilla Capstone-RISC-V, Capstone-RISC-V with Caplifive defines domain internal structures which can consist of privilege levels found in traditional architectures. The highest privilege level operates using capabilities in the same way as in vanilla Capstone-RISC-V, whereas lower privilege levels are exposed to an abstraction compatible with that on traditional architectures. In particular, Caplifive allows software in lower privilege levels to access memory using raw addresses and potentially through virtual memory, as long as the access is allowed according to the capabilities configured in the modified PMP structure. Note that such details are internal to each domain itself. Across domains, software interacts using capabilities in the same way as in vanilla Capstone-RISC-V.

The Caplifive extension additionally includes the following changes:

Each Capstone-RISC-V instruction is given a mnemonic prefixed with CS.. In contexts where it is clear we are discussing Capstone-RISC-V instructions, we will omit the CS. prefix for brevity.

In assembly code, the list of operands to an instruction is supplied following the instruction mnemonic, with the operands separated by commas, in the order of rd, rs1, rs2, imm for any operand the instruction expects.

When specifying the semantics of instructions, we use the following notations to represent the type of each operand:

The initial motivation, design, evaluation, and analysis of Capstone have been discussed in the following paper:

At any point in time, a hart operates in one of the following modes (mode ID in parentheses):

U-, S-, and M-modes already exist in the base RV64IZicsr ISA. When operating in those modes, the hart follows the same behaviours as defined in RV64IZicsr, e.g., using physical addresses for memory accesses in M-mode and virtual addresses for memory accesses if the virtual memory is enabled in S-mode and U-mode.

C-mode (capability mode) is an extra privilege level introduced in the Caplifive extension. It replaces M-mode when CAPSTONE_EN = 1 (CAPSTONE_EN is a single-bit hart-local state). When operating in C-mode, the hart is required to use capabilities for accessing the memory (including fetching instructions). C-mode exposes the same set of interfaces to S-mode and U-mode as M-mode does. For example, C-mode can handle undelegated interrupts and exceptions from S-mode and U-mode. Whether CAPSTONE_EN = 1 is therefore transparent to S-mode and U-mode, which can interact with C-mode in the same way as with M-mode.

When CAPSTONE_EN = 1, the run-time state of the system is organised in individual compartments called domains. Each domain includes the execution context of a logical thread. A hart at any point in time executes in exactly one domain.

When a domain is running on a hart, the following events are notable:

We call the first domain that runs on a hart after its reset the genesis domain of the hart.

The Capstone-RISC-V ISA extends each of the 32 general-purpose registers, so it contains either a capability or a raw XLEN-bit integer. The type of data contained in a register is maintained and type confusion is not allowed, except for x0/c0 as discussed below. In assembly code, the type of data expected in a register operand is indicated by the alias used for the register, as summarised in the following table.

x0/c0 is a read-only register that can be used both as an integer and as a capability, depending on the context. When used as an integer, it has the value 0. When used as a capability, it has the value { valid = 0, type = 0, cursor = 0, base = 0, end = 0, perms = 0 }. Any attempt to write to x0/c0 will be silently ignored (no exceptions are raised).

In this document, for i = 0, 1, …​, 31, we use x[i] to refer to the general-purpose register with index i.

The following M-mode CSRs are available in C-mode without any changes:

We also refer to the above CSRs using their aliases (with the m- prefix replaced c-) in the C-mode context.

The M-mode CSRs mtvec, mscratch, and mepc have their corresponding capability-extended replacements available in C-mode, as described in the following section.

The Capstone-RISC-V ISA adds the following registers. The +h sign indicates that the register is available in the hypervisor extension.

Some of the registers only allow capability values and have special semantics related to the system-wide machine state. They are referred to as capability control and status registers (CCSRs). Under their respective constraints, CCSRs can be manipulated using control and status instructions.

The manipulation constraints for each CCSR are indicated below.

Some of the registers are added as control and status registers (CSRs). These registers are manipulated by the same instructions that manipulate CSRs as in RV64IZicsr. When the manipulation constraints of these additional CSRs are not satisfied, the behaviour of these instructions follows the RV64IZicsr convention for other CSRs.

The manipulation constraints for each additional CSR are indicated below.

Each register has a scope that is either of the following:

Domain-scoped registers that can immediately affect the behaviours of a domain in C-mode include pc, ctvec, cscratch, mstatus, mideleg, medeleg, mip, mie. We call such registers C-effective registers.

Under certain circumstances, a set of registers need to be mapped to memory locations in an architecturally-defined layout. For example, some registers need to be saved or restored upon context switches. In such cases, unless otherwise specified, the layout for both domain-scoped registers and C-effective registers follows the following order without any padding:

The memory is addressed using an XLEN-bit integer at byte-level granularity.

In addition to raw integers, each CLEN-bit aligned address can also store a capability. The type of data contained in a memory location is maintained and confusion of the type is not allowed.

The physical memory can only be accessed through capabilities.

The Capstone-RISC-V instruction set is based on the RV64IZicsr instruction set. The (uncompressed) instructions are fixed 32-bit wide, and laid out in memory in little-endian order. In the encoding space of the RV64IZicsr instruction set, Capstone-RISC-V instructions occupies the “custom-2” subset, i.e., the opcode of all Capstone-RISC-V instructions is 0b1011011.

Capstone-RISC-V instruction encodings follow three basic formats: R-type, I-type and S-type, as described below (more details are also provided in the RISC-V ISA Manual).

R-type instructions receive up to three register operands, and I-type/S-type instructions receive up to two register operands and a 12-bit-wide immediate operand.

The Capstone-RISC-V ISA also uses a register operand of R-type as an immediate operand in some instructions, which is called register-immediate (RI) type for convenience in this document.

The RI-type instruction format is derived from the R-type instruction format. An RI-type instruction receives up to two register operands and a 5-bit-wide immediate operand.

Unless otherwise specified, the instructions introduced in Capstone-RISC-V on top of the base RV64IZicsr instruction set are available in C-mode only. Attempts to execute them in other modes trigger Illegal instruction (2) exceptions.

Upon reset, the system state must conform to the following specifications.

Some instructions can affect the type field of a capability directly. In general, the type field cannot be set arbitrarily. Instead, it is changed as the side effect of certain semantically significant operations.

The DROP instruction invalidates a capability.

An exception is raised when any of the following conditions is met:

If no exception is raised:

The LDC instruction loads a capability or an integer scalar from the memory depending on the type of data at the specified memory location.

An exception is raised when any of the following conditions is met:

If no exception is raised:

The STC instruction stores a capability or an integer scalar to the memory, depending on the type of data contained in the specified source register.

An exception is raised when any of the following conditions is met:

If no exception is raised:

The CJALR and CBNZ instructions allow jumping to a capability, i.e., setting the program counter to a given capability, in a unconditional or conditional manner.

Domains in the Capstone-RISC-V ISA are individual software compartments that are protected by a safe context switching mechanism, i.e., domain crossing. The mechanism is provided by the CALL and RETURN instructions.

In RV64IZicsr, memory access instructions include load instructions (i.e., lb, lh, ld, lw, lbu, lhu, lwu), and store instructions (i.e., sb, sh, sw, sd). These instructions take an integer as a raw address, and load or store a value from/to this address. In Capstone, these instructions are extended to take a capability as an address when executed in C-mode. In non-C modes, the behaviours of those instructions are unchanged.

In RV64IZicsr, conditional branch instructions (i.e., beq, bne, blt, bge, bltu, and bgeu), and unconditional jump instructions (i.e., jal and jalr) are used to control the flow of execution. In Capstone, these instructions are adjusted to support the situation where the program counter is a capability when executed in C-mode. In non-C modes, the behaviours of those instructions are unchanged.

C-mode can execute the following M-mode privileged instructions defined in Zicsr:

When a CSR that is available in M-mode but not available in C-mode is accessed in C-mode, an illegal instruction (2) exception is raised.

We extend RV64IZicsr with the following extra exception codes:

Those extra exception codes are only visible to C-mode. In other words, only C-mode software is allowed to handle those exceptions. They cannot be delegated to S-mode or U-mode.

For interrupts, the same encodings as in RV64IZicsr are used.

To provide the exception handler with extra exception-related information along with the exception code, Capstone-RISC-V follows the base RV64IZicsr and uses the CSRs xepc, xtval, xtval2, and xtinst. The only difference is that cepc will hold a capability if the excepting state has a capability pc as in the case of a horizontal trap in C-mode.

For exceptions defined in RV64IZicsr, the data written to those CSRs remain unchanged. The data provided for the added exception types defined above are as follows:

With CAPSTONE_EN = 0, the interrupt (H-interrupts only, as the notion of the V-interrupt does not apply here) and exception handling mechanisms are same as they are defined in RV64IZicsr.

With CAPSTONE_EN = 1, the handling of exceptions and V-interrupts uses the same mechanisms for exception and interrupt handling in RV64IZicsr, with the following minor changes:

The handling of H-interrupts with CAPSTONE_EN = 1 is new. The hart transfers the control flow to a dedicated H-interrupt handler domain (specified in cih). The current context is saved and sealed in a sealed-return capability which is then supplied to the H-interrupt handler domain as an argument. When handling is complete, the H-interrupt handler domain can use the RETURN instruction to resume the execution of the excepted domain. This process resembles that of a CALL-RETURN pair, except that it is asynchronous, rather than synchronous, to the execution of the original domain.

The cis CSR encodes the control and status associated with H-interrupts. The diagram below shows its layout.

The layout of cis follows that of mip in RV64IZicsr. When a bit is set, the corresponding H-interrupt is pending.

All the fields are read-write.

The cid CSR specifies types of H-interrupts to delegate as V-interrupts to the running domain. The layout of cid is identical to that of cis. When a bit is set in cid, the corresponding H-interrupt is not taken to the interrupt handling domain defined in cih, but handled within the currently running domain as a corresponding C-mode V-interrupt.

When the interrupt controller attempts to change the pending status of an interrupt line for a hart, either mip or cis is affected. Assuming the interrupt corresponds to bit x in mip and cis, the following is the criteria for deciding which of the two to operate on:

For example, if the interrupt controller wishes to clear the machine timer interrupt pending bit (MTIP) when CAPSTONE_EN = 1 and the MTIP bit in cid is set, the MTIP bit in mip will be cleared.

The H-interrupt delivery process starts with a certain event typically asynchronous to the execution of the hart. The sources of such events include the external interrupt controller, the timer, and other CPU cores, which correspond to the external, timer, and software H-interrupt types (i.e., x = E, T, and S). When such an event occurs, the xIP field in the cis register is set to 1 to indicate that the H-interrupt is pending.

At any point during the execution of a hart, if any xIP field is set and at the same time the cih register contains a capability, the H-interrupt is delivered to the H-interrupt handler domain.

The H-interrupt is ignored if any of the following conditions is met:

Otherwise: