Setup#

Before debugging, compile your software with debug information. To achieve this, add the -g flag to your compilation command. This generates debug information even when optimizations are turned on. Note that higher optimization levels make debugging more difficult, so it might be helpful to turn off these optimizations using the -O0 compiler option.

Debugging using ROCgdb#

To start debugging your application, follow these steps:

1. Run ROCgdb with your ROCm application.

   rocgdb my_application
   

   At this point the application is not running, but you’ll have access to the debugger console. Here you can use every gdb option for host debugging and you can use them and extra ROCgdb specific features for device debugging.

2. Set a breakpoint before running the application with debugger.

   tbreak my_app.cpp:458
   

   This places a temporary breakpoint at the specified line. To start your application, use:

   run
   

   If the breakpoint is in the device code, the debugger shows the device and host threads. The device threads are not individual work items; instead, they represent a wavefront on the device. You can switch between the device wavefronts as you can between the host threads.

3. You can also switch between layouts, which allows you to use different layouts for different situations while debugging.

   layout src
   layout asm
   

   The src layout is the source code view, while the asm is the assembly view. For more layouts, see GDB documentation.

   info threads
   

   The preceding command lists all threads with Id and information on where the thread is stopped.

4. To switch threads, use:

   thread <id>
   

5. To take a step in the execution, use:

   next
   
   # Alternatively you can use the shorthand
   
   n
   

6. To dump the content of the current wavefront’s registers, use:

   info registers
   
   # Alternatively you can use the shorthand
   
   i r
   

   The preceding command only dumps the general purpose registers, which is all-inclusive data about the state of the current wavefront. To get data for all registers, use command info all-registers.

ROCgdb user guide#

The ROCgdb user guide provides detailed information about using ROCgdb. This user guide is also installed in the following directories when you install ROCm:

• /opt/rocm/share/info/rocgdb/gdb.info as a texinfo file

• /opt/rocm/share/doc/rocgdb/rocgdb.pdf as a PDF file

For specific information about debugging heterogeneous programs on ROCm software, refer to the following chapters in the ROCgdb user guide:

• Debugging Heterogeneous Programs: It provides general information about debugging heterogeneous programs. It also discusses features and commands that are not currently implemented but provisionally planned for future versions.

• Configuration-Specific Information > Architectures > AMD GPU: It provides specific information about debugging heterogeneous programs on ROCm software with supported AMDGPU chips. This section also lists the implementation status and known issues of the current version.

You can use the standard GDB commands for both CPU and GPU code debugging.