How to Perform User-Space Remote Debugging with gdbserver on RISC-V Linux

[fanghuaqi]

When performing user-space application debugging on a RISC-V Linux system using gdbserver and a remote riscv64-unknown-linux-gnu-gdb, it is essential to ensure that software breakpoints (inserted as ebreak instructions) are handled by the Linux kernel—not the hardware debug module.

🔑 Critical OpenOCD Configuration

If you use OpenOCD to load and launch the operating system (e.g., during development or via flash programming as described in Nuclei Studio Flash Programming), OpenOCD enables ebreaku and ebreaks by default to support low-level firmware debugging. However, this setting breaks user-space gdbserver, causing the hart to halt in Debug Mode instead of delivering SIGTRAP to the application.

To fix this, explicitly disable user and supervisor ebreak traps before resuming into Linux:

# In your OpenOCD script, after init and halt and before resume
riscv set_ebreaku off
riscv set_ebreaks off

This ensures that:

• User-mode ebreak → traps to S-mode (handled by Linux as SIGTRAP)
• gdbserver can function normally with breakpoints, stepping, etc.

⚠️ Note: The dcsr register cannot be modified from software (not even in M-mode). Only OpenOCD (via JTAG in Debug Mode) can configure these bits.

📚 Background

This issue and solution are discussed in detail in the SiFive community forum:
Remote GDB of Linux app

✅ Workflow Summary

1. Use OpenOCD to load firmware/kernel with:

   riscv set_ebreaku off
   riscv set_ebreaks off

2. Resume into Linux and ensure network is ready.
3. On target: gdbserver :1234 ./app
4. On host:

   riscv64-unknown-linux-gnu-gdb ./app
   (gdb) target remote <target>:1234

With this configuration, user-space remote debugging works reliably on RISC-V Linux platforms.