README-ROCM.md

   1 AMD ROCm Debugger (ROCgdb)
   2 ==========================
   3
   4 The AMD ROCm Debugger (ROCgdb) is the AMD ROCm source-level debugger for Linux,
   5 based on the GNU Debugger (GDB). It enables heterogeneous debugging on the AMD
   6 ROCm platform of an x86-based host architecture along with AMD GPU architectures
   7 supported by the AMD Debugger API Library (ROCdbgapi). The AMD Debugger API
   8 Library (ROCdbgapi) is included with the AMD ROCm release.
   9
  10 The current AMD ROCm Debugger (ROCgdb) is an initial prototype that focuses on
  11 source line debugging. Symbolic variable debugging capabilities are not
  12 currently supported.
  13
  14 For more information about AMD ROCm, see:
  15
  16 - https://github.com/RadeonOpenCompute/ROCm
  17
  18 You can use the standard GDB commands for both CPU and GPU code debugging. For
  19 more information about ROCgdb, refer to the *ROCgdb User Guide* which is
  20 installed at:
  21
  22 - ``/opt/rocm/share/info/gdb.info`` as a texinfo file
  23 - ``/opt/rocm/share/doc/gdb/gdb.pdf`` as a PDF file
  24
  25 You can refer to the following chapters in the *ROCgdb User Guide* for more
  26 specific information about debugging heterogeneous programs on AMD ROCm:
  27
  28 - *Debugging Heterogeneous Programs* provides general information about
  29   debugging heterogeneous programs. It presents features and commands that are
  30   not currently implemented but provisionally planned for future versions.
  31 - *Configuration-Specific Information > Architectures > AMD GPU* provides
  32   specific information about debugging heterogeneous programs on AMD ROCm with
  33   supported AMD GPU chips. This section also lists the implementation status and
  34   known issues of the current version.
  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:
  38
  39 - http://www.gnu.org/software/gdb
  40
  41 Build the AMD ROCm Debugger
  42 ---------------------------
  43
  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.
  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    AMD 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
  57    apt install bison flex gcc make ncurses-dev texinfo g++ zlib1g-dev \
  58      libexpat-dev libpython2.7-dev python2.7-minimal liblzma-dev \
  59      libbabeltrace-dev libbabeltrace-ctf-dev
  60    ````
  61
  62 4. For CentOS 8.1 and RHEL 8.1 the following adds the needed packages:
  63
  64    ````shell
  65    yum install -y epel-release centos-release-scl bison flex gcc make \
  66      texinfo texinfo-tex gcc-c++ zlib-devel expat-devel python2-devel \
  67      xz-devel libbabeltrace-devel ncurses-devel
  68    wget http://repo.okay.com.mx/centos/8/x86_64/release/libbabeltrace-devel-1.5.4-2.el8.x86_64.rpm \
  69    && rpm -ivh --nodeps libbabeltrace-devel-1.5.4-2.el8.x86_64.rpm
  70    ````
  71
  72 5. For SLES 15 Service Pack 1 the following adds the needed packages:
  73
  74    ````shell
  75    zypper in bison flex gcc make texinfo gcc-c++ zlib-devel libexpat-devel \
  76      python-devel xz-devel babeltrace-devel ncurses-devel
  77    ````
  78
  79 An example command-line to build ROCgdb on Linux is:
  80
  81 ````shell
  82 cd rocgdb
  83 mkdir build
  84 cd build
  85 ../configure --program-prefix=roc \
  86   --enable-64-bit-bfd --enable-targets="x86_64-linux-gnu,amdgcn-amd-amdhsa" \
  87   --disable-ld --disable-gas --disable-gdbserver --disable-sim --enable-tui \
  88   --disable-gdbtk --disable-shared --with-expat --with-system-zlib \
  89   --without-guile --with-babeltrace --with-lzma --with-python
  90 make
  91 ````
  92
  93 Specify ``--with-rocm-dbgapi=PATH`` if the the AMD Debugger API Library
  94 (ROCdbgapi) is not installed in its default location. The ``configure`` script
  95 looks in ``PATH/include`` and ``PATH/lib``. The default value for ``PATH`` is
  96 ``/opt/rocm``.
  97
  98 The built ROCgdb executable will be placed in:
  99
 100 - ``build/gdb/gdb``
 101
 102 The texinfo *User Manual* will be placed in:
 103
 104 - ``build/gdb/doc/gdb.info``
 105
 106 To install ROCgdb:
 107
 108 ````shell
 109 make install
 110 ````
 111
 112 The installed ROCgdb will be placed in:
 113
 114 - ``<prefix>/bin/rocgdb``
 115
 116 To execute ROCgdb, the ROCdbgapi library and its dependent ROCcomgr library must
 117 be installed. These can be installed as part of the AMD ROCm release by the
 118 ``rocm-dbgapi`` package:
 119
 120 - ``librocm-dbgapi.so.0``
 121 - ``libamd_comgr.so.1``
 122
 123 The PDF *User Manual* can be generated with:
 124
 125 ````shell
 126 make pdf
 127 ````
 128
 129 The generated PDF will be placed in:
 130
 131 - ``build/gdb/doc/gdb.pdf``