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.