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