Crate rsemu 

rsemu — a multiplatform emulator built bottom-up on a generic framework.

The crate is organised as one always-compiled emulation core, with every other component behind its own Cargo feature. See ROADMAP.md for the architecture and CLAUDE.md for the rules this code is written under.

Status

Most of the phase-1 core exists: address spaces and regions (core::space), the oscillator forest and scheduler (core::clock, core::sched), wires (core::wire), the concurrency seam (core::sync), properties (core::props), snapshots (core::state), and the machine-description front end (machine).

The first CPU core is in: cpu::mos6502, a cycle-accurate 6502 interpreter behind the cpu-mos6502 feature (enable it to see cpu). With machine-nes, machine::catalog ships a NES that a real cartridge boots on: rsemu run nes-ntsc --cart smb.nes.

With machine-apple1, machine::catalog also ships an Apple 1 — a 6502, 4 KiB of RAM, an MC6821 and a 256-byte monitor ROM — which is the first machine a person can actually type at: rsemu run apple1. It reaches the terminal through host::chardev, the character-stream seam a 16550 will use next.

The picture comes out through host::display, the scanout seam: a device emits whatever the silicon does — the 2C02 emits a palette index, not a colour — and the host converts it, captures it as a PNG (display-png), or hands it to a canvas. web/ is the browser demo that does the last of those, from the demo feature.

The sound comes out through host::audio, which is the same seam again: a device emits what the silicon does — the RP2A03 emits an unsigned level out of a non-linear DAC pair at 894 886.36… Hz — and the host centres it, applies the console’s own RC network, resamples it to 44.1 or 48 kHz with an exact integer phase, and writes it to a .wav or hands it to WebAudio. Every float in that path is an amplitude, never a time, so a machine’s state hash does not depend on whether anybody is listening.

With gdb, host::gdb speaks the GDB remote serial protocol over TCP, so rsemu debug apple1 --gdb :1234 is a guest a debugger can step through.

With vnc, host::vnc speaks RFB (RFC 6143) over TCP, so rsemu run pc-at --vnc :5900 is a guest anybody with a viewer can watch and type at. What they type reaches the machine through host::input, at a virtual instant the scheduler chose rather than the one the network chose — which is what makes --record-input and --replay-input reproduce a session bit for bit.

With usermode, usermode is level-3 execution: a program runs with no guest kernel under it, its ecall leaves the core through core::exec, and something in Rust services it. rsemu supplies the machine half — the exit, a memory map with no devices in it, a scheduling contract for guest threads, and the record/replay funnel; the syscall kernel is a downstream crate’s (ROADMAP.md §2.1).

With jit, the translation runtime is in: a per-CPU software TLB, a block cache keyed on (guest PC, Block::key) with its exits patched straight to their successors, and a page filter that throws a translation away when the guest writes into the page it was lifted from — ROADMAP.md §9.1’s first three mechanisms, in front of the IR interpreter. See jit.

Not yet: a native window or a native sound card — both need either a GUI/audio dependency the policy forbids or a seventh unsafe subsystem the ceiling forbids; the JIT’s host code generators, so everything is still interpreted — the translation IR they lower from is under ir and the runtime they slot into is under jit; and the rest of the host layer (VNC, an interactive monitor console).

no_std

The emulation core is no_std + alloc. std is a default feature; building with --no-default-features must always work, and CI enforces it.

Re-exports

pub use crate::core::Error;

pub use crate::core::Result;

Modules

bus

Bus fabrics.

core

The emulation core: the generic machinery every machine is built from.

cpu

CPU cores.

dev

Device models.

floatfloat

Software IEEE-754 arithmetic — the floating-point unit every guest shares.

fwfw-pcbios

Firmware rsemu ships: guest programs, built by the host build.

host

The host-facing layer: where rsemu meets the machine it is running on (ROADMAP.md §3, §8).

irir

The architecture-neutral translation IR.

jitjit

The translation runtime: the software TLB, the block cache, block chaining and self-modifying-code detection.

machine

The machine description language (ROADMAP.md §5).

usermodeusermode

Level-3 execution: running a program with no guest kernel under it.

wasmwasm

WebAssembly entry points.

Constants

VERSION

The crate version, as reported by rsemu --version.

Functions

build_info

A short description of how this build was configured.