cardinal-uxn 0.4.1

Uxn CPU interpreter
Documentation

Cardinal is a fork of Raven an independent re-implementation of the Uxn CPU and Varvara Ordinator.

The Uxn/Varvara ecosystem is a personal computing stack.

Cardinal is my personal stack for the Uxn/Varvara ecosystem.

For details on project origins, see Raven's project writeup.

The cardinal-uxn crate includes two implementations of the Uxn CPU:

  • The safe interpreter is a #[no_std] crate written in 100% safe Rust, with a single dependency (zerocopy). It is 10-20% faster than the reference implementation for CPU-heavy workloads (e.g. fib.tal, and mandelbrot.tal
  • The unsafe ("native") interpreter is written in aarch64 assembly (with Rust shims on either side), and runs 40-50% faster than the reference implementation

The native interpreter can be checked against the safe interpreter with fuzz testing:

cargo install cargo-fuzz # this only needs to be run once
cargo +nightly fuzz run --release fuzz-native

The Varvara implementation (cardinal-varvara) includes all peripherals, and has been tested on many of the flagship applications (Left, Orca, Noodle, Potato).

The repository includes two applications built on these libraries:

  • cardinal-cli is a command-line application to run console-based ROMs
  • cardinal-gui is a full-fledged GUI, which runs both as a native application and Raven on the web

The web demo is built with truck, e.g.

cargo install --locked trunk # this only needs to be run once
cd cardinal-gui
trunk build --release --public-url=/projects/cardinal/demo/ # edit this path

July 2025 Changes

  • stdout and stderr callbacks
  • feat(audio): support dynamic sample rate selection between 48000 and 44100 Hz
  • refactor(deps): update to the latest and greatest 7/25 for all dependencies!
  • feat(cardinal-gui): add cardinal-demo binary with hot reload, inject, and rom cycling; cardinal-orcas binary added, wip.
  • wasm notice: cardinal-gui supports wasm. the others do not. PRs welcome.

© 2024-2025 Matthew Keeter, David Horner Released under the Mozilla Public License 2.0

The repository includes ROMs compiled from the uxnemu reference implementation, which are © Devine Lu Linvega and released under the MIT license; see the roms/ subfolder for details.