Commit | Line | Data |
---|---|---|
ac682ec5 T |
1 | AMD ROCm Debugger (ROCgdb) |
2 | ========================== | |
abeeff98 | 3 | |
966f6a27 T |
4 | DISCLAIMER |
5 | ---------- | |
6 | ||
7 | The information contained herein is for informational purposes only and is | |
8 | subject to change without notice. While every precaution has been taken in the | |
9 | preparation of this document, it may contain technical inaccuracies, omissions | |
10 | and typographical errors, and AMD is under no obligation to update or otherwise | |
11 | correct this information. Advanced Micro Devices, Inc. makes no representations | |
12 | or warranties with respect to the accuracy or completeness of the contents of | |
13 | this document, and assumes no liability of any kind, including the implied | |
14 | warranties of noninfringement, merchantability or fitness for particular | |
15 | purposes, with respect to the operation or use of AMD hardware, software or | |
16 | other products described herein. No license, including implied or arising by | |
17 | estoppel, to any intellectual property rights is granted by this document. Terms | |
18 | and limitations applicable to the purchase or use of AMD’s products are as set | |
19 | forth in a signed agreement between the parties or in AMD’s Standard Terms and | |
20 | Conditions of Sale. S AMD, the AMD Arrow logo, Radeon, Ryzen, Epyc, and | |
21 | combinations thereof are trademarks of Advanced Micro Devices, Inc. Google® is a | |
22 | registered trademark of Google LLC. PCIe® is a registered trademark of PCI-SIG | |
23 | Corporation. Linux is the registered trademark of Linus Torvalds in the U.S. and | |
24 | other countries. Ubuntu and the Ubuntu logo are registered trademarks of | |
25 | Canonical Ltd. Other product names used in this publication are for | |
26 | identification purposes only and may be trademarks of their respective | |
27 | companies. | |
28 | ||
29 | Introduction | |
30 | ------------ | |
31 | ||
ac682ec5 T |
32 | The AMD ROCm Debugger (ROCgdb) is the AMD ROCm source-level debugger for Linux, |
33 | based on the GNU Debugger (GDB). It enables heterogeneous debugging on the AMD | |
34 | ROCm platform of an x86-based host architecture along with AMD GPU architectures | |
35 | supported by the AMD Debugger API Library (ROCdbgapi). The AMD Debugger API | |
36 | Library (ROCdbgapi) is included with the AMD ROCm release. | |
b7bc1207 | 37 | |
ac682ec5 T |
38 | The current AMD ROCm Debugger (ROCgdb) is an initial prototype that focuses on |
39 | source line debugging. Symbolic variable debugging capabilities are not | |
40 | currently supported. | |
b7bc1207 | 41 | |
ac682ec5 | 42 | For more information about AMD ROCm, see: |
abeeff98 LM |
43 | |
44 | - https://github.com/RadeonOpenCompute/ROCm | |
45 | ||
b7bc1207 T |
46 | You can use the standard GDB commands for both CPU and GPU code debugging. For |
47 | more information about ROCgdb, refer to the *ROCgdb User Guide* which is | |
48 | installed at: | |
49 | ||
50 | - ``/opt/rocm/share/info/gdb.info`` as a texinfo file | |
51 | - ``/opt/rocm/share/doc/gdb/gdb.pdf`` as a PDF file | |
52 | ||
53 | You can refer to the following chapters in the *ROCgdb User Guide* for more | |
ac682ec5 | 54 | specific information about debugging heterogeneous programs on AMD ROCm: |
b7bc1207 T |
55 | |
56 | - *Debugging Heterogeneous Programs* provides general information about | |
ac682ec5 T |
57 | debugging heterogeneous programs. It presents features and commands that are |
58 | not currently implemented but provisionally planned for future versions. | |
b7bc1207 | 59 | - *Configuration-Specific Information > Architectures > AMD GPU* provides |
ac682ec5 T |
60 | specific information about debugging heterogeneous programs on AMD ROCm with |
61 | supported AMD GPU chips. This section also lists the implementation status and | |
62 | known issues of the current version. | |
b7bc1207 T |
63 | |
64 | For more information about the GNU Debugger (GDB), refer to the ``README`` file | |
65 | in this folder or check the GNU Debugger (GDB) web site at: | |
abeeff98 LM |
66 | |
67 | - http://www.gnu.org/software/gdb | |
68 | ||
ac682ec5 T |
69 | Build the AMD ROCm Debugger |
70 | --------------------------- | |
abeeff98 | 71 | |
7d43aaec T |
72 | ROCgdb can be built on Ubuntu 16.04, Ubuntu 18.04, Centos 8.1, RHEL 8.1, and SLES |
73 | 15 Service Pack 1. | |
abeeff98 LM |
74 | |
75 | Building ROCgdb has the following prerequisites: | |
76 | ||
77 | 1. A C++11 compiler such as GCC 4.8 or Clang 3.3. | |
78 | ||
79 | 2. AMD Debugger API Library (ROCdbgapi) which can be installed as part of the | |
ac682ec5 | 80 | AMD ROCm release by the ``rocm-dbgapi`` package. |
abeeff98 LM |
81 | |
82 | 3. For Ubuntu 16.04 and Ubuntu 18.04 the following adds the needed packages: | |
83 | ||
84 | ````shell | |
7d43aaec T |
85 | apt install bison flex gcc make ncurses-dev texinfo g++ zlib1g-dev \ |
86 | libexpat-dev libpython2.7-dev python2.7-minimal liblzma-dev \ | |
abeeff98 LM |
87 | libbabeltrace-dev libbabeltrace-ctf-dev |
88 | ```` | |
89 | ||
7d43aaec | 90 | 4. For CentOS 8.1 and RHEL 8.1 the following adds the needed packages: |
abeeff98 LM |
91 | |
92 | ````shell | |
7d43aaec | 93 | yum install -y epel-release centos-release-scl bison flex gcc make \ |
ac682ec5 | 94 | texinfo texinfo-tex gcc-c++ zlib-devel expat-devel python2-devel \ |
7d43aaec | 95 | xz-devel libbabeltrace-devel ncurses-devel |
ac682ec5 T |
96 | wget http://repo.okay.com.mx/centos/8/x86_64/release/libbabeltrace-devel-1.5.4-2.el8.x86_64.rpm \ |
97 | && rpm -ivh --nodeps libbabeltrace-devel-1.5.4-2.el8.x86_64.rpm | |
7d43aaec T |
98 | ```` |
99 | ||
100 | 5. For SLES 15 Service Pack 1 the following adds the needed packages: | |
101 | ||
102 | ````shell | |
103 | zypper in bison flex gcc make texinfo gcc-c++ zlib-devel libexpat-devel \ | |
104 | python-devel xz-devel babeltrace-devel ncurses-devel | |
abeeff98 LM |
105 | ```` |
106 | ||
107 | An example command-line to build ROCgdb on Linux is: | |
108 | ||
109 | ````shell | |
110 | cd rocgdb | |
111 | mkdir build | |
112 | cd build | |
113 | ../configure --program-prefix=roc \ | |
114 | --enable-64-bit-bfd --enable-targets="x86_64-linux-gnu,amdgcn-amd-amdhsa" \ | |
115 | --disable-ld --disable-gas --disable-gdbserver --disable-sim --enable-tui \ | |
116 | --disable-gdbtk --disable-shared --with-expat --with-system-zlib \ | |
117 | --without-guile --with-babeltrace --with-lzma --with-python | |
118 | make | |
119 | ```` | |
120 | ||
121 | Specify ``--with-rocm-dbgapi=PATH`` if the the AMD Debugger API Library | |
122 | (ROCdbgapi) is not installed in its default location. The ``configure`` script | |
123 | looks in ``PATH/include`` and ``PATH/lib``. The default value for ``PATH`` is | |
124 | ``/opt/rocm``. | |
125 | ||
126 | The built ROCgdb executable will be placed in: | |
127 | ||
128 | - ``build/gdb/gdb`` | |
129 | ||
a8b43b7b T |
130 | The texinfo *User Manual* will be placed in: |
131 | ||
132 | - ``build/gdb/doc/gdb.info`` | |
133 | ||
abeeff98 LM |
134 | To install ROCgdb: |
135 | ||
136 | ````shell | |
137 | make install | |
138 | ```` | |
139 | ||
140 | The installed ROCgdb will be placed in: | |
141 | ||
142 | - ``<prefix>/bin/rocgdb`` | |
143 | ||
144 | To execute ROCgdb, the ROCdbgapi library and its dependent ROCcomgr library must | |
ac682ec5 | 145 | be installed. These can be installed as part of the AMD ROCm release by the |
abeeff98 LM |
146 | ``rocm-dbgapi`` package: |
147 | ||
148 | - ``librocm-dbgapi.so.0`` | |
149 | - ``libamd_comgr.so.1`` | |
a8b43b7b T |
150 | |
151 | The PDF *User Manual* can be generated with: | |
152 | ||
153 | ````shell | |
154 | make pdf | |
155 | ```` | |
156 | ||
157 | The generated PDF will be placed in: | |
158 | ||
159 | - ``build/gdb/doc/gdb.pdf`` |