GPU Performance API

Overview

The GPU Performance API (GPUPerfAPI, or GPA) is a powerful library, providing access to GPU Performance Counters. It can help analyze the performance and execution characteristics of applications using a Radeon™ GPU. This library is used by Radeon Compute Profiler and CodeXL as well as several third-party tools.

Downloads

Prebuilt binaries can be downloaded from the Releases page: https://github.com/GPUOpen-Tools/GPA/releases

Table of Contents

• Major Features
• What's New
• System Requirements
• Cloning the Repository
• Source Code Directory Layout
• Documentation
• Raw Hardware Counters
• Known Issues
• Building the Source Code
• License
• Historical Release Notes
• Style and Format Change

Major Features

• Provides a standard API for accessing GPU Performance counters for both graphics and compute workloads across multiple GPU APIs.
• Supports Vulkan™, DirectX™ 12, DirectX 11, OpenGL, and OpenCL™.
• Supports all current Radeon graphics cards and APUs based on Graphics IP version 8 and newer.
• Supports both Windows and Linux.
• Provides derived "public" counters based on raw hardware counters.
• Provides access to some raw hardware counters. See Raw Hardware Counters for more information.

What's New

• Version 3.7 (11/24/20)
  • Add support for additional GPUs and APUs, including AMD RDNA™ 2 Radeon™ RX 6000 series GPUs.
  • New RT counters for DXR workloads on AMD RDNA™ 2 Radeon™ RX 6000 series GPUs.
    • RayTriTests, and RayBoxTests: These counters collect the number of ray intersections for triangles and boxes, respectively.
    • TotalRayTests: This counter collects the aggregated number of ray-box and ray-triangle intersection tests.
    • RayTestsPerWave: This counter collects ray intersection test count at a more granular level – per wave.
  • New Scalar and Instruction cache counters on AMD RDNA™ Radeon™ RX 5000 series GPUs.
    • Scalar cache: ScalarCacheHit, ScalarCacheRequestCount, ScalarCacheHitCount, ScalarCacheMissCount
    • Instruction cache: InstCacheHit, InstCacheRequestCount, InstCacheHitCount, InstCacheMissCount
  • Update the Vulkan® sample to remove the static link and use the system-specific Vulkan® loader.
  • Remove OpenCL™ support from Linux.
  • Remove downloading the Vulkan® SDK by the build script.

System Requirements

• An AMD Radeon GPU or APU based on Graphics IP version 8 and newer.
• Windows: Radeon Software Adrenaline 2020 Edition 20.11.2 or later (Driver Packaging Version 20.45 or later).
• Linux: Radeon Software for Linux Revision 20.45 or later.
• Radeon GPUs or APUs based on Graphics IP version 6 and 7 are no longer supported by GPUPerfAPI. Please use an older version (3.3) with older hardware.
• Windows 7, 8.1, and 10.
• Ubuntu (16.04 and later) and CentOS/RHEL (7 and later) distributions.

Cloning the Repository

To clone the GPA repository, execute the following git command

• git clone https://github.com/GPUOpen-Tools/gpu_performance_api

After cloning the repository, please run the following python script to retrieve the required dependencies and generate the build files (see BUILD.md for more information):

• python PreBuild.py

Source Code Directory Layout

• build -- contains build scripts and cmake build modules
• docs -- contains sphinx documentation sources and a Doxygen configuration file
• include -- contains GPUPerfAPI public headers
• scripts -- scripts to use to clone/update dependent repositories
• source/auto_generated -- contains auto-generated source code used when building GPUPerfAPI
• source/examples -- contains the source code for a DirectX 12, DirectX 11, Vulkan and OpenGL sample which use GPUPerfAPI
• source/gpu_perf_api_common -- contains source code for a Common library shared by all versions of GPUPerfAPI
• source/gpu_perf_api_cl -- contains the source for the OpenCL™ version of GPUPerfAPI
• source/gpu_perf_api_counter_generator -- contains the source code for a Common library providing all counter data
• source/gpu_perf_api_counters -- contains the source code for a library that can be used to query counters without an active GPUPerfAPI context
• source/gpu_perf_api_dx -- contains source code shared by the DirectX versions of GPUPerfAPI
• source/gpu_perf_api_dx11 -- contains the source for the DirectX11 version of GPUPerfAPI
• source/gpu_perf_api_dx12 -- contains the source for the DirectX12 version of GPUPerfAPI
• source/gpu_perf_api_gl -- contains the source for the OpenGL version of GPUPerfAPI
• source/gpu_perf_api_unit_tests -- contains a small set of unit tests for GPUPerfAPI
• source/gpu_perf_api_vk -- contains the source for the Vulkan version of GPUPerfAPI
• source/public_counter_compiler -- source code for a tool to generate C++ code for public counters from text files defining the counters.
• source/public_counter_compiler_input_files -- input files that can be fed as input to the PublicCounterCompiler tool

Documentation

The documentation for GPUPerfAPI can be found in each GitHub release. In the release .zip file or .tgz file, there will be a "docs" directory. Simply open the index.html file in a web browser to view the documentation.

The documentation is hosted publicly at: http://gpuperfapi.readthedocs.io/en/latest/

Raw Hardware Counters

This release exposes both "Derived" counters and "Raw Hardware" counters. Derived counters are counters that are computed using a set of raw hardware counters. While querying raw hardware counters was possible in earlier GPUPerfAPI releases, the current release makes it much simpler. In previous releases, you had to build GPUPerfAPI with special build flags in order to produce an "Internal" version that exposed the raw hardware counters. Current versions allow you to access the raw hardware counters in a default build, by simply specifying a new flag when calling GPA_OpenContext. The current CMake build system still allows you to produce an "Internal" build of GPUPerfAPI that also exposes the raw hardware counters, but that is a deprecated build and it is likely to be removed in a future release.

Known Issues

• On Ubuntu 20.04 LTS, Vulkan ICD may not be set to use AMD Vulkan ICD. In this case, it needs to be explicitly set to use AMD Vulkan ICD before using the GPA. It can be done by setting the "VK_ICD_FILENAMES" environment variable to "/etc/vulkan/icd.d/amd_icd64.json"
• VSVerticesIn, HSPatches, and DSVerticesIn counters aren't availbale on Radeon RX 6000 Series GPU using OpenGL.
• FetchSize counter will show an error when enabled on Radeon RX 6000 Series GPU using OpenGL. This is expected to be fixed in a future driver release.
• Adjusting the GPU clock mode on Linux is accomplished by writing to
  
  /sys/class/drm/card<N>/device/power_dpm_force_performance_level
  
  where <N> is the index of the card in question. By default this file is only modifiable by root, so the application being profiled would have to be run as root in order for it to modify the clock mode. It is possible to modify the permissions for the file instead so that it can be written by unprivileged users. The following command will achieve this. Note, however, that changing the permissions on a system file like this could circumvent security. Also, on multi-GPU systems, you may have to replace "card0" with the appropriate card number. Permissions on this file may be reset when rebooting the system:
  • sudo chmod ugo+w /sys/class/drm/card0/device/power_dpm_force_performance_level
• The following performance counter values may not be accurate for DirectX 11 applications running on a Radeon 5700, and 6000 Series GPU. This is expected to be fixed in a future driver release.
  • VALUInstCount, SALUInstCount, VALUBusy, SALUBusy for all shader stages: These values should be representative of performance, but may not be 100% accurate.
  • Most of the ComputeShader counters (all except the MemUnit and WriteUnit counters): These values should be representative of performance, but may not be 100% accurate.
• The following performance counter values may not be accurate for OpenGL applications running on a Radeon 5700 Series GPU. This is expected to be addressed in a future driver release:
  • VALUInstCount, SALUInstCount, VALUBusy, SALUBusy for all shader stages: These values should be representative of performance, but may not be 100% accurate.
  • Most of the ComputeShader counters (all except the MemUnit and WriteUnit counters): These values should be representative of performance, but may not be 100% accurate.
• On Linux, setting the GPU clock mode is not working correctly for Radeon 5700 Series GPUs, potentially leading to some inconsistencies in counter values from one run to the next. This is expected to be addressed in a future driver release.

Style and Format Change

The source code of this product is being reformatted to follow the Google C++ Style Guide https://google.github.io/styleguide/cppguide.html. In the interim you may encounter a mix of both an older C++ coding style, as well as the newer Google C++ Style. Please refer to the _clang-format file in the root directory of the product for additional style information.