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 By default, the test log will be written into the path "TestResults.qpa". If the
 143 platform requires a different path, it can be specified with:
 144
 145         --deqp-log-filename=<path>
 146
 147 No other command line options are allowed.
 148
 149 ### Win32
 150
 151         cd <builddir>/external/vulkancts/modules/vulkan
 152         Debug/deqp-vk.exe --deqp-caselist-file=...
 153
 154 Test log will be written into TestResults.qpa
 155
 156 ### Linux
 157
 158         cd <builddir>/external/vulkancts/modules/vulkan
 159         ./deqp-vk --deqp-vk-caselist-file=...
 160
 161 ### Android
 162
 163         adb push <vulkancts>/external/vulkancts/mustpass/1.0.0/vk-default.txt /sdcard/vk-default.txt
 164         adb shell
 165
 166 In device shell:
 167
 168         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"
 169
 170 Test progress will be written to device log and can be displayed with:
 171
 172         adb logcat -s dEQP
 173
 174 Test log will be written into `/sdcard/TestResults.qpa`.
 175
 176
 177 Conformance Submission Package Requirements
 178 -------------------------------------------
 179
 180 The conformance submission package must contain the following:
 181
 182 1. Full test logs (`TestResults.qpa`) from CTS runs against all driver builds
 183 2. Result of `git status` and `git log` from CTS source directory
 184 3. Any patches used on top of release tag
 185 4. Conformance statement
 186
 187 Test logs (1) should be named `<submission pkg dir>/TestResults-<driver build type>.qpa`,
 188 for example `TestResults-armeabi-v7a.qpa`. On platforms where multiple different driver
 189 builds (for example 64-bit and 32-bit) are present, CTS logs must be provided
 190 for each driver build as part of the submission package.
 191
 192 The CTS build must always be done from clean git repository that doesn't have any
 193 uncommitted changes. Thus it is necessary to run and capture output of `git
 194 status` and `git log` (2) in the source directory:
 195
 196         git status > <submission pkg dir>/git-status.txt
 197         git log --first-parent <release tag>^..HEAD > <submission pkg dir>/git-log.txt
 198
 199 Any changes made to CTS must be committed to the local repository, and provided
 200 as part of the submission package (3). This can be done by running:
 201
 202         git format-patch -o <submission pkg dir> <release tag>..HEAD
 203
 204 In general, bugfixes and changes to platform-specific code (mostly under
 205 `framework/platform`) are allowed. The commit message for each change must
 206 include a clear description of the change and why it is necessary. Non-porting
 207 related changes must be accompanied by a waiver (see below).
 208
 209 NOTE: When cherry-picking patches on top of release tag, please use `git cherry-pick -x`
 210 to include original commit hash in the commit message.
 211
 212 Conformance statement (4) must be included in a file called `STATEMENT-<adopter>`
 213 and must contain following:
 214
 215         CONFORM_VERSION:         <git tag of CTS release>
 216         PRODUCT:                 <string-value>
 217         CPU:                     <string-value>
 218         OS:                      <string-value>
 219
 220 Note that product/cpu/os information is also captured in `dEQP-VK.info.*` tests
 221 if `vk::Platform::describePlatform()` is implemented.
 222
 223 If the submission package covers multiple products, you can list them by appending
 224 additional `PRODUCT:` lines to the conformance statement. For example:
 225
 226         CONFORM_VERSION:         vulkan-cts-1.0.0.2
 227         PRODUCT:                 Product A
 228         PRODUCT:                 Product B
 229         ...
 230
 231 The actual submission package consists of the above set of files which must
 232 be bundled into a gzipped tar file named `VK10_<adopter><_info>.tgz`. `<adopter>`
 233 is the name of the Adopting member company, or some recognizable abbreviation.
 234 The `<_info>` field is optional. It may be used to uniquely identify a submission
 235 by OS, platform, date, or other criteria when making multiple submissions.
 236
 237 One way to create a suiteable gzipped tar file is to execute the command:
 238
 239         tar -cvzf <filename.tgz> -C <submission pkg dir> .
 240
 241 where `<submission pkg dir>` is the directory containing the files from (1)-(4)
 242 from above. A submission package must contain all of the files listed above,
 243 and only those files.
 244
 245 As an example submission package could contain:
 246
 247         STATEMENT-Khronos
 248         git-log.txt
 249         git-status.txt
 250         0001-Remove-Waived-Filtering-Tests.patch
 251         0002-Fix-Pipeline-Parameters.patch
 252         TestResults-armeabi-v7a.qpa
 253         TestResults-arm64-v8a.qpa
 254
 255
 256 Waivers
 257 -------
 258
 259 The process for requesting a waiver is to report the issue by filing a bug
 260 report in the Gitlab VulkanCTS project (TODO Github?). When creating the
 261 submission package, include references to the waiver in the commit message of
 262 the relevant change. Including as much information as possible in your bug
 263 report (including a unified diff or a merge request of suggested file changes)
 264 will ensure the issue can be progressed as rapidly as possible. Issues must
 265 be labeled "Waiver" (TODO!) and identify the version of the CTS and affected
 266 tests.
 267
 268 Conformance Criteria
 269 --------------------
 270
 271 Conformance run is considered passing if all tests finish with allowed result
 272 codes. Test results are contained in the TestResults.qpa log. Each
 273 test case section contains XML tag Result, for example:
 274
 275         <Result StatusCode="Pass">Not validated</Result>
 276
 277 The result code is the value of the StatusCode attribute. Following status
 278 codes are allowed:
 279
 280         Pass
 281         NotSupported
 282         QualityWarning
 283         CompatibilityWarning
 284
 285 Submission package can be verified using `external/vulkancts/verify_submission.py`
 286 script. The script takes two arguments: path to extracted submission package
 287 and path to current mustpass list. For example:
 288
 289         python external/vulkancts/verify_submission.py VK_10_Khronos_1/ external/vulkancts/mustpass/1.0.0/vk-default.txt
 290
 291
 292 Vulkan platform port
 293 --------------------
 294
 295 Vulkan support from Platform implementation requires providing
 296 `getVulkanPlatform()` method in `tcu::Platform` class implementation.
 297
 298 See `framework/common/tcuPlatform.hpp` and examples in
 299 `framework/platform/win32/tcuWin32Platform.cpp` and
 300 `framework/platform/android/tcuAndroidPlatform.cpp`.
 301
 302
 303 Null (dummy) driver
 304 -------------------
 305
 306 For testing and development purposes it might be useful to be able to run
 307 tests on dummy Vulkan implementation. One such implementation is provided in
 308 vkNullDriver.cpp. To use that, implement `vk::Platform::createLibrary()` with
 309 `vk::createNullDriver()`.
 310
 311
 312 Cherry GUI
 313 ----------
 314
 315 Vulkan test module can be used with Cherry (GUI for test execution and
 316 analysis). Cherry is available at
 317 https://android.googlesource.com/platform/external/cherry. Please follow
 318 instructions in README to get started.
 319
 320 To enable support for Vulkan tests, dEQP-VK module must be added to list of
 321 test packages.
 322
 323 In `cherry/testrunner.go`, add following line to `testPackageDescriptors` list
 324 (line 645 in `NewTestRunner` function):
 325
 326         {"dEQP-VK", "deqp-vk", "../external/vulkancts/modules/vulkan", dataDir + "dEQP-VK-cases.xml"},
 327
 328 Before first launch, and every time test hierarchy has been modified, test
 329 case list must be refreshed by running:
 330
 331         python scripts/build_caselists.py path/to/cherry/data
 332
 333 Cherry must be restarted for the case list update to take effect.