vihaco / virtual ISA & machine framework

QuEra Computing · Rust · v0.1

vihaco

Rust 2024 License MIT Source github.com/QuEraComputing/vihaco
counter.rs
use eyre::Result;
use vihaco::{component, Effects, Execute, Execution, StepResult};

component! {
    component Counter {
        value: i64,
    }

    instruction {
        Add(i64),
        Read,
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Value(pub i64);

impl Execute<counter::instruction::Add> for counter::Counter {
    type Message = ();
    type Effect = ();
    type Fault = eyre::Report;

    fn execute(&mut self, instruction: &counter::instruction::Add, _: ()) -> Result<StepResult<()>> {
        self.value += instruction.0;
        Ok(StepResult { effects: Effects::none(), execution: Execution::Complete })
    }
}

impl Execute<counter::instruction::Read> for counter::Counter {
    type Message = ();
    type Effect = Value;
    type Fault = eyre::Report;

    fn execute(&mut self, _: &counter::instruction::Read, _: ()) -> Result<StepResult<Value>> {
        Ok(StepResult { effects: Effects::one(Value(self.value)), execution: Execution::Complete })
    }
}

A component is an execution unit: it takes a typed instruction plus a resolved message and returns typed effects. The derives handle opcodes, encoding, and the runtime glue.

i. Instruction sets

Bytecode as Rust enums

#[derive(Instruction)] turns an enum into an opcode set with inferred (or fixed) encoding width. Nest enums to compose several component instruction families under one machine type.

ii. Components & effects

Execute, then observe

Components consume a resolved Message and return typed Effects. Observers react to those effects with Observe, keeping execution and delivery cleanly separated.

iii. Pattern-derived syntax

From source text to module

#[derive(Parse)] generates a chumsky parser for your instruction syntax from declarative, compile-time-checked patterns. Module parsing produces typed function bodies for your resolver.

§Install

vihaco is a Cargo workspace of focused crates. vihaco is the foundation — add the others as your project needs them. There is no umbrella crate and no published release yet, so depend on the git repo:

[dependencies]
vihaco        = { git = "https://github.com/QuEraComputing/vihaco" }
vihaco-cpu    = { git = "https://github.com/QuEraComputing/vihaco" }  # optional: a ready-made CPU component
vihaco-parser = { git = "https://github.com/QuEraComputing/vihaco" }  # optional: #[derive(Parse)] for source text

Requires Rust edition 2024.

Continue to the Quick Start →

Continue to the Quick Start, work through the Guides, or browse the API Reference.