Watch
1
0
Fork
You've already forked ounce-core
0
mirror of synced 2026-11-16 22:36:14 +00:00
Clean-room Nintendo Switch 2 (Tegra T239 / Horizon OS FW 23.0.1) Emulator Engine in Pure Rust
  • Rust 79%
  • Python 12.6%
  • HTML 3.8%
  • Swift 2.6%
  • JavaScript 1%
  • Other 0.9%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-14 19:47:40 +00:00
.github verify: add Linux ARM64 ELF matrix runner and graduate run-elf to bounded-verified (#440) 2026-11-14 19:09:34 +00:00
assets Report This Problem: prefill every field the app knows 2026-11-12 19:26:09 +02:00
conformance feat(conformance): publish twelve measured ARM64 v0.2.0 cases 2026-11-13 17:38:58 +02:00
crates Fix Tier-4 u64::MAX sentinel collisions (#391) and add scalar NaN regression tests (#362) (#431) 2026-11-14 08:31:33 +02:00
docs docs(roadmap): add vetted 2026-2027 family and education roadmaps (#441) 2026-11-14 19:47:40 +00:00
licenses Report host verification failures and package macOS app releases 2026-11-11 13:58:18 +02:00
scripts verify: add Linux ARM64 ELF matrix runner and graduate run-elf to bounded-verified (#440) 2026-11-14 19:09:34 +00:00
site Rewrite README and site with AIDA; move detail to docs/DETAILS.md 2026-11-12 12:57:38 +02:00
src feat(cli): emit ounce.run.v1 JSON report via --report-json (#439) 2026-11-14 18:57:35 +00:00
tests feat(verify): support static AArch64 ELFs in diverge and fuzz ELF loader + decoder (#430) 2026-11-14 08:27:50 +02:00
tools Report This Problem: prefill every field the app knows 2026-11-12 19:26:09 +02:00
.gitattributes feat: package a versioned hardware conformance seed and adapter runner 2026-11-09 05:01:27 +00:00
.gitignore Fix stale launcher guidance and decode saved diagnosis dossiers 2026-11-11 10:43:37 +02:00
AGENTS.md docs: consolidate provenance register into single docs/PROVENANCE.md 2026-11-11 13:56:05 +02:00
build.rs Report This Problem: prefill every field the app knows 2026-11-12 19:26:09 +02:00
Cargo.lock chore(release): prepare v0.8.2 (#438) 2026-11-14 18:14:14 +00:00
Cargo.toml chore(release): prepare v0.8.2 (#438) 2026-11-14 18:14:14 +00:00
CHANGELOG.md Release 0.8.1: argument-overflow fix, headless no-audio, no prebuilt Mac app 2026-11-13 11:13:13 +02:00
CITATION.cff chore: citation file, release-note categories and a nightly fresh-seed fuzz (#312) 2026-11-10 08:52:20 +02:00
CLAUDE.md docs: add multi-agent setup (Claude, Codex, Antigravity) and Linux env script 2026-11-08 09:14:44 +00:00
CODE_OF_CONDUCT.md docs: contributor on-ramp (first contribution path, add-a-program guide, templates, security, conduct) 2026-11-08 15:08:27 +02:00
CONTRIBUTING.md Add contributor-friendly automation workflows and helpers 2026-11-12 14:35:07 +02:00
CREDITS.md docs: consolidate provenance register into single docs/PROVENANCE.md 2026-11-11 13:56:05 +02:00
GEMINI.md docs: add multi-agent setup (Claude, Codex, Antigravity) and Linux env script 2026-11-08 09:14:44 +00:00
LICENSE Merge origin/main into clean-room branch; add MIT license 2026-10-26 09:28:15 +00:00
PLAN.md wip: docs: E2 owner decision memo and E1 issue #190 finding 2026-11-11 10:44:34 +02:00
README.md docs: add community AArch64 verification and multi-opt guide (#437) 2026-11-14 17:07:28 +00:00
SECURITY.md docs: contributor on-ramp (first contribution path, add-a-program guide, templates, security, conduct) 2026-11-08 15:08:27 +02:00
THIRD_PARTY.md Fix runtime notice gaps and supersede stale provenance warnings 2026-11-08 09:28:54 +02:00
THIRD_PARTY_NOTICES.txt Normalize collected notice line endings 2026-11-08 06:45:48 +02:00

Does your code behave the same on ARM64?

Ounce-Core runs a program on three CPU engines and compares the output with real ARM64 hardware.

CI First-frame oracles MIT

Ounce-Core in 90 seconds: one program, three engines, one hardware reference. Click to watch the full video.

Watch the full 90-second video

Try it in your browser

What it is

You ship a library built on x86. Will it give the same answer on ARM64? You may not own an ARM64 machine to find out.

Ounce-Core runs the program and diffs its output byte for byte against a reference recorded on real ARM64 hardware. When the two differ, it helps you find where they split. It is open source and written in Rust. The vision explains the aim.

What it has done

  • It found real bugs. In one week of running unmodified open-source programs (LZ4, xxHash, SQLite, Lua) against an Apple Silicon Mac, it found a prefetch instruction that corrupted registers, two floating-point instructions with the wrong sign (so sin, cos and pow returned wrong values), and many missing vector instructions. All were fixed, each with a test.
  • It agrees with the hardware on real programs. LZ4, xxHash, SQLite 3.50.4, Lua 5.4.7, and heavily starred upstream C libraries (ibireme/yyjson, nothings/stb stb_truetype, facebook/zstd) give byte-identical output across Tier-3, Tier-4, and native execution. 27 Linux ARM64 programs across 59 multi-optimization-level matrix rows (-O1, -O2, -O3, -O3 -mcpu=apple_m1) pass with zero divergences (matrix report). The first-frame corpus of 50/50 outside programs passes its pixel checks, on the inputs those checks cover.
  • It is safe Rust. The runtime in src/ forbids unsafe code, and the compiler enforces it. The two small crates that need unsafe are kept apart, and CI checks the boundary.

Limit: this is a testing tool, not a fast emulator. It does not run arbitrary programs, instruction coverage is partial, and a match is evidence for the inputs tested, not proof (limits).

The Growing Family

The Ounce Project Family: Ounce-Core, Ounce-HB, Ounce-Runtime, and DeckStream

Built by curiosity. Tested by evidence. Powered by community.

Four independent, open-source projects sharing a development philosophy, an evidence-first discipline, and an active community:

Project What it is for When to choose it Licence Link
ounce-core (this repo) ARM64 execution and verification research engine. Runs programs across three CPU tiers and compares output with real hardware. You want evidence-first correctness, hardware differential checks, or the safe-Rust core. MIT You are here
ounce-hb Simplified homebrew runner built around Ounce-Core with diagnostics and exit codes. You want a turn-key CLI to run and diagnose homebrew with stable exit codes and plain-language failure explanations. MIT ounce-hb
ounce-runtime Experimental performance runtime with native JIT and GPU development. You want high performance, visual presentation via Metal/Vulkan/DX12, or controller input under GPL-3.0 terms. GPL-3.0-or-later ounce-runtime
deckstream Steam Deck NAS/WebDAV game launcher and streaming experimentation. You want an on-demand virtual filesystem for handheld Linux gaming PCs (SteamOS) with Gaming Mode integration. MIT deckstream

Independent siblings, clean boundaries. Each project solves a distinct problem with its own repository, tests, and releases. DeckStream is an independent sibling, not an Ounce-Core derivative; no code flows inappropriately across licensing boundaries (ounce-core, ounce-hb, and deckstream are MIT; ounce-runtime is GPL-3.0-or-later).

Try it

1. In your browser. Step through ARM64 code one instruction at a time in the playground. Nothing to install.

2. On your machine. You need Rust 1.85 or newer. On Debian or Ubuntu, first run sudo apt-get install -y libasound2-dev libudev-dev.

git clone https://github.com/hffgzktbcc-blip/ounce-core.git && cd ounce-core
cargo build --release
cargo run --release -- run tests/fixtures/nro/hello/hello.nro fixture

The last command runs a small test program and prints result=0x00000EEE. To check your own program against a host build, see Add a program or the Community Verification Guide. To find where a run first goes wrong, see the diagnosis guide.

3. Help out. Have an ARM64 Mac, Raspberry Pi or Linux VM? Run python3 scripts/verify_differential.py --json my-results.json and report it in issue #248. No ARM64 machine? Pick a no-code task or a good first issue. Read CONTRIBUTING.md before opening a pull request.

More

Ounce-Core is not affiliated with Nintendo or NVIDIA. It loads homebrew and synthetic programs only. The only source of this project is this repository, so build from source. Licensed under MIT.