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 Running CTS
 101 -----------
 102
 103 Following command line options MUST be used when running CTS:
 104
 105         --deqp-caselist-file=<vulkancts>/external/vulkancts/mustpass/1.0.0/vk-default.txt
 106         --deqp-log-images=disable
 107         --deqp-log-shader-sources=disable
 108
 109 In addition on multi-device systems the device for which conformance is claimed
 110 can be selected with:
 111
 112         --deqp-vk-device-id=<value>
 113
 114 No other command line options are allowed.
 115
 116
 117 Win32:
 118
 119         > cd <builddir>/external/vulkancts/modules/vulkan
 120         > Debug/deqp-vk.exe --deqp-caselist-file=...
 121
 122 Test log will be written into TestResults.qpa
 123
 124
 125 Linux:
 126
 127         $ cd <builddir>/external/vulkancts/modules/vulkan
 128         $ ./deqp-vk --deqp-vk-caselist-file=...
 129
 130
 131 Android:
 132
 133         $ adb push <vulkancts>/external/vulkancts/mustpass/1.0.0/vk-default.txt /sdcard/vk-default.txt
 134         $ adb shell
 135
 136 In device shell:
 137
 138         $ 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"
 139
 140 Process can be followed by running:
 141
 142         $ adb logcat -s dEQP
 143
 144 Test log will be written into /sdcard/TestResults.qpa
 145
 146
 147 Pre-compiling SPIR-V binaries
 148 -----------------------------
 149
 150 For distribution, and platforms that don't support GLSL to SPIR-V compilation,
 151 SPIR-V binaries must be pre-built with following command:
 152
 153         $ python external/vulkancts/build_spirv_binaries.py
 154
 155 Binaries will be written to external/vulkancts/data/vulkan/prebuilt/.
 156
 157 Test modules (or in case of Android, the APK) must be re-built after building
 158 SPIR-V programs in order for the binaries to be available.
 159
 160
 161 Vulkan platform port
 162 --------------------
 163
 164 Vulkan support from Platform implementation requires providing
 165 getVulkanPlatform() method in tcu::Platform class implementation.
 166
 167 See framework/common/tcuPlatform.hpp and examples in
 168 framework/platform/win32/tcuWin32Platform.cpp and
 169 framework/platform/android/tcuAndroidPlatform.cpp.
 170
 171
 172 Null (dummy) driver
 173 -------------------
 174
 175 For testing and development purposes it might be useful to be able to run
 176 tests on dummy Vulkan implementation. One such implementation is provided in
 177 vkNullDriver.cpp. To use that, implement vk::Platform::createLibrary() with
 178 vk::createNullDriver().
 179
 180
 181 Cherry GUI
 182 ----------
 183
 184 Vulkan test module can be used with Cherry (GUI for test execution and
 185 analysis). Cherry is available at
 186 https://android.googlesource.com/platform/external/cherry. Please follow
 187 instructions in README to get started.
 188
 189 To enable support for Vulkan tests, dEQP-VK module must be added to list of
 190 test packages.
 191
 192 In cherry/testrunner.go, add following line to testPackageDescriptors list
 193 (line 608 in NewTestRunner function):
 194
 195         {"dEQP-VK", "deqp-vk", "../external/vulkancts/modules/vulkan", dataDir + "dEQP-VK-cases.xml"},
 196
 197 Before first launch, and every time test hierarchy has been modified, test
 198 case list must be refreshed by running:
 199
 200         $ python scripts/build_caselists.py path/to/cherry/data
 201
 202 Cherry must be restarted for the case list update to take effect.