README-ROCM.md

   1 AMD ROCm Debugger (ROCgdb)
   2 ==========================
   3
   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
  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.
  37
  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.
  41
  42 For more information about AMD ROCm, see:
  43
  44 - https://github.com/RadeonOpenCompute/ROCm
  45
  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
  54 specific information about debugging heterogeneous programs on AMD ROCm:
  55
  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.
  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:
  66
  67 - http://www.gnu.org/software/gdb
  68
  69 Build the AMD ROCm Debugger
  70 ---------------------------
  71
  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.
  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
  80    AMD ROCm release by the ``rocm-dbgapi`` package.
  81
  82 3. For Ubuntu 16.04 and Ubuntu 18.04 the following adds the needed packages:
  83
  84    ````shell
  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
  88    ````
  89
  90 4. For CentOS 8.1 and RHEL 8.1 the following adds the needed packages:
  91
  92    ````shell
  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
  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
 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
 130 The texinfo *User Manual* will be placed in:
 131
 132 - ``build/gdb/doc/gdb.info``
 133
 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
 145 be installed. These can be installed as part of the AMD ROCm release by the
 146 ``rocm-dbgapi`` package:
 147
 148 - ``librocm-dbgapi.so.0``
 149 - ``libamd_comgr.so.1``
 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``