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