The HSA-Debugger has been superseded by the RadeonOpenCompute/ROCm-Debugger now located at https://github.com/RadeonOpenCompute/ROCm-Debugger

HSA Debugger January 2016 Release (version 1.0)

Overview

The HSA Debugger provides a gdb-based debugging environment for debugging host application and HSAIL kernels running on AMD HSA platforms. The kernel programming language currently supported is HSAIL 1.0. There are two packages included in this Alpha Release:

• AMD HSAIL gdb package that contains the hsail-gdb tool
  • based on GDB 7.8, the GNU source-level debugger
• AMD GPU Kernel Debug SDK package that contains the necessary header, library and sample files to run the hsail-gdb tool

Table of Contents

• Major Features
• What's New
• System Requirements
• Package Contents
• Installation
• Usage Examples
• Known Issues
• HSAIL gdb LICENSE and SDK LICENSE

#### Major Features * Seamless host application and HSAIL kernel source debugging using a familiar gdb-based debugging environment on AMD HSA platforms * Set HSAIL kernel breakpoints, single stepping and inspect HSAIL registers within HSAIL kernel source * View active GPU states (active work-groups, work-items and wavefronts information) #### What's New in January 2016 Release (version 1.0) * First public release supporting AMD Kaveri and Carrizo * Open source: [GDB](https://github.com/HSAFoundation/HSA-Debugger-GDB-Source-AMD), [AMD GPU Debug SDK](https://github.com/HSAFoundation/HSA-Debugger-Source-AMD) * Adds ability to set and run to HSAIL kernel source breakpoints without setting HSAIL function breakpoints first * Adds ability to safely kill HSAIL applications while a dispatch is inflight using the kill command * Many bug fixes and stability improvements

What's New in September 2015 Beta Release (version 0.6)

• Initial AMD Carrizo support (alpha).
• Improves support for HSAIL-level debugging for Kalmar applications.
• Improves support for HSAIL-level debugging for SNACK applications.
• Adds support for conditional breakpoint based on the global work-item id.
• Improves support for running hsail-gdb on hsa cluster machines.
• Improves support when terminating application or hsail-gdb abruptly.
• Adds support to step into the kernel from the kernel function breakpoint using the gdb next command.
• Adds a utility program amd-debug-lock to determine whether the hsa system is in a gpu locked state (requiring a system reboot to release the lock).
• Adds debian installation packages.
• Adds common prefix name for all log files generated using HSAIL_GDB_ENABLE_LOG environment variable.
• Enables running hsail-gdb when it is installed in a read only folder
• Removes version number from the AMDHsailGdb and AMDGPUKernelDebugSDK folder names.
• Fixes a segmentation fault if the users entered incorrect hsail breakpoint commands
• Fixes incorrect reporting of number of work-groups in info hsail kernels command when there are partial work-groups.
• Fixes incorrect reporting of the focus work-item in info hsail wis command
• Fixes incorrect reporting of the work-group id that is being switched to after the first step into the kernel.
• The temporary temp_source kernel file for debugging is now deleted after the hsail-gdb session completes.

What's New in May 2015 Alpha Release (version 0.5)

• Initial AMD internal release.
• Initial AMD Kaveri support (alpha).

## System Requirements * Hardware: AMD Kaveri and Carrizo APUs that implement HSA (i.e. A10-7850K, A10-7800, A10-8700, etc.) * Refer to the [HSA Platforms & Installation wiki page](https://github.com/HSAFoundation/HSA-Docs-AMD/wiki/HSA-Platforms-&-Installation) for additional information. * OS: 64-bit Ubuntu 14.04 * HSA Runtime: [AMD HSA Runtime September 2015 release v1.0.3](https://github.com/HSAFoundation/HSA-Runtime-AMD) * HSA Driver: [AMD HSA Drivers v1.6](https://github.com/HSAFoundation/HSA-Drivers-Linux-AMD)

HSAIL applications must use the LibHSAIL from Dec 3rd 2015 or newer built with BUILD_WITH_LIBBRIGDWARF=1 to assemble HSAIL text to BRIG.

## Package Contents The directory structure of the HSA Debugger packages: * *AMDGPUKernelDebugSDK* * *include* * *AMDGPUDebug.h*, *amd_hsa_tools_interfaces.h* * *bin/x86_64* * *amd-debug-lock* * *lib/x86_64* * *libAMDGPUDebugHSA-x64.so*, *libAMDHSADebugAgent-x64.so*, *libAMDHwDbgFacilities-x64.so* * *samples* * *Common* * *HSAResourceManager.h* * *HSAResourceManager.cpp* * *MatrixMultiplication* * *Makefile*, *MatrixMul.cpp*, *matrixMul_kernel.brig*, *matrixMul_kernel.hsail* * *LICENSE.txt* * *AMDHsailGdb* * *bin/x86_64* * *hsail-gdb*, *amd-gdb*, *.gdbinit* * *LICENSE.txt* * *ubuntu* * *amd-gpu-kernel-debug-sdk__amd64.deb* * *amd-hsail-gdb__amd64.deb*

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

## Installation First, make sure that the HSA system is setup correctly * [Install HSA Driver](https://github.com/HSAFoundation/HSA-Drivers-Linux-AMD#installing-and-configuring-the-kernel) * [Install HSA Runtime](https://github.com/HSAFoundation/HSA-Runtime-AMD/#installing-and-configuring-the-hsa-runtime) * [Verify the setup by running HSAIL *vector_copy* sample successfully](https://github.com/HSAFoundation/HSA-Runtime-AMD#running-the-sample---vector_copy) * Note that the *vector_copy* sample can't be debugged with hsail-gdb since the pre-generated BRIG file was not created with debugging support. As part of the HSAIL debugger package, there is a sample HSAIL *MatrixMultiplication* that can be used with hsail-gdb.

###HSA Debugger Installation

1. Download the debian packages (amd-gpu-kernel-debug-sdk__amd64.deb and amd-hsail-gdb__amd64.deb)
   • sudo dpkg -i amd-gpu-kernel-debug-sdk_<VERSION>_amd64.deb
   • sudo dpkg -i amd-hsail-gdb_<VERSION>_amd64.deb
     • The installed files will be placed in /opt/amd/hsa-debugger folder.
2. Ensure the environment variable LD_LIBRARY_PATH contains the directory of the HSA Runtime library (the default is /opt/hsa/lib). You can add the following line into .bashrc file

• export LD_LIBRARY_PATH=/opt/hsa/lib:${LD_LIBRARY_PATH}

3. Verify the setup

• Copy the samples to a writeable folder
  • cp -r /opt/amd/hsa-debugger/AMDGPUKernelDebugSDK/samples ~/
• cd ~/samples/MatrixMultiplication
• make
  • The Makefile assumes that the hsa header files are located at /opt/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 hsa binary (matrixMul_kernel.brig) to run the kernel.
  • /opt/amd/hsa-debugger/AMDHsailGdb/bin/x86_64/hsail-gdb MatrixMul
  • Tips: include the directory that contains the hsail-gdb tool in your PATH environment variable

## Known Issues for January 2016 Release * Debugging the multiple_cl_files SNACK example can cause a system hang. * HSAIL programs (i.e. hsa code objects) that contain more than one BRIG module are not supported * HSAIL kernels that contain global (or read only) variables are not supported * HSAIL kernels that contain hsail function calls are not supported * HSAIL backtrace is not supported * Usage of hsail-gdb objects in python scripts in not yet supported.