Embive (Embedded RISC-V)

Embive is an interpreter/virtual-machine that leverages RISC-V bytecode, enabling sandboxed code execution on tiny devices (e.g. microcontrollers).

🛡️ Secure: No unsafe code, no panics on release builds.
📦 Embeddable: No standard library required.
⚡ Deterministic: No heap allocation required.

This library was inspired by WebAssembly and Q3VM: Allow compiled code to be dinamically loaded by a host application, while also restricting memory access and resource usage.

How It Works

Embive supports the RISC-V RV32IMAC instruction-set, making it compatible with many available languages and toolchains.

For better performance at the target device, Embive uses a two-stage execution model:

1. Transpilation (more info. here)
   Converts RISC-V ELF file to an optimized bytecode binary:
   • Reorder immediates
   • Expand compressed registers wherever possible
   • Simplify instruction matching
2. Interpretation
   Executes the bytecode using a register-based virtual machine with:
   • Memory isolation
   • Syscall and interruption support
   • Instruction limiting

The transpiled bytecode is stable and can be executed by any device running the Embive interpreter. As such, the transpilation can even be done ahead-of-time and by a different machine.

Languages

To target Embive, a language/toolchain must have the following pre-requisites:

• Support RISC-V 32-bit bare-metal targets
• Allow custom linking (text at 0x00000000 and data at 0x80000000)
• Output an ELF file (.elf)

Embive templates are available for the following languages:

• C/C++
• Nim
• Rust

Example

use core::num::NonZeroI32;
use embive::{
    interpreter::{
        memory::{Memory, SliceMemory, MemoryType},
        registers::CPURegister, Error,
        Interpreter, State, SYSCALL_ARGS,
    },
    transpiler::transpile_elf,
};

// RISC-V code to be transpiled and executed.
// The default code will execute the syscalls implemented
// bellow, loading values from RAM and adding them together.
// Check the available Embive templates for more info.
const ELF_FILE: &[u8] = include_bytes!(
    concat!(env!("CARGO_MANIFEST_DIR"), "/tests/app.elf")
);

// A simple syscall implementation
fn syscall<M: Memory>(
    nr: i32,
    args: &[i32; SYSCALL_ARGS],
    memory: &mut M,
) -> Result<Result<i32, NonZeroI32>, Error> {
    // Match the syscall number
    let ret = match nr {
        // Add two numbers (arg[0] + arg[1])
        1 => Ok(args[0] + args[1]),
        // Load from RAM (arg[0])
        2 => match i32::load(memory, args[0] as u32) {
            Ok(val) => Ok(val),
            Err(_) => Err(1.try_into().unwrap()), // Error loading
        },
        _ => Err(2.try_into().unwrap()), // Not implemented
    };

    // Outer Result is returned to the host (interpreter)
    // Inner result is returned to the guest code
    Ok(ret) // No host error
}

fn main() {
    // 16KB of code
    let mut code = [0; 16384];

    // Convert RISC-V ELF to Embive binary
    transpile_elf(ELF_FILE, &mut code).unwrap();

    // 4KB of RAM
    let mut ram = [0; 4096];

    // Create memory from code and RAM slices
    let mut memory = SliceMemory::new(&code, &mut ram);

    // Create interpreter with instruction limit
    let mut interpreter = Interpreter::new(&mut memory, 10);

    // Run the interpreter, handling all possible states
    loop {
        match interpreter.run().unwrap() {
            // Keep running after reaching instruction limit (10)
            State::Running => {},
            // Handle syscall if called by guest code (ECALL)
            State::Called => interpreter.syscall(&mut syscall).unwrap(),
            // Interrupt (passing value = 10) if guest is waiting (WFI)
            State::Waiting => interpreter.interrupt(10).unwrap(),
            // Stop if guest code exited (EBREAK)
            State::Halted => break,
        }
    }

    // Code does "10 + 20" using syscalls (load from ram and add numbers)
    // Check the result (Ok(30)) (Registers: A0 = 0, A1 = 30)
    assert_eq!(
        interpreter
            .registers
            .cpu
            .get(CPURegister::A0 as u8)
            .unwrap(),
        0
    );
    assert_eq!(
        interpreter
            .registers
            .cpu
            .get(CPURegister::A1 as u8)
            .unwrap(),
        30
    );
}

Instruction Limiting

In many cases, it is desirable to pause the guest after a number of instructions have been executed.

This can not only restrict the guest from using all the machine resources, but it also allows the host to execute other periodic tasks without relying on threading.

You can read more about instruction limiting in the interpreter::Engine::new documentation.

System Calls

System calls are a way for the interpreted code to interact with the host environment.

When an ecall instruction is executed, the interpreter will return the state Called and the host can then handle the syscall.

You can read more about system calls in the interpreter::Engine::syscall documentation.

Interrupts

Interrupts can be trigged on the guest code by the host. This is a complement to system calls, allowing asynchronous communication between the host and guest.

When a wfi instruction is executed, the interpreter will return the state Waiting, meaning that the guest has expressed that it is waiting for an interrupt to be triggered.

You can read more about interrupts in the interpreter::Engine::interrupt documentation.

Features

Supported RISC-V Extensions

What about Floating Point?

Rust doesn't support custom rounding modes nor does it expose the IEEE exception flags. Hence, fully implementing the RISC-V F and/or D extensions would require a soft-float library.

As at the time Embive was created no soft-float library satisfied my requirements (portable, safe, no_std, and complete), it was decided to not support the floating point extensions.

You can still use floats with Embive as the GCC/Clang compiler provides a soft-float implementation, but expect larger binaries and lower performance. In some cases, you can offload the floating computation to the host using syscalls.

Minimum supported Rust version (MSRV)

Embive default features are guaranteed to compile on stable Rust 1.81 and up.
Check the Features section for more information.

License

Embive is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.