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.
10 All standard GDB commands can be used for both CPU and GPU code debugging. In particular:
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
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.
22 For more information about ROCm and ROCgdb, please refer to the Release Notes
23 which includes current restrictions:
25 - https://github.com/RadeonOpenCompute/ROCm
27 For more information about GDB, please refer to the README file in this folder
28 or check the GDB home page at:
30 - http://www.gnu.org/software/gdb
32 Build the ROCm Debugger
33 -----------------------
35 ROCgdb can be built on Ubuntu 16.04, Ubuntu 18.04, and Centos 7.6.
37 Building ROCgdb has the following prerequisites:
39 1. A C++11 compiler such as GCC 4.8 or Clang 3.3.
41 2. AMD Debugger API Library (ROCdbgapi) which can be installed as part of the
42 ROCm release by the ``rocm-dbgapi`` package.
44 3. For Ubuntu 16.04 and Ubuntu 18.04 the following adds the needed packages:
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
52 4. For Centos 7.6 the following adds the needed packages:
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
61 An example command-line to build ROCgdb on Linux is:
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
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
80 The built ROCgdb executable will be placed in:
90 The installed ROCgdb will be placed in:
92 - ``<prefix>/bin/rocgdb``
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:
98 - ``librocm-dbgapi.so.0``
99 - ``libamd_comgr.so.1``