GPA 3.8 updates

Author: PLohrmannAMD

BUILD.md

@@ -11,7 +11,7 @@ GPUPerfAPI no longer uses git submodules to reference dependent repositories. In
 order to clone/update any dependent repositories.
 
 #### Prerequisites
-  * Python, which can be installed from https://www.python.org/. Either Python 2.7 or 3.x should work.
+  * Python 3.x, which can be installed from https://www.python.org/.
   * CMake 3.7.2 or newer
     * For Windows, this can be downloaded from https://cmake.org/download/
     * For Linux, this can be installed using: sudo apt-get install cmake
@@ -32,8 +32,8 @@ present on the system, this script will instead do a "git pull" on those reposit
 this script everytime you pull new changes from GPA repository.
  * NOTE: For GPA 3.3 or newer, if you are updating an existing clone of the GPA repo from a GPA release prior than 3.3, you will first need to delete the Common/Lib/Ext/GoogleTest directory. Starting with GPA 3.3, GPA is now using a fork of the official GoogleTest repo. Failure to remove this directory will lead to git errors when running [pre_build.py](build/pre_build.py) or [fetch_dependencies.py](scripts/fetch_dependencies.py).
  * This script will also download and execute the Vulkan� SDK installer.
-   * On Windows, running the installer may require elevation.  If you've previously installed the required Vulkan version, UpdateCommon will simply copy the files form the default installation location into the correct place into the GPUPerfAPI directory tree.
-   * UpdateCommon is set up to install the version of the Vulkan SDK which was used during development. If you want to use a newer version of the SDK, the following file will need to be updated:
+   * On Windows, running the installer may require elevation.  If you've previously installed the required Vulkan version, fetch_dependencies.py will simply copy the files from the default installation location into the correct place into the GPUPerfAPI directory tree.
+   * fetch_dependencies.py is set up to install the version of the Vulkan SDK which was used during development. If you want to use a newer version of the SDK, the following file will need to be updated:
      * [fetch_dependencies.py](scripts/fetch_dependencies.py)
    * By default the build will expect the Vulkan SDK to be found in a directory pointed to by the `VULKAN_SDK` environment variable. This environment variable is automatically set by the Windows SDK installer, but you may need to set it manually after running the Linux SDK installer. The Linux SDK includes a script called `setup-env.sh` to aid in setting this environment variable:
      * `source ~/VulkanSDK/1.0.68.0/setup-env.sh` (adjust path as necessary)
@@ -44,7 +44,6 @@ this script everytime you pull new changes from GPA repository.
     * `--config=[debug,release]`: Specify the config for which to generate makefiles. Default is both. A specific config can only be specified on Linux. On Windows, both configs are always supported by the generated VS solution and project files.
    * `--platform=[x86,x64]`: Specify the platform for which to generate build files. Default is both.
    * `--clean`: Deletes CMakeBuild directory and regenerates all build files from scratch
-   * `--internal`: Generates build files to build the internal version of GPA
    * `--skipdx11`: Does not generate build files for DX11 version of GPA (Windows only)
    * `--skipdx12`: Does not generate build files for DX12 version of GPA (Windows only)
    * `--skipvulkan`: Does not generate build files for Vulkan version of GPA
@@ -65,12 +64,11 @@ this script everytime you pull new changes from GPA repository.
 ##### Build Instructions
  * Load cmake_bld\x64\GPUPerfAPI.sln into Visual Studio to build the 64-bit version of GPA
  * Load cmake_bld\x86\GPUPerfAPI.sln into Visual Studio to build the 32-bit version of GPA
- * After a successful build, the GPUPerfAPI binaries can be found in `GPA\Output\$(Configuration)` (for example GPA\Output\Release)
+ * After a successful build, the GPUPerfAPI binaries can be found in `gpu_performance_api\output\$(Configuration)` (for example gpu_performance_api\output\release)
 
 #### Additional Information
  * The Windows projects each include a .rc file that embeds the VERSIONINFO resource into the final binary. Internally within AMD, a Jenkins build system will dynamically update
    the build number. The version and build numbers can be manually updated by modifying the [gpa_version.h](source/gpu_perf_api_common/gpa_version.h) file.
- * When building the internal version (using the --internal switch when calling [pre_build.py](build/pre_build.py), each binary filename will have a "-Internal" suffix (for example GPUPerfAPIDX11-x64-Internal.dll)
 
 ## Linux Build Information
 
@@ -83,7 +81,7 @@ this script everytime you pull new changes from GPA repository.
  * Execute "make" in the cmake_bld/x64/release to build the 64-bit release version of GPA
  * Execute "make" in the cmake_bld/x86/debug to build the 32-bit debug version of GPA
  * Execute "make" in the cmake_bld/x86/release to build the 32-bit release version of GPA
- * After a successful build, the GPUPerfAPI binaries can be found in `GPA/Output/$(Configuration)` (for example GPA/Output/release)
+ * After a successful build, the GPUPerfAPI binaries can be found in `gpu_performance_api/output/$(Configuration)` (for example gpu_performance_api/output/release)
  * When building the internal version, each binary filename will also have a "-Internal" suffix (for example libGPUPerfAPIGL-Internal.so)
 
 ## PublicCounterCompiler Tool

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2016-2020 Advanced Micro Devices, Inc. All rights reserved.
+Copyright (c) 2016-2021 Advanced Micro Devices, Inc. All rights reserved.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,16 +1,11 @@
 # GPU Performance API
 ---
-
-## Overview
-The GPU Performance API (GPUPerfAPI, or GPA) is a powerful library, providing access to GPU Performance Counters.
+The GPU Performance API (GPUPerfAPI, or GPA) is a powerful library which provides 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](https://github.com/GPUOpen-Tools/RCP) and [CodeXL](https://github.com/GPUOpen-Tools/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
+is used by [Radeon GPU Profiler](https://github.com/GPUOpen-Tools/radeon_gpu_profiler) as well as several third-party tools.
 
 ## Table of Contents
+* [Downloads](#downloads)
 * [Major Features](#major-features)
 * [What's New](#whats-new)
 * [System Requirements](#system-requirements)
@@ -24,6 +19,9 @@ Prebuilt binaries can be downloaded from the Releases page: https://github.com/G
 * [Historical Release Notes](ReleaseNotes.md)
 * [Style and Format Change](#Style-and-Format-Change)
 
+## Downloads
+Prebuilt binaries can be downloaded from the Releases page: https://github.com/GPUOpen-Tools/gpu_performance_api/releases.
+
 ## 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™.
@@ -33,24 +31,21 @@ Prebuilt binaries can be downloaded from the Releases page: https://github.com/G
 * Provides access to some raw hardware counters. See [Raw Hardware Counters](#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.
+* Version 3.8 (04/01/21)
+  * Add support for additional GPUs and APUs, including AMD Radeon™ RX 6700 series GPUs.
+  * Code has been updated to adhere to Google C++ Style Guide.
+    * New public headers have been added.
+    * Old headers are deprecated and will emit compile-time message.
+    * Projects loading GPA will need to be recompiled, but no code changes are required unless moving to the new headers.
+  * Improvements made to sample applications.
+  * Updated documentation for new codestyle (and https://github.com/GPUOpen-Tools/gpu_performance_api/issues/56)
+  * Support for the --internal flag to has been removed from 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](https://github.com/GPUOpen-Tools/GPA/releases/tag/v3.3)) with older hardware.
+* 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](https://github.com/GPUOpen-Tools/gpu_performance_api/releases/tag/v3.3)) with older hardware.
 * Windows 7, 8.1, and 10.
 * Ubuntu (16.04 and later) and CentOS/RHEL (7 and later) distributions.
 
@@ -59,12 +54,12 @@ 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](BUILD.md) for more information):
-  * python PreBuild.py
+  * python pre_build.py
 
 ## Source Code Directory Layout
 * [build](build) -- contains build scripts and cmake build modules
 * [docs](docs) -- contains sphinx documentation sources and a Doxygen configuration file
-* [include](include) -- contains GPUPerfAPI public headers
+* [include/gpu_performance_api](include/gpu_performance_api) -- contains GPUPerfAPI public headers
 * [scripts](scripts) -- scripts to use to clone/update dependent repositories
 * [source/auto_generated](source/auto_generated) -- contains auto-generated source code used when building GPUPerfAPI
 * [source/examples](source/examples) -- contains the source code for a DirectX 12, DirectX 11, Vulkan and OpenGL sample which use GPUPerfAPI
@@ -89,31 +84,39 @@ The documentation is hosted publicly at: http://gpuperfapi.readthedocs.io/en/lat
 
 ## 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.
+This version allows you to access the raw hardware counters by simply specifying a flag when calling GpaOpenContext.
 
 ## 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 <br><br>/sys/class/drm/card\<N\>/device/power_dpm_force_performance_level<br><br> 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.
+### Ubuntu 20.04 LTS Vulkan ICD Issue
+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```.
+
+### OpenGL Fetchsize Counter on Radeon RX 6000
+FetchSize counter will show an error when enabled on Radeon RX 6000 Series GPU using OpenGL.
+
+### Adjusting Linux Clock Mode
+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: ```sudo chmod ugo+w /sys/class/drm/card0/device/power_dpm_force_performance_level```
+* Note that changing the permissions on a system file like this could circumvent security.
+* On multi-GPU systems you may have to replace "card0" with the appropriate card number.
+* You may have to reboot the system for the change to take effect.
+* Setting the GPU clock mode is not working correctly for <b>Radeon 5700 Series GPUs</b>, potentially leading to some inconsistencies in counter values from one run to the next.
+
+### DirectX11 Performance Counter Accuracy For Select Counters and GPUs
+The following performance counter values may not be accurate for DirectX 11 applications running on a Radeon 5700, and 6000 Series GPU.
+* 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.
+
+### OpenGL Performance Counter Accuracy For Radeon 7500
+The following performance counter values may not be accurate for OpenGL applications running on a Radeon 5700 Series GPU.
+* 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.
+
+### Variability in Deterministic Counters For Select GPUs
+Performance counters which should be deterministic are showing variability on Radeon 5700 and 6000 Series GPUs. The values should be useful for performance analysis, but may not be 100% correct.
+* e.g. VSVerticesIn, PrimitivesIn, PSPixelsOut, PreZSamplesPassing
+
+### Profiling Bundles
+Profiling bundles in DirectX12 and Vulkan is not working properly. It is recommended to remove those GPA Samples from your application, or move the calls out of the bundle for profiling.
 
 ## Style and Format Change