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 an RV64IZicsr extension that makes the following types of changes to the base architecture:

In addition to Capstone, which is referred to as Pure Capstone in the Capstone-RISC-V ISA, we propose a variant of Capstone, called TransCapstone. While memory accesses and control flow transfers are only possible using capabilities in Pure Capstone, TransCapstone fuses capabilities with privilege levels and virtual memory found in traditional architectures, which allows for a smooth transition from existing architectures to Capstone.

The following types of changes are made to Pure Capstone to obtain TransCapstone:

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:

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 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.

In Pure Capstone, the memory can only be accessed through capabilities.

In TransCapstone, the physical memory is divided into two disjoint regions: the normal memory and the secure memory. While the normal memory is only accessible through MMU (Memory Management Unit), the secure memory can only be accessed through capabilities. The bounds of the secure memory [SBASE, SEND) are implementation-defined.

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

The manipulation constraints for each CCSR are indicated below.

The manipulation constraints for each additional CSR are indicated below.

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 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.

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

Some instructions affect the type field of a capability.

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).

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

In TransCapstone, the LDC and STC instructions are extended to support loading and storing capabilities from/to the normal memory using raw addresses.

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:

Pure Capstone

TransCapstone

If no exception is raised: Set pc to x[rs1], and pc.cursor to x[rs1].cursor + imm. Meanwhile, former pc (pc.cursor is the address of the next instruction) is written to x[rd].

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

Pure Capstone

TransCapstone

If no exception is raised: If x[rs1] is 0, the instruction is a no-op. Otherwise, set pc to x[rs1], and pc.cursor to x[rs1].cursor + imm.

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.

In RV64IZicsr, memory access instructions include load instructions (i.e., lb, lh, lw, lbu, lhu, lwu, ld), and store instructions (i.e., sb, sh, sw, sd). In RV64IZicsr, 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.

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.

Some instructions in RV64IZicsr now raise "illegal instruction (2)" exceptions when executed in Pure Capstone or TransCapstone secure world, under all or some circumstances.

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 RV64IZicsr, where applicable, for ease of implementation and interoperability.

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

For Pure Capstone and the secure world in TransCapstone, the exception-related data is stored in the tval CSR, similar to RV64IZicsr. The exception handler can use the value to decide how to handle the exception. However, such data is available only for in-domain exception handling, where the exception handling process does not involve a domain switch. For exception handling that crosses domain or world boundaries (i.e., when ceh is a sealed capability or when the normal world ends up handling the exception), the exception data is not available. This is to protect the confidentiality of domain execution. Note that this design does not stop the excepted domain from selectively trusting a different domain with such data.

For exceptions defined in RV64IZicsr, the same data as in it is written to tval. For the added exceptions, the following data is written to tval:

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 happens if any of the involved memory accesses fails

TransCapstone retains the same interrupt and exception handling mechanims for the normal world as in RV64IZicsr.

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 to 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.