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 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.1/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.1.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/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/verify_submission.py VK_10_Khronos_1/ external/vulkancts/mustpass/1.0.1/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.