Commit | Line | Data |
---|---|---|
abeeff98 LM |
1 | ROCm Debugger (ROCgdb) |
2 | ====================== | |
3 | ||
b7bc1207 T |
4 | The ROCm Debugger (ROCgdb) is the ROCm source-level debugger for Linux, based on |
5 | the GNU Debugger (GDB). It enables heterogenous debugging on the ROCm platform | |
6 | of an x86-based host architecture along with AMD GPU architectures supported by | |
7 | the AMD Debugger API Library (ROCdbgapi). The AMD Debugger API Library | |
8 | (ROCdbgapi) is included with the ROCm release. | |
9 | ||
340cf1ee | 10 | The current ROCm Debugger (ROCgdb) is an initial prototype that focuses on |
b7bc1207 T |
11 | source line debugging and does not provide symbolic variable debugging |
12 | capabilities. The user guide presents features and commands that may be | |
13 | implemented in future versions. | |
14 | ||
15 | For more information about ROCm, see: | |
abeeff98 LM |
16 | |
17 | - https://github.com/RadeonOpenCompute/ROCm | |
18 | ||
b7bc1207 T |
19 | You can use the standard GDB commands for both CPU and GPU code debugging. For |
20 | more information about ROCgdb, refer to the *ROCgdb User Guide* which is | |
21 | installed at: | |
22 | ||
23 | - ``/opt/rocm/share/info/gdb.info`` as a texinfo file | |
24 | - ``/opt/rocm/share/doc/gdb/gdb.pdf`` as a PDF file | |
25 | ||
26 | You can refer to the following chapters in the *ROCgdb User Guide* for more | |
27 | specific information about debugging heterogenous programs on ROCm: | |
28 | ||
29 | - *Debugging Heterogeneous Programs* provides general information about | |
30 | debugging heterogenous programs. | |
31 | - *Configuration-Specific Information > Architectures > AMD GPU* provides | |
32 | specific information about debugging heterogenous programs on ROCm with | |
33 | supported AMD GPU chips. This section also lists the features, commands, and | |
34 | known issues that may be implemented and resolved in future releases. | |
35 | ||
36 | For more information about the GNU Debugger (GDB), refer to the ``README`` file | |
37 | in this folder or check the GNU Debugger (GDB) web site at: | |
abeeff98 LM |
38 | |
39 | - http://www.gnu.org/software/gdb | |
40 | ||
41 | Build the ROCm Debugger | |
42 | ----------------------- | |
43 | ||
44 | ROCgdb can be built on Ubuntu 16.04, Ubuntu 18.04, and Centos 7.6. | |
45 | ||
46 | Building ROCgdb has the following prerequisites: | |
47 | ||
48 | 1. A C++11 compiler such as GCC 4.8 or Clang 3.3. | |
49 | ||
50 | 2. AMD Debugger API Library (ROCdbgapi) which can be installed as part of the | |
51 | ROCm release by the ``rocm-dbgapi`` package. | |
52 | ||
53 | 3. For Ubuntu 16.04 and Ubuntu 18.04 the following adds the needed packages: | |
54 | ||
55 | ````shell | |
56 | apt install bison flex gcc make ncurses-dev texinfo g++ \ | |
57 | zlib1g-dev libexpat-dev libpython2.7-dev python2.7-minimal liblzma-dev \ | |
58 | libbabeltrace-dev libbabeltrace-ctf-dev | |
59 | ```` | |
60 | ||
e658b565 | 61 | 4. For CentOS 7.6 the following adds the needed packages: |
abeeff98 LM |
62 | |
63 | ````shell | |
64 | yum install -y epel-release centos-release-scl | |
e658b565 | 65 | yum install -y bison flex gcc make texinfo texinfo-tex gcc-c++ \ |
abeeff98 LM |
66 | zlib-devel expat-devel python-devel xz-devel \ |
67 | libbabeltrace-devel ncurses-devel | |
68 | ```` | |
69 | ||
70 | An example command-line to build ROCgdb on Linux is: | |
71 | ||
72 | ````shell | |
73 | cd rocgdb | |
74 | mkdir build | |
75 | cd build | |
76 | ../configure --program-prefix=roc \ | |
77 | --enable-64-bit-bfd --enable-targets="x86_64-linux-gnu,amdgcn-amd-amdhsa" \ | |
78 | --disable-ld --disable-gas --disable-gdbserver --disable-sim --enable-tui \ | |
79 | --disable-gdbtk --disable-shared --with-expat --with-system-zlib \ | |
80 | --without-guile --with-babeltrace --with-lzma --with-python | |
81 | make | |
82 | ```` | |
83 | ||
84 | Specify ``--with-rocm-dbgapi=PATH`` if the the AMD Debugger API Library | |
85 | (ROCdbgapi) is not installed in its default location. The ``configure`` script | |
86 | looks in ``PATH/include`` and ``PATH/lib``. The default value for ``PATH`` is | |
87 | ``/opt/rocm``. | |
88 | ||
89 | The built ROCgdb executable will be placed in: | |
90 | ||
91 | - ``build/gdb/gdb`` | |
92 | ||
a8b43b7b T |
93 | The texinfo *User Manual* will be placed in: |
94 | ||
95 | - ``build/gdb/doc/gdb.info`` | |
96 | ||
abeeff98 LM |
97 | To install ROCgdb: |
98 | ||
99 | ````shell | |
100 | make install | |
101 | ```` | |
102 | ||
103 | The installed ROCgdb will be placed in: | |
104 | ||
105 | - ``<prefix>/bin/rocgdb`` | |
106 | ||
107 | To execute ROCgdb, the ROCdbgapi library and its dependent ROCcomgr library must | |
108 | be installed. These can be installed as part of the ROCm release by the | |
109 | ``rocm-dbgapi`` package: | |
110 | ||
111 | - ``librocm-dbgapi.so.0`` | |
112 | - ``libamd_comgr.so.1`` | |
a8b43b7b T |
113 | |
114 | The PDF *User Manual* can be generated with: | |
115 | ||
116 | ````shell | |
117 | make pdf | |
118 | ```` | |
119 | ||
120 | The generated PDF will be placed in: | |
121 | ||
122 | - ``build/gdb/doc/gdb.pdf`` |