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 | ||
7d43aaec T |
44 | ROCgdb can be built on Ubuntu 16.04, Ubuntu 18.04, Centos 8.1, RHEL 8.1, and SLES |
45 | 15 Service Pack 1. | |
abeeff98 LM |
46 | |
47 | Building ROCgdb has the following prerequisites: | |
48 | ||
49 | 1. A C++11 compiler such as GCC 4.8 or Clang 3.3. | |
50 | ||
51 | 2. AMD Debugger API Library (ROCdbgapi) which can be installed as part of the | |
52 | ROCm release by the ``rocm-dbgapi`` package. | |
53 | ||
54 | 3. For Ubuntu 16.04 and Ubuntu 18.04 the following adds the needed packages: | |
55 | ||
56 | ````shell | |
7d43aaec T |
57 | apt install bison flex gcc make ncurses-dev texinfo g++ zlib1g-dev \ |
58 | libexpat-dev libpython2.7-dev python2.7-minimal liblzma-dev \ | |
abeeff98 LM |
59 | libbabeltrace-dev libbabeltrace-ctf-dev |
60 | ```` | |
61 | ||
7d43aaec | 62 | 4. For CentOS 8.1 and RHEL 8.1 the following adds the needed packages: |
abeeff98 LM |
63 | |
64 | ````shell | |
7d43aaec T |
65 | yum install -y epel-release centos-release-scl bison flex gcc make \ |
66 | texinfo texinfo-tex gcc-c++ zlib-devel expat-devel python-devel \ | |
67 | xz-devel libbabeltrace-devel ncurses-devel | |
68 | ```` | |
69 | ||
70 | 5. For SLES 15 Service Pack 1 the following adds the needed packages: | |
71 | ||
72 | ````shell | |
73 | zypper in bison flex gcc make texinfo gcc-c++ zlib-devel libexpat-devel \ | |
74 | python-devel xz-devel babeltrace-devel ncurses-devel | |
abeeff98 LM |
75 | ```` |
76 | ||
77 | An example command-line to build ROCgdb on Linux is: | |
78 | ||
79 | ````shell | |
80 | cd rocgdb | |
81 | mkdir build | |
82 | cd build | |
83 | ../configure --program-prefix=roc \ | |
84 | --enable-64-bit-bfd --enable-targets="x86_64-linux-gnu,amdgcn-amd-amdhsa" \ | |
85 | --disable-ld --disable-gas --disable-gdbserver --disable-sim --enable-tui \ | |
86 | --disable-gdbtk --disable-shared --with-expat --with-system-zlib \ | |
87 | --without-guile --with-babeltrace --with-lzma --with-python | |
88 | make | |
89 | ```` | |
90 | ||
91 | Specify ``--with-rocm-dbgapi=PATH`` if the the AMD Debugger API Library | |
92 | (ROCdbgapi) is not installed in its default location. The ``configure`` script | |
93 | looks in ``PATH/include`` and ``PATH/lib``. The default value for ``PATH`` is | |
94 | ``/opt/rocm``. | |
95 | ||
96 | The built ROCgdb executable will be placed in: | |
97 | ||
98 | - ``build/gdb/gdb`` | |
99 | ||
a8b43b7b T |
100 | The texinfo *User Manual* will be placed in: |
101 | ||
102 | - ``build/gdb/doc/gdb.info`` | |
103 | ||
abeeff98 LM |
104 | To install ROCgdb: |
105 | ||
106 | ````shell | |
107 | make install | |
108 | ```` | |
109 | ||
110 | The installed ROCgdb will be placed in: | |
111 | ||
112 | - ``<prefix>/bin/rocgdb`` | |
113 | ||
114 | To execute ROCgdb, the ROCdbgapi library and its dependent ROCcomgr library must | |
115 | be installed. These can be installed as part of the ROCm release by the | |
116 | ``rocm-dbgapi`` package: | |
117 | ||
118 | - ``librocm-dbgapi.so.0`` | |
119 | - ``libamd_comgr.so.1`` | |
a8b43b7b T |
120 | |
121 | The PDF *User Manual* can be generated with: | |
122 | ||
123 | ````shell | |
124 | make pdf | |
125 | ```` | |
126 | ||
127 | The generated PDF will be placed in: | |
128 | ||
129 | - ``build/gdb/doc/gdb.pdf`` |