Commit | Line | Data |
---|---|---|
abeeff98 LM |
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`` |