README-ROCM.md

   1 ROCm Debugger (ROCgdb)
   2 ======================
   3
   4 This is ROCgdb, the ROCm source-level debugger for Linux, based on GDB, the GNU
   5 source-level debugger. It includes support for heterogenous debugging on the
   6 ROCm platform of an x86-based host architecture together with the AMD
   7 commercially available GPU architectures supported by the AMD Debugger API which
   8 is included with the ROCm release as the ROCdbgapi library.
   9
  10 Standard GDB commands can be used for both CPU and GPU code debugging. For more
  11 information about ROCgdb, please refer to the *ROCgdb User Manual* which is
  12 installed as both texinfo files and as a single PDF file in
  13 ``/opt/rocm/share/doc/gdb`. In particular, refer to the *Debugging Heterogeneous
  14 Programs* chapter for general information, and the *AMD GPU* subsection of the
  15 *Architectures* section in the *Configuration-Specific Information* chapter. The
  16 *AMD GPU* subsection also provides the list of features not currently
  17 implemented, and known current restrictions.
  18
  19 For more information about ROCm, please refer to:
  20
  21 - https://github.com/RadeonOpenCompute/ROCm
  22
  23 For more information about GDB, please refer to the README file in this folder
  24 or check the GDB home page at:
  25
  26 - http://www.gnu.org/software/gdb
  27
  28 Build the ROCm Debugger
  29 -----------------------
  30
  31 ROCgdb can be built on Ubuntu 16.04, Ubuntu 18.04, and Centos 7.6.
  32
  33 Building ROCgdb has the following prerequisites:
  34
  35 1. A C++11 compiler such as GCC 4.8 or Clang 3.3.
  36
  37 2. AMD Debugger API Library (ROCdbgapi) which can be installed as part of the
  38    ROCm release by the ``rocm-dbgapi`` package.
  39
  40 3. For Ubuntu 16.04 and Ubuntu 18.04 the following adds the needed packages:
  41
  42    ````shell
  43    apt install bison flex gcc make ncurses-dev texinfo g++ \
  44      zlib1g-dev libexpat-dev libpython2.7-dev python2.7-minimal liblzma-dev \
  45      libbabeltrace-dev libbabeltrace-ctf-dev
  46    ````
  47
  48 4. For Centos 7.6 the following adds the needed packages:
  49
  50    ````shell
  51    yum install -y epel-release centos-release-scl
  52    yum install -y bison flex gcc make texinfo gcc-c++ \
  53      zlib-devel expat-devel python-devel xz-devel \
  54      libbabeltrace-devel ncurses-devel
  55    ````
  56
  57 An example command-line to build ROCgdb on Linux is:
  58
  59 ````shell
  60 cd rocgdb
  61 mkdir build
  62 cd build
  63 ../configure --program-prefix=roc \
  64   --enable-64-bit-bfd --enable-targets="x86_64-linux-gnu,amdgcn-amd-amdhsa" \
  65   --disable-ld --disable-gas --disable-gdbserver --disable-sim --enable-tui \
  66   --disable-gdbtk --disable-shared --with-expat --with-system-zlib \
  67   --without-guile --with-babeltrace --with-lzma --with-python
  68 make
  69 ````
  70
  71 Specify ``--with-rocm-dbgapi=PATH`` if the the AMD Debugger API Library
  72 (ROCdbgapi) is not installed in its default location. The ``configure`` script
  73 looks in ``PATH/include`` and ``PATH/lib``. The default value for ``PATH`` is
  74 ``/opt/rocm``.
  75
  76 The built ROCgdb executable will be placed in:
  77
  78 - ``build/gdb/gdb``
  79
  80 The texinfo *User Manual* will be placed in:
  81
  82 - ``build/gdb/doc/gdb.info``
  83
  84 To install ROCgdb:
  85
  86 ````shell
  87 make install
  88 ````
  89
  90 The installed ROCgdb will be placed in:
  91
  92 - ``<prefix>/bin/rocgdb``
  93
  94 To execute ROCgdb, the ROCdbgapi library and its dependent ROCcomgr library must
  95 be installed. These can be installed as part of the ROCm release by the
  96 ``rocm-dbgapi`` package:
  97
  98 - ``librocm-dbgapi.so.0``
  99 - ``libamd_comgr.so.1``
 100
 101 The PDF *User Manual* can be generated with:
 102
 103 ````shell
 104 make pdf
 105 ````
 106
 107 The generated PDF will be placed in:
 108
 109 - ``build/gdb/doc/gdb.pdf``