Nixe

This is an educational and experimental project written in Rust. Its long-term goal is to research and build functional emulators for Nintendo Switch and Nintendo Switch 2 while sharing well-defined components between both platforms whenever technically appropriate.

Goals

• Study modern console emulation and low-level systems programming.
• Build a functional Nintendo Switch emulator incrementally.
• Prepare an extensible foundation for Nintendo Switch 2 research and emulation.
• Reuse CPU, memory, graphics, tooling, and other infrastructure when the underlying behavior is genuinely shared.
• Favor testable, documented, and maintainable Rust code.

Project Status

The project is currently in an early development and research phase.

Milestones:

• Content formats
  • Random-access storage abstraction with bounded sub-storage views.
  • User-supplied key management; cryptographic keys are never bundled or downloaded.
  • NSP/PFS0 and XCI/HFS0 package loading.
  • NSZ, XCZ, and NCZ compressed package support.
  • Block-compressed random access and progressive caching for solid NCZ streams.
  • NCA header parsing, section discovery, decryption, and integrity validation.
  • ExeFS and RomFS filesystem loading.
  • BKTR patch RomFS composition using base and update content.
  • CNMT and NACP metadata parsing.
  • Title names, publishers, languages, versions, properties, and icons.
  • Recursive package discovery and title cataloguing.
  • Base application, update, DLC, duplicate, and conflict resolution.
• Executable formats
  • NRO executable loading with segments, BSS, metadata, and optional ASET support.
  • Classic NSO executable loading with LZ4-compressed segments, BSS, module metadata, and MOD0 parsing.
  • Execute-only and ZBIC-compressed NSO variants.
  • NPDM process metadata, filesystem permissions, service access control, and kernel capabilities.
  • AArch64 executable relocations and immutable, page-safe NRO/NSO mapping plans.
• Runtime
  • Atomic installation of prepared executable mappings into permission-aware process memory.
  • Deterministic launch plans and loader coordination for packaged titles, DLC, and NRO homebrew.
  • Runtime entry-point integration: NPDM-driven process setup, initialized main-thread ABI, and verified entry-block translation.
  • Bounded reference execution with safepoints, structured faults, process-local handles and mounts, and deterministic teardown.
• CPU
  • CPU contracts: A64/A32/T32 profiles and state, plus permission-aware synthetic process memory and instruction fetching.
  • IR foundation: typed block construction, verification, deterministic printing, and shared canonical semantic primitives.
  • Declarative decoder framework: indexed A64/A32/T32 classification, typed operands, profile gating, and stable coverage IDs.
  • A64 scalar frontend: bounded block translation with control flow, integer and memory lifting, explicit flags, guest addresses, and precise memory semantics.
  • Reference execution and fallback: modular scalar interpretation, process-aware memory access, precise faults, and actionable missing-instruction reports.
  • Switch 1 scalar execution states: modular A32/T32 decoding and reference execution with conditions, IT state, memory, and correct interworking.

Testing

Run

cargo test-all

Integration tests against real titles

To run integration tests against caller-owned titles, copy .env.integration.example to .env.integration, configure the paths, and run ./scripts/test-integration.sh.

Differential tests

Optional CPU differential tests require QEMU user-mode (qemu-aarch64 and qemu-arm), the Rust aarch64-unknown-linux-gnu and armv7-unknown-linux-gnueabihf targets, and their cross-linkers.

sudo apt update && sudo apt install qemu-user gcc-aarch64-linux-gnu gcc-arm-linux-gnueabihf
rustup target add aarch64-unknown-linux-gnu armv7-unknown-linux-gnueabihf

Verify with

qemu-aarch64 --version
qemu-arm --version
aarch64-linux-gnu-gcc --version
arm-linux-gnueabihf-gcc --version

Then run

cargo test-diff

Fuzz tests

CPU decoder, translation, IR verifier, and diagnostic fuzz targets require a nightly Rust toolchain and cargo-fuzz:

rustup toolchain install nightly
cargo install cargo-fuzz
cargo fuzz-all

The aggregate alias runs 10,000 iterations for each target. See fuzz/README.md for target-specific commands and configuration.

Contributing

See CONTRIBUTING.md.

Legal Notice

This project is intended for lawful education, research, interoperability, and preservation work. It does not provide or distribute games, firmware, cryptographic keys, copyrighted console files, or leaked confidential material.

Users and contributors are responsible for complying with the laws applicable in their jurisdictions and for using only software and data they are legally entitled to use.

Nintendo Switch and Nintendo Switch 2 are trademarks of Nintendo. This project is independent and is not affiliated with, sponsored by, or endorsed by Nintendo or NVIDIA.

License

Nixe is licensed under the GNU General Public License version 3 or later. See LICENSE.txt.