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 All standard GDB commands can be used for both CPU and GPU code debugging. In particular:
  11
  12 - The ``info threads`` command lists both CPU threads and GPU waves.
  13 - The ``info sharedlibrary`` command lists both loaded CPU and GPU code objects.
  14 - The new ``info agents`` command lists the heterogenous agents once the program
  15   has started.
  16
  17 The ``_wave_id`` convenience variable can be used when the focused thread is a
  18 GPU wave. It returns a string with the following format ``x,y,z/w`` where `x`,
  19 ``y``, and ``z`` are the grid position of the wave's work-group in the dispatch,
  20 and ``w`` is the wave's number within the work-group.
  21
  22 For more information about ROCm and ROCgdb, please refer to the Release Notes
  23 which includes current restrictions:
  24
  25 - https://github.com/RadeonOpenCompute/ROCm
  26
  27 For more information about GDB, please refer to the README file in this folder
  28 or check the GDB home page at:
  29
  30 - http://www.gnu.org/software/gdb
  31
  32 Build the ROCm Debugger
  33 -----------------------
  34
  35 ROCgdb can be built on Ubuntu 16.04, Ubuntu 18.04, and Centos 7.6.
  36
  37 Building ROCgdb has the following prerequisites:
  38
  39 1. A C++11 compiler such as GCC 4.8 or Clang 3.3.
  40
  41 2. AMD Debugger API Library (ROCdbgapi) which can be installed as part of the
  42    ROCm release by the ``rocm-dbgapi`` package.
  43
  44 3. For Ubuntu 16.04 and Ubuntu 18.04 the following adds the needed packages:
  45
  46    ````shell
  47    apt install bison flex gcc make ncurses-dev texinfo g++ \
  48      zlib1g-dev libexpat-dev libpython2.7-dev python2.7-minimal liblzma-dev \
  49      libbabeltrace-dev libbabeltrace-ctf-dev
  50    ````
  51
  52 4. For Centos 7.6 the following adds the needed packages:
  53
  54    ````shell
  55    yum install -y epel-release centos-release-scl
  56    yum install -y bison flex gcc make texinfo gcc-c++ \
  57      zlib-devel expat-devel python-devel xz-devel \
  58      libbabeltrace-devel ncurses-devel
  59    ````
  60
  61 An example command-line to build ROCgdb on Linux is:
  62
  63 ````shell
  64 cd rocgdb
  65 mkdir build
  66 cd build
  67 ../configure --program-prefix=roc \
  68   --enable-64-bit-bfd --enable-targets="x86_64-linux-gnu,amdgcn-amd-amdhsa" \
  69   --disable-ld --disable-gas --disable-gdbserver --disable-sim --enable-tui \
  70   --disable-gdbtk --disable-shared --with-expat --with-system-zlib \
  71   --without-guile --with-babeltrace --with-lzma --with-python
  72 make
  73 ````
  74
  75 Specify ``--with-rocm-dbgapi=PATH`` if the the AMD Debugger API Library
  76 (ROCdbgapi) is not installed in its default location. The ``configure`` script
  77 looks in ``PATH/include`` and ``PATH/lib``. The default value for ``PATH`` is
  78 ``/opt/rocm``.
  79
  80 The built ROCgdb executable will be placed in:
  81
  82 - ``build/gdb/gdb``
  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``