Architecture

​

Overview

​

Project Structure

src/
├── common/          # Shared utilities and I/O
├── core/            # Emulation core (HLE)
└── frontend/        # User interface layers

​

Component Overview

core/
├── hw/                    # Hardware emulation
│   └── tegra_x1/         # NVIDIA Tegra X1 SoC
│       ├── cpu/          # ARM CPU emulation
│       └── gpu/          # Maxwell GPU emulation
├── horizon/               # Nintendo OS (HLE)
│   ├── kernel/           # Kernel services
│   ├── services/         # System services
│   ├── filesystem/       # File system layer
│   ├── loader/           # Game loaders
│   └── display/          # Display management
├── audio/                 # Audio subsystem
├── input/                 # Input handling
└── debugger/              # GDB debugger

​

Core Architecture

​

Hardware Emulation Layer

​

CPU Emulation

• Dynamic recompiler for ARMv8-A architecture
• Cross-platform JIT compilation
• Used on Intel Macs and as fallback
• Location: src/core/hw/tegra_x1/cpu/dynarmic/

• Uses macOS Hypervisor.framework
• Native ARM64 execution with hardware virtualization
• Significantly faster than dynarmic on Apple Silicon
• Requires specific entitlements
• Location: src/core/hw/tegra_x1/cpu/hypervisor/

​

GPU Emulation

• GPU Core: src/core/hw/tegra_x1/gpu/gpu.hpp
• Graphics Engines:
  • 3D Engine: engines/3d.cpp (Maxwell 3D graphics pipeline)
  • 2D Engine: engines/2d.cpp (2D blitting operations)
  • Compute Engine: engines/compute.cpp (GPGPU compute)
  • DMA Engine: engines/copy.cpp (memory transfers)

1. Decompiler: Converts NVIDIA shader bytecode to IR (shader_decompiler/)
2. IR Optimization: Analyzes and optimizes intermediate representation
3. Metal Codegen: Emits Metal Shading Language code (codegen/lang/msl/)
4. Caching: Compiled shaders cached for reuse (shader_cache.cpp)

• Command Buffer: Metal command encoding (renderer/metal/command_buffer.cpp)
• Buffer Cache: Vertex/index buffer management (renderer/buffer_cache.cpp)
• Texture Cache: Texture format conversion and caching (renderer/texture_cache.cpp)
• Pipeline Cache: Graphics pipeline state objects (renderer/pipeline_cache.cpp)

​

Horizon OS Layer (HLE)

​

Kernel Services

• Process Management: Multi-process execution (process.cpp, process_manager.cpp)
• Threading: Guest and host thread coordination (thread.cpp, guest_thread.cpp, host_thread.cpp)
• Memory: Shared memory, transfer memory, code memory objects
• Synchronization: Events and synchronization primitives
• IPC (HIPC): Inter-process communication via ports and sessions (kernel/hipc/)

​

System Services

sm/         # Service manager
fssrv/      # File system services
visrv/      # Display/visual services
nvdrv/      # NVIDIA driver services
hid/        # Human interface devices (input)

​

File System Layer

• Virtual File System: Unified file abstraction (filesystem.cpp)
• Content Archives: NCA file parsing (content_archive.cpp)
• RomFS: Read-only filesystem (romfs/)
• Partition FS: PFS0 support (partition_filesystem.hpp)
• Device Mounting: Multi-device file access (device.cpp)

​

Loader System

• NRO: Nintendo Relocatable Object (homebrew) (nro_loader.cpp)
• NSO: Nintendo Shared Object (system modules) (nso_loader.cpp)
• NCA: Nintendo Content Archive (official games) (nca_loader.cpp)
• NX: Custom format (nx_loader.cpp)
• NSP: Nintendo Submission Package (nsp_loader.cpp)

​

Audio Subsystem

• Cubeb Backend: Cross-platform audio (enabled by default)
  • Location: audio/cubeb/
  • Real-time audio streaming
  • Low-latency output
• Null Backend: Silent fallback when cubeb disabled
  • Location: audio/null/

​

Input System

• Device Manager: Input device detection and management (device_manager.cpp)
• Profiles: Controller configuration profiles (profile.cpp)
• Apple GameController: Native macOS controller support (apple_gc/)
• Input Types: Keyboard, controller, cursor support

​

Frontend Architecture

​

SDL3 Frontend

• Minimum macOS: 13.0
• Window Management: SDL3 window creation and events (window.cpp)
• Input: SDL3 input to emulator mapping
• Metal Integration: SDL3 Metal view for rendering

​

SwiftUI Frontend

• Minimum macOS: 15.0
• Native UI: Modern macOS interface
• Features:
  • Game library management (GameListView.swift)
  • Settings interface (settings/)
  • Integrated debugger UI (debugger/)
  • Metal rendering view (MetalView.swift)

​

C API Bridge

• Swift/Objective-C integration
• Frontend abstraction
• Clean separation between core and UI

​

External Dependencies

​

CPU Emulation

• dynarmic: ARMv8-A dynamic recompiler

​

Audio

• cubeb: Cross-platform audio backend

​

Graphics

• metal-cpp: C++ wrapper for Metal API
• stb: Image loading (STB libraries)

​

Utilities

• hatch: TOML configuration parser
• fmt: String formatting library
• toml11: TOML11 configuration

​

Nintendo Formats

• libyaz0: Yaz0 compression (used in Nintendo filesystems)
• nx2elf: Nintendo executable conversion

​

Build System

• Root CMake: CMakeLists.txt - Project setup and dependencies
• Source CMake: src/CMakeLists.txt - Component inclusion
• Core CMake: src/core/CMakeLists.txt - Massive core library definition
• Frontend CMake: src/frontend/CMakeLists.txt - Frontend selection

​

Compiler Requirements

• C++ Standard: C++20
• Warnings: Treated as errors (-Werror)
• Warning Flags: -Wall -Wextra -Wconversion -Wsign-conversion

​

Platform Configuration

// Hypervisor backend
#if HYDRA_HYPERVISOR_ENABLED
  // Use Hypervisor.framework
#endif

// Cubeb audio
#if HYDRA_CUBEB_ENABLED
  // Use cubeb backend
#endif

// Debug builds
#ifdef HYDRA_DEBUG
  // Extra logging and checks
#endif

​

Execution Flow

​

Initialization Sequence

​

Service Call Flow

Guest Code (ARM64)
    |
    v
SVC Instruction (Supervisor Call)
    |
    v
Kernel IPC Handler
    |
    v
Service Lookup (sm/user_interface.cpp)
    |
    v
Service Implementation (e.g., fssrv/filesystem_proxy.cpp)
    |
    v
Return Result to Guest

​

Debugging Support

• GDB Server: Remote debugging via GDB protocol (gdb_server.cpp)
• Debugger Manager: Multi-process debugging (debugger_manager.cpp)
• SwiftUI Integration: Built-in debugger UI (SwiftUI frontend)

​

Memory Management

​

Guest Memory

• CPU MMU: ARM64 memory management unit emulation (cpu/mmu.cpp)
• GPU MMU (GMMU): GPU memory management (gpu/gmmu.cpp)
• Shared Regions: Host-guest shared memory for performance

​

Caching Strategy

• Shader Cache: Persistent compiled shader storage
• Texture Cache: GPU texture deduplication
• Buffer Cache: Vertex/index buffer reuse
• Pipeline Cache: Render state objects

​

Threading Model

• Guest Threads: Emulated Switch threads (kernel/guest_thread.cpp)
• Host Threads: Native macOS threads for scheduling (kernel/host_thread.cpp)
• Thread Synchronization: Event-based sync between guest threads
• CPU Execution: Per-thread execution contexts

​

Performance Optimizations

​

Apple Silicon

• Hypervisor Framework: Native ARM64 execution
• Metal: GPU-accelerated rendering
• Unified Memory: Efficient host-guest memory sharing

​

Caching

• Shader Compilation: One-time MSL compilation with caching
• Pipeline States: Pre-compiled render states
• Texture Formats: On-demand conversion with cache

​

Multi-threading

• GPU Command Buffer: Async command encoding
• Audio Streaming: Separate audio thread
• File I/O: Async filesystem operations

​

Next Steps

1. Build from Source: See Building
2. Read Contributing Guide: Contributing
3. Explore Source Code: Clone and examine the repository
4. Join Discord: Get help from the development community