Merge "Fix deStrnlen fall-back implementation" into nougat-cts-dev
[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.1/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/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.1/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 No other command line options are allowed.
144
145 ### Win32
146
147         cd <builddir>/external/vulkancts/modules/vulkan
148         Debug/deqp-vk.exe --deqp-caselist-file=...
149
150 Test log will be written into TestResults.qpa
151
152 ### Linux
153
154         cd <builddir>/external/vulkancts/modules/vulkan
155         ./deqp-vk --deqp-vk-caselist-file=...
156
157 ### Android
158
159         adb push <vulkancts>/external/vulkancts/mustpass/1.0.1/vk-default.txt /sdcard/vk-default.txt
160         adb shell
161
162 In device shell:
163
164         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"
165
166 Test progress will be written to device log and can be displayed with:
167
168         adb logcat -s dEQP
169
170 Test log will be written into `/sdcard/TestResults.qpa`.
171
172
173 Conformance Submission Package Requirements
174 -------------------------------------------
175
176 The conformance submission package must contain the following:
177
178 1. Full test logs (`TestResults.qpa`) from CTS runs against all driver builds
179 2. Result of `git status` and `git log` from CTS source directory
180 3. Any patches used on top of release tag
181 4. Conformance statement
182
183 Test logs (1) should be named `<submission pkg dir>/TestResults-<driver build type>.qpa`,
184 for example `TestResults-armeabi-v7a.qpa`. On platforms where multiple different driver
185 builds (for example 64-bit and 32-bit) are present, CTS logs must be provided
186 for each driver build as part of the submission package.
187
188 The CTS build must always be done from clean git repository that doesn't have any
189 uncommitted changes. Thus it is necessary to run and capture output of `git
190 status` and `git log` (2) in the source directory:
191
192         git status > <submission pkg dir>/git-status.txt
193         git log --first-parent <release tag>^..HEAD > <submission pkg dir>/git-log.txt
194
195 Any changes made to CTS must be committed to the local repository, and provided
196 as part of the submission package (3). This can be done by running:
197
198         git format-patch -o <submission pkg dir> <release tag>..HEAD
199
200 In general, bugfixes and changes to platform-specific code (mostly under
201 `framework/platform`) are allowed. The commit message for each change must
202 include a clear description of the change and why it is necessary. Non-porting
203 related changes must be accompanied by a waiver (see below).
204
205 NOTE: When cherry-picking patches on top of release tag, please use `git cherry-pick -x`
206 to include original commit hash in the commit message.
207
208 Conformance statement (4) must be included in a file called `STATEMENT-<adopter>`
209 and must contain following:
210
211         CONFORM_VERSION:         <git tag of CTS release>
212         PRODUCT:                 <string-value>
213         CPU:                     <string-value>
214         OS:                      <string-value>
215
216 Note that product/cpu/os information is also captured in `dEQP-VK.info.*` tests
217 if `vk::Platform::describePlatform()` is implemented.
218
219 If the submission package covers multiple products, you can list them by appending
220 additional `PRODUCT:` lines to the conformance statement. For example:
221
222         CONFORM_VERSION:         vulkan-cts-1.0.1.0
223         PRODUCT:                 Product A
224         PRODUCT:                 Product B
225         ...
226
227 The actual submission package consists of the above set of files which must
228 be bundled into a gzipped tar file named `VK10_<adopter><_info>.tgz`. `<adopter>`
229 is the name of the Adopting member company, or some recognizable abbreviation.
230 The `<_info>` field is optional. It may be used to uniquely identify a submission
231 by OS, platform, date, or other criteria when making multiple submissions.
232
233 One way to create a suiteable gzipped tar file is to execute the command:
234
235         tar -cvzf <filename.tgz> -C <submission pkg dir> .
236
237 where `<submission pkg dir>` is the directory containing the files from (1)-(4)
238 from above. A submission package must contain all of the files listed above,
239 and only those files.
240
241 As an example submission package could contain:
242
243         STATEMENT-Khronos
244         git-log.txt
245         git-status.txt
246         0001-Remove-Waived-Filtering-Tests.patch
247         0002-Fix-Pipeline-Parameters.patch
248         TestResults-armeabi-v7a.qpa
249         TestResults-arm64-v8a.qpa
250
251
252 Waivers
253 -------
254
255 The process for requesting a waiver is to report the issue by filing a bug
256 report in the Gitlab VulkanCTS project (TODO Github?). When creating the
257 submission package, include references to the waiver in the commit message of
258 the relevant change. Including as much information as possible in your bug
259 report (including a unified diff or a merge request of suggested file changes)
260 will ensure the issue can be progressed as rapidly as possible. Issues must
261 be labeled "Waiver" (TODO!) and identify the version of the CTS and affected
262 tests.
263
264 Conformance Criteria
265 --------------------
266
267 Conformance run is considered passing if all tests finish with allowed result
268 codes. Test results are contained in the TestResults.qpa log. Each
269 test case section contains XML tag Result, for example:
270
271         <Result StatusCode="Pass">Not validated</Result>
272
273 The result code is the value of the StatusCode attribute. Following status
274 codes are allowed:
275
276         Pass
277         NotSupported
278         QualityWarning
279         CompatibilityWarning
280
281 Submission package can be verified using `external/vulkancts/verify_submission.py`
282 script. The script takes two arguments: path to extracted submission package
283 and path to current mustpass list. For example:
284
285         python external/vulkancts/verify_submission.py VK_10_Khronos_1/ external/vulkancts/mustpass/1.0.1/vk-default.txt
286
287
288 Vulkan platform port
289 --------------------
290
291 Vulkan support from Platform implementation requires providing
292 `getVulkanPlatform()` method in `tcu::Platform` class implementation.
293
294 See `framework/common/tcuPlatform.hpp` and examples in
295 `framework/platform/win32/tcuWin32Platform.cpp` and
296 `framework/platform/android/tcuAndroidPlatform.cpp`.
297
298 If any WSI extensions are supported, platform port must also implement
299 methods for creating native display (`vk::Platform::createWsiDisplay`)
300 and window handles (`vk::wsi::Display::createWindow`). Otherwise tests
301 under `dEQP-VK.wsi` will fail.
302
303
304 Null (dummy) driver
305 -------------------
306
307 For testing and development purposes it might be useful to be able to run
308 tests on dummy Vulkan implementation. One such implementation is provided in
309 vkNullDriver.cpp. To use that, implement `vk::Platform::createLibrary()` with
310 `vk::createNullDriver()`.
311
312
313 Validation Layers
314 -----------------
315
316 Vulkan CTS framework includes first-party support for validation layers, that
317 can be turned on with `--deqp-validation=enable` command line option.
318
319 When validation is turned on, default instance and device will be created with
320 validation layers enabled and debug callback is registered to record any
321 messages. Debug messages collected during test execution will be included at
322 the end of the test case log.
323
324 If any validation errors are found, test result will be set to `InternalError`.
325
326 By default `VK_DEBUG_REPORT_INFORMATION_BIT_EXT` and `_DEBUG_BIT_EXT` messages
327 are excluded from the log, but that can be customized by modifying
328 `vkt::TestCaseExecutor::deinit()` in `vktTestPackage.cpp`.
329
330
331 Cherry GUI
332 ----------
333
334 Vulkan test module can be used with Cherry (GUI for test execution and
335 analysis). Cherry is available at
336 https://android.googlesource.com/platform/external/cherry. Please follow
337 instructions in README to get started.
338
339 Before first launch, and every time test hierarchy has been modified, test
340 case list must be refreshed by running:
341
342         python scripts/build_caselists.py path/to/cherry/data
343
344 Cherry must be restarted for the case list update to take effect.