You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
*[Building the Documentation](#building-the-documentation)
8
9
9
10
## Cloning/Updating Dependent Repositories
10
11
GPUPerfAPI no longer uses git submodules to reference dependent repositories. Instead, you need to follow these instructions in
11
12
order to clone/update any dependent repositories.
12
13
13
14
#### Prerequisites
14
-
*This step requires that python be installed on the system. Python can be installed from https://www.python.org/
15
+
* Python, which can be installed from https://www.python.org/
15
16
16
17
#### Instructions
17
18
* Simply execute the [UpdateCommon.py](Scripts/UpdateCommon.py) python script located in the [Scripts](Scripts) directory:
18
19
*`python Scripts/UpdateCommon.py`
19
-
This script will clone any dependent repositories that are not present on the system. If any of the dependent repositories are already
20
+
*This script will clone any dependent repositories that are not present on the system. If any of the dependent repositories are already
20
21
present on the system, this script will instead do a "git pull" on those repositories to ensure that they are up to date. Please re-run
21
22
this script everytime you pull new changes from GPA repository.
23
+
* This script will also download and execute the Vulkan™ SDK installer.
24
+
* 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.
25
+
* 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 files will need to be updated:
@@ -45,23 +52,27 @@ this script everytime you pull new changes from GPA repository.
45
52
46
53
## Linux Build Information
47
54
55
+
##### Prerequisites
56
+
* Install the Mesa common development package: sudo apt-get install mesa-common-dev
57
+
* For 32-bit builds, install the multilib packages: sudo apt-get install gcc-multilib g++-multilib
58
+
48
59
##### Build Instructions
49
60
* cd into the Build\Linux directory
50
61
* Execute `./build.sh`
51
62
* By default this performs a from-scratch build of the release versions of GPUPerfAPI, both 32-bit and 64-bit binaries.
52
63
* The following arguments can be passed to build.sh to alter the build:
53
64
*`debug`: performs a debug build
54
-
*`skip32buildbuild`: skips building the 32-bit binaries
65
+
*`skip32bitbuild`: skips building the 32-bit binaries
55
66
*`skipopengl`: skips building the OpenGL version of GPUPerfAPI
56
-
*`skipopengles`: skips building the OpenGLES version of GPUPerfAPI
57
67
*`skipopencl`: skips building the OpenCL version of GPUPerfAPI
58
68
*`skiphsa`: skips building the ROCm/HSA version of GPUPerfAPI
69
+
*`skipvulkan`: skips building the Vulkan version of GPUPerfAPI
59
70
*`quick` or `incremental`: performs an incremental build (as opposed to a from-scratch build)
60
71
*`buildinternal`: builds the internal versions of GPUPerfAPI
61
72
*`hsadir`: overrides the location of the ROCm/HSA header files (by default they are expected to be in /opt/rocm/hsa)
62
73
*`gtestlibdir`: overrides the location of the GoogleTest libraries (by default they are expected to be in Common/Lib/Ext/GoogleTest/1-7/lib/gcc5/x64. There is also a gcc4.x-compatible version in Common/Lib/Ext/GoogleTest/1-7/lib/x64 for use when building on a system with gcc 4.x)
63
74
*`gtestlibdir32`: overrides the location of the 32-bit GoogleTest libraries (by default they are expected to be in Common/Lib/Ext/GoogleTest/1-7/lib/gcc5/x86. There is also a gcc4.x-compatible version in Common/Lib/Ext/GoogleTest/1-7/lib/x86 for use when building on a system with gcc 4.x)
64
-
* 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 Src/GPUPerfAPIGL subdirectory.
75
+
* After a successful build, the GPUPerfAPI binaries can be found in Output/bin.
65
76
* Example build command line (builds the debug versions of the binaries, skipping the HSA library):
66
77
* ./build.sh debug skiphsa
67
78
* 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:
@@ -75,13 +86,14 @@ this script everytime you pull new changes from GPA repository.
75
86
*`DbgInternalx86`: makes the 32-bit debug Internal version
76
87
*`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):
77
88
* DeviceInfo (*)
89
+
* GPUPerfAPI (*)
78
90
* GPUPerfAPI-Common (*)
79
91
* GPUPerfAPICounterGenerator (*)
80
92
* GPUPerfAPICounters
81
93
* GPUPerfAPICL
82
94
* GPUPerfAPIGL
83
-
* GPUPerfAPIGLES
84
95
* GPUPerfAPIHSA
96
+
* GPUPerfAPIVk
85
97
* 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:
86
98
* Example: make Dbg HSA_DIR=/home/user/hsa_dir
87
99
* When building the internal version, each binary filename will also have a "-Internal" suffix (for example libGPUPerfAPIGL-Internal.so)
@@ -90,29 +102,51 @@ this script everytime you pull new changes from GPA repository.
90
102
91
103
The PublicCounterCompiler Tool is a utility, written in C#, that will generate C++ code to define the public (or derived) counters.
92
104
It takes as input text files contained in the [PublicCounterCompilerInputFiles](Src/PublicCounterCompilerInputFiles) directory and
93
-
outputs files in the [GPUPerfAPICounterGenerator](Src/GPUPerfAPICounterGenerator) and [GPUPerfAPIUnitTests](Src/GPUPerfAPIUnitTests) directories.
105
+
outputs files in the [GPUPerfAPICounterGenerator](Src/GPUPerfAPICounterGenerator), [GPUPerfAPIUnitTests](Src/GPUPerfAPIUnitTests)
106
+
and [docs](docs) directories.
94
107
95
108
There are three ways to execute the tool:
96
109
* With no parameters - it opens the user interface with no fields prepopulated
97
110
* 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.
98
-
* Param 1: API -- the API to compile counters for (ex: GL, CL, HSA, DX11, etc).
111
+
* Param 1: API -- the API to compile counters for (ex: GL, CL, HSA, DX11, DX12, VK, etc).
99
112
* Param 2: HW generation: the generation to compile counters for (ex: Gfx6, Gfx7, Gfx8, etc.)
100
-
* With five parameters - the user interface does not open. It simply generates the c++ files using the specified input and output file locations
113
+
* With six or seven parameters - the user interface does not open. It simply generates the c++ files using the specified input and output file locations
101
114
* Param 1: Counter names file - text file containing hardware counter names and type (CounterNames[API][GEN].txt)
102
115
* Param 2: Public counter definition file - text file defining how the public counters are calculated (PublicCounterDefinitions\*.txt)
103
116
* Param 3: Output Dir - the directory to generate the output in (Ex: the path to the GPUPerfAPICounterGenerator directory)
104
117
* Param 4: Test output Dir - the directory to generate the test output in (Ex: the path to the GPUPerfAPIUnitTests/counters directory)
105
-
* Param 5: Active section label - the label to take the counter names from (ex: dx11gfx6)
118
+
* Param 5: API - the API to take the counter names from (ex: DX12)
119
+
* Param 6: GPU - the GPU to take the counter names from (ex: Gfx9)
120
+
* Param 7: GPU ASIC - (optional) the subversion of GPU to take the counter names from
106
121
107
122
See the various PublicCounterDefinitions\*.txt files in the [PublicCounterCompilerInputFiles](Src/PublicCounterCompilerInputFiles) directory. These contain all the counter definitions.
108
123
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.
109
124
110
125
Counter formulas are expressed in a Reverse Polish Notation and are made up the following elements:
111
126
* numbers: these are zero-based counter indexes referring to individual counters within the list of hardware counters
127
+
* hardware counters may also be referred to by name (e.g.: GPUTime_Bottom_To_Bottom) or templated name (e.g.: SPI*_SPI_PERF_CSG_BUSY) which will automatically refer to the correct number of instances
112
128
* math operators: The supported operators are +, -, /, *
113
129
* numeric literals: Numbers contained within parentheses are numeric literals (as opposed to counter indexes)
114
-
* 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.)
130
+
* functions: The supported functions are: min, max, sum, ifnotzero, and vcomparemax4. "max and "sum" have variants that work on multiple items at once (i.e. sum16, sum64, etc.)
115
131
* hardware params: The supported hardware params are "num_shader_engines". "num_simds", "su_clock_prim", "num_prim_pipes", and "TS_FREQ"
116
132
117
133
For more details, see the "EvaluateExpression" function in the [GPAPublicCounters.cpp](Src/GPUPerfAPICounterGenerator/GPAPublicCounters.cpp) file.
118
134
135
+
## Building the Documentation
136
+
137
+
##### Prerequisites
138
+
* A working python installation is required
139
+
* Install Sphinx:
140
+
*`pip install Sphinx`
141
+
* Install Sphinx Read The Docs theme:
142
+
*`pip install sphinx-rtd-theme` (read the docs theme is not installed by default)
143
+
* Install spelling checker (optional)
144
+
*`pip install pyenchant`
145
+
*`pip install sphinxcontrib-spelling`
146
+
147
+
##### Building
148
+
* Once you have Sphinx installed, simply run the following command from the "docs" subdirectory:
149
+
*`make html`
150
+
* To run the spelling checker:
151
+
* edit conf.py and uncomment the line adding in the `sphinxcontrib.spelling` extension
0 commit comments