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         $ python android/scripts/build.py
  85         $ python android/scripts/install.py
  86
  87
  88 Building Mustpass
  89 -----------------
  90
  91 Current mustpass is checked into repository and can be found at:
  92
  93         external/vulkancts/mustpass/1.0.0/vk-default.txt
  94
  95 Vulkan CTS mustpass can be re-generated by running:
  96
  97         $ python <vulkancts>/external/vulkancts/build_mustpass.py
  98
  99
 100 Pre-compiling SPIR-V binaries
 101 -----------------------------
 102
 103 For distribution, and platforms that don't support GLSL to SPIR-V compilation,
 104 SPIR-V binaries must be pre-built with following command:
 105
 106         $ python external/vulkancts/build_spirv_binaries.py
 107
 108 Binaries will be written to external/vulkancts/data/vulkan/prebuilt/.
 109
 110 Test modules (or in case of Android, the APK) must be re-built after building
 111 SPIR-V programs in order for the binaries to be available.
 112
 113
 114 Running CTS
 115 -----------
 116
 117 Following command line options MUST be used when running CTS:
 118
 119         --deqp-caselist-file=<vulkancts>/external/vulkancts/mustpass/1.0.0/vk-default.txt
 120         --deqp-log-images=disable
 121         --deqp-log-shader-sources=disable
 122
 123 In addition on multi-device systems the device for which conformance is claimed
 124 can be selected with:
 125
 126         --deqp-vk-device-id=<value>
 127
 128 No other command line options are allowed.
 129
 130
 131 Win32:
 132
 133         > cd <builddir>/external/vulkancts/modules/vulkan
 134         > Debug/deqp-vk.exe --deqp-caselist-file=...
 135
 136 Test log will be written into TestResults.qpa
 137
 138
 139 Linux:
 140
 141         $ cd <builddir>/external/vulkancts/modules/vulkan
 142         $ ./deqp-vk --deqp-vk-caselist-file=...
 143
 144
 145 Android:
 146
 147         $ adb push <vulkancts>/external/vulkancts/mustpass/1.0.0/vk-default.txt /sdcard/vk-default.txt
 148         $ adb shell
 149
 150 In device shell:
 151
 152         $ 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"
 153
 154 Process can be followed by running:
 155
 156         $ adb logcat -s dEQP
 157
 158 Test log will be written into /sdcard/TestResults.qpa
 159
 160
 161 Conformance Submission Package Requirements
 162 -------------------------------------------
 163
 164 Conformance submission package must contain following:
 165
 166 1) Full test logs (TestResults.qpa) from CTS runs against all driver builds
 167 2) Result of "git status" and "git log" from CTS source directory
 168 3) Any patches used on top of release tag
 169 4) Conformance statement
 170
 171 Test logs (1) should be named TestResults-<driver build type>.qpa, for example
 172 TestResults-armeabi-v7a.qpa. On platforms where multiple different driver
 173 builds (for example 64-bit and 32-bit) are present, CTS must be ran against
 174 all of them.
 175
 176 CTS build must always be done from clean git repository that doesn't have any
 177 uncommitted changes. Thus it is necessary to run and capture output of "git
 178 status" and "git log" (2) in the source directory:
 179
 180         git status > <submission pkg dir>/git-status.txt
 181         git log <release tag>..HEAD > <submission pkg dir>/git-log.txt
 182
 183 Any changes made to CTS must be committed to the repository, and provided
 184 as part of the submission package (3). This can be done by running:
 185
 186         git format-patch -o <submission pkg dir> <release tag>..HEAD
 187
 188 In general bugfixes and changes to platform-specific code (mostly under
 189 framework/platform) are allowed.
 190
 191 Conformance statement (4) must be included in a file called STATEMENT-<adopter>
 192 and must contain following:
 193
 194         CONFORM_VERSION:         <git tag of CTS release>
 195         PRODUCT:                 <string-value>
 196         CPU:                     <string-value>
 197         OS:                      <string-value>
 198
 199 Note that product/cpu/os information is also captured in dEQP-VK.info.* tests
 200 if vk::Platform::describePlatform() is implemented.
 201
 202
 203 Vulkan platform port
 204 --------------------
 205
 206 Vulkan support from Platform implementation requires providing
 207 getVulkanPlatform() method in tcu::Platform class implementation.
 208
 209 See framework/common/tcuPlatform.hpp and examples in
 210 framework/platform/win32/tcuWin32Platform.cpp and
 211 framework/platform/android/tcuAndroidPlatform.cpp.
 212
 213
 214 Null (dummy) driver
 215 -------------------
 216
 217 For testing and development purposes it might be useful to be able to run
 218 tests on dummy Vulkan implementation. One such implementation is provided in
 219 vkNullDriver.cpp. To use that, implement vk::Platform::createLibrary() with
 220 vk::createNullDriver().
 221
 222
 223 Cherry GUI
 224 ----------
 225
 226 Vulkan test module can be used with Cherry (GUI for test execution and
 227 analysis). Cherry is available at
 228 https://android.googlesource.com/platform/external/cherry. Please follow
 229 instructions in README to get started.
 230
 231 To enable support for Vulkan tests, dEQP-VK module must be added to list of
 232 test packages.
 233
 234 In cherry/testrunner.go, add following line to testPackageDescriptors list
 235 (line 608 in NewTestRunner function):
 236
 237         {"dEQP-VK", "deqp-vk", "../external/vulkancts/modules/vulkan", dataDir + "dEQP-VK-cases.xml"},
 238
 239 Before first launch, and every time test hierarchy has been modified, test
 240 case list must be refreshed by running:
 241
 242         $ python scripts/build_caselists.py path/to/cherry/data
 243
 244 Cherry must be restarted for the case list update to take effect.