1 AMD ROCm Debugger (ROCgdb)
2 ==========================
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
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.
38 The current AMD ROCm Debugger (ROCgdb) is an initial prototype that focuses on
39 source line debugging. Symbolic variable debugging capabilities are not
42 For more information about AMD ROCm, see:
44 - https://github.com/RadeonOpenCompute/ROCm
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
50 - ``/opt/rocm/share/info/gdb.info`` as a texinfo file
51 - ``/opt/rocm/share/doc/gdb/gdb.pdf`` as a PDF file
53 You can refer to the following chapters in the *ROCgdb User Guide* for more
54 specific information about debugging heterogeneous programs on AMD ROCm:
56 - *Debugging Heterogeneous Programs* provides general information about
57 debugging heterogeneous programs. It presents features and commands that are
58 not currently implemented but provisionally planned for future versions.
59 - *Configuration-Specific Information > Architectures > AMD GPU* provides
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.
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:
67 - http://www.gnu.org/software/gdb
69 Build the AMD ROCm Debugger
70 ---------------------------
72 ROCgdb can be built on Ubuntu 16.04, Ubuntu 18.04, Centos 8.1, RHEL 8.1, and SLES
75 Building ROCgdb has the following prerequisites:
77 1. A C++11 compiler such as GCC 4.8 or Clang 3.3.
79 2. AMD Debugger API Library (ROCdbgapi) which can be installed as part of the
80 AMD ROCm release by the ``rocm-dbgapi`` package.
82 3. For Ubuntu 16.04 and Ubuntu 18.04 the following adds the needed packages:
85 apt install bison flex gcc make ncurses-dev texinfo g++ zlib1g-dev \
86 libexpat-dev libpython2.7-dev python2.7-minimal liblzma-dev \
87 libbabeltrace-dev libbabeltrace-ctf-dev
90 4. For CentOS 8.1 and RHEL 8.1 the following adds the needed packages:
93 yum install -y epel-release centos-release-scl bison flex gcc make \
94 texinfo texinfo-tex gcc-c++ zlib-devel expat-devel python2-devel \
95 xz-devel libbabeltrace-devel ncurses-devel
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
100 5. For SLES 15 Service Pack 1 the following adds the needed packages:
103 zypper in bison flex gcc make texinfo gcc-c++ zlib-devel libexpat-devel \
104 python-devel xz-devel babeltrace-devel ncurses-devel
107 An example command-line to build ROCgdb on Linux is:
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
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
126 The built ROCgdb executable will be placed in:
130 The texinfo *User Manual* will be placed in:
132 - ``build/gdb/doc/gdb.info``
140 The installed ROCgdb will be placed in:
142 - ``<prefix>/bin/rocgdb``
144 To execute ROCgdb, the ROCdbgapi library and its dependent ROCcomgr library must
145 be installed. These can be installed as part of the AMD ROCm release by the
146 ``rocm-dbgapi`` package:
148 - ``librocm-dbgapi.so.0``
149 - ``libamd_comgr.so.1``
151 The PDF *User Manual* can be generated with:
157 The generated PDF will be placed in:
159 - ``build/gdb/doc/gdb.pdf``