Merge bug fixes from Khronos CTS release branch am: 3d8e6ee58a
[platform/upstream/VK-GL-CTS.git] / external / vulkancts / README.md
1 Vulkan CTS README
2 =================
3
4 This document describes how to build and run Vulkan Conformance Test suite.
5
6 Vulkan CTS is built on dEQP framework. dEQP documentation is available
7 at http://source.android.com/devices/graphics/testing.html
8
9
10 Requirements
11 ------------
12
13 ### Common
14
15  * Git (for checking out sources)
16  * Python 2.7.x (all recent versions in 2.x should work, 3.x is not supported)
17  * CMake 2.8 or newer
18
19 ### Win32
20
21  * Visual Studio 2013 or newer (glslang uses several C++11 features)
22
23 ### Linux
24
25  * Standard toolchain (make, gcc/clang)
26
27 ### Android
28
29  * Android NDK r10e
30  * Android SDK with: SDK Tools, SDK Platform-tools, SDK Build-tools, and API 22
31  * Apache Ant
32  * Windows: either NMake or JOM in PATH
33
34
35 Building CTS
36 ------------
37
38 To build dEQP, you need first to download sources for zlib, libpng, glslang,
39 and spirv-tools.
40
41 To download sources, run:
42
43         python external/fetch_sources.py
44
45 You may need to re-run `fetch_sources.py` to update to the latest glslang and
46 spirv-tools revisions occasionally.
47
48 NOTE: glslang integration is not yet available on Android due to a toolchain
49 bug, so pre-compiled SPIR-V binaries must be used. See instructions below.
50
51 With CMake out-of-source builds are always recommended. Create a build directory
52 of your choosing, and in that directory generate Makefiles or IDE project
53 using cmake.
54
55
56 ### Windows x86-32
57
58         cmake <path to vulkancts> -G"Visual Studio 12"
59         start dEQP-Core-default.sln
60
61 ### Windows x86-64
62
63         cmake <path to vulkancts> -G"Visual Studio 12 Win64"
64         start dEQP-Core-default.sln
65
66 ### Linux 32-bit Debug
67
68         cmake <path to vulkancts> -DCMAKE_BUILD_TYPE=Debug -DCMAKE_C_FLAGS=-m32 -DCMAKE_CXX_FLAGS=-m32
69         make -j
70
71 Release build can be done by using -DCMAKE_BUILD_TYPE=Release
72
73 ### Linux 64-bit Debug
74
75         cmake <path to vulkancts> -DCMAKE_BUILD_TYPE=Debug -DCMAKE_C_FLAGS=-m64 -DCMAKE_CXX_FLAGS=-m64
76         make -j
77
78 ### Android
79
80 Following command will build CTS into android/package/bin/dEQP-debug.apk.
81
82         python android/scripts/build.py
83
84 The package can be installed by either running:
85
86         python android/scripts/install.py
87
88 By default the CTS package will contain libdeqp.so built for armeabi-v7a, arm64-v8a,
89 and x86 ABIs, but that can be changed in android/scripts/common.py script.
90
91 To pick which ABI to use at install time, following commands must be used
92 instead:
93
94         adb install --abi <ABI name> android/package/bin/dEQP-debug.apk /data/local/tmp/dEQP-debug.apk
95
96
97 Building Mustpass
98 -----------------
99
100 Current mustpass is checked into repository and can be found at:
101
102         external/vulkancts/mustpass/1.0.0/vk-default.txt
103
104 Vulkan CTS mustpass can be re-generated by running:
105
106         python <vulkancts>/external/vulkancts/build_mustpass.py
107
108
109 Pre-compiling SPIR-V binaries
110 -----------------------------
111
112 For distribution, and platforms that don't support GLSL to SPIR-V compilation,
113 SPIR-V binaries must be pre-built with following command:
114
115         python external/vulkancts/build_spirv_binaries.py
116
117 Binaries will be written to `external/vulkancts/data/vulkan/prebuilt/`.
118
119 Test modules (or in case of Android, the APK) must be re-built after building
120 SPIR-V programs in order for the binaries to be available.
121
122
123 Running CTS
124 -----------
125
126 Following command line options MUST be used when running CTS:
127
128         --deqp-caselist-file=<vulkancts>/external/vulkancts/mustpass/1.0.0/vk-default.txt
129         --deqp-log-images=disable
130         --deqp-log-shader-sources=disable
131
132 In addition on multi-device systems the device for which conformance is claimed
133 can be selected with:
134
135         --deqp-vk-device-id=<value>
136
137 To speed up the conformance run on some platforms the following command line
138 option may be used to disable frequent fflush() calls to the output logs:
139
140         --deqp-log-flush=disable
141
142 No other command line options are allowed.
143
144 ### Win32
145
146         cd <builddir>/external/vulkancts/modules/vulkan
147         Debug/deqp-vk.exe --deqp-caselist-file=...
148
149 Test log will be written into TestResults.qpa
150
151 ### Linux
152
153         cd <builddir>/external/vulkancts/modules/vulkan
154         ./deqp-vk --deqp-vk-caselist-file=...
155
156 ### Android
157
158         adb push <vulkancts>/external/vulkancts/mustpass/1.0.0/vk-default.txt /sdcard/vk-default.txt
159         adb shell
160
161 In device shell:
162
163         am start -n com.drawelements.deqp/android.app.NativeActivity -e cmdLine "deqp --deqp-caselist-file=/sdcard/vk-default.txt --deqp-log-images=disable --deqp-log-shader-sources=disable --deqp-log-filename=/sdcard/TestResults.qpa"
164
165 Test progress will be written to device log and can be displayed with:
166
167         adb logcat -s dEQP
168
169 Test log will be written into `/sdcard/TestResults.qpa`.
170
171
172 Conformance Submission Package Requirements
173 -------------------------------------------
174
175 The conformance submission package must contain the following:
176
177 1. Full test logs (`TestResults.qpa`) from CTS runs against all driver builds
178 2. Result of `git status` and `git log` from CTS source directory
179 3. Any patches used on top of release tag
180 4. Conformance statement
181
182 Test logs (1) should be named `<submission pkg dir>/TestResults-<driver build type>.qpa`,
183 for example `TestResults-armeabi-v7a.qpa`. On platforms where multiple different driver
184 builds (for example 64-bit and 32-bit) are present, CTS logs must be provided
185 for each driver build as part of the submission package.
186
187 The CTS build must always be done from clean git repository that doesn't have any
188 uncommitted changes. Thus it is necessary to run and capture output of `git
189 status` and `git log` (2) in the source directory:
190
191         git status > <submission pkg dir>/git-status.txt
192         git log <release tag>..HEAD > <submission pkg dir>/git-log.txt
193
194 Any changes made to CTS must be committed to the local repository, and provided
195 as part of the submission package (3). This can be done by running:
196
197         git format-patch -o <submission pkg dir> <release tag>..HEAD
198
199 In general, bugfixes and changes to platform-specific code (mostly under
200 `framework/platform`) are allowed. The commit message for each change must
201 include a clear description of the change and why it is necessary. Non-porting
202 related changes must be accompanied by a waiver (see below).
203
204 NOTE: When cherry-picking patches on top of release tag, please use `git cherry-pick -x`
205 to include original commit hash in the commit message.
206
207 Conformance statement (4) must be included in a file called `STATEMENT-<adopter>`
208 and must contain following:
209
210         CONFORM_VERSION:         <git tag of CTS release>
211         PRODUCT:                 <string-value>
212         CPU:                     <string-value>
213         OS:                      <string-value>
214
215 Note that product/cpu/os information is also captured in `dEQP-VK.info.*` tests
216 if `vk::Platform::describePlatform()` is implemented.
217
218 If the submission package covers multiple products, you can list them by appending
219 additional `PRODUCT:` lines to the conformance statement. For example:
220
221         CONFORM_VERSION:         vulkan-cts-1.0.0.2
222         PRODUCT:                 Product A
223         PRODUCT:                 Product B
224         ...
225
226 The actual submission package consists of the above set of files which must
227 be bundled into a gzipped tar file named `VK10_<adopter><_info>.tgz`. `<adopter>`
228 is the name of the Adopting member company, or some recognizable abbreviation.
229 The `<_info>` field is optional. It may be used to uniquely identify a submission
230 by OS, platform, date, or other criteria when making multiple submissions.
231
232 One way to create a suiteable gzipped tar file is to execute the command:
233
234         tar -cvzf <filename.tgz> -C <submission pkg dir> .
235
236 where `<submission pkg dir>` is the directory containing the files from (1)-(4)
237 from above. A submission package must contain all of the files listed above,
238 and only those files.
239
240 As an example submission package could contain:
241
242         STATEMENT-Khronos
243         git-log.txt
244         git-status.txt
245         0001-Remove-Waived-Filtering-Tests.patch
246         0002-Fix-Pipeline-Parameters.patch
247         TestResults-armeabi-v7a.qpa
248         TestResults-arm64-v8a.qpa
249
250
251 Waivers
252 -------
253
254 The process for requesting a waiver is to report the issue by filing a bug
255 report in the Gitlab VulkanCTS project (TODO Github?). When creating the
256 submission package, include references to the waiver in the commit message of
257 the relevant change. Including as much information as possible in your bug
258 report (including a unified diff or a merge request of suggested file changes)
259 will ensure the issue can be progressed as rapidly as possible. Issues must
260 be labeled "Waiver" (TODO!) and identify the version of the CTS and affected
261 tests.
262
263 Conformance Criteria
264 --------------------
265
266 Conformance run is considered passing if all tests finish with allowed result
267 codes. Test results are contained in the TestResults.qpa log. Each
268 test case section contains XML tag Result, for example:
269
270         <Result StatusCode="Pass">Not validated</Result>
271
272 The result code is the value of the StatusCode attribute. Following status
273 codes are allowed:
274
275         Pass
276         NotSupported
277         QualityWarning
278         CompatibilityWarning
279
280 Submission package can be verified using `external/vulkancts/verify_submission.py`
281 script. The script takes two arguments: path to extracted submission package
282 and path to current mustpass list. For example:
283
284         python external/vulkancts/verify_submission.py VK_10_Khronos_1/ external/vulkancts/mustpass/1.0.0/vk-default.txt
285
286
287 Vulkan platform port
288 --------------------
289
290 Vulkan support from Platform implementation requires providing
291 `getVulkanPlatform()` method in `tcu::Platform` class implementation.
292
293 See `framework/common/tcuPlatform.hpp` and examples in
294 `framework/platform/win32/tcuWin32Platform.cpp` and
295 `framework/platform/android/tcuAndroidPlatform.cpp`.
296
297
298 Null (dummy) driver
299 -------------------
300
301 For testing and development purposes it might be useful to be able to run
302 tests on dummy Vulkan implementation. One such implementation is provided in
303 vkNullDriver.cpp. To use that, implement `vk::Platform::createLibrary()` with
304 `vk::createNullDriver()`.
305
306
307 Validation Layers
308 -----------------
309
310 Vulkan CTS framework includes first-party support for validation layers, that
311 can be turned on with `--deqp-validation=enable` command line option.
312
313 When validation is turned on, default instance and device will be created with
314 validation layers enabled and debug callback is registered to record any
315 messages. Debug messages collected during test execution will be included at
316 the end of the test case log.
317
318 If any validation errors are found, test result will be set to `InternalError`.
319
320 By default `VK_DEBUG_REPORT_INFORMATION_BIT_EXT` and `_DEBUG_BIT_EXT` messages
321 are excluded from the log, but that can be customized by modifying
322 `vkt::TestCaseExecutor::deinit()` in `vktTestPackage.cpp`.
323
324
325 Cherry GUI
326 ----------
327
328 Vulkan test module can be used with Cherry (GUI for test execution and
329 analysis). Cherry is available at
330 https://android.googlesource.com/platform/external/cherry. Please follow
331 instructions in README to get started.
332
333 To enable support for Vulkan tests, dEQP-VK module must be added to list of
334 test packages.
335
336 In `cherry/testrunner.go`, add following line to `testPackageDescriptors` list
337 (line 645 in `NewTestRunner` function):
338
339         {"dEQP-VK", "deqp-vk", "../external/vulkancts/modules/vulkan", dataDir + "dEQP-VK-cases.xml"},
340
341 Before first launch, and every time test hierarchy has been modified, test
342 case list must be refreshed by running:
343
344         python scripts/build_caselists.py path/to/cherry/data
345
346 Cherry must be restarted for the case list update to take effect.