2 GDB Quickstart

GreemDev edited this page 2025-08-26 00:07:01 -05:00

Unescape Escape

Table of Contents

• Installing GDB
• Note: If you're a Windows user, it's highly recommended to use GDB through WSL or on a Linux machine instead. In our experience, using aarch64 gdb on Windows causes many issues.
• Enabling the GDB Stub in Ryujinx
• Connecting GDB to a Game
• Steps:
• Actually Using GDB

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This is a quick start guide for using GDB on Ryujinx, intended for users who want to debug games or mods more easily on Ryujinx.

NOTE: Ryujinx’s GDB Stub still lacks some features (e.g., watchpoints). If possible for your situation, it’s highly recommended to use real Switch hardware with Atmosphere for GDB debugging instead.

Guide for using GDB on a modded Switch running Atmosphere: GDB for Switch Modding Cheatsheet/Tutorial

Installing GDB

Note: If you're a Windows user, it's highly recommended to use GDB through WSL or on a Linux machine instead. In our experience, using aarch64 gdb on Windows causes many issues.

The device you install GDB on can be different from the one running Ryujinx.

Tutorial

Enabling the GDB Stub in Ryujinx

To use the GDB Stub, you need Ryujinx Canary version 1.3.109 or Stable 1.3.3 (when it exists, this is the next indev stable release as of writing) or newer.

1. Go to Ryujinx → Options → Debug
2. Enable GDB Stub and set the GDB Stub Port (e.g. 22225)

Connecting GDB to a Game

First, find the local IP address of the PC running Ryujinx.

On Windows, press Win + X → Terminal → ipconfig → Look for something like 192.168.0.5.

If you are using WSL, see Accessing Windows networking apps from Linux (host IP)

Make sure the computer you're connecting from is on the same network as the computer running Ryujinx.

Anywhere you see <ip addr>, replace it with the IP address of the PC running Ryujinx. For example, <ip addr>:22225 becomes 192.168.0.5:22225.

Steps:

1. Make sure the game you want to debug is already running or launching in Ryujinx.

2. Open a terminal and start GDB:

gdb-multiarch

or

aarch64-none-elf-gdb

3. Connect GDB to Ryujinx using this command: (Note: (gdb) is the prompt; type only the part after it. 22225 is the port you set in Ryujinx Debug settings.)

(gdb) target extended-remote <ip addr>:22225

4. If successful, the game running in Ryujinx will be attached and paused. You should see something like:

Remote debugging using 192.168.0.5:22225
warning: No executable has been specified and target does not support
determining executable automatically.  Try using the "file" command.
0x00000000102eb2d8 in ?? ()
=> 0x00000000102eb2d8:  41 03 00 d4     svc     #0x1a

Note: You do not need to run attach 0xNN — the application is automatically attached when you connect.

Actually Using GDB

Once connected, the application will be attached and paused.

Use c to continue execution and press Ctrl+C to interrupt.

Helpful resources:

• GDB for Switch Modding Cheatsheet/Tutorial
• Run monitor help in GDB to see extra supported commands:
  • monitor backtrace (mo bt) - show stack trace for the current thread, use Ryujinx GetGuestStackTrace
  • monitor registers (mo reg) - display register values for the current thread, use Ryujinx GetCpuRegisterPrintout
  • monitor get info - show process information like memory layout and loaded modules