- Rust 79%
- Python 12.6%
- HTML 3.8%
- Swift 2.6%
- JavaScript 1%
- Other 0.9%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .github | ||
| assets | ||
| conformance | ||
| crates | ||
| docs | ||
| licenses | ||
| scripts | ||
| site | ||
| src | ||
| tests | ||
| tools | ||
| .gitattributes | ||
| .gitignore | ||
| AGENTS.md | ||
| build.rs | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CHANGELOG.md | ||
| CITATION.cff | ||
| CLAUDE.md | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| CREDITS.md | ||
| GEMINI.md | ||
| LICENSE | ||
| PLAN.md | ||
| README.md | ||
| SECURITY.md | ||
| THIRD_PARTY.md | ||
| THIRD_PARTY_NOTICES.txt | ||
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.
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,cosandpowreturned 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/forbidsunsafecode, and the compiler enforces it. The two small crates that needunsafeare 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
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
- Details: subsystem status, how the proof works, test harness, full commands, roadmap, repository layout
- Reproduce the results and what they do not show
- Research paper and vision
- Mac app and interactive lab
- Sources, provenance and legal notice
- Came here for the Switch emulator? What changed and why
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.
