ounce-core is an experimental, non-commercial AArch64 execution and high-level service implementation research runtime written in Rust. It contains an interpreter, three execution tiers, a paged memory model, a subset of Horizon-style supervisor calls (SVCs) and services, software models of audio and input, and a graphics model whose output is drawn by a CPU rasterizer by default (an optional gpu-present build replays a subset of draw commands through wgpu). It is a test harness for studying these subsystems. It is a clean-room research runtime, not a tool for running commercial software, and makes no claim of compatibility with any commercial software.

• Safe Rust only: the crate is #![forbid(unsafe_code)], and grep -rnE "unsafe[ ({]" src returns no matches.
• Five runtime dependencies: byteorder, cpal (host audio playback), gilrs (gamepad input), minifb (host window), thiserror. The optional gpu-present feature adds wgpu, winit and pollster for GPU presentation.
• No network code, no telemetry. The only URL in the source is the project's own repository link in the CLI banner.

Most of the code, tests and documentation here are written by AI coding agents (Claude Code and Antigravity), directed and reviewed by the maintainer. Agent-made commits carry the agent as author or co-author. Every change must pass CI and the stage harness before it is merged. That harness checks programs written for this repository; it does not show that any other software works. Treat anything not covered by a test as unverified.

What this repository does not contain

• No firmware, system archives, or code or data derived from them.
• No encryption keys. The loader decrypts only containers built with the in-repo synthetic test key; retail keys are rejected (LoadError::RestrictedCipher). A prod.keys-format parser exists for unit tests of the key-file format only. The .gitignore excludes key files.
• No game content, ROMs, or dumps. Test inputs are synthetic: they are generated at runtime or written as AArch64 instructions in source.
• No code copied from third-party projects. Earlier revisions contained firmware-derived and third-party-derived byte sequences; they were removed from the current tree but are still reachable in git history. See Known Issues.

Trademarks. "Nintendo", "Nintendo Switch", "Switch 2", "NVIDIA", "Tegra", "Horizon" and related names are trademarks of their respective owners. This project is not affiliated with, endorsed by, or sponsored by any of them. Names appear only to describe the hardware and ABI being modelled.

No warranty; not legal advice. The software is provided as is. Anyone using, modifying or distributing it is responsible for complying with the copyright, anti-circumvention and other laws that apply where they are. Consult a lawyer before any use beyond private research.

License. MIT. See LICENSE. The license covers the code in this repository only. It does not cover any third-party material that may appear in earlier commits (see Known Issues).

Status reflects what the code does and what the tests exercise. "Modelled" means the behaviour is simulated in software, not measured against hardware.

Known limitations

• Timing and MIPS figures are host measurements of small synthetic programs. They are not comparable to hardware and are not pass/fail criteria.
• Behaviour that is not in the test suite should be assumed unverified.

ounce-core/
├── assets/           # Vector artwork (banner, logo, architecture diagram)
├── src/
│   ├── audio/        # Audio renderer model and PCM output sink
│   ├── cpu/          # AArch64 decoder, interpreter, Tier-1/2 JIT, Tier-3 super-block engine
│   ├── crypto/       # AES-128 and AES-128-CTR (user-supplied keys)
│   ├── fs/           # Virtual filesystem, RomFS parser, save-data storage
│   ├── gpu/          # Command-buffer model, rasterizer, shader translator, upscaler model
│   ├── hid/          # Controller state model and deadzone filters
│   ├── kernel/       # SVC dispatcher, IPC, scheduler, synchronization, SDK-style HLE runtime
│   ├── loader/       # Container parsers and synthetic image builders
│   ├── mmu/          # Paged memory model
│   ├── ui/           # Headless package inspector and CLI telemetry
│   └── main.rs       # CLI and the 25-stage integration harness
├── Cargo.toml
└── README.md

cargo test --release --features gpu-present  # 103 unit tests
cargo run --release --features gpu-present -- test  # 25-stage integration harness (exits 0xEEE)

The harness runs synthetic AArch64 programs through the CPU, kernel and service models. Each stage passes when its guest program returns the expected exit code. Host timings are printed for information only.

• Rust 1.85 or newer (edition 2024).
• Host: aarch64 or x86_64, Linux, macOS or Windows.
• Prebuilt Linux binaries dynamically link to the system ALSA and udev libraries. On Debian/Ubuntu: sudo apt install libasound2 libudev1. On Fedora: sudo dnf install alsa-lib systemd-libs. On Arch: sudo pacman -S alsa-lib systemd-libs. Building from source also needs the development headers (libasound2-dev libudev-dev on Debian/Ubuntu).
• GPU presentation (optional): build with --features gpu-present. macOS uses Metal and needs nothing extra. Windows uses Vulkan or DX12 from the installed GPU driver. Linux needs a Vulkan driver plus libvulkan1 and libxkbcommon-x11-0 on Debian/Ubuntu (vulkan-loader libxkbcommon-x11 on Fedora, vulkan-icd-loader libxkbcommon-x11 on Arch); mesa-vulkan-drivers gives a software Vulkan driver for machines without a GPU. If the GPU path cannot start, the runtime falls back to the software window and then to headless.

cargo run --release -- info                      # Show modelled hardware and engine status
cargo run --release -- test                      # Run the 25-stage harness
cargo run --release -- run tests/fixtures/nro/hello/hello.nro fixture  # Boot the libnx homebrew fixture (prints result=0x00000EEE)
cargo run --release -- inspect ./dumps/title     # Inspect a user-supplied unencrypted directory
cargo run --release -- run ./dumps/title --gui   # Boot an unencrypted loose directory in a window
cargo run --release -- demo-dir ./demo --gui     # Generate a synthetic loose package and boot it
cargo run --release -- play                      # Keyboard-driven controller and graphics demo
cargo run --release -- 3d 120                    # Software rasterizer benchmark
cargo run --release --features gpu-present -- gfx --present=gpu   # Present through the GPU swapchain
cargo run --release -- gfx 60 --present=headless # No window; OUNCE_DUMP_FRAMES=<dir> writes PPM frames

--present=auto|gpu|minifb|headless (or OUNCE_PRESENT) picks the presentation backend; auto tries the GPU first when the feature is compiled in. WGPU_BACKEND (vulkan, metal, dx12, gl) and WGPU_ADAPTER_NAME select the GPU, and OUNCE_VSYNC=0 disables vsync.

• Git history. The history has not been fully purged yet. Commits before 76ce766 (for example c7f16f2 and 4be9640) contain firmware-derived and third-party-derived byte sequences and a loader for an external payload file. They are still reachable from main, all branches and the v0.3.x tags through merge 25205cc, and from GitHub pull request refs. A purge is in progress. Do not use or redistribute those commits.
• Commercial container decryption. Decryption in loader/nca.rs is restricted by policy to synthetic test vectors (SYNTHETIC_TEST_KEY). Retail key decryption is disabled; research binaries must be supplied as unencrypted loose directories or homebrew packages.
• License scope. The MIT license applies to this tree only. It does not cover material in the earlier commits listed above.

Changes must keep the test suite and the 25-stage harness passing. New test inputs must be synthetic or written by hand from the public AArch64 and SPIR-V specifications. Do not add firmware, keys, game content, or code or data copied from other projects.