diff --git a/.wordlist.txt b/.wordlist.txt index 1f3d749067..72ad5476eb 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -28,6 +28,7 @@ BMC BitCode Blit Bluefield +breakpoint CCD CDNA CIFAR diff --git a/docs/how-to/rocgdb.rst b/docs/how-to/rocgdb.rst new file mode 100644 index 0000000000..55be8d17a8 --- /dev/null +++ b/docs/how-to/rocgdb.rst @@ -0,0 +1,99 @@ +.. meta:: + :description: This chapter describes the usage of ROCgdb, a tool for debugging + ROCm software. + :keywords: AMD, ROCm, HIP, ROCgdb, performance, debugging + +******************************************************************************* +ROCgdb +******************************************************************************* + +.. _rocgdb_introduction: +Introduction +=============================================================================== +This document introduces ROCgdb, the AMD ROCm debugger for Linux targets. + +ROCgdb is an extension to GDB, the GNU Project debugger. The tool provides developers +with a mechanism for debugging CUDA applications running on actual hardware. This +enables developers to debug applications without the potential variations introduced +by simulation and emulation environments. It is meant to present a seamless debugging +environment that allows simultaneous debugging of both GPU and CPU code within the +same application, just like programming in HIP is a seamless extension of C++ +programming. The existing GDB debugging features are inherently present for debugging +the host code, and additional features have been provided to support debugging ROCm +device code. + +ROCgdb supports HIP kernel debugging. It allows the user to set breakpoints, to +single-step ROCm applications, and also to inspect and modify the memory and variables +of any given thread running on the hardware. + +.. _rocgdb_installation: +Installation +=============================================================================== +The ROCm installation also installs the ROCgdb debugger, but some steps are necessary +before using the debugger. + +.. _rocgdb_setup: +Setup +=============================================================================== +Before debugging you have to compile your software with debug information. To do this +you have to add the '-g' flag for your compilation command. This will generate debug +information even when optimizations are turned on. Notice that higher optimization +levels make the debugging more difficult, so it might be useful to turn off these +optimizations by using the '-O0' compiler option. + +.. _rocgdb_debugging: +Debugging +=============================================================================== +This section is a brief introduction on how to use ROCgdb. For a more information on the +functionality of gdb look up the gdb documentation. + +First step is to 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. + +Before you run your application with the debugger, you'll need to set a breakpoint. + +``tbreak my_app.cpp:458`` + +This will place a breakpoint at the specified line. To start your application use this +command: + +``run`` + +If the breakpoint is in device code the debugger will show the device and host threads as +well. The device threads will not be individual threads, instead they represent a +wavefront on the device. You can switch between the device wavefronts, like you would +between host threads. + +You can also switch between layouts. 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. There are +further layouts you can look up on the gdb documentation. + +``info threads`` + +This command lists all threads with id and information on where the thread is stopped. + +To switch threads you can use the following command: + +``thread `` + +To take a step in the execution use: + +``n`` + +To dump the content of the current wavefronts registers use: + +``i r`` + +For further information on the usage of gdb, you can go to the `gdb documentation +`_. diff --git a/docs/index.md b/docs/index.md index b85ab88f38..6c7bb70d8b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -97,6 +97,7 @@ Our documentation is organized into the following categories: * [Setting up for deep learning with ROCm](./how-to/deep-learning-rocm.md) * [GPU-enabled MPI](./how-to/gpu-enabled-mpi.rst) * [System level debugging](./how-to/system-debugging.md) +* [ROCgdb](./how-to/rocgdb.rst) * [GitHub examples](https://github.com/amd/rocm-examples) ::: diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 433e30e811..214b2494dd 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -53,6 +53,8 @@ subtrees: title: Using MPI - file: how-to/system-debugging.md title: Debugging + - file: how-to/rocgdb.rst + title: ROCgdb - file: how-to/tuning-guides.md title: Tuning guides subtrees: