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.