yaze/docs/internal/research/emulator-improvements.md

Emulator Core Improvements Roadmap

Last Updated: October 10, 2025
Status: Active Planning

Overview

This document outlines improvements, refactors, and optimizations for the yaze emulator core. These changes aim to enhance accuracy, performance, and code maintainability.

Items are presented in order of descending priority, from critical accuracy fixes to quality-of-life improvements.

---

Critical Priority: APU Timing Fix

Problem Statement

The emulator's Audio Processing Unit (APU) currently fails to load and play music. Analysis shows that the SPC700 processor gets "stuck" during the initial handshake sequence with the main CPU. This handshake is responsible for uploading the sound driver from ROM to APU RAM. The failure of this timing-sensitive process prevents the sound driver from running.

Root Cause: CPU-APU Handshake Timing

The process of starting the APU and loading a sound bank requires tightly synchronized communication between the main CPU (65816) and the APU's CPU (SPC700).

The Handshake Protocol

1. APU Ready: SPC700 boots, initializes, signals ready by writing $AA to port $F4 and $BB to port $F5
2. CPU Waits: Main CPU waits in tight loop, reading combined 16-bit value from I/O ports until it sees $BBAA
3. CPU Initiates: CPU writes command code $CC to APU's input port
4. APU Acknowledges: SPC700 sees $CC and prepares to receive data block
5. Synchronized Byte Transfer: CPU and APU enter lock-step loop to transfer sound driver byte-by-byte:
   • CPU sends data
   • CPU waits for APU to read data and echo back confirmation
   • Only upon receiving confirmation does CPU send next byte

Point of Failure

The "stuck" behavior occurs because one side fails to meet the other's expectation. Due to timing desynchronization:

• The SPC700 is waiting for a byte that the CPU has not yet sent (or sent too early), OR
• The CPU is waiting for an acknowledgment that the SPC700 has already sent (or has not yet sent)

The result is an infinite loop on the SPC700, detected by the watchdog timer in Apu::RunCycles.

Technical Analysis

The handshake's reliance on precise timing exposes inaccuracies in the current SPC700 emulation model.

Issue 1: Incomplete Opcode Timing

The emulator uses a static lookup table (spc700_cycles.h) for instruction cycle counts. This provides a base value but fails to account for:

• Addressing Modes: Different addressing modes have different cycle costs
• Page Boundaries: Memory accesses crossing 256-byte page boundaries take an extra cycle
• Branching: Conditional branches take different cycle counts depending on whether branch is taken

While some of this is handled (e.g., DoBranch), it is not applied universally, leading to small, cumulative errors.

Issue 2: Fragile Multi-Step Execution Model

The step/bstep mechanism in Spc700::RunOpcode is a significant source of fragility. It attempts to model complex instructions by spreading execution across multiple calls. This means the full cycle cost of an instruction is not consumed atomically. An off-by-one error in any step corrupts the timing of the entire APU.

Issue 3: Floating-Point Precision

The use of double for the apuCyclesPerMaster ratio can introduce minute floating-point precision errors. Over thousands of cycles required for the handshake, these small errors accumulate and contribute to timing drift between CPU and APU.

Proposed Solution: Cycle-Accurate Refactoring

Step 1: Implement Cycle-Accurate Instruction Execution

The Spc700::RunOpcode function must be refactored to calculate and consume the exact cycle count for each instruction before execution.

• Calculate Exact Cost: Before running an opcode, determine its precise cycle cost by analyzing opcode, addressing mode, and potential page-boundary penalties
• Atomic Execution: Remove the bstep mechanism. An instruction, no matter how complex, should be fully executed within a single call to a new Spc700::Step() function

Step 2: Centralize the APU Execution Loop

The main Apu::RunCycles loop should be the sole driver of APU time.

• Cycle Budget: At the start of a frame, calculate the total "budget" of APU cycles needed
• Cycle-by-Cycle Stepping: Loop, calling Spc700::Step() and Dsp::Cycle(), decrementing cycle budget until exhausted

Example of the new loop in Apu::RunCycles:

void Apu::RunCycles(uint64_t master_cycles) {
  // 1. Calculate cycle budget for this frame
  const uint64_t target_apu_cycles = ...; 

  // 2. Run the APU until the budget is met
  while (cycles_ < target_apu_cycles) {
    // 3. Execute one SPC700 cycle/instruction and get its true cost
    int spc_cycles_consumed = spc700_.Step();
    
    // 4. Advance DSP and Timers for each cycle consumed
    for (int i = 0; i < spc_cycles_consumed; ++i) {
      Cycle(); // This ticks the DSP and timers
    }
  }
}

Step 3: Use Integer-Based Cycle Ratios

To eliminate floating-point errors, convert the apuCyclesPerMaster ratio to a fixed-point integer ratio. This provides perfect, drift-free conversion between main CPU and APU cycles over long periods.

---

High Priority: Core Architecture & Timing Model

CPU Cycle Counting

• Issue: The main CPU loop in Snes::RunCycle() advances the master cycle counter by a fixed amount (+= 2). Real 65816 instructions have variable cycle counts. The current workaround of scattering callbacks_.idle() calls is error-prone and difficult to maintain.
• Recommendation: Refactor Cpu::ExecuteInstruction to calculate and return the precise cycle cost of each instruction, including penalties for addressing modes and memory access speeds. The main Snes loop should then consume this exact value, centralizing timing logic and dramatically improving accuracy.

Main Synchronization Loop

• Issue: The main loop in Snes::RunFrame() is state-driven based on the in_vblank_ flag. This can be fragile and makes it difficult to reason about component state at any given cycle.
• Recommendation: Transition to a unified main loop driven by a single master cycle counter. In this model, each component (CPU, PPU, APU, DMA) is "ticked" forward based on the master clock. This is a more robust and modular architecture that simplifies component synchronization.

---

Medium Priority: PPU Performance

Rendering Approach Optimization

• Issue: The PPU currently uses a "pixel-based" renderer (Ppu::RunLine calls HandlePixel for every pixel). This is highly accurate but can be slow due to high function call overhead and poor cache locality.
• Optimization: Refactor the PPU to use a scanline-based renderer. Instead of processing one pixel at a time, process all active layers for an entire horizontal scanline, compose them into a temporary buffer, and then write the completed scanline to the framebuffer. This is a major architectural change but is a standard and highly effective optimization technique in SNES emulation.

Benefits:

• Reduced function call overhead
• Better cache locality
• Easier to vectorize/SIMD
• Standard approach in accurate SNES emulators

---

Low Priority: Code Quality & Refinements

APU Code Modernization

• Issue: The code in dsp.cc and spc700.cc, inherited from other projects, is written in a very C-like style, using raw pointers, memset, and numerous "magic numbers."
• Refactor: Gradually refactor this code to use modern C++ idioms:
  • Replace raw arrays with std::array
  • Use constructors with member initializers instead of memset
  • Define constexpr variables or enum class types for hardware registers and flags
  • Improve type safety, readability, and long-term maintainability

Audio Subsystem & Buffering

• Issue: The current implementation in Emulator::Run queues audio samples directly to the SDL audio device. If the emulator lags for even a few frames, the audio buffer can underrun, causing audible pops and stutters.
• Improvement: Implement a lock-free ring buffer (or circular buffer) to act as an intermediary. The emulator thread would continuously write generated samples into this buffer, while the audio device (in its own thread) would continuously read from it. This decouples the emulation speed from the audio hardware, smoothing out performance fluctuations and preventing stutter.

Debugger & Tooling Optimizations

DisassemblyViewer Data Structure

• Issue: DisassemblyViewer uses a std::map to store instruction traces. For a tool that handles frequent insertions and lookups, this can be suboptimal.
• Optimization: Replace std::map with std::unordered_map for faster average-case performance.

BreakpointManager Lookups

• Issue: The ShouldBreakOn... functions perform a linear scan over a std::vector of all breakpoints. This is O(n) and could become a minor bottleneck if a very large number of breakpoints are set.
• Optimization: For execution breakpoints, use a std::unordered_set<uint32_t> for O(1) average lookup time. This would make breakpoint checking near-instantaneous, regardless of how many are active.

---

Completed Improvements

Audio System Fixes (v0.4.0)

Problem Statement

The SNES emulator experienced audio glitchiness and skips, particularly during the ALTTP title screen, with audible pops, crackling, and sample skipping during music playback.

Root Causes Fixed

1. Aggressive Sample Dropping: Audio buffering logic was dropping up to 50% of generated samples, creating discontinuities
2. Incorrect Resampling: Duplicate calculations in linear interpolation wasted CPU cycles
3. Missing Frame Synchronization: DSP's NewFrame() method was never called, causing timing drift
4. Missing Hermite Interpolation: Only Linear/Cosine/Cubic were available (Hermite is the industry standard)

Solutions Implemented

1. Never Drop Samples: Always queue all generated samples unless buffer critically full (>4 frames)
2. Fixed Resampling Code: Removed duplicate calculations and added bounds checking
3. Frame Boundary Synchronization: Added dsp.NewFrame() call before sample generation
4. Hermite Interpolation: New interpolation type matching bsnes/Snes9x standard

Interpolation options (src/app/emu/audio/dsp.cc):

Interpolation	Notes
Linear	Fastest; retains legacy behaviour.
Hermite	New default; balances quality and speed.
Cosine	Smoother than linear with moderate cost.
Cubic	Highest quality, heavier CPU cost.

Result: Manual testing on the ALTTP title screen, overworld theme, dungeon ambience, and menu sounds no longer exhibits audible pops or skips. Continue to monitor regression tests after the APU timing refactor lands.

---

Implementation Priority

1. Critical (v0.4.0): APU timing fix - Required for music playback
2. High (v0.5.0): CPU cycle counting accuracy - Required for game compatibility
3. High (v0.5.0): Main synchronization loop refactor - Foundation for accuracy
4. Medium (v0.6.0): PPU scanline renderer - Performance optimization
5. Low (ongoing): Code quality improvements - Technical debt reduction

---

Success Metrics

APU Timing Fix Success

• Music plays in all tested games
• Sound effects work correctly
• No audio glitches or stuttering
• Handshake completes within expected cycle count

Overall Emulation Accuracy

• CPU cycle accuracy within ±1 cycle per instruction
• APU synchronized within ±1 cycle with CPU
• PPU timing accurate to scanline level
• All test ROMs pass

Performance Targets

• 60 FPS on modest hardware (2015+ laptops)
• PPU optimizations provide 20%+ speedup
• Audio buffer never underruns in normal operation

---

Related Documentation

• docs/E4-Emulator-Development-Guide.md - Implementation details
• docs/E1-emulator-enhancement-roadmap.md - Feature roadmap
• docs/E5-debugging-guide.md - Debugging techniques

---

Status: Active Planning
Next Steps: Begin APU timing refactoring for v0.4.0