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, and Centos 7.6.
  45
  46 Building ROCgdb has the following prerequisites:
  47
  48 1. A C++11 compiler such as GCC 4.8 or Clang 3.3.
  49
  50 2. AMD Debugger API Library (ROCdbgapi) which can be installed as part of the
  51    ROCm release by the ``rocm-dbgapi`` package.
  52
  53 3. For Ubuntu 16.04 and Ubuntu 18.04 the following adds the needed packages:
  54
  55    ````shell
  56    apt install bison flex gcc make ncurses-dev texinfo g++ \
  57      zlib1g-dev libexpat-dev libpython2.7-dev python2.7-minimal liblzma-dev \
  58      libbabeltrace-dev libbabeltrace-ctf-dev
  59    ````
  60
  61 4. For CentOS 7.6 the following adds the needed packages:
  62
  63    ````shell
  64    yum install -y epel-release centos-release-scl
  65    yum install -y bison flex gcc make texinfo texinfo-tex gcc-c++ \
  66      zlib-devel expat-devel python-devel xz-devel \
  67      libbabeltrace-devel ncurses-devel
  68    ````
  69
  70 An example command-line to build ROCgdb on Linux is:
  71
  72 ````shell
  73 cd rocgdb
  74 mkdir build
  75 cd build
  76 ../configure --program-prefix=roc \
  77   --enable-64-bit-bfd --enable-targets="x86_64-linux-gnu,amdgcn-amd-amdhsa" \
  78   --disable-ld --disable-gas --disable-gdbserver --disable-sim --enable-tui \
  79   --disable-gdbtk --disable-shared --with-expat --with-system-zlib \
  80   --without-guile --with-babeltrace --with-lzma --with-python
  81 make
  82 ````
  83
  84 Specify ``--with-rocm-dbgapi=PATH`` if the the AMD Debugger API Library
  85 (ROCdbgapi) is not installed in its default location. The ``configure`` script
  86 looks in ``PATH/include`` and ``PATH/lib``. The default value for ``PATH`` is
  87 ``/opt/rocm``.
  88
  89 The built ROCgdb executable will be placed in:
  90
  91 - ``build/gdb/gdb``
  92
  93 The texinfo *User Manual* will be placed in:
  94
  95 - ``build/gdb/doc/gdb.info``
  96
  97 To install ROCgdb:
  98
  99 ````shell
 100 make install
 101 ````
 102
 103 The installed ROCgdb will be placed in:
 104
 105 - ``<prefix>/bin/rocgdb``
 106
 107 To execute ROCgdb, the ROCdbgapi library and its dependent ROCcomgr library must
 108 be installed. These can be installed as part of the ROCm release by the
 109 ``rocm-dbgapi`` package:
 110
 111 - ``librocm-dbgapi.so.0``
 112 - ``libamd_comgr.so.1``
 113
 114 The PDF *User Manual* can be generated with:
 115
 116 ````shell
 117 make pdf
 118 ````
 119
 120 The generated PDF will be placed in:
 121
 122 - ``build/gdb/doc/gdb.pdf``