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