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  * Git (for checking out sources)
  15  * Python 2.7.x (all recent versions in 2.x should work, 3.x is not supported)
  16  * CMake 2.8 or newer
  17
  18 Win32:
  19  * Visual Studio 2013 or newer (glslang uses several C++11 features)
  20
  21 Linux:
  22  * Standard toolchain (make, gcc/clang)
  23
  24 Android:
  25  * Android NDK r10e
  26  * Android SDK with following packages:
  27    + SDK Tools
  28    + SDK Platform-tools
  29    + SDK Build-tools
  30    + 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
  62 Windows x86-64:
  63
  64         > cmake <path to vulkancts> -G"Visual Studio 12 Win64"
  65         > start dEQP-Core-default.sln
  66
  67
  68 Linux 32-bit Debug:
  69
  70         $ cmake <path to vulkancts> -DCMAKE_BUILD_TYPE=Debug -DCMAKE_C_FLAGS=-m32 -DCMAKE_CXX_FLAGS=-m32
  71         $ make -j
  72
  73 Release build can be done by using -DCMAKE_BUILD_TYPE=Release
  74
  75
  76 Linux 64-bit Debug:
  77
  78         $ cmake <path to vulkancts> -DCMAKE_BUILD_TYPE=Debug -DCMAKE_C_FLAGS=-m64 -DCMAKE_CXX_FLAGS=-m64
  79         $ make -j
  80
  81
  82 Android:
  83
  84 Following command will build CTS into android/package/bin/dEQP-debug.apk.
  85
  86         $ python android/scripts/build.py
  87
  88 The package can be installed by either running:
  89
  90         $ python android/scripts/install.py
  91
  92 By default the CTS package will contain libdeqp.so built for armeabi-v7a, arm64-v8a,
  93 and x86 ABIs, but that can be changed in android/scripts/common.py script.
  94
  95 To pick which ABI to use at install time, following commands must be used
  96 instead:
  97
  98         $ adb install --abi <ABI name> android/package/bin/dEQP-debug.apk /data/local/tmp/dEQP-debug.apk
  99
 100
 101 Building Mustpass
 102 -----------------
 103
 104 Current mustpass is checked into repository and can be found at:
 105
 106         external/vulkancts/mustpass/1.0.0/vk-default.txt
 107
 108 Vulkan CTS mustpass can be re-generated by running:
 109
 110         $ python <vulkancts>/external/vulkancts/build_mustpass.py
 111
 112
 113 Pre-compiling SPIR-V binaries
 114 -----------------------------
 115
 116 For distribution, and platforms that don't support GLSL to SPIR-V compilation,
 117 SPIR-V binaries must be pre-built with following command:
 118
 119         $ python external/vulkancts/build_spirv_binaries.py
 120
 121 Binaries will be written to external/vulkancts/data/vulkan/prebuilt/.
 122
 123 Test modules (or in case of Android, the APK) must be re-built after building
 124 SPIR-V programs in order for the binaries to be available.
 125
 126
 127 Running CTS
 128 -----------
 129
 130 Following command line options MUST be used when running CTS:
 131
 132         --deqp-caselist-file=<vulkancts>/external/vulkancts/mustpass/1.0.0/vk-default.txt
 133         --deqp-log-images=disable
 134         --deqp-log-shader-sources=disable
 135
 136 In addition on multi-device systems the device for which conformance is claimed
 137 can be selected with:
 138
 139         --deqp-vk-device-id=<value>
 140
 141 No other command line options are allowed.
 142
 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
 152 Linux:
 153
 154         $ cd <builddir>/external/vulkancts/modules/vulkan
 155         $ ./deqp-vk --deqp-vk-caselist-file=...
 156
 157
 158 Android:
 159
 160         $ adb push <vulkancts>/external/vulkancts/mustpass/1.0.0/vk-default.txt /sdcard/vk-default.txt
 161         $ adb shell
 162
 163 In device shell:
 164
 165         $ 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"
 166
 167 Process can be followed by running:
 168
 169         $ adb logcat -s dEQP
 170
 171 Test log will be written into /sdcard/TestResults.qpa
 172
 173
 174 Conformance Submission Package Requirements
 175 -------------------------------------------
 176
 177 The conformance submission package must contain the following:
 178
 179 1) Full test logs (TestResults.qpa) from CTS runs against all driver builds
 180 2) Result of "git status" and "git log" from CTS source directory
 181 3) Any patches used on top of release tag
 182 4) Conformance statement
 183
 184 Test logs (1) should be named <submission pkg dir>/TestResults-<driver build type>.qpa,
 185 for example TestResults-armeabi-v7a.qpa. On platforms where multiple different driver
 186 builds (for example 64-bit and 32-bit) are present, CTS logs must be provided
 187 for each driver build.
 188
 189 The CTS build must always be done from clean git repository that doesn't have any
 190 uncommitted changes. Thus it is necessary to run and capture output of "git
 191 status" and "git log" (2) in the source directory:
 192
 193         git status > <submission pkg dir>/git-status.txt
 194         git log <release tag>..HEAD > <submission pkg dir>/git-log.txt
 195
 196 Any changes made to CTS must be committed to the local repository, and provided
 197 as part of the submission package (3). This can be done by running:
 198
 199         git format-patch -o <submission pkg dir> <release tag>..HEAD
 200
 201 In general, bugfixes and changes to platform-specific code (mostly under
 202 framework/platform) are allowed. The commit message for each change must
 203 include a clear description of the change and why it is necessary. Non-porting
 204 related changes must be accompanied by a waiver (see below).
 205
 206 Note: When cherry-picking patches on top of release tag, please use "git cherry-pick -x"
 207 to include original commit hash in the commit message.
 208
 209 Conformance statement (4) must be included in a file called STATEMENT-<adopter>
 210 and must contain following:
 211
 212         CONFORM_VERSION:         <git tag of CTS release>
 213         PRODUCT:                 <string-value>
 214         CPU:                     <string-value>
 215         OS:                      <string-value>
 216
 217 Note that product/cpu/os information is also captured in dEQP-VK.info.* tests
 218 if vk::Platform::describePlatform() is implemented.
 219
 220 The actual submission package consists of the above set of files which must
 221 be bundled into a gzipped tar file named VK10_<adopter><_info>.tgz. <adopter>
 222 is the name of the Adopting member company, or some recognizable abbreviation.
 223 The <_info> field is optional. It may be used to uniquely identify a submission
 224 by OS, platform, date, or other criteria when making multiple submissions.
 225
 226 One way to create a suiteable gzipped tar file is to execute the command:
 227
 228 $ tar -cvzf <filename.tgz> -C <submission pkg dir> .
 229
 230 where <submission pkg dir> is the directory containing the files from (1)-(4)
 231 from above. A submission package must contain all of the files listed above,
 232 and only those files.
 233
 234
 235 Waivers
 236 -------
 237
 238 The process for requesting a waiver is to report the issue by filing a bug
 239 report in the Gitlab VulkanCTS project (TODO Github?). When creating the
 240 submission package, include references to the wiaver in the commit message of
 241 the relevant change. Including as much information as possible in your bug
 242 report (including a unified diff or a merge request of suggested file changes)
 243 will ensure the issue can be progressed as rapidly as possible. Issues must
 244 be labeled "Waiver" (TODO!) and identify the version of the CTS and affected
 245 tests.
 246
 247 Conformance Criteria
 248 --------------------
 249
 250 Conformance run is considered passing if all tests finish with allowed result
 251 codes. The test results are contained in the TestResults.qpa log. Each
 252 test case section contains XML tag Result, for example:
 253
 254         <Result StatusCode="Pass">Not validated</Result>
 255
 256 The result code is the value of the StatusCode attribute. Following status
 257 codes are allowed:
 258
 259         Pass, NotSupported, QualityWarning, CompatibilityWarning
 260
 261 TODO: Create script for verifying logs.
 262
 263
 264 Vulkan platform port
 265 --------------------
 266
 267 Vulkan support from Platform implementation requires providing
 268 getVulkanPlatform() method in tcu::Platform class implementation.
 269
 270 See framework/common/tcuPlatform.hpp and examples in
 271 framework/platform/win32/tcuWin32Platform.cpp and
 272 framework/platform/android/tcuAndroidPlatform.cpp.
 273
 274
 275 Null (dummy) driver
 276 -------------------
 277
 278 For testing and development purposes it might be useful to be able to run
 279 tests on dummy Vulkan implementation. One such implementation is provided in
 280 vkNullDriver.cpp. To use that, implement vk::Platform::createLibrary() with
 281 vk::createNullDriver().
 282
 283
 284 Cherry GUI
 285 ----------
 286
 287 Vulkan test module can be used with Cherry (GUI for test execution and
 288 analysis). Cherry is available at
 289 https://android.googlesource.com/platform/external/cherry. Please follow
 290 instructions in README to get started.
 291
 292 To enable support for Vulkan tests, dEQP-VK module must be added to list of
 293 test packages.
 294
 295 In cherry/testrunner.go, add following line to testPackageDescriptors list
 296 (line 608 in NewTestRunner function):
 297
 298         {"dEQP-VK", "deqp-vk", "../external/vulkancts/modules/vulkan", dataDir + "dEQP-VK-cases.xml"},
 299
 300 Before first launch, and every time test hierarchy has been modified, test
 301 case list must be refreshed by running:
 302
 303         $ python scripts/build_caselists.py path/to/cherry/data
 304
 305 Cherry must be restarted for the case list update to take effect.