-ROCm Debugger (ROCgdb)
-======================
+AMD ROCm Debugger (ROCgdb)
+==========================
+
+DISCLAIMER
+----------
+
+The information contained herein is for informational purposes only and is
+subject to change without notice. While every precaution has been taken in the
+preparation of this document, it may contain technical inaccuracies, omissions
+and typographical errors, and AMD is under no obligation to update or otherwise
+correct this information. Advanced Micro Devices, Inc. makes no representations
+or warranties with respect to the accuracy or completeness of the contents of
+this document, and assumes no liability of any kind, including the implied
+warranties of noninfringement, merchantability or fitness for particular
+purposes, with respect to the operation or use of AMD hardware, software or
+other products described herein. No license, including implied or arising by
+estoppel, to any intellectual property rights is granted by this document. Terms
+and limitations applicable to the purchase or use of AMD’s products are as set
+forth in a signed agreement between the parties or in AMD’s Standard Terms and
+Conditions of Sale. S AMD, the AMD Arrow logo, Radeon, Ryzen, Epyc, and
+combinations thereof are trademarks of Advanced Micro Devices, Inc. Google® is a
+registered trademark of Google LLC. PCIe® is a registered trademark of PCI-SIG
+Corporation. Linux is the registered trademark of Linus Torvalds in the U.S. and
+other countries. Ubuntu and the Ubuntu logo are registered trademarks of
+Canonical Ltd. Other product names used in this publication are for
+identification purposes only and may be trademarks of their respective
+companies.
+
+Introduction
+------------
+
+The AMD ROCm Debugger (ROCgdb) is the AMD ROCm source-level debugger for Linux,
+based on the GNU Debugger (GDB). It enables heterogeneous debugging on the AMD
+ROCm platform of an x86-based host architecture along with AMD GPU architectures
+supported by the AMD Debugger API Library (ROCdbgapi). The AMD Debugger API
+Library (ROCdbgapi) is included with the AMD ROCm release.
+
+The current AMD ROCm Debugger (ROCgdb) is an initial prototype that focuses on
+source line debugging. Symbolic variable debugging capabilities are not
+currently supported.
+
+For more information about AMD ROCm, see:
-This is ROCgdb, the ROCm source-level debugger for Linux, based on GDB, the GNU
-source-level debugger. It includes support for heterogenous debugging on the
-ROCm platform of an x86-based host architecture together with the AMD
-commercially available GPU architectures supported by the AMD Debugger API which
-is included with the ROCm release as the ROCdbgapi library.
-
-All standard GDB commands can be used for both CPU and GPU code debugging. In particular:
+- https://github.com/RadeonOpenCompute/ROCm
-- The ``info threads`` command lists both CPU threads and GPU waves.
-- The ``info sharedlibrary`` command lists both loaded CPU and GPU code objects.
-- The new ``info agents`` command lists the heterogenous agents once the program
- has started.
+You can use the standard GDB commands for both CPU and GPU code debugging. For
+more information about ROCgdb, refer to the *ROCgdb User Guide* which is
+installed at:
-The ``_wave_id`` convenience variable can be used when the focused thread is a
-GPU wave. It returns a string with the following format ``x,y,z/w`` where `x`,
-``y``, and ``z`` are the grid position of the wave's work-group in the dispatch,
-and ``w`` is the wave's number within the work-group.
+- ``/opt/rocm/share/info/gdb.info`` as a texinfo file
+- ``/opt/rocm/share/doc/gdb/gdb.pdf`` as a PDF file
-For more information about ROCm and ROCgdb, please refer to the Release Notes
-which includes current restrictions:
+You can refer to the following chapters in the *ROCgdb User Guide* for more
+specific information about debugging heterogeneous programs on AMD ROCm:
-- https://github.com/RadeonOpenCompute/ROCm
+- *Debugging Heterogeneous Programs* provides general information about
+ debugging heterogeneous programs. It presents features and commands that are
+ not currently implemented but provisionally planned for future versions.
+- *Configuration-Specific Information > Architectures > AMD GPU* provides
+ specific information about debugging heterogeneous programs on AMD ROCm with
+ supported AMD GPU chips. This section also lists the implementation status and
+ known issues of the current version.
-For more information about GDB, please refer to the README file in this folder
-or check the GDB home page at:
+For more information about the GNU Debugger (GDB), refer to the ``README`` file
+in this folder or check the GNU Debugger (GDB) web site at:
- http://www.gnu.org/software/gdb
-Build the ROCm Debugger
------------------------
+Build the AMD ROCm Debugger
+---------------------------
-ROCgdb can be built on Ubuntu 16.04, Ubuntu 18.04, and Centos 7.6.
+ROCgdb can be built on Ubuntu 16.04, Ubuntu 18.04, Centos 8.1, RHEL 8.1, and SLES
+15 Service Pack 1.
Building ROCgdb has the following prerequisites:
1. A C++11 compiler such as GCC 4.8 or Clang 3.3.
2. AMD Debugger API Library (ROCdbgapi) which can be installed as part of the
- ROCm release by the ``rocm-dbgapi`` package.
+ AMD ROCm release by the ``rocm-dbgapi`` package.
3. For Ubuntu 16.04 and Ubuntu 18.04 the following adds the needed packages:
````shell
- apt install bison flex gcc make ncurses-dev texinfo g++ \
- zlib1g-dev libexpat-dev libpython2.7-dev python2.7-minimal liblzma-dev \
+ apt install bison flex gcc make ncurses-dev texinfo g++ zlib1g-dev \
+ libexpat-dev libpython2.7-dev python2.7-minimal liblzma-dev \
libbabeltrace-dev libbabeltrace-ctf-dev
````
-4. For Centos 7.6 the following adds the needed packages:
+4. For CentOS 8.1 and RHEL 8.1 the following adds the needed packages:
+
+ ````shell
+ yum install -y epel-release centos-release-scl bison flex gcc make \
+ texinfo texinfo-tex gcc-c++ zlib-devel expat-devel python2-devel \
+ xz-devel libbabeltrace-devel ncurses-devel
+ wget http://repo.okay.com.mx/centos/8/x86_64/release/libbabeltrace-devel-1.5.4-2.el8.x86_64.rpm \
+ && rpm -ivh --nodeps libbabeltrace-devel-1.5.4-2.el8.x86_64.rpm
+ ````
+
+5. For SLES 15 Service Pack 1 the following adds the needed packages:
````shell
- yum install -y epel-release centos-release-scl
- yum install -y bison flex gcc make texinfo gcc-c++ \
- zlib-devel expat-devel python-devel xz-devel \
- libbabeltrace-devel ncurses-devel
+ zypper in bison flex gcc make texinfo gcc-c++ zlib-devel libexpat-devel \
+ python-devel xz-devel babeltrace-devel ncurses-devel
````
An example command-line to build ROCgdb on Linux is:
- ``build/gdb/gdb``
+The texinfo *User Manual* will be placed in:
+
+- ``build/gdb/doc/gdb.info``
+
To install ROCgdb:
````shell
- ``<prefix>/bin/rocgdb``
To execute ROCgdb, the ROCdbgapi library and its dependent ROCcomgr library must
-be installed. These can be installed as part of the ROCm release by the
+be installed. These can be installed as part of the AMD ROCm release by the
``rocm-dbgapi`` package:
- ``librocm-dbgapi.so.0``
- ``libamd_comgr.so.1``
+
+The PDF *User Manual* can be generated with:
+
+````shell
+make pdf
+````
+
+The generated PDF will be placed in:
+
+- ``build/gdb/doc/gdb.pdf``
projects / deliverable / binutils-gdb.git / blobdiff