Crate qcode_emulator 

Concrete execution of the QCode IR.

This crate answers what does this IR compute: it evaluates QCode over a pre-lifted, immutable module against concrete machine state. It is the reference execution strategy — the one qcode_jit is differentially tested against, and the one qcode_vm builds a machine on top of.

Abstract over the domain

Execution is generic over the interpretation domain. DomainValue, DomainMemory and Interpreter describe what a value, a memory and an evaluator have to provide; concrete execution is one instantiation, and a symbolic or abstract one is another. StandaloneEmulator is the concrete implementation, built on SizedValue.

Fidelity

Floating point goes through rustc_apfloat rather than the host’s f64, including correctly rounded 80-bit x87 extended precision, and x87 arithmetic honours the guest’s control word for rounding mode and precision control. Results match hardware rather than whatever the host FPU happens to do.

Example

use qcode::{context::Context, qcode};
use qcode_emulator::StandaloneEmulator;

let mut ctx = Context::new();
qcode!(
    ctx,
    "
    <src>
        goto <dst @x=0x2>;
    <dst @x>
        %sum = i64 @x + 0x3;
        goto <0x1001>;
    "
);

let mut emu = StandaloneEmulator::new(src);
emu.step(&ctx).expect("the branch binds the block parameter");
emu.step(&ctx).expect("the destination uses it");

assert_eq!(emu.get_value(&ctx, sum.into()), Some(5));

To run a guest program — mapped memory, page permissions, faults delivered as values, code lifted on demand — see qcode_vm, which layers those on top of this crate.

Structs

CallSite

EmulatedMemory

Emulator

EmulatorError

SizedValue

StandaloneEmulator

A lifetime-free emulator that takes &Context<'_> explicitly on each call. Use this when you need to store an emulator without a lifetime (e.g., across an FFI boundary).

Enums

BodyArg

A positional argument to a map body for run_map_body: a scalar param value, or the field vector of an aggregate (tuple) param.

CallContinuation

CallInterception

EmulatorErrorKind

Traits

DomainMemory

DomainValue

A trait to describe a value This is used to abstract over different types of interpretations (symbolic, concrete, abstract, etc.)

EmulatorMemory

The byte-addressable memory an emulator run needs, over and above the value-domain reads and writes of DomainMemory.

Interpreter

Type Aliases

Result