README-ROCM.md

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