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