The Capstone-RISC-V Instruction Set Reference

The ultimate goal of Capstone is to unify the numerous hardware abstracts that have been added as extensions to existing architectures as afterthought mitigations to security vulnerabilities. This goal requires a high level of flexibility and extensibility of the Capstone architecture. More specifically, we aim to support the following in a unified manner.

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. Capstone extends the traditional capability model with new capability types including the following.

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

The Capstone-RISC-V ISA is a 64-bit RISC-V extension that makes the following types of changes to the base architecture:

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 design of Capstone has been discussed in the following paper:

Capstone currently supports two variants of the ISA, i.e., Pure Capstone and TransCapstone. While Pure Capstone is a pure capability-based ISA, TransCapstone is a hybrid ISA that supports both capabilities and traditional virtual memory. In TransCapstone, the memory is divided into two parts, i.e., the secure memory and the untrusted memory. The range of the secure memory is defined as [SBASE, SEND), where SBASE and SEND are required to be aligned to CLEN bits. These two variants share most of the parts of the ISA, and separate descriptions are provided for the parts that are different.

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 confusion of the type 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 Capstone-RISC-V ISA adds the following registers:

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 state registers (CCSRs). Under their respective constraints, CCSRs can be manipulated using CCSR manipulation instructions.

The manipulation constraints for each CCSR are indicated below.

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 Capstone-RISC-V instruction set is based on the RV64G 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 RV64G 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 two basic formats: R-type and I-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 instructions receive up to two register operands and a 12-bit-wide immediate operand.

Some instructions affect the type field of a capability.

TODO: check whether dropping is actually necessary.

The DROP instruction invalidates a capability.

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

If no exception is raised: x[rs1].valid is set to 0 (invalid).

Capstone offers a set of instructions for loading and storing integers of various sizes using capabilities.

In Capstone, two specific instructions (i.e., LDC and LTC) are used to load and store capabilities.

In TransCapstone, besides the LDC and STC instructions, two additional instructions (i.e., LDCR and STCR) are added to load and store capabilities from/to the normal memory using raw addresses. These 2 instructions are only available in TransCapstone and an exception will be raised if they are executed in Pure Capstone.

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.

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

If no exception is raised:

Domains in Capstone-RISC-V 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 TransCapstone, a pair of extra instructions, i.e., CAPENTER and CAPEXIT, is added to support switching between the secure world and the normal world. The CAPENTER instruction causes an entry into the secure world from the normal world, and the CAPEXIT instruction causes an exit from the secure world into the normal world.

The CAPENTER instruction can only be used in the normal world, whereas the CAPEXIT instruction can only be used in the secure world. In addition, the CAPEXIT instruction can only be used when an exit capability is provided. Attempting to use those instructions in the wrong world or without the required capability will cause an exception. The behaviours of these 2 instructions roughly correspond to the CALL and RETURN instructions respectively.

The CCSRRW instruction is used to read and write specified capability CSRs.

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

If no exception is raised:

In RISC-V, a set of instructions are used to control the flow of execution. These instructions include conditional branch instructions (i.e., beq, bne, blt, bge, bltu, and bgeu), and unconditional jump instructions (i.e., jal and jalr). In Capstone, adjustments are made to these instructions to support capability-aware execution.

The following adjustments are made to these instructions:

In RISC-V, memory access instructions include load instructions (i.e., lb, lh, lw, lbu, lhu, lwu, ld, and fld), and store instructions (i.e., sb, sh, sw, sd, and fsd). As the Capstone-RISC-V ISA extends each of the 32 general-purpose registers, instructions that take these registers as operands are also extended. These instructions (i.e., lb, lh, lw, lbu, lhu, lwu, ld, sb, sh, sw, and sd) take an integer as a raw address, and load or store a value from or to this address. In Capstone, adjustments are made to these instructions to support capability-aware memory access.

The following adjustments are made to these instructions:

The exception code is what the exception handler domain receives as an argument when an exception occurs on Pure Capstone or in TransCapstone secure world. It is an integer value that indicates what the type of the exception is. TransCapstone also has exit codes, which are the values returned to the CAPENTER instruction in case the exception cannot be handled in the secure world. We define the exception code and the exit code for each type of exception below. It aligns with the exception codes defined in RISC-V 64, where applicable, for ease of implementation and interoperability.

For Pure Capstone, the handling of interrupts and exceptions is relatively straightforward. Regardless of whether the event is an interrupt or an exception, or what the type of the interrupt or exception is, the processor core will always transfer the control flow to the corresponding handler domain (specified in the ceh register for exceptions and the cih register for interrupts). The current context is saved and sealed in a sealed-return capability which is then supplied to the exception handler domain as an argument. When exception handling is complete, the exception 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.

TODO: specify what "panics" means here

TODO: specify what happens if any of the involved memory accesses fails

TransCapstone retains the same interrupt and exception handling mechanims for the normal world as in RISC-V 64.

For the secure world in TransCapstone, the handling of interrupts and exceptions is more complex, and it becomes relevant whether the event is an interrupt or an exception.

For interrupts, in order to prevent denial-of-service attacks by the secure world, the processor core needs to transfer the control back to the normal world safely. The interrupt will be translated to one in the normal world that occurs at the CAPENTER instruction used to enter the secure world. Since interrupts are typically relevant only to the management of system resources, the interrupt should be transparent to both the secure world and the user process. In other words, the secure world will simply resume execution from where it was interrupted after the interrupt is handled by the normal-world OS.

For exceptions, we want to give the secure world the chance handle them first. If the secure world manages to handle the exception, the normal world will not be involved. The end result is that the whole exception or its handling is not even visible to the normal world. If the secure world fails to handle an exeption (i.e., when it would end up panicking in the case of Pure Capstone, such as when ceh is not a valid sealed capability), however, the normal world will take over. The exception will not be translated into an exception in the normal world, but instead indicated in the exit code that the CAPENTER instruction in the user process receives. The user process can then decide what to do based on the exit code (e.g., terminate the domain in the secure world).

Below we discuss the details of the handling of interrupts and exceptions generated in the secure world.

The instructions SETWORLD and ONPARTITION are related to world switching in TransCapstone.

The instructions load their operands from the register x[rs1], which expects an integer. SETWORLD directly sets the core to the specified world (0 for normal world and non-zero for secure world). The program counter will also be made into a capability or an integer correspondingly while retaining the cursor value. ONPARTITION switches on (non-zero) or off (0) the world partitioning checks in memory.

The instructions make it easy to set up the environment for testing either Pure Capstone or TransCapstone:

The instructions SETEH and ONNORMALEH affect the behaviours of interrupt and exception handling.

The SETEH instruction sets the secure-world exception handler domain (i.e., ceh) to the specified capability x[rs1]. The ONNORMALEH instruction checks x[rs1] and switches on (non-zero) or off (0) normal world handling of secure-world exceptions. When this is on, an exception that occurs in the secure world will trap to the normal world first before being handled by the secure-world exception handler (ceh), which is the expected behaviour in TransCapstone. When it is off, the exception will be directly handled by the secure-world exception handler, as is expected in Pure Capstone.