Debugging Tools & Techniques

Tools and techniques for debugging Dolphin Emulator

Overview

Debugging Dolphin requires a combination of traditional debugging tools, emulator-specific features, and knowledge of GameCube/Wii hardware. This guide covers the essential debugging workflows.

Development Builds

Debug vs Release Builds

Debug Build

Build with debug symbols and assertions enabled:

cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build

Benefits:

• Full debug symbols
• Assertions enabled
• No optimization (easier to step through)
• Better stack traces

Drawbacks:

• Significantly slower execution
• Larger binary size

RelWithDebInfo

Build with optimizations but retain debug symbols:

cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build

Benefits:

• Debug symbols available
• Optimized performance
• Good balance for debugging performance issues

Drawbacks:

• Harder to step through optimized code
• Some variables may be optimized away

Release Build

Fully optimized production build:

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

Use this for performance testing, not debugging.

For most debugging work, use Debug builds. For performance profiling, use RelWithDebInfo.

Debugger Setup

Visual Studio (Windows)

1. Open solution

   Open the generated Dolphin.sln in Visual Studio after running CMake.

2. Set startup project

   Right-click the dolphin-emu project and select “Set as Startup Project”.

3. Configure debugging

   Set breakpoints by clicking in the left margin of the code editor.

4. Start debugging

   Press F5 to start debugging, or Ctrl+F5 to run without debugging.

Useful shortcuts:

• F5: Start/continue debugging
• F9: Toggle breakpoint
• F10: Step over
• F11: Step into
• Shift+F11: Step out

Visual Studio Code

launch.json

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Dolphin",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/build/Binaries/dolphin-emu",
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "environment": [],
      "externalConsole": false,
      "MIMode": "gdb",
      "setupCommands": [
        {
          "description": "Enable pretty-printing",
          "text": "-enable-pretty-printing",
          "ignoreFailures": true
        }
      ]
    }
  ]
}

tasks.json

Create .vscode/tasks.json for building:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build Dolphin",
      "type": "shell",
      "command": "cmake --build build --config Debug",
      "group": {
        "kind": "build",
        "isDefault": true
      }
    }
  ]
}

GDB (Linux)

# Start with GDB
gdb ./build/Binaries/dolphin-emu

# Common GDB commands
(gdb) break Core::RunLoop     # Set breakpoint
(gdb) run                      # Start program
(gdb) next                     # Step over (n)
(gdb) step                     # Step into (s)
(gdb) continue                 # Continue execution (c)
(gdb) print variable_name      # Print variable (p)
(gdb) backtrace               # Show stack trace (bt)
(gdb) quit                     # Exit GDB

Enable pretty printing for STL containers:

# Add to ~/.gdbinit
set print pretty on
set print object on
set print static-members on
python
import sys
sys.path.insert(0, '/usr/share/gcc/python')
from libstdcxx.v6.printers import register_libstdcxx_printers
register_libstdcxx_printers(None)
end

LLDB (macOS)

# Start with LLDB
lldb ./build/Binaries/dolphin-emu

# Common LLDB commands
(lldb) breakpoint set -n Core::RunLoop   # Set breakpoint
(lldb) run                                # Start program
(lldb) next                               # Step over (n)
(lldb) step                               # Step into (s)
(lldb) continue                           # Continue execution (c)
(lldb) frame variable variable_name       # Print variable
(lldb) bt                                 # Show stack trace

Logging and Diagnostics

Log Levels

Dolphin uses different log levels for diagnostic output:

#include "Common/Logging/Log.h"

// Different log levels
DEBUG_LOG_FMT(VIDEO, "Debug message: {}", value);
INFO_LOG_FMT(VIDEO, "Info message: {}", value);
NOTICE_LOG_FMT(VIDEO, "Notice message: {}", value);
WARN_LOG_FMT(VIDEO, "Warning message: {}", value);
ERROR_LOG_FMT(VIDEO, "Error message: {}", value);

Log types (first parameter):

• VIDEO: Video backend
• AUDIO: Audio processing
• CORE: Core emulation
• BOOT: Boot process
• POWERPC: PowerPC CPU
• IOS: IOS emulation
• DSP: DSP emulation

Viewing Logs

GUI

In Dolphin’s UI:

1. View → Show Log
2. View → Show Log Configuration
3. Enable desired log types and levels

Console

Run Dolphin from terminal to see logs in real-time:

./dolphin-emu 2>&1 | tee dolphin.log

Log File

Logs are saved to:

• Windows: %USERPROFILE%\Documents\Dolphin Emulator\Logs\
• Linux: ~/.local/share/dolphin-emu/Logs/
• macOS: ~/Library/Application Support/Dolphin/Logs/

Adding Debug Logging

When debugging issues, add temporary logging:

INFO_LOG_FMT(CORE, "Function called with value: {:#x}", value);
DEBUG_LOG_FMT(VIDEO, "Texture cache size: {}", texture_cache.size());

// Format multiple values
DEBUG_LOG_FMT(POWERPC, "PC: {:#010x}, LR: {:#010x}, Instr: {:#010x}",
              PC, LR, instruction);

Remove or disable verbose debug logging before submitting pull requests.

Message Handlers

Custom Assertions

Dolphin uses a custom message handler for assertions and errors:

#include "Common/MsgHandler.h"

// In tests, assertions are caught
bool TestMsgHandler(const char* caption, const char* text, 
                    bool yes_no, Common::MsgType style)
{
  fmt::print(stderr, "{}\n", text);
  ADD_FAILURE();  // For test framework
  return true;     // Return yes to any question
}

Common::RegisterMsgAlertHandler(TestMsgHandler);

This prevents the emulator from breaking on assertions during testing.

Common Debugging Scenarios

Debugging Crashes

1. Get stack trace

   When Dolphin crashes, capture the stack trace:

   • Windows: Check Event Viewer or use Visual Studio debugger
   • Linux: ulimit -c unlimited && ./dolphin-emu then gdb dolphin-emu core
   • macOS: Check Console.app for crash reports
2. Enable core dumps

   Configure system to save core dumps:

   # Linux
   ulimit -c unlimited
   sudo sysctl -w kernel.core_pattern=/tmp/core-%e.%p.%h.%t
   
3. Analyze with debugger

   Load core dump:

   gdb ./dolphin-emu /tmp/core-dolphin-emu.12345
   (gdb) backtrace full
   

Debugging JIT Code

For JIT compiler issues:

// Enable JIT logging
DEBUG_LOG_FMT(DYNA_REC, "Compiling block at {:#010x}", address);

// Disable JIT for specific functions
if (address == 0x80001234)
{
  // Fall back to interpreter
  return false;
}

Use the “Enable Debugging UI” option in Dolphin settings to access JIT-related debugging features.

Memory Issues

AddressSanitizer

Build with ASan to detect memory errors:

cmake -B build -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_CXX_FLAGS="-fsanitize=address -fno-omit-frame-pointer"
cmake --build build

Valgrind

Run under Valgrind (Linux):

valgrind --leak-check=full --track-origins=yes ./dolphin-emu

Memory Debugger

Use Dolphin’s built-in memory viewer:

1. View → Memory
2. Navigate to address
3. Set memory breakpoints

Performance Issues

1. Profile with built-in tools

   Enable performance statistics:

   • View → Show Performance Monitor
   • View → Show FPS counter
2. Use external profilers

   Linux:

   perf record -g ./dolphin-emu
   perf report
   

   Windows:

   • Visual Studio Profiler
   • Intel VTune

   macOS:

   • Instruments (Xcode)
3. Identify bottlenecks

   Look for hot paths in profiler output and optimize accordingly.

Emulator-Specific Debugging

Code Breakpoints

Dolphin includes a debugger for the emulated PowerPC CPU:

1. View → Code: Open the code debugger
2. Set breakpoints on PowerPC addresses
3. Step through emulated code instruction by instruction
4. View registers, memory, and call stack

Memory Breakpoints

Break when emulated code accesses specific memory:

1. View → Memory: Open memory viewer
2. Right-click on address → Add Breakpoint
3. Choose read, write, or read/write breakpoint

Register Tracking

Monitor PowerPC register changes:

1. View → Registers: Open register window
2. Watch values change as code executes
3. Edit registers to test different scenarios

Unit Test Debugging

When debugging failing tests:

# Run specific test under debugger
gdb --args ./Binaries/Tests/tests --gtest_filter="BitField.Storage"

# Set breakpoint in GDB
(gdb) break BitFieldTest.cpp:59
(gdb) run

# When breakpoint hits, inspect
(gdb) print object
(gdb) print object.hex

See the Testing guide for more information on running and writing tests.

Best Practices

1. Use assertions

   Add assertions to catch invalid states early:

   ASSERT(pointer != nullptr);
   DEBUG_ASSERT(index < size);
   
2. Validate assumptions

   Check preconditions and postconditions:

   void Process(const Data* data)
   {
     ASSERT(data != nullptr);
     // ... processing ...
     ASSERT(result.IsValid());
   }
   
3. Use descriptive variable names

   Makes debugging easier when inspecting variables:

   // Good - clear in debugger
   int texture_cache_hits = 0;
   
   // Bad - unclear in debugger
   int tch = 0;
   
4. Isolate the problem

   Narrow down the issue:

   • Binary search commits with git bisect
   • Disable features to identify culprit
   • Create minimal reproduction case
5. Document findings

   Keep notes about:

   • What you tried
   • What worked/didn’t work
   • Root cause analysis

Compiler Warnings

Always fix compiler warnings. They often indicate real bugs.

Enable additional warnings:

cmake -B build -DCMAKE_CXX_FLAGS="-Wall -Wextra -Wpedantic"

Treat warnings as errors during development:

cmake -B build -DCMAKE_CXX_FLAGS="-Werror"

Getting Help

If you’re stuck debugging an issue:

1. Search existing issues: Check GitHub for similar problems
2. Ask on IRC: #dolphin-emu @ irc.libera.chat
3. Create detailed report: Include:
   • Steps to reproduce
   • Expected vs actual behavior
   • Stack traces or logs
   • Build configuration
   • System information

Next Steps

Code Style

Review coding standards and formatting

Testing

Learn about unit testing practices