Architecture Overview

​

Introduction

​

Core Components

​

System Architecture

​

Module Organization

​

core/src/cpu/

• cpu_manager.rs: Multi-core CPU management with 8 ARMv8 cores
• unicorn_interface.rs: Safe wrapper around Unicorn Engine
• Memory mapping and register management

​

core/src/gpu/

• mod.rs: GPU state and Vulkan initialization
• sm86.rs: SM86 instruction decoder for NVIDIA Ampere architecture
• sm86_decoder_generated.rs: Generated instruction decoder (254+ instructions)
• spirv.rs: SPIR-V emission for shader translation

​

core/src/nn/

• 160+ service stubs for system calls
• Macro-based service generation
• Service initialization and dispatch

​

core/src/sys/

• Service container holding all active services
• GPU state integration
• Global system initialization

​

Design Principles

​

Key Design Decisions

1. Shared Memory Architecture: All 8 CPU cores share a single 12GB memory space mapped through Unicorn’s mem_map_ptr, enabling true multicore memory coherency
2. SPIR-V as IR: GPU shaders are decoded from SASS (SM86 binary) to SPIR-V intermediate representation, then executed via Vulkan
3. Macro-Generated Services: The 160+ firmware services use Rust macros to generate boilerplate, reducing code duplication
4. Pinned Memory: The shared memory buffer is pinned using Pin<Box<[u8]>> to ensure pointers remain valid across the program lifetime

​

Performance Characteristics

​

Memory Allocation

// From core/src/cpu/cpu_manager.rs:24
let shared_memory = Pin::new(vec![0u8; MEMORY_SIZE as usize].into_boxed_slice());

​

Core Scheduling

// core/src/cpu/cpu_manager.rs:48
pub fn run_all(&self) {
    // for now, just step all cores sequentially (round-robin)
    // in the future, this would be threaded
    for (_i, core) in self.cores.iter().enumerate() {
        core.step();
    }
}

​

Development Status

​

Implemented Components

• ✅ CPU manager with 8-core initialization
• ✅ Shared memory setup
• ✅ Unicorn integration for ARMv8
• ✅ SM86 decoder skeleton (254+ instruction definitions)
• ✅ SPIR-V emitter with full instruction set
• ✅ Service registration system (160 services)
• ✅ Vulkan initialization

​

In Progress

• 🚧 SM86 instruction implementations
• 🚧 SASS to SPIR-V translation logic
• 🚧 Service implementations
• 🚧 Multithreaded core execution
• 🚧 File system emulation
• 🚧 Graphics pipeline

​

Next Steps

• CPU Architecture - Deep dive into ARMv8 emulation and multicore management
• GPU Architecture - SM86 decoder and SPIR-V translation pipeline
• Memory Architecture - 12GB shared memory layout and management
• Services Architecture - Firmware service system and HLE approach