Debugging Support

Learn how to use Hydra’s debugging features including GDB support and logging

Hydra includes comprehensive debugging capabilities for developers, including GDB server support, symbol tables, and detailed logging.

GDB Debugging Support

Hydra features a built-in GDB server that allows you to debug guest (Nintendo Switch) code using standard GDB tools.

GDB Server Architecture

src/core/debugger/gdb_server.hpp

class GdbServer {
  public:
    GdbServer(Debugger& debugger);
    ~GdbServer();
    
    void RegisterThread(Thread& thread);
    void NotifySupervisorPaused(horizon::kernel::GuestThread* thread,
                                Signal signal);
    void BreakpointHit(horizon::kernel::GuestThread* thread);
    
  private:
    i32 server_socket;
    i32 client_socket;
    std::thread server_thread;
    std::atomic<bool> running;
    
    std::vector<vaddr_t> breakpoint_addresses;
    std::map<vaddr_t, u32> replaced_instructions;
};

The GDB server runs on a separate thread and communicates with GDB clients over TCP/IP.

Supported GDB Features

Register Access

Read and write ARM64 registers:

void HandleRegRead(std::string_view command);
std::string ReadReg(u32 id);

Supported registers:

• General purpose (x0-x31)
• Special registers (PC, SP, LR)
• FP/SIMD registers (v0-v31)
• System registers (PSTATE, etc.)

Memory Access

Read guest memory during debugging:

void HandleMemRead(std::string_view command);

• Read arbitrary memory addresses
• Supports page-granular access
• Respects memory protection

Breakpoints

Set and manage breakpoints:

void HandleInsertBreakpoint(std::string_view command);
void HandleRemoveBreakpoint(std::string_view command);

std::vector<vaddr_t> breakpoint_addresses;
std::map<vaddr_t, u32> replaced_instructions;

Breakpoint types:

• Software breakpoints (BRK instruction)
• Hardware breakpoints (CPU backend dependent)

Thread Control

Control thread execution:

void HandleVCont(std::string_view command);
void HandleSetActiveThread(std::string_view command);
void HandleThreadStatus();

• Continue/pause threads
• Switch active thread
• Query thread status

Executable Information

Query loaded executables:

void HandleGetExecutables();

• List loaded modules
• Get memory ranges
• Symbol information

Enabling GDB Debugging

To use GDB debugging with Hydra:

1. Enable GDB in Configuration

   Edit your config.toml:

   [debug]
   gdb_enabled = true
   gdb_port = 1234
   gdb_wait_for_client = false  # Wait for GDB before starting
   
2. Start Hydra

   Launch the emulator. The GDB server will start listening on the configured port.

   hydra game.nsp
   

   You should see a log message indicating the GDB server is ready.

3. Connect GDB Client

   Use gdb or a compatible debugger:

   gdb-multiarch
   (gdb) target remote localhost:1234
   (gdb) set architecture aarch64
   
4. Debug Your Game

   Set breakpoints and debug:

   (gdb) break *0x7100000000
   (gdb) continue
   (gdb) info registers
   (gdb) x/10i $pc
   

If gdb_wait_for_client is true, the emulator will pause at startup until a GDB client connects.

GDB Protocol Support

The GDB server implements standard RSP (Remote Serial Protocol) commands:

src/core/debugger/gdb_server.cpp

const char GDB_START = '$';
const char GDB_END = '#';
const char GDB_ACK = '+';
const char GDB_NACK = '-';

const char GDB_OK[] = "OK";
const char GDB_ERROR[] = "E01";

Target XML

The server provides AArch64 target description:

std::string_view get_target_xml_aarch64() {
    return R"(<?xml version="1.0"?>
    <!DOCTYPE target SYSTEM "gdb-target.dtd">
    <target version="1.0">
      <architecture>aarch64</architecture>
      <feature name="org.gnu.gdb.aarch64.core">
        <reg name="x0" bitsize="64"/>
        <reg name="x1" bitsize="64"/>
        ...
      </feature>
    </target>)";
}

Debugger Framework

Hydra includes a comprehensive debugging framework beyond GDB:

Debugger Class

src/core/debugger/debugger.hpp

class Debugger {
  public:
    Debugger(const std::string_view name, 
             horizon::kernel::Process* process);
    
    // Thread management
    void RegisterThisThread(const std::string_view name);
    void UnregisterThisThread();
    
    // Breakpoints
    void BreakOnThisThread(fmt::format_string<T...> f, T&&... args);
    
    // Symbols
    SymbolTable& GetModuleTable();
    SymbolTable& GetFunctionTable();
    
    // GDB
    void ActivateGdbServer();
    void NotifySupervisorPaused(horizon::kernel::GuestThread* thread,
                                Signal signal);
    void BreakpointHit(horizon::kernel::GuestThread* thread);
};

Thread Management

Guest Threads

Track Nintendo Switch threads:

class Thread {
  public:
    Thread(const std::string_view name);
    
    const std::string& GetName() const;
    ThreadStatus GetStatus() const;
    const std::string& GetBreakReason() const;
    
  private:
    std::string name;
    horizon::kernel::GuestThread* guest_thread;
    ThreadStatus status;
    std::string break_reason;
};

Thread Status

Monitor thread execution state:

enum class ThreadStatus {
    Running,
    Break,
};

• Running: Thread is executing normally
• Break: Thread hit a breakpoint or debugger assertion

Symbol Tables

The debugger maintains symbol tables for modules and functions:

src/core/debugger/debugger.hpp

struct Symbol {
    std::string name;
    Range<vaddr_t> guest_mem_range;
};

class SymbolTable {
  public:
    void RegisterSymbol(const Symbol& symbol);
    std::string FindSymbol(vaddr_t addr);
    
  private:
    std::vector<Symbol> symbols;
};

Module Symbols

Track loaded executables and libraries:

debugger.GetModuleTable().RegisterSymbol({
    "game.nso",
    Range<vaddr_t>(0x7100000000, 0x7100800000)
});

Function Symbols

Register individual functions for better debugging:

debugger.GetFunctionTable().RegisterSymbol({
    "main",
    Range<vaddr_t>(0x7100001000, 0x7100001100)
});

Debug Assertions

Use debug assertions in your code:

src/core/debugger/debugger.hpp

#define DEBUGGER_ASSERT(condition, c, f, ...) \
    if (!(condition)) { \
        GET_CURRENT_PROCESS_DEBUGGER().BreakOnThisThread( \
            f PASS_VA_ARGS(__VA_ARGS__)); \
    }

#ifdef HYDRA_DEBUG
#define DEBUGGER_ASSERT_DEBUG(condition, c, ...) \
    DEBUGGER_ASSERT(condition, c, __VA_ARGS__)
#else
#define DEBUGGER_ASSERT_DEBUG(condition, c, ...) \
    if (condition) {}
#endif

DEBUGGER_ASSERT_DEBUG is only active in debug builds, while DEBUGGER_ASSERT is always active.

Stack Traces

The debugger can capture and resolve stack traces:

struct StackFrame {
    Debugger* debugger;
    StackFrameType type;  // Host or Guest
    u64 addr;
    
    ResolvedStackFrame Resolve() const;
};

struct ResolvedStackFrame {
    std::string module;
    std::string function;
    u64 addr;
};

Message Logging

Capture debug messages with stack traces:

struct Message {
    LogMessage log;
    StackTrace stack_trace;
};

Each thread maintains a ring buffer of messages for inspection.

Logging Configuration

Control debug output verbosity:

config.toml

[debug]
log_output = "file"        # "none", "stdout", or "file"
log_fs_access = false      # Log filesystem operations
debug_logging = true       # Enable verbose debug logs

None

Disables all logging output

• Fastest performance
• No debug information
• Not recommended

StdOut

Logs to standard output

• Real-time viewing
• Good for development
• Can clutter terminal

File

Logs to file in logs directory

• Recommended for debugging
• Doesn’t impact terminal
• Easy to share logs
• Searchable history

CPU Backend Differences

Debug capabilities vary by CPU backend:

Apple Hypervisor

Debug Features:

• Native hardware breakpoints
• Fast breakpoint handling
• Debug exception trapping
• No single-step support

features.supports_native_breakpoints = true;
features.supports_synchronous_single_step = false;

Dynarmic

Debug Features:

• Software breakpoints
• Single-step execution
• Instruction-level debugging
• Exception callbacks

features.supports_native_breakpoints = false;
features.supports_synchronous_single_step = true;

For the best debugging experience, use the Dynarmic CPU backend which supports single-stepping.

Advanced Debugging

Executable Registration

Register executables for symbol resolution:

debugger.RegisterExecutable("game.nso", executable_file);

Custom Debug Commands

The GDB server supports custom commands via monitor:

void HandleRcmd(std::string_view command);

Use in GDB:

(gdb) monitor help
(gdb) monitor executables

Best Practices

1. Use Dynarmic for Development

   The Dynarmic CPU backend provides better debugging support with single-step capability.

2. Enable File Logging

   Set log_output = "file" to capture all debug information without cluttering your terminal.

3. Register Symbols

   Register module and function symbols to get meaningful stack traces and breakpoint names.

4. Use Debug Builds

   Build Hydra in debug mode for additional assertions and checks:

   cmake -DCMAKE_BUILD_TYPE=Debug ..
   

Common Debug Workflows

Debugging a Crash

1. Enable GDB and file logging
2. Reproduce the crash
3. Check logs for stack trace
4. Connect GDB at crash point
5. Examine registers and memory

Analyzing Game Behavior

1. Set breakpoint at function of interest
2. Run until breakpoint hit
3. Single-step through code (Dynarmic)
4. Inspect registers and memory
5. Continue or repeat

Performance Profiling

1. Enable performance logging
2. Run game for representative period
3. Analyze logs for hotspots
4. Use GDB to understand slow code
5. Optimize as needed

Combine GDB debugging with Hydra’s logging system for the most comprehensive debugging experience.

Troubleshooting

GDB Won't Connect

• Check gdb_enabled = true in config
• Verify port is not in use (default 1234)
• Ensure firewall allows connection
• Try telnet localhost 1234 to test

Breakpoints Not Working

• Verify address is correct
• Check if code is loaded at that address
• Try hardware breakpoints (Hypervisor)
• Switch to Dynarmic backend for software breakpoints

Missing Symbols

• Register executables with debugger
• Load symbol files if available
• Use info symbol in GDB
• Check module table registration