ROCm Debugger - Deprecated Project

This ROCm Debugger is a Deprecated project.

As of 2018, this is a deprecated software project. The ROCm software team is working on a new GDB-based debugger that works with the ROCr Debug Agent to support debugging GPU kernels.

Overview

The ROCm Debugger provides a gdb-based debugging environment for debugging host application and GPU kernels running on Radeon Open Compute platforms (ROCm). It can support all language runtimes (such as HIP and HCC) built on top of ROCm. Initially, the debugging support within the GPU kernels starts with the HSAIL 1.0 programming language. This support requires a kernel compilation path that goes through HSAIL kernel (such as through HCC-HSAIL or libHSAIL/HSAILAsm).

There are two packages included in this release:

ROCm gdb package that contains the rocm-gdb tool
- based on GDB 7.11, the GNU source-level debugger
ROCm GPU Debug SDK package that contains the necessary header, library and sample files to run the rocm-gdb tool

The ROCm Debugger extends the existing HSA Debugger with new features for ROCm .

Major Features
What's New
System Requirements
Package Contents
Installation
Usage Examples
Known Issues
ROCm GDB LICENSE and SDK LICENSE

Major Features

Seamless host application and GPU kernel source debugging using a familiar gdb-based debugging environment on ROCm
Set GPU kernel breakpoints, single stepping and inspect registers within HSAIL kernel source
View active GPU states (active work-groups, work-items and wavefronts information)
Disassemble GPU kernel at GPU kernel function and source breakpoint
Trace GPU kernel launches into an output file

What's New in May 2017 Release (version 1.5)

Compatible with ROCm 1.5 release
Added the info rocm devices command to show the available devices in the system

What's New in Dec 2016 Release (version 1.4)

Compatible with ROCm 1.4 release
Support for demangling kernel names of HIP and HCC kernels (requires clang_tot_upgrade branch of HCC). Also requires c++filt to be intalled on the system. c++filt can be installed using sudo apt-get install binutils

What's New in Nov 2016 Release (version 1.3)

Compatible with ROCm 1.3 release
Support for AMD code object loader extension
Initial support for Polaris GPUs
Detect and gracefully fail on unsupported devices

What's New in Aug 2016 Release (version 1.2)

Compatible with ROCm 1.2 release
Update gdb base to gdb v7.11.
Initial support for provided GPU debug information via the GDB machine interface
Support for debugging applications that use SIGUSR2. (Provided by Pull Request#1 from Didier Nadeaud)
Add support to report HSAIL source text along with line number when single stepping.

What's New in April 2016 Release (version 1.0)

Compatible with ROCm 1.0 release
Support 6th Generation AMD A-series APU processors (codenamed “Carrizo”)
Support AMD Radeon™ R9 Fury, Fury X and Fury Nano GPUs (codenamed “Fiji”)
Support CodeXL 2.0
Add support to gdb disassemble command to disassemble and show the GPU isa disassembly text
Add ability to trace GPU kernel launches
Add gdb help rocm command to show the list of rocm debugging related commands
Add support to report the hardware slot scheduling information for wavefronts

System Requirements

Boltzmann system
- CPU: CPUs with PCIe Gen3 Atomics: Haswell-class Intel(c) Core CPUs v3 or newer and Intel Xeon E5 v3 or newer.
- GPU: AMD Radeon™ R9 Fury, Fury X and Fury Nano GPUs (codenamed “Fiji”)
- Refer to the ROCm platform requirements for additional information
or 6th Generation AMD A-series APU processors (codenamed “Carrizo”).
OS: 64-bit Ubuntu 14.04 and Fedora 23
ROCm 1.2 platform

To debug within a GPU kernel, the GPU kernel must be assembled using the latest LibHSAIL/HSAILAsm (from April 4th 2016 or newer) built with BUILD_WITH_LIBBRIGDWARF=1.

Package Contents

The directory structure of the ROCm Debugger packages:

gpudebugsdk
- include
  - AMDGPUDebug.h, FacilitiesInterface.h
- bin/x86_64
  - amd-debug-lock, rocm-gdb-debug-flags.sh
- lib/x86_64
  - libAMDGPUDebugHSA-x64.so, libAMDHSADebugAgent-x64.so, libAMDHwDbgFacilities-x64.so
- samples
  - Common
    - HSAResourceManager.h, HSAResourceManager.cpp, HSAExtensionFinalizer.h, HSAExtensionFinalizer.cpp
  - MatrixMultiplication
    - Makefile, MatrixMul.cpp, matrixMul_kernel.brig, matrixMul_kernel.hsail
- LICENSE.txt
gdb
- bin/x86_64
  - rocm-gdb, amd-gdb, .gdbinit, data-directory
- LICENSE.txt
ubuntu
- rocm-gpudebugsdk_<VERSION>_amd64.deb
- rocm-gdb_<VERSION>_amd64.deb

If you download the ROCm Debugger packages or files separately, you must create the same directory structure as shown above in order to run rocm-gdb successfully.

Installation

First, make sure that the ROCm platform is setup correctly.

Install ROCm
Verify the setup by running HSAIL vector_copy sample successfully
- Note that with the default vector_copy sample, you can't single step within the GPU kernel as the GPU kernel is not compiled with debugging support.
- As part of the ROCm debugger package, there is a sample MatrixMultiplication that can be used with rocm-gdb.
Install c++filt using sudo apt-get install binutils

###ROCm Debugger Installation

If you did not install ROCm Debugger as part of the ROCm installation, you can download the ROCm Debugger debian packages (rocm-gpudebugsdk_<VERSION>_amd64.deb and rocm-gdb_<VERSION>_amd64.deb) independently and install them as follows.
- sudo dpkg -i rocm-gpudebugsdk_<VERSION>_amd64.deb
- sudo dpkg -i rocm-gdb_<VERSION>_amd64.deb
  - The installed files will be placed in /opt/rocm/gpudebugsdk and /opt/rocm/gdb folders.
- Note that both rocm-gpudebugsdk and rocm-gdb debian packages are included as part of the ROCm repo install.
Verify the setup

Run the MatrixMultiplication sample provided in the GPU Debug SDK package
- cd /opt/rocm/gpudebugsdk/samples/MatrixMultiplication
- make
  - The Makefile assumes that the hsa header files are located at /opt/rocm/hsa/include. If you encounter a compilation failure, please update the HSADIR within the Makefile to the directory of the hsa header files in the system.
  - Note that matrixMul_kernel.hsail is included for reference only. This sample will load the pre-built brig binary (matrixMul_kernel.brig) to run the kernel.
- /opt/rocm/bin/rocm-gdb MatrixMul
  - Tips: include the /opt/rocm/bin in your PATH environment variable

Usage Examples

Check out the tutorial for some usage examples.

Known Issues

Debugging hsa code objects that contain more than one BRIG module are not supported
Debugging HSAIL kernels that contain global (or read only) variables are not supported
Debugging HSAIL kernels that contain HSAIL function calls are not supported
Using rocm-gdb objects in python scripts is not yet supported
Single stepping branch instructions could require multiple step commands

rocmarchive/ROCm-Debugger