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:

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

Similar to the general-purpose registers, the program counter (pc) is also extended to contain a capability or an integer.

The Capstone-RISC-V ISA adds the following registers:

TODO: talk about how to read/write those registers.

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: The valid field of the capability in rs1 is set to 0 (invalid).

The JMP and JNZ instructions allow jumping to a capability, i.e., setting the program counter to a given capability.

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

If no exception is raised: For JMP instruction, the program counter (pc) is set to the capability in rs1. If the capability is valid and executable, the next instruction will be fetched from its cursor field.

The behaviour of JNZ depends on the content of rs2:

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.

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

For RETURN, an exception is raised also when any of the following conditions are met:

If no exception is raised:

For CALL:

For RETURN when the content of rs1 is 0:

For RETURN when the content of rs1 is not 0:

TransCapstone-RISC-V is an extended version of Capstone-RISC-V which adds a pair of extra instructions CAPENTER and CAPEXIT 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 the worldswitched field of the sealed-return instruction is 1 (world switch involved). Attempting to use those instructions in the wrong world or with the wrong worldswitched field content will cause an exception. The behaviours of those instructions roughly correspond to the CALL and RETURN instructions respectively. The differences: