🐳 melonds_gdb_debug_docker

Debug melonDS with pwngdb via the GDB protocol in a Docker environment 🚀

This repository provides a ready to use Docker setup for debugging melonDS using pwngdb, making ARM9 and ARM7 debugging much easier.

📦 Requirements

• Windows 10 / 11
• Docker Desktop for Windows
• WSL and Hyper V enabled

---

🛠 How to Use

1. Install Docker Desktop for Windows
   https://www.docker.com/products/docker-desktop/

2. Enable Hyper V and WSL via optionalfeatures.exe

3. Update WSL from a terminal
   wsl --update

4. Download this repository
   https://github.com/DaisukeDaisuke/melonds_gdb_debug_docker/archive/refs/heads/main.zip

5. Launch Docker Desktop 🐳

6. Run up.bat and wait until the setup completes ⏳

7. Enjoy debugging 🎉

---

🎮 Enable melonDS GDB Feature

1. Open Config > Emu settings

2. Go to Dev tools

   • Enable GDB stub
   • Set ports as follows:
     • ARM9 port: 64640
     • ARM7 port: 64641

---

✅ Recommended melonDS Fork

For debugging purposes, it is strongly recommended to use a melonDS fork that includes the changes proposed in PR #2424.

This fork improves GDB debugging behavior by stopping execution correctly on data aborts and by fixing issues in exception and breakpoint handling. These changes are important for stable low level debugging and for pwngdb based workflows.

In addition, this fork makes it possible to use extended hardware watchpoint and memory watch commands during debugging. These commands rely on correct exception handling and GDB stub behavior, which are addressed by the changes in PR #2424.

The following extended commands can be used with this fork:

• hwatch ADDRESS [SIZE] [TYPE]
  Set a hardware watchpoint on the specified address. Optional arguments can be used to specify access size and access type.

• info hw
  Display the currently active hardware watchpoints.

• dh ID [ID2 ...]
  Remove one or more specified hardware watchpoints.

• dh all
  Remove all active hardware watchpoints.

Example:

• Set a hardware write watchpoint on ARM9 memory: hwatch 0x02000000 4 w

• List active hardware watchpoints: info hw

These features are useful for tracking memory accesses, analyzing execution flow, and debugging Nintendo DS software at the ARM level.

Reference: melonDS-emu/melonDS#2424

---

🔌 GDB Commands

Connect to the target

target remote host.docker.internal:64640

---

Step execution

pwngdb> s

---

Run until function return

finish

---

Show instructions near PC

nearpc

---

Step to next call

nextcall

---

🛑 Breakpoints

Add breakpoint

b *0x02000000

List breakpoints

i b

Remove breakpoint

d <id>

Remove All breakpoint

d

---

🧠 This environment is especially useful for low level ARM debugging, exploit research, and reverse engineering on Nintendo DS software.

Enjoy hacking responsibly 🔍