> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/dolphin-emu/dolphin/llms.txt
> Use this file to discover all available pages before exploring further.

# DSP Emulation

> Technical details of GameCube and Wii DSP (Digital Signal Processor) emulation in Dolphin

The GameCube and Wii DSP (Digital Signal Processor) is responsible for audio processing and other signal processing tasks. Dolphin provides multiple approaches to DSP emulation, including a legal replacement ROM and interpreter implementations.

## DSP Overview

The DSP is a specialized processor that handles:

* Audio mixing and effects processing
* Microcode (UCode) execution for different audio systems
* DMA transfers between main memory and DSP memory
* Communication with the CPU via mailbox system

## CPU-DSP Communication

The CPU communicates with the DSP through a mailbox system. Here's the typical communication pattern:

### DSPSendCommands2 Function

This is a typical CPU-side function for sending commands to the DSP:

```c theme={null}
void DSPSendCommands2(_pBuffer, _NumberOfMessages, _StartWork)
{
    // Wait for DSP to be running
    while (!DSP_Running_Check());
    
    OldInterrupts = OSDisableInterrupts();

    // Check if DSP mailbox is ready
    if (DSPCheckMailToDSP() != 0)
    {
        OSRestoreInterrupts();
        return -1;
    }

    // Send number of messages
    DSPSendMailToDSP(_NumberOfMessages)
    
    // Trigger DSP interrupt
    DSPAssertInt()

    // Wait for mailbox to be ready
    while (DSPCheckMailToDSP() != 0) {}

    if (_NumberOfMessages == 0)
        _NumberOfMessages = 1

    // Optional: Start work
    if (_StartWork != 0)
    {
        r28 = DSPStartWork(*_pBuffer, _StartWork)
    }
    _StartWork = 0

    // Send all messages in buffer
    while(Count != _NumberOfMessages)
    {
        DSPSendMailToDSP(Buffer[Count])
        while (DSPCheckMailToDSP() != 0) {}
        Count++
    }

    OSRestoreInterrupts(OldInterrupts)

    return r28;
}
```

### Communication Flow

1. **Initialization**: CPU waits for DSP to be ready
2. **Message Count**: CPU sends the number of messages to transmit
3. **Interrupt**: CPU triggers DSP interrupt to signal new data
4. **Message Transfer**: CPU sends each message and waits for acknowledgment
5. **Completion**: Interrupts are restored and control returns

<Note>
  All DSP communication operations require disabling interrupts to ensure atomic mailbox operations.
</Note>

## Legal DSP ROM Replacement

Dolphin includes a legal replacement for the proprietary GameCube/Wii DSP IROM and DROM (coefficient ROM). This allows Dolphin to emulate DSP functionality without requiring copyrighted ROM dumps.

### Version History

<Accordion title="Version 0.4 (0xe789b5a5, 0xa4a575f5)">
  **Date**: August 17, 2021\
  **Authors**: Tilka, Pokechu22

  **Changes**:

  * Minor accuracy and documentation improvements
  * Removed use of SRS instruction with AX registers (instructions don't actually exist)
</Accordion>

<Accordion title="Version 0.3.1 (0x128ea7a2, 0xa4a575f5)">
  **Date**: August 10, 2017\
  **Author**: ligfx

  **Changes**:

  * When running from ROM entrypoint, skip bootucode\_ax branch
  * Prevents bad DMA transfers and crashes since ROM doesn't set AX registers
</Accordion>

<Accordion title="Version 0.3 (0x3aa4a793, 0xa4a575f5)">
  **Date**: June 2, 2017\
  **Author**: ligfx

  **Changes**:

  * Explicitly set 23 coefficient values used by GBA UCode
  * Tweaked parameters to match those 23 values more closely
  * Moved functions to proper places
  * Updated BootUCode to configure DMA using both AX and IX registers
  * Added partial functions used by GBA UCode
</Accordion>

<Accordion title="Version 0.2.1 (0xd9907f71, 0xdb6880c1)">
  **Date**: June 29, 2015\
  **Author**: stgn

  **Changes**:

  * **COEF**: 4-tap polyphase FIR filters
  * **IROM**: Unchanged
  * Coefficients roughly equivalent to official DROM
  * Greatly improved resampling quality over linear interpolation
</Accordion>

<Accordion title="Version 0.2 (0xd9907f71, 0xb019c2fb)">
  **Date**: March 16, 2013\
  **Author**: delroth

  **Changes**:

  * **COEF**: Linear interpolation for resampling (instead of real 4-tap FIR)
  * **IROM**: Added all mixing functions, some unused functions still missing
  * Works with AX, AXWii, and Zelda UCode games
  * Card/IPL/GBA UCodes likely still broken, require real DSP ROM
</Accordion>

<Accordion title="Version 0.1 (0x9c8f593c, 0x10000001)">
  **Date**: July 31, 2011\
  **Author**: LM

  **Changes**:

  * **COEF**: Fake (all zeroes)
  * **IROM**: Reversed and rewrote UCode loading/reset, everything else missing
  * Works with Zelda UCode games and some AX games
  * Compatible games: SMG 1/2, Pikmin 1/2, Zelda TP, Mario Kart DD, Luigi's Mansion, Super Mario Sunshine, etc.
  * Only works if game doesn't use COEF and IROM mixing functions
</Accordion>

### ROM Components

**IROM (Instruction ROM)**:

* Contains DSP microcode functions
* Handles UCode loading and initialization
* Provides mixing and audio processing routines
* DMA transfer configuration

**DROM/COEF (Coefficient ROM)**:

* Contains coefficients for FIR filters
* Used for audio resampling
* Critical for audio quality

### UCode Compatibility

| UCode Type | Support Status    | Notes                |
| ---------- | ----------------- | -------------------- |
| Zelda      | Full              | Supported since v0.1 |
| AX         | Full              | Supported since v0.2 |
| AXWii      | Full              | Supported since v0.2 |
| GBA        | Full              | Supported since v0.3 |
| Card       | Requires real ROM | Not fully supported  |
| IPL        | Requires real ROM | Not fully supported  |

### CRC Values

The legal ROM replacement generates specific CRC values:

| Version | IROM CRC   | DROM CRC   |
| ------- | ---------- | ---------- |
| 0.4     | 0xe789b5a5 | 0xa4a575f5 |
| 0.3.1   | 0x128ea7a2 | 0xa4a575f5 |
| 0.3     | 0x3aa4a793 | 0xa4a575f5 |
| 0.2.1   | 0xd9907f71 | 0xdb6880c1 |
| 0.2     | 0xd9907f71 | 0xb019c2fb |
| 0.1     | 0x9c8f593c | 0x10000001 |

<Warning>
  Dolphin may report wrong CRCs when using the legal ROM replacement instead of the official ROM, but this does not affect functionality for supported games.
</Warning>

## Filter Coefficients

The DROM contains coefficients for 4-tap polyphase FIR (Finite Impulse Response) filters used in audio resampling.

### Coefficient Generation

Starting with version 0.2.1, coefficients are generated using a Python script (`generate_coefs.py`) that:

1. Calculates optimal filter coefficients
2. Matches 23 specific values used by GBA UCode (v0.3+)
3. Provides quality comparable to official DROM

### Audio Quality Impact

| Version | Resampling Method    | Quality                                    |
| ------- | -------------------- | ------------------------------------------ |
| 0.1     | None (zeroes)        | Poor - only for games not using resampling |
| 0.2     | Linear interpolation | Basic                                      |
| 0.2.1+  | 4-tap polyphase FIR  | High - comparable to official              |

## DMA Transfers

The DSP uses DMA (Direct Memory Access) for efficient data transfer between main memory and DSP memory.

### BootUCode DMA Configuration

The BootUCode function configures DMA transfers using:

**IX Registers** (Index registers):

* Traditional method for DMA configuration
* Single transfer per call

**AX Registers** (Accumulator extended):

* Added in v0.3 for GBA UCode support
* Allows two sequential transfers in one call
* GBA UCode requires this functionality

<Note>
  Version 0.4 removed use of SRS instructions with AX registers, as these instructions don't actually exist in the real DSP hardware.
</Note>

## DSP User's Manual

The repository includes a comprehensive LaTeX-based DSP User's Manual with detailed instruction set documentation.

### Building the Manual

1. Install a LaTeX environment (e.g., MiKTeX)
2. Install required packages listed in `GameCube_DSP_Users_Manual.tex`
3. Run pdflatex twice:
   ```bash theme={null}
   pdflatex GameCube_DSP_Users_Manual.tex
   pdflatex GameCube_DSP_Users_Manual.tex
   ```
4. The second pass builds the table of contents and indexes

<Accordion title="Required LaTeX Packages">
  Search for `\usepackage` statements in the TEX file to find all dependencies. Common packages include:

  * Standard document formatting packages
  * Code listing packages
  * Diagram and table packages
  * Index generation packages
</Accordion>

## Implementation Notes

### Dolphin DSP Emulation Modes

Dolphin offers multiple DSP emulation backends:

1. **DSP HLE (High-Level Emulation)**:
   * Fast, high-level reimplementation
   * Doesn't require DSP ROM
   * May have compatibility issues with some games

2. **DSP LLE Interpreter**:
   * Low-level emulation
   * Accurate but slower
   * Uses legal ROM replacement or real DSP ROM

3. **DSP LLE Recompiler**:
   * Low-level emulation with JIT compilation
   * Balance of accuracy and performance
   * Uses legal ROM replacement or real DSP ROM

### Performance Considerations

* HLE is fastest but may have audio glitches
* LLE Interpreter is most accurate but CPU-intensive
* LLE Recompiler provides good accuracy with better performance
* Legal ROM replacement has minimal performance impact vs real ROM

<Note>
  For most games, the legal DSP ROM replacement provides full compatibility with the LLE backends while avoiding copyright concerns.
</Note>