Skip to content
ovskyPublic
forked from pound-emu/pound

About

Open source emulator for the Nintedo Switch 1 and 2. Highly work in progress

Resources

Contributing

Stars

114 stars

Watchers

5 watching

Forks

ย 
ย 

Latest commit

ย 

History

349 Commits

Folders and files

Repository files navigation

CI: Linux, ARM64 and Windows CI: Android APK License: GPLv3 Language: C

๐ŸŽฎ Compound Emulator

๐ŸŒŸ An Open-Source Nintendo Switch Emulator Written in C

Switch 2 support is a research target, not a shipping capability: this build has no console keys, no content decryption, and no Switch 2 execution layer.

High-fidelity system emulation. Highly experimental, but steadily growing.

Stars License C Language Cross-Platform


๐ŸŽฌ Preview

๐Ÿ“ธ Screenshots & Gameplay

Click to expand and view the latest emulation screenshots

Preview 1

Preview 2


โœจ What's Compound?

Compound is an ambitious, production-focused Nintendo Switch emulator project written in clean C with a relentless focus on correctness, performance, and portability. Unlike many emulation projects, Compound emphasizes:

  • ๐Ÿงฌ Defensive architecture with checked arithmetic and runtime validation
  • ๐Ÿ—๏ธ Architecture-first design with clear separation of concerns
  • ๐Ÿš€ High-performance JIT compilation via the Ballistic ARM64 recompiler
  • ๐ŸŒ Cross-platform excellence โ€“ Linux, macOS, Windows, Android, and ARM64
  • ๐Ÿ“Š Professional-grade debugging with GUI, live reload, and comprehensive logging
  • ๐ŸŽฏ Staged development approach โ€“ foundations first, then execution, then compatibility

Perfect for:

  • ๐ŸŽฎ Gaming enthusiasts and emulation developers
  • ๐Ÿ”ฌ Systems programming researchers and students
  • ๐Ÿ› ๏ธ Hardware debugging and reverse engineering

๐ŸŽฏ Key Highlights

Feature Status Details
๐Ÿงฑ Build & CI Infrastructure โœ… Complete Presets, CMake 3.25+, cross-platform CI
๐Ÿญ Runtime & Memory System โœ… Complete mimalloc allocator, checked arithmetic, pool/slab/arena allocators, host accounting
๐Ÿ› Debug Tooling โœ… Working GUI with live reload, comprehensive logging
โšก Ballistic ARM64 JIT โœ… Complete Recompiler integration and code cache
๐Ÿ’พ Filesystem & Crypto โœ… Complete HFS0 parser, 64-bit file reader, SHA-256, RSA-2048 PKCS#1 v1.5 verification
๐Ÿ–ฅ๏ธ Guest CPU & OS โœ… Complete A64 interpreter subset; kernel objects, one-sided event handles and services
๐ŸŽจ Graphics & Audio โœ… Complete SM86โ†’SPIR-V translation, Vulkan scaffolding, SDL audio output and gamepad input
๐ŸŽฎ Title Support โœ… Complete Content-based NRO/NSO parsing and boot mapping; encrypted packages are recognised and refused
๐ŸŽฎ Switch 2 โŒ Not implemented No keys, decryption, or execution layer; compatibility is always reported false

๐Ÿ“Š Project Status

Compound is in early-stage, active development. The emulator has:

โœ… A solid foundation with working unit tests and presets
โœ… Defensive systems for memory safety and correctness
โœ… Professional debugging tools with GUI and instrumentation
๐Ÿšง Experimental work in JIT, guest CPU and OS, and graphics translation
๐Ÿ”ฎ Planned: Guest execution, compatibility, graphics, and full Switch support

Current Capabilities

โœ“ Build system (CMake, Ninja, Clang)
โœ“ CI/CD (Linux, macOS, Windows, Android, ARM64)
โœ“ Unit testing and validation
โœ“ Memory accounting and profiling
โœ“ Pool, slab, and rewindable arena allocators
โœ“ Debug GUI with real-time diagnostics
โœ“ Logging framework
โœ“ Guest CPU baseline (A64 interpreter subset, Horizon OS kernel objects, SVC dispatch, guest-created events, thread scheduler, memory layout)
โœ“ Title detection and validation (NRO/NSO images; NCA/NSP/XCI recognised and explicitly refused)
โœ“ RSA-2048 PKCS#1 v1.5 signature verification (caller-supplied keys only)
โœ“ Boot mapping for NRO/NSO images (segments, permissions, stack, initial PC/SP)
โœ“ Input, audio ring, SDL audio output, gamepad and keyboard mapping, platform services
โœ— Commercial title boot (needs user-supplied keys, decryption, and a filesystem stack)
โœ— Switch 2 execution (no keys, no decryption, no execution layer)

๐Ÿ›ฃ๏ธ Development Roadmap

๐Ÿ—๏ธ Phase 1: Foundation & Runtime

  • mimalloc host allocator integration
  • Build and CI infrastructure
  • Unit tests and debug instrumentation
  • Advanced memory ownership and allocation strategies (pool, slab, rewindable arena)
  • Hardened validation paths (checked arithmetic, ranges, alignment, overlap predicates)

๐Ÿ“ Phase 2: Filesystem & Cryptography

  • HFS0 filesystem parser
  • Filesystem reader abstraction
  • SHA256 and crypto primitives
  • Verification and signature handling (RSA-2048 PKCS#1 v1.5, verification only)

โšก Phase 3: JIT & Execution Engine

  • Ballistic ARM64 code cache allocator
  • JIT metadata manager
  • Error logging and diagnostics
  • Execution loop integration

๐Ÿ–ฅ๏ธ Phase 4: Guest CPU & OS Emulation

  • ARM64 CPU instruction dispatch (interpreter subset)
  • Horizon OS kernel abstraction (objects, handles and services)
  • System call handling (SVC dispatch for handles, events, yields and the tick)
  • Thread scheduling and blocking waits
  • Synchronization cancellation (svcCancelSynchronization)
  • Guest-created events with one-sided readable and writable handles (svcCreateEvent)
  • Core OS services and memory layout

๐ŸŽจ Phase 5: Graphics & Completeness

  • SM86 โ†’ SPIR-V translation
  • Vulkan render backend (stub implementation, ready for integration)
  • Input, audio, and platform services (SDL gamepad/keyboard, S16 audio ring and output, lifecycle/timing)
  • Bootable guest state for validated NRO/NSO images (commercial packages and Switch 2 titles are refused)

๐ŸŒณ Repository Structure

compound/
โ”œโ”€โ”€ ๐Ÿ“ src/
โ”‚   โ”œโ”€โ”€ emulator core and runtime
โ”‚   โ”œโ”€โ”€ GUI and debug tools
โ”‚   โ””โ”€โ”€ bootstrap and initialization
โ”œโ”€โ”€ ๐Ÿ“ cmake/
โ”‚   โ”œโ”€โ”€ build modules and toolchains
โ”‚   โ””โ”€โ”€ platform-specific configuration
โ”œโ”€โ”€ ๐Ÿ“ tests/
โ”‚   โ”œโ”€โ”€ unit test suite
โ”‚   โ””โ”€โ”€ validation harness
โ”œโ”€โ”€ ๐Ÿ“ android/
โ”‚   โ”œโ”€โ”€ Android packaging
โ”‚   โ””โ”€โ”€ JNI integration
โ”œโ”€โ”€ ๐Ÿ“ extern/
โ”‚   โ”œโ”€โ”€ vendored dependencies
โ”‚   โ””โ”€โ”€ third-party libraries
โ”œโ”€โ”€ ๐Ÿ“ docs/
โ”‚   โ”œโ”€โ”€ architecture and design
โ”‚   โ”œโ”€โ”€ build and CI documentation
โ”‚   โ”œโ”€โ”€ programming rules
โ”‚   โ””โ”€โ”€ graphics (SM86โ†’SPIR-V) rules
โ””โ”€โ”€ ๐Ÿ“ LICENSE, README, etc.

๐Ÿ”ง Building Compound

โœ… Requirements

  • CMake 3.25 or later
  • Ninja build system
  • Clang compiler (GCC/MSVC with adjustments)
  • C++17 or later support

๐Ÿš€ Quick Start

# Configure and build
cmake --preset debug
cmake --build --preset debug --parallel

# Run tests
ctest --preset debug

# Verbose output (optional)
cmake --build --preset debug --verbose

๐Ÿ“‹ Available Presets

Preset Platform Architecture Features
debug Linux / macOS x86-64 ASan + UBSan enabled
release Linux / macOS x86-64 Optimized build
debug-windows Windows x86-64 clang-cl compiler
release-windows Windows x86-64 Optimized (clang-cl)
linux-aarch64-debug Linux ARM64 Cross-compile, QEMU tested
linux-aarch64-release Linux ARM64 Cross-compile, optimized
android-arm64-debug Android ARM64 Produces libmain.so
android-arm64-release Android ARM64 Optimized Android library

For detailed setup, prerequisites, and Android packaging, see docs/BUILDING.md.


๐Ÿ“š Documentation

Comprehensive documentation is available in the /docs folder:

Document Purpose
ARCHITECTURE.md System design, module breakdown, and design patterns
BUILDING.md Build setup, platform-specific instructions, Android packaging
CI.md CI/CD workflows, automation, and testing strategies
PROGRAMMING_RULES.md Code style, safety, and best practices
SM86_TO_SPIRV_RULES.md Graphics shader translation rules and patterns

๐Ÿค Contributing

Before contributing, please read:

  1. CONTRIBUTING.md โ€“ Contribution guidelines
  2. PROGRAMMING_RULES.md โ€“ Code standards
  3. ARCHITECTURE.md โ€“ System design overview

How to Contribute

# 1. Fork the repository
# 2. Create a feature branch
git checkout -b feature/your-amazing-feature

# 3. Commit with clear messages
git commit -m "Add: [feature description]"

# 4. Push and open a PR
git push origin feature/your-amazing-feature

Good contribution areas:

  • ๐Ÿ› Bug fixes in core systems
  • ๐Ÿ“– Documentation and examples
  • โœ… Unit tests and validation
  • ๐Ÿš€ Performance optimizations
  • ๐ŸŒ Platform support and portability

๐Ÿ”„ Branch Strategy

Branch Purpose Status
main Stable baseline, release-ready Production
general-upgrade-dev-v1 Primary development track Active
general-upgrade-experimental-* Feature-specific experimental work In Progress
origin/enhancement/project-upgrade-core-cmake Build system improvements Active

The repository uses a staged experimental approach: features are tested in dedicated experimental branches, then selectively merged into the main development stream.


๐ŸŽ“ Architecture Highlights

Design Principles

โœจ Correctness First
Runtime validation, checked arithmetic, and defensive coding patterns ensure system stability.

โšก Performance-Conscious
Ballistic ARM64 JIT provides high-speed guest code execution without sacrificing clarity.

๐Ÿงฑ Clean Architecture
Clear separation of concerns with well-defined module boundaries and interfaces.

๐ŸŒ Cross-Platform
Native support for Linux, macOS, Windows, Android, and ARM64 architectures.

Key Systems

  • Memory System: mimalloc allocator with host accounting; pool, slab, and rewindable arena strategies; shared checked-arithmetic validation
  • JIT Engine: Ballistic ARM64 recompiler for high-performance execution
  • Guest OS: Horizon OS kernel objects, per-process handles with one-sided event rights, named services, SVC dispatch including svcCreateEvent, svcMapMemory, svcUnmapMemory, a priority round-robin thread scheduler with blocking waits and svcCancelSynchronization, and a partitioned address space whose region table gates guest access, answers svcQueryMemory, and reprotects an existing region with svcSetMemoryPermission/svcSetMemoryAttribute
  • Graphics: SM86โ†’SPIR-V translation with Vulkan render backend scaffolding
  • Title Loading: Content-based NRO/NSO detection, layout validation, and boot mapping; NCA/NSP/XCI are recognised and refused because this build has no keys or decryption
  • Crypto: SHA-256 and RSA-2048 PKCS#1 v1.5 verification over caller-supplied public keys
  • Platform: SDL audio output, gamepad/keyboard mapping, and host lifecycle/timing services, with an SDL-free core input/audio layer
  • Debug Tools: GUI with live reload, comprehensive logging, and profiling
  • Validation: Extensive unit tests and runtime checks
  • Filesystem: Experimental HFS0 parser and file-backed reader abstraction

๐Ÿ“œ License

Compound is licensed under the GNU General Public License v3.0. See LICENSE for full details.

Copyright (C) 2024 - Emulator Contributors
Licensed under GPLv3 โ€“ You are free to use, modify, and distribute
under the terms of the GPL v3.

๐ŸŽ‰ Latest Updates

Recent Work

  • ๐Ÿงฑ Foundation strengthening: Shared validation helpers, an arena allocator with ownership tags and checkpoints, and a 64-bit file reader
  • โšก JIT experimentation: Ballistic ARM64 integration progress
  • ๐Ÿ–ฅ๏ธ Guest CPU and OS: A64 interpreter subset, a Horizon OS handle/service kernel with one-sided readable and writable event handles, SVC dispatch including svcCreateEvent, svcMapMemory, svcUnmapMemory, a thread scheduler with blocking waits, synchronization cancellation with svcCancelSynchronization, and a memory-layout slice that partitions the guest address space, answers svcSetHeapSize/svcQueryMemory, and reprotects regions with svcSetMemoryPermission/svcSetMemoryAttribute
  • ๐Ÿ“ Filesystem work: HFS0 parser and a file-backed reader with 64-bit offsets
  • ๐Ÿ” Crypto: SHA-256 plus RSA-2048 PKCS#1 v1.5 signature verification over caller-supplied keys; no Nintendo keys are shipped
  • ๐ŸŽจ Graphics: SM86โ†’SPIR-V translation with Vulkan render backend scaffolding
  • ๐ŸŽฎ Title loading: Content-based NRO/NSO detection, validated segment layouts, and boot mapping; encrypted NCA/NSP/XCI packages are refused by name rather than approximated
  • ๐Ÿ”Š Platform services: Thread-safe S16 audio ring, SDL audio output, gamepad/keyboard input mapping, and lifecycle/timing capability reporting
  • ๐Ÿ› Testing: 32 registered CTest suites, including validation, arena, RSA, file reader, loader, input, audio, and platform services

Next Focus

  1. Integration of Vulkan render backend with main render loop
  2. Key handling, package decryption, and a filesystem stack for commercial titles
  3. IPC/CMIF shared memory and the remaining svcMapMemory/svcUnmapMemory alias path

๐Ÿ™Œ Join the Emulation Community!

Have questions or ideas?
๐Ÿ‘‰ Open an issue or start a discussion

Want to help?
๐Ÿ‘‰ Check the roadmap and pick a task!


Made with โค๏ธ by the Emulation Community

GitHub โ€ข Issues โ€ข Discussions

About

Open source emulator for the Nintedo Switch 1 and 2. Highly work in progress

Resources

Contributing

Stars

114 stars

Watchers

5 watching

Forks

Releases

Packages

Contributors

Languages