RISC-V Custom Code for VM Extensions

VM extensions in OpenVM are supported in the Rust frontend by inserting custom RISC-V machine code to be passed through LLVM into the RISC-V ELF using a standard 32-bit RISC-V encoding. This document specifies the custom machine code used for the default set of VM extensions. This custom code will be transpiled to OpenVM assembly using the modular transpiler specified here. The default VM extensions that support transpilation are:

• RV32IM: An extension supporting the 32-bit RISC-V ISA with multiplication.
• Keccak-256: An extension implementing the Keccak-256 hash function compatibly with RISC-V memory.
• SHA2-256: An extension implementing the SHA2-256 hash function compatibly with RISC-V memory.
• BigInt: An extension supporting 256-bit signed and unsigned integer arithmetic, including multiplication. This extension respects the RISC-V memory format.
• Algebra: An extension supporting modular arithmetic over arbitrary fields and their complex field extensions. This extension respects the RISC-V memory format.
• Elliptic curve: An extension for elliptic curve operations over Weierstrass curves, including addition and doubling. This can be used to implement multi-scalar multiplication and ECDSA scalar multiplication. This extension respects the RISC-V memory format.
• Pairing: An extension containing opcodes used to implement the optimal Ate pairing on the BN254 and BLS12-381 curves. This extension respects the RISC-V memory format.

Classification of Custom RISC-V Machine Code

We divide the types of custom RISC-V machine code associated with VM extensions into two categories:

• Intrinsic Instruction: the custom machine code is a single custom RISC-V instruction, compliant with the RISC-V specification.
• Kernel Code: the custom machine code is a 32-bit aligned binary sequence with bit length a multiple of 32. The machine code does not need to conform to any RISC-V ISA specification. Kernel code is used as a means to statically link foreign OpenVM assembly code into the ELF without a custom linker. Kernel code cannot be executed directly by a RISC-V machine without additional toolchain support from the transpiler.

Conventions for RISC-V Intrinsic Instructions

The RISC-V instruction format used for intrinsic instructions in OpenVM conforms to the convention for non-standard ISA extensions described in Chapters 34-35 of the RISC-V Instruction Set Manual Volume I: Unprivileged ISA (Version 20240411) to avoid collisions with existing RISC-V extensions. The format is specified as follows:

• Intrinsics are non-standard brownfield ISA extensions of the 30-bit encoding space of the base ISA.
• Intrinsics use custom-0 opcode[6:0] prefix 0001011 and custom-1 opcode[6:0] prefix 0101011. Intrinsics which do not require additional configuration parameters use custom-0, and ones which do (e.g., prime field arithmetic and elliptic curve arithmetic) use custom-1.
• We use funct3 as the top level distinguisher between opcode classes, and then funct7 (if R-type) or imm (if I-type or B-type) for more specific specification.

We now specify the custom instructions for the default set of VM extensions.

System Instructions

The terminate instruction is a requested trap that will cause an orderly termination to guest execution with the specified exit code.

RV32IM Extension

The RV32IM extension supports the RV32I Base Integer Instruction Set, Version 2.1 with XLEN=32 and the "M" Extension for Integer Multiplication and Division, Version 2.0 with XLEN=32, following the specification of the RISC-V Instruction Set Manual Volume I: Unprivileged ISA (Version 20240411).

Memory Alignment: Chapter 2.6 of loc. cit. specifies that the behavior of loads and stores whose effective addresses are not naturally aligned to the referenced datatype (i.e., the effective address is not divisible by the size of the access in bytes) depends on the execution environment interface (EEI). The OpenVM execution environment does not support misaligned loads and stores. More specifically, guest execution considers misaligned accesses invalid and host execution will raise an exception resulting in a fatal trap.

IO

In addition to the standard RV32IM opcodes, we support the following additional intrinsic instructions to handle interactions between the guest and host environments. These instructions require the host execution environment to maintain the following data structures as part of its state:

• input_stream: a non-interactive queue of byte vectors which is provided at the start of execution. This may be considered as the non-interactive input to the guest program.
• hint_stream: a queue of bytes populated during execution via instructions such as hintinput.
• user IO space: a fixed length array of bytes, with length num_public_values which is a configuration constant of the execution environment. The length must equal 8 times a power of two. The IO space can be overwritten, and the final state of the IO space is persisted after execution halts.

The guest execution has no control over what the host provides in input_stream and hint_stream, so the guest must take care to validate all data and account for behavior in cases of untrusted input.

nativestorew connects RV32 address space and native address space. We put it in RV32 extension because its implementation is here. But we use funct3 = 111 because the native extension has an available slot.

Keccak Extension

SHA2-256 Extension

BigInt Extension

We support a single branch instruction, beq256, which is B-type.

Native (Kernel) Extension

The following are not intrinsic instructions, but custom RISC-V instructions used to frame the insertion of custom kernel code. They are not meant to be used alone. See the transpiler for more details.

These use the custom-0 opcode prefix and funct3 = 0b111.

nativestorew also uses funct3 = 111. It's listed in the RV32 extension.

Algebra Extension

Modular arithmetic instructions depend on the modulus N. The ordered list of supported moduli should be saved in the .openvm section of the ELF file in the serialized format. This is achieved by the moduli_declare! macro; for example, the following code

moduli_declare! {
    Bls12381 { modulus = "0x1a0111ea397fe69a4b1ba7b6434bacd764774b84f38512bf6730d2a0f6b0f6241eabfffeb153ffffb9feffffffffaaab" },
    Bn254 { modulus = "21888242871839275222246405745257275088696311157297823662689037894645226208583" },
}

generates classes Bls12381 and Bn254 that represent the elements of the corresponding modular fields. Hexadecimal and decimal formats are supported.

Field Arithmetic

For each created modular class, one must call a corresponding setup_* function before using the intrinsics. For example, for the structs above this would be setup_0() and setup_1(). This function generates the setup intrinsics which are distinguished by the rs2 operand that specifies the chip this instruction is passed to. For developer convenience, in the Rust function bindings for these intrinsics, each modulus's setup_* function is automatically called on the first use of any of its intrinsics.

We use config.mod_idx(N) to denote the index of N in this list. In the list below, idx denotes config.mod_idx(N).

Note: The output for the first 4 instructions is not guaranteed to be less than N. See the ISA specification for more details.

Since funct7 is 7-bits, up to 16 moduli can be supported simultaneously. We use idx*8 to leave some room for future expansion.

Complex Extension Field Arithmetic

Complex extension field arithmetic over Fp2 depends on Fp where -1 is not a quadratic residue. The extension can be configured to support Fp2 arithmetic for a subset of the Fp with modular arithmetic enabled. We use the same config.mod_idx(Fp::MODULUS) to denote the index of Fp2 in this list. In the list below, idx denotes config.mod_idx(Fp::MODULUS).

Elliptic Curve Extension

The elliptic curve extension supports arithmetic over short Weierstrass curves, which requires specification of the elliptic curve C. The extension must be configured to support a fixed ordered list of supported curves. We use config.curve_idx(C) to denote the index of C in this list. In the list below, idx denotes config.curve_idx(C).

Since funct7 is 7-bits, up to 16 curves can be supported simultaneously. We use idx*8 to leave some room for future expansion.

Pairing Extension

Instructions for accelerating optimal Ate pairing depend on a pairing friendly elliptic curve C and associated Fp, Fp2, Fp12 and constant XI: Fp2. Presently only the curves BN254 and BLS12-381 are supported, with pairing_idx(Bn254) = 0 and pairing_idx(Bls12_381) = 1. In the list below, idx denotes pairing_idx(C).