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