| 1 | ROCm Debugger (ROCgdb) |
| 2 | ====================== |
| 3 | |
| 4 | This is ROCgdb, the ROCm source-level debugger for Linux, based on GDB, the GNU |
| 5 | source-level debugger. It includes support for heterogenous debugging on the |
| 6 | ROCm platform of an x86-based host architecture together with the AMD |
| 7 | commercially available GPU architectures supported by the AMD Debugger API which |
| 8 | is included with the ROCm release as the ROCdbgapi library. |
| 9 | |
| 10 | All standard GDB commands can be used for both CPU and GPU code debugging. In particular: |
| 11 | |
| 12 | - The ``info threads`` command lists both CPU threads and GPU waves. |
| 13 | - The ``info sharedlibrary`` command lists both loaded CPU and GPU code objects. |
| 14 | - The new ``info agents`` command lists the heterogenous agents once the program |
| 15 | has started. |
| 16 | |
| 17 | The ``_wave_id`` convenience variable can be used when the focused thread is a |
| 18 | GPU wave. It returns a string with the following format ``x,y,z/w`` where `x`, |
| 19 | ``y``, and ``z`` are the grid position of the wave's work-group in the dispatch, |
| 20 | and ``w`` is the wave's number within the work-group. |
| 21 | |
| 22 | For more information about ROCm and ROCgdb, please refer to the Release Notes |
| 23 | which includes current restrictions: |
| 24 | |
| 25 | - https://github.com/RadeonOpenCompute/ROCm |
| 26 | |
| 27 | For more information about GDB, please refer to the README file in this folder |
| 28 | or check the GDB home page at: |
| 29 | |
| 30 | - http://www.gnu.org/software/gdb |
| 31 | |
| 32 | Build the ROCm Debugger |
| 33 | ----------------------- |
| 34 | |
| 35 | ROCgdb can be built on Ubuntu 16.04, Ubuntu 18.04, and Centos 7.6. |
| 36 | |
| 37 | Building ROCgdb has the following prerequisites: |
| 38 | |
| 39 | 1. A C++11 compiler such as GCC 4.8 or Clang 3.3. |
| 40 | |
| 41 | 2. AMD Debugger API Library (ROCdbgapi) which can be installed as part of the |
| 42 | ROCm release by the ``rocm-dbgapi`` package. |
| 43 | |
| 44 | 3. For Ubuntu 16.04 and Ubuntu 18.04 the following adds the needed packages: |
| 45 | |
| 46 | ````shell |
| 47 | apt install bison flex gcc make ncurses-dev texinfo g++ \ |
| 48 | zlib1g-dev libexpat-dev libpython2.7-dev python2.7-minimal liblzma-dev \ |
| 49 | libbabeltrace-dev libbabeltrace-ctf-dev |
| 50 | ```` |
| 51 | |
| 52 | 4. For Centos 7.6 the following adds the needed packages: |
| 53 | |
| 54 | ````shell |
| 55 | yum install -y epel-release centos-release-scl |
| 56 | yum install -y bison flex gcc make texinfo gcc-c++ \ |
| 57 | zlib-devel expat-devel python-devel xz-devel \ |
| 58 | libbabeltrace-devel ncurses-devel |
| 59 | ```` |
| 60 | |
| 61 | An example command-line to build ROCgdb on Linux is: |
| 62 | |
| 63 | ````shell |
| 64 | cd rocgdb |
| 65 | mkdir build |
| 66 | cd build |
| 67 | ../configure --program-prefix=roc \ |
| 68 | --enable-64-bit-bfd --enable-targets="x86_64-linux-gnu,amdgcn-amd-amdhsa" \ |
| 69 | --disable-ld --disable-gas --disable-gdbserver --disable-sim --enable-tui \ |
| 70 | --disable-gdbtk --disable-shared --with-expat --with-system-zlib \ |
| 71 | --without-guile --with-babeltrace --with-lzma --with-python |
| 72 | make |
| 73 | ```` |
| 74 | |
| 75 | Specify ``--with-rocm-dbgapi=PATH`` if the the AMD Debugger API Library |
| 76 | (ROCdbgapi) is not installed in its default location. The ``configure`` script |
| 77 | looks in ``PATH/include`` and ``PATH/lib``. The default value for ``PATH`` is |
| 78 | ``/opt/rocm``. |
| 79 | |
| 80 | The built ROCgdb executable will be placed in: |
| 81 | |
| 82 | - ``build/gdb/gdb`` |
| 83 | |
| 84 | To install ROCgdb: |
| 85 | |
| 86 | ````shell |
| 87 | make install |
| 88 | ```` |
| 89 | |
| 90 | The installed ROCgdb will be placed in: |
| 91 | |
| 92 | - ``<prefix>/bin/rocgdb`` |
| 93 | |
| 94 | To execute ROCgdb, the ROCdbgapi library and its dependent ROCcomgr library must |
| 95 | be installed. These can be installed as part of the ROCm release by the |
| 96 | ``rocm-dbgapi`` package: |
| 97 | |
| 98 | - ``librocm-dbgapi.so.0`` |
| 99 | - ``libamd_comgr.so.1`` |