|
| 1 | +# GPUPerfAPI Build Instructions |
| 2 | +--- |
| 3 | +## Table of Contents |
| 4 | +* [Windows Build Information](#Windows) |
| 5 | +* [Linux Build Information](#Linux) |
| 6 | +* [PublicCounterCompiler Tool](#PublicCounterCompiler) |
| 7 | + |
| 8 | +<A Name="Windows"> |
| 9 | +## Windows Build Information |
| 10 | + |
| 11 | +##### Prerequisites |
| 12 | + * Microsoft Visual Studio 2015 Community Edition or higher + Update 1 |
| 13 | + * Windows 10 SDK Version 10.0.10586.0 from https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk |
| 14 | + * You can override the version of the Windows 10 SDK used by modifying Common/Lib/Ext/Windows-Kits/Global-WindowsSDK.props |
| 15 | + |
| 16 | +##### Build Instructions |
| 17 | + * Load Build\VS2015\GPUPerfAPI.sln into Visual Studio |
| 18 | + * Build the 64-bit and/or 32-bit configuration |
| 19 | + * After a successful build, the GPUPerfAPI binaries can be found in __Build\VS2015\\$(Configuration)-$(Platform)__ (for example Build\VS2015\Release-x64) |
| 20 | + |
| 21 | +#### Additional Information |
| 22 | + * The Visual Studio solution includes a Documentation project that allows you to generate the HTML-based source code documentation using Doxygen. In order |
| 23 | + to build that project, you'll need to modify [Documentation.vcxproj](GPUPerfAPI/Build/VS2015/Documentation.vcxproj) and modify the paths to the doxygen executable. |
| 24 | + * 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 |
| 25 | + the build number. The version and build numbers can be manually updated by modifying the [GPAVersion.h](GPUPerfAPI/GPUPerfAPI-Common/GPAVersion.h) file. |
| 26 | + * Information on building the Internal version: |
| 27 | + * To generate the internal version, two environment variables are required to be set prior to building in Visual Studio: |
| 28 | + * GDT_BUILD=GDT_INTERNAL |
| 29 | + * GDT_BUILD_SUFFIX=-Internal |
| 30 | + * The output location of the binaries will be __Build\VS2015\\$(Configuration)-$(Platform)-Internal__ (for example Build\VS2015\Release-x64-Internal) |
| 31 | + * Each binary filename will also have a "-Internal" suffix (for example GPUPerfAPIDX11-x64-Internal.dll) |
| 32 | + |
| 33 | +<A Name="Linux"> |
| 34 | +## Linux Build Information |
| 35 | + |
| 36 | +##### Build Instructions |
| 37 | + * cd into the Build\Linux directory |
| 38 | + * Execute __./build.sh__ |
| 39 | + * By default this performs a from-scratch build of the release versions of GPUPerfAPI, both 32-bit and 64-bit binaries. |
| 40 | + * The following arguments can be passed to build.sh to alter the build: |
| 41 | + * __debug__: performs a debug build |
| 42 | + * __skip32buildbuild__: skips building the 32-bit binaries |
| 43 | + * __skipopengl__: skips building the OpenGL version of GPUPerfAPI |
| 44 | + * __skipopengles__: skips building the OpenGLES version of GPUPerfAPI |
| 45 | + * __skipopencl__: skips building the OpenCL version of GPUPerfAPI |
| 46 | + * __skiphsa__: skips building the ROCm/HSA version of GPUPerfAPI |
| 47 | + * __quick__ or __incremental__: performs an incremental build (as opposed to a from-scratch build) |
| 48 | + * __buildinternal__: builds the internal versions of GPUPerfAPI |
| 49 | + * __hsadir__: overrides the location of the ROCm/HSA header files (by default they are expected to be in /opt/rocm/hsa) |
| 50 | + * After a successful build, the GPUPerfAPI binaries can be found in their respective source file directories. For instance, the binaries for the OpenGL version of GPUPerfAPI (libGPUPerfAPIGL.so) can be found in the GPUPerfAPIGL subdirectory. |
| 51 | + * Example build command line (builds the debug versions of the binaries, skipping the HSA library): |
| 52 | + * ./build.sh debug skiphsa |
| 53 | + * In addition to using the build.sh build script to build all of GPUPerfAPI, you can also build a single API library by executing __make__ in that library's directory. This is useful when making localized changes in a single version of GPUPerfAPI. When using __make__, the following default targets are supported: |
| 54 | + * __\<default\>__: makes the 64-bit release version |
| 55 | + * __x86__: makes the 32-bit release version |
| 56 | + * __Dbg__: makes the 64-bit debug version |
| 57 | + * __Dbgx86__: makes the 32-bit debug version |
| 58 | + * __Internal__: makes the 64-bit release Internal version |
| 59 | + * __Internalx86__: makes the 32-bit release Internal version |
| 60 | + * __DbgInternal__: makes the 64-bit debug Internal version |
| 61 | + * __DbgInternalx86__: makes the 32-bit debug Internal version |
| 62 | + * __Make__ is supported in the following directories (those marked with (*) are required to be built before the others, as they produce static libraries used by the others): |
| 63 | + * DeviceInfo (*) |
| 64 | + * GPUPerfAPI-Common (*) |
| 65 | + * GPUPerfAPICounterGenerator (*) |
| 66 | + * GPUPerfAPICounters |
| 67 | + * GPUPerfAPICL |
| 68 | + * GPUPerfAPIGL |
| 69 | + * GPUPerfAPIGLES |
| 70 | + * GPUPerfAPIHSA |
| 71 | + * When using __make__ to build the ROCM/HSA version of GPUPerfAPI, by default the HSA headers are expected to be in /opt/rocm/hsa. You can override this by specifying "HSA_DIR=<dir>" on the make command line: |
| 72 | + * Example: make Dbg HSA_DIR=/home/user/hsa_dir |
| 73 | + * When building the internal version, each binary filename will also have a "-Internal" suffix (for example libGPUPerfAPIGL-Internal.so) |
| 74 | + |
| 75 | +<A NAME="PublicCounterCompiler"> |
| 76 | +## PublicCounterCompiler Tool |
| 77 | + |
| 78 | +The PublicCounterCompiler Tool is a utility, written in C#, that will generate C++ code to define the public (or derived) counters. |
| 79 | +It takes as input text files contained in the [PublicCounterCompilerInputFiles](GPUPerfAPI/PublicCounterCompilerInputFiles) directory and |
| 80 | +outputs files in the [GPUPerfAPICounterGenerator](GPUPerfAPI/GPUPerfAPICounterGenerator) and [GPUPerfAPIUnitTests](GPUPerfAPI/GPUPerfAPIUnitTests) directories. |
| 81 | + |
| 82 | +There are three ways to execute the tool: |
| 83 | +* With no parameters - it opens the user interface with no fields prepopulated |
| 84 | +* With two parameters - it opens the user interface with the two main fields prepopulated. When you press the "Compile Public Counters" button it will load the correct input files and generate the output files in the correct location. |
| 85 | + * Param 1: API -- the API to compile counters for (ex: GL, CL, HSA, DX11, etc). |
| 86 | + * Param 2: HW generation: the generation to compile counters for (ex: Gfx6, Gfx7, Gfx8, etc.) |
| 87 | +* With five parameters - the user interface does not open. It simply generates the c++ files using the specified input and output file locations |
| 88 | + * Param 1: Counter names file - text file containing hardware counter names and type (CounterNames[API][GEN].txt) |
| 89 | + * Param 2: Public counter definition file - text file defining how the public counters are calculated (PublicCounterDefinitions\*.txt) |
| 90 | + * Param 3: Output Dir - the directory to generate the output in (Ex: the path to the GPUPerfAPICounterGenerator directory) |
| 91 | + * Param 4: Test output Dir - the directory to generate the test output in (Ex: the path to the GPUPerfAPIUnitTests/counters directory) |
| 92 | + * Param 5: Active section label - the label to take the counter names from (ex: dx11gfx6) |
| 93 | + |
| 94 | +See the various PublicCounterDefinitions\*.txt files in the [PublicCounterCompilerInputFiles](GPUPerfAPI/PublicCounterCompilerInputFiles) directory. These contain all the counter definitions. |
| 95 | +Each counter is given a name, a description, a type, an optional usage type, a list of hardware counters required and a formula applied to the values of the hardware counters to calculate the value of the counter. |
| 96 | + |
| 97 | +Counter formulas are expressed in a Reverse Polish Notation and are made up the following elements: |
| 98 | +* numbers: these are zero-based counter indexes referring to individual counters within the list of hardware counters |
| 99 | +* math operators: The supported operators are +, -, /, * |
| 100 | +* numeric literals: Numbers contained within parentheses are numeric literals (as opposed to counter indexes) |
| 101 | +* functions: The supported functions are: min, max, sum, and ifnotzero. "max and "sum" have variants that work on multiple items at once (i.e. sum16, sum63, etc.) |
| 102 | +* hardware params: The supported hardware params are "num_shader_engines". "num_simds", "su_clock_prim", "num_prim_pipes", and "TS_FREQ" |
| 103 | + |
| 104 | +For more details, see the "EvaluateExpression" function in the [GPAPublicCounters.cpp](GPUPerfAPI/GPUPerfAPICounterGenerator/GPAPublicCounters.cpp) file. |
| 105 | + |
0 commit comments