| 1 |
# SPIR-V Tools |
| 2 |
|
| 3 |
## Overview |
| 4 |
|
| 5 |
The SPIR-V Tools project provides an API and commands for processing SPIR-V |
| 6 |
modules. |
| 7 |
|
| 8 |
The project includes an assembler, binary module parser, disassembler, |
| 9 |
validator, and optimizer for SPIR-V. Except for the optimizer, all are based |
| 10 |
on a common static library. The library contains all of the implementation |
| 11 |
details, and is used in the standalone tools whilst also enabling integration |
| 12 |
into other code bases directly. The optimizer implementation resides in its |
| 13 |
own library, which depends on the core library. |
| 14 |
|
| 15 |
The interfaces have stabilized: |
| 16 |
We don't anticipate making a breaking change for existing features. |
| 17 |
|
| 18 |
SPIR-V is defined by the Khronos Group Inc. |
| 19 |
See the [SPIR-V Registry][spirv-registry] for the SPIR-V specification, |
| 20 |
headers, and XML registry. |
| 21 |
|
| 22 |
## Downloads |
| 23 |
|
| 24 |
[](https://ci.appveyor.com/project/Khronoswebmaster/spirv-tools/branch/master) |
| 25 |
<img alt="Linux" src="kokoro/img/linux.png" width="20px" height="20px" hspace="2px"/>[](https://storage.googleapis.com/spirv-tools/badges/build_link_linux_clang_release.html) |
| 26 |
<img alt="MacOS" src="kokoro/img/macos.png" width="20px" height="20px" hspace="2px"/>[](https://storage.googleapis.com/spirv-tools/badges/build_link_macos_clang_release.html) |
| 27 |
<img alt="Windows" src="kokoro/img/windows.png" width="20px" height="20px" hspace="2px"/>[](https://storage.googleapis.com/spirv-tools/badges/build_link_windows_vs2017_release.html) |
| 28 |
|
| 29 |
[More downloads](docs/downloads.md) |
| 30 |
|
| 31 |
## Versioning SPIRV-Tools |
| 32 |
|
| 33 |
See [`CHANGES`](CHANGES) for a high level summary of recent changes, by version. |
| 34 |
|
| 35 |
SPIRV-Tools project version numbers are of the form `v`*year*`.`*index* and with |
| 36 |
an optional `-dev` suffix to indicate work in progress. For example, the |
| 37 |
following versions are ordered from oldest to newest: |
| 38 |
|
| 39 |
* `v2016.0` |
| 40 |
* `v2016.1-dev` |
| 41 |
* `v2016.1` |
| 42 |
* `v2016.2-dev` |
| 43 |
* `v2016.2` |
| 44 |
|
| 45 |
Use the `--version` option on each command line tool to see the software |
| 46 |
version. An API call reports the software version as a C-style string. |
| 47 |
|
| 48 |
## Supported features |
| 49 |
|
| 50 |
### Assembler, binary parser, and disassembler |
| 51 |
|
| 52 |
* Support for SPIR-V 1.0, through 1.5 |
| 53 |
* Based on SPIR-V syntax described by JSON grammar files in the |
| 54 |
[SPIRV-Headers](https://github.com/KhronosGroup/SPIRV-Headers) repository. |
| 55 |
* Usually, support for a new version of SPIR-V is ready within days after |
| 56 |
publication. |
| 57 |
* Support for extended instruction sets: |
| 58 |
* GLSL std450 version 1.0 Rev 3 |
| 59 |
* OpenCL version 1.0 Rev 2 |
| 60 |
* Assembler only does basic syntax checking. No cross validation of |
| 61 |
IDs or types is performed, except to check literal arguments to |
| 62 |
`OpConstant`, `OpSpecConstant`, and `OpSwitch`. |
| 63 |
|
| 64 |
See [`docs/syntax.md`](docs/syntax.md) for the assembly language syntax. |
| 65 |
|
| 66 |
### Validator |
| 67 |
|
| 68 |
The validator checks validation rules described by the SPIR-V specification. |
| 69 |
|
| 70 |
Khronos recommends that tools that create or transform SPIR-V modules use the |
| 71 |
validator to ensure their outputs are valid, and that tools that consume SPIR-V |
| 72 |
modules optionally use the validator to protect themselves from bad inputs. |
| 73 |
This is especially encouraged for debug and development scenarios. |
| 74 |
|
| 75 |
The validator has one-sided error: it will only return an error when it has |
| 76 |
implemented a rule check and the module violates that rule. |
| 77 |
|
| 78 |
The validator is incomplete. |
| 79 |
See the [CHANGES](CHANGES) file for reports on completed work, and |
| 80 |
the [Validator |
| 81 |
sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/1) for planned |
| 82 |
and in-progress work. |
| 83 |
|
| 84 |
*Note*: The validator checks some Universal Limits, from section 2.17 of the SPIR-V spec. |
| 85 |
The validator will fail on a module that exceeds those minimum upper bound limits. |
| 86 |
It is [future work](https://github.com/KhronosGroup/SPIRV-Tools/projects/1#card-1052403) |
| 87 |
to parameterize the validator to allow larger |
| 88 |
limits accepted by a more than minimally capable SPIR-V consumer. |
| 89 |
|
| 90 |
|
| 91 |
### Optimizer |
| 92 |
|
| 93 |
The optimizer is a collection of code transforms, or "passes". |
| 94 |
Transforms are written for a diverse set of reasons: |
| 95 |
|
| 96 |
* To restructure, simplify, or normalize the code for further processing. |
| 97 |
* To eliminate undesirable code. |
| 98 |
* To improve code quality in some metric such as size or performance. |
| 99 |
**Note**: These transforms are not guaranteed to actually improve any |
| 100 |
given metric. Users should always measure results for their own situation. |
| 101 |
|
| 102 |
As of this writing, there are 67 transforms including examples such as: |
| 103 |
* Simplification |
| 104 |
* Strip debug info |
| 105 |
* Strip reflection info |
| 106 |
* Specialization Constants |
| 107 |
* Set spec constant default value |
| 108 |
* Freeze spec constant to default value |
| 109 |
* Fold `OpSpecConstantOp` and `OpSpecConstantComposite` |
| 110 |
* Unify constants |
| 111 |
* Eliminate dead constant |
| 112 |
* Code Reduction |
| 113 |
* Inline all function calls exhaustively |
| 114 |
* Convert local access chains to inserts/extracts |
| 115 |
* Eliminate local load/store in single block |
| 116 |
* Eliminate local load/store with single store |
| 117 |
* Eliminate local load/store with multiple stores |
| 118 |
* Eliminate local extract from insert |
| 119 |
* Eliminate dead instructions (aggressive) |
| 120 |
* Eliminate dead branches |
| 121 |
* Merge single successor / single predecessor block pairs |
| 122 |
* Eliminate common uniform loads |
| 123 |
* Remove duplicates: Capabilities, extended instruction imports, types, and |
| 124 |
decorations. |
| 125 |
* Normalization |
| 126 |
* Compact IDs |
| 127 |
* CFG cleanup |
| 128 |
* Flatten decorations |
| 129 |
* Merge returns |
| 130 |
* Convert AMD-specific instructions to KHR instructions |
| 131 |
* Code improvement |
| 132 |
* Conditional constant propagation |
| 133 |
* If-conversion |
| 134 |
* Loop fission |
| 135 |
* Loop fusion |
| 136 |
* Loop-invariant code motion |
| 137 |
* Loop unroll |
| 138 |
* Other |
| 139 |
* Generate WebGPU initializers |
| 140 |
* Graphics robust access |
| 141 |
* Upgrade memory model to VulkanKHR |
| 142 |
|
| 143 |
Additionally, certain sets of transformations have been packaged into |
| 144 |
higher-level recipes. These include: |
| 145 |
|
| 146 |
* Optimization for size (`spirv-opt -Os`) |
| 147 |
* Optimization for performance (`spirv-opt -O`) |
| 148 |
|
| 149 |
For the latest list with detailed documentation, please refer to |
| 150 |
[`include/spirv-tools/optimizer.hpp`](include/spirv-tools/optimizer.hpp). |
| 151 |
|
| 152 |
For suggestions on using the code reduction options, please refer to this [white paper](https://www.lunarg.com/shader-compiler-technologies/white-paper-spirv-opt/). |
| 153 |
|
| 154 |
|
| 155 |
### Linker |
| 156 |
|
| 157 |
*Note:* The linker is still under development. |
| 158 |
|
| 159 |
Current features: |
| 160 |
* Combine multiple SPIR-V binary modules together. |
| 161 |
* Combine into a library (exports are retained) or an executable (no symbols |
| 162 |
are exported). |
| 163 |
|
| 164 |
See the [CHANGES](CHANGES) file for reports on completed work, and the [General |
| 165 |
sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/2) for |
| 166 |
planned and in-progress work. |
| 167 |
|
| 168 |
|
| 169 |
### Reducer |
| 170 |
|
| 171 |
*Note:* The reducer is still under development. |
| 172 |
|
| 173 |
The reducer simplifies and shrinks a SPIR-V module with respect to a |
| 174 |
user-supplied *interestingness function*. For example, given a large |
| 175 |
SPIR-V module that cause some SPIR-V compiler to fail with a given |
| 176 |
fatal error message, the reducer could be used to look for a smaller |
| 177 |
version of the module that causes the compiler to fail with the same |
| 178 |
fatal error message. |
| 179 |
|
| 180 |
To suggest an additional capability for the reducer, [file an |
| 181 |
issue](https://github.com/KhronosGroup/SPIRV-Tools/issues]) with |
| 182 |
"Reducer:" as the start of its title. |
| 183 |
|
| 184 |
|
| 185 |
### Fuzzer |
| 186 |
|
| 187 |
*Note:* The fuzzer is still under development. |
| 188 |
|
| 189 |
The fuzzer applies semantics-preserving transformations to a SPIR-V binary |
| 190 |
module, to produce an equivalent module. The original and transformed modules |
| 191 |
should produce essentially identical results when executed on identical inputs: |
| 192 |
their results should differ only due to floating-point round-off, if at all. |
| 193 |
Significant differences in results can pinpoint bugs in tools that process |
| 194 |
SPIR-V binaries, such as miscompilations. This *metamorphic testing* approach |
| 195 |
is similar to the method used by the [GraphicsFuzz |
| 196 |
project](https://github.com/google/graphicsfuzz) for fuzzing of GLSL shaders. |
| 197 |
|
| 198 |
To suggest an additional capability for the fuzzer, [file an |
| 199 |
issue](https://github.com/KhronosGroup/SPIRV-Tools/issues]) with |
| 200 |
"Fuzzer:" as the start of its title. |
| 201 |
|
| 202 |
|
| 203 |
### Extras |
| 204 |
|
| 205 |
* [Utility filters](#utility-filters) |
| 206 |
* Build target `spirv-tools-vimsyntax` generates file `spvasm.vim`. |
| 207 |
Copy that file into your `$HOME/.vim/syntax` directory to get SPIR-V assembly syntax |
| 208 |
highlighting in Vim. This build target is not built by default. |
| 209 |
|
| 210 |
## Contributing |
| 211 |
|
| 212 |
The SPIR-V Tools project is maintained by members of the The Khronos Group Inc., |
| 213 |
and is hosted at https://github.com/KhronosGroup/SPIRV-Tools. |
| 214 |
|
| 215 |
Consider joining the `[email protected]` mailing list, via |
| 216 |
[https://www.khronos.org/spir/spirv-tools-mailing-list/](https://www.khronos.org/spir/spirv-tools-mailing-list/). |
| 217 |
The mailing list is used to discuss development plans for the SPIRV-Tools as an open source project. |
| 218 |
Once discussion is resolved, |
| 219 |
specific work is tracked via issues and sometimes in one of the |
| 220 |
[projects][spirv-tools-projects]. |
| 221 |
|
| 222 |
(To provide feedback on the SPIR-V _specification_, file an issue on the |
| 223 |
[SPIRV-Headers][spirv-headers] GitHub repository.) |
| 224 |
|
| 225 |
See [`docs/projects.md`](docs/projects.md) to see how we use the |
| 226 |
[GitHub Project |
| 227 |
feature](https://help.github.com/articles/tracking-the-progress-of-your-work-with-projects/) |
| 228 |
to organize planned and in-progress work. |
| 229 |
|
| 230 |
Contributions via merge request are welcome. Changes should: |
| 231 |
* Be provided under the [Apache 2.0](#license). |
| 232 |
* You'll be prompted with a one-time "click-through" |
| 233 |
[Khronos Open Source Contributor License Agreement][spirv-tools-cla] |
| 234 |
(CLA) dialog as part of submitting your pull request or |
| 235 |
other contribution to GitHub. |
| 236 |
* Include tests to cover updated functionality. |
| 237 |
* C++ code should follow the [Google C++ Style Guide][cpp-style-guide]. |
| 238 |
* Code should be formatted with `clang-format`. |
| 239 |
[kokoro/check-format/build.sh](kokoro/check-format/build.sh) |
| 240 |
shows how to download it. Note that we currently use |
| 241 |
`clang-format version 5.0.0` for SPIRV-Tools. Settings are defined by |
| 242 |
the included [.clang-format](.clang-format) file. |
| 243 |
|
| 244 |
We intend to maintain a linear history on the GitHub `master` branch. |
| 245 |
|
| 246 |
### Source code organization |
| 247 |
|
| 248 |
* `example`: demo code of using SPIRV-Tools APIs |
| 249 |
* `external/googletest`: Intended location for the |
| 250 |
[googletest][googletest] sources, not provided |
| 251 |
* `external/effcee`: Location of [Effcee][effcee] sources, if the `effcee` library |
| 252 |
is not already configured by an enclosing project. |
| 253 |
* `external/re2`: Location of [RE2][re2] sources, if the `re2` library is not already |
| 254 |
configured by an enclosing project. |
| 255 |
(The Effcee project already requires RE2.) |
| 256 |
* `include/`: API clients should add this directory to the include search path |
| 257 |
* `external/spirv-headers`: Intended location for |
| 258 |
[SPIR-V headers][spirv-headers], not provided |
| 259 |
* `include/spirv-tools/libspirv.h`: C API public interface |
| 260 |
* `source/`: API implementation |
| 261 |
* `test/`: Tests, using the [googletest][googletest] framework |
| 262 |
* `tools/`: Command line executables |
| 263 |
|
| 264 |
Example of getting sources, assuming SPIRV-Tools is configured as a standalone project: |
| 265 |
|
| 266 |
git clone https://github.com/KhronosGroup/SPIRV-Tools.git spirv-tools |
| 267 |
git clone https://github.com/KhronosGroup/SPIRV-Headers.git spirv-tools/external/spirv-headers |
| 268 |
git clone https://github.com/google/googletest.git spirv-tools/external/googletest |
| 269 |
git clone https://github.com/google/effcee.git spirv-tools/external/effcee |
| 270 |
git clone https://github.com/google/re2.git spirv-tools/external/re2 |
| 271 |
|
| 272 |
### Tests |
| 273 |
|
| 274 |
The project contains a number of tests, used to drive development |
| 275 |
and ensure correctness. The tests are written using the |
| 276 |
[googletest][googletest] framework. The `googletest` |
| 277 |
source is not provided with this project. There are two ways to enable |
| 278 |
tests: |
| 279 |
* If SPIR-V Tools is configured as part of an enclosing project, then the |
| 280 |
enclosing project should configure `googletest` before configuring SPIR-V Tools. |
| 281 |
* If SPIR-V Tools is configured as a standalone project, then download the |
| 282 |
`googletest` source into the `<spirv-dir>/external/googletest` directory before |
| 283 |
configuring and building the project. |
| 284 |
|
| 285 |
*Note*: You must use a version of googletest that includes |
| 286 |
[a fix][googletest-pull-612] for [googletest issue 610][googletest-issue-610]. |
| 287 |
The fix is included on the googletest master branch any time after 2015-11-10. |
| 288 |
In particular, googletest must be newer than version 1.7.0. |
| 289 |
|
| 290 |
### Dependency on Effcee |
| 291 |
|
| 292 |
Some tests depend on the [Effcee][effcee] library for stateful matching. |
| 293 |
Effcee itself depends on [RE2][re2]. |
| 294 |
|
| 295 |
* If SPIRV-Tools is configured as part of a larger project that already uses |
| 296 |
Effcee, then that project should include Effcee before SPIRV-Tools. |
| 297 |
* Otherwise, SPIRV-Tools expects Effcee sources to appear in `external/effcee` |
| 298 |
and RE2 sources to appear in `external/re2`. |
| 299 |
|
| 300 |
|
| 301 |
## Build |
| 302 |
|
| 303 |
Instead of building manually, you can also download the binaries for your |
| 304 |
platform directly from the [master-tot release][master-tot-release] on GitHub. |
| 305 |
Those binaries are automatically uploaded by the buildbots after successful |
| 306 |
testing and they always reflect the current top of the tree of the master |
| 307 |
branch. |
| 308 |
|
| 309 |
In order to build the code, you first need to sync the external repositories |
| 310 |
that it depends on. Assume that `<spirv-dir>` is the root directory of the |
| 311 |
checked out code: |
| 312 |
|
| 313 |
```sh |
| 314 |
cd <spirv-dir> |
| 315 |
git clone https://github.com/KhronosGroup/SPIRV-Headers.git external/spirv-headers |
| 316 |
git clone https://github.com/google/effcee.git external/effcee |
| 317 |
git clone https://github.com/google/re2.git external/re2 |
| 318 |
git clone https://github.com/google/googletest.git external/googletest # optional |
| 319 |
|
| 320 |
``` |
| 321 |
|
| 322 |
*Note*: |
| 323 |
The script `utils/git-sync-deps` can be used to checkout and/or update the |
| 324 |
contents of the repos under `external/` instead of manually maintaining them. |
| 325 |
|
| 326 |
### Build using CMake |
| 327 |
You can build the project using [CMake][cmake]: |
| 328 |
|
| 329 |
```sh |
| 330 |
cd <spirv-dir> |
| 331 |
mkdir build && cd build |
| 332 |
cmake [-G <platform-generator>] <spirv-dir> |
| 333 |
``` |
| 334 |
|
| 335 |
Once the build files have been generated, build using the appropriate build |
| 336 |
command (e.g. `ninja`, `make`, `msbuild`, etc.; this depends on the platform |
| 337 |
generator used above), or use your IDE, or use CMake to run the appropriate build |
| 338 |
command for you: |
| 339 |
|
| 340 |
```sh |
| 341 |
cmake --build . [--config Debug] # runs `make` or `ninja` or `msbuild` etc. |
| 342 |
``` |
| 343 |
|
| 344 |
#### Note about the fuzzer |
| 345 |
|
| 346 |
The SPIR-V fuzzer, `spirv-fuzz`, can only be built via CMake, and is disabled by |
| 347 |
default. To build it, clone protobuf and use the `SPIRV_BUILD_FUZZER` CMake |
| 348 |
option, like so: |
| 349 |
|
| 350 |
```sh |
| 351 |
# In <spirv-dir> (the SPIRV-Tools repo root): |
| 352 |
git clone --depth=1 --branch v3.13.0 https://github.com/protocolbuffers/protobuf external/protobuf |
| 353 |
|
| 354 |
# In your build directory: |
| 355 |
cmake [-G <platform-generator>] <spirv-dir> -DSPIRV_BUILD_FUZZER=ON |
| 356 |
cmake --build . --config Debug |
| 357 |
``` |
| 358 |
|
| 359 |
You can also add `-DSPIRV_ENABLE_LONG_FUZZER_TESTS=ON` to build additional |
| 360 |
fuzzer tests. |
| 361 |
|
| 362 |
|
| 363 |
### Build using Bazel |
| 364 |
You can also use [Bazel](https://bazel.build/) to build the project. |
| 365 |
```sh |
| 366 |
cd <spirv-dir> |
| 367 |
bazel build :all |
| 368 |
``` |
| 369 |
|
| 370 |
### Tools you'll need |
| 371 |
|
| 372 |
For building and testing SPIRV-Tools, the following tools should be |
| 373 |
installed regardless of your OS: |
| 374 |
|
| 375 |
- [CMake](http://www.cmake.org/): if using CMake for generating compilation |
| 376 |
targets, you need to install CMake Version 2.8.12 or later. |
| 377 |
- [Python 3](http://www.python.org/): for utility scripts and running the test |
| 378 |
suite. |
| 379 |
- [Bazel](https://bazel.build/) (optional): if building the source with Bazel, |
| 380 |
you need to install Bazel Version 0.29.1 on your machine. Other versions may |
| 381 |
also work, but are not verified. |
| 382 |
|
| 383 |
SPIRV-Tools is regularly tested with the following compilers: |
| 384 |
|
| 385 |
On Linux |
| 386 |
- GCC version 4.8.5 |
| 387 |
- Clang version 3.8 |
| 388 |
|
| 389 |
On MacOS |
| 390 |
- AppleClang 10.0 |
| 391 |
|
| 392 |
On Windows |
| 393 |
- Visual Studio 2015 |
| 394 |
- Visual Studio 2017 |
| 395 |
|
| 396 |
Other compilers or later versions may work, but they are not tested. |
| 397 |
|
| 398 |
### CMake options |
| 399 |
|
| 400 |
The following CMake options are supported: |
| 401 |
|
| 402 |
* `SPIRV_BUILD_FUZZER={ON|OFF}`, default `OFF` - Build the spirv-fuzz tool. |
| 403 |
* `SPIRV_COLOR_TERMINAL={ON|OFF}`, default `ON` - Enables color console output. |
| 404 |
* `SPIRV_SKIP_TESTS={ON|OFF}`, default `OFF`- Build only the library and |
| 405 |
the command line tools. This will prevent the tests from being built. |
| 406 |
* `SPIRV_SKIP_EXECUTABLES={ON|OFF}`, default `OFF`- Build only the library, not |
| 407 |
the command line tools and tests. |
| 408 |
* `SPIRV_USE_SANITIZER=<sanitizer>`, default is no sanitizing - On UNIX |
| 409 |
platforms with an appropriate version of `clang` this option enables the use |
| 410 |
of the sanitizers documented [here][clang-sanitizers]. |
| 411 |
This should only be used with a debug build. |
| 412 |
* `SPIRV_WARN_EVERYTHING={ON|OFF}`, default `OFF` - On UNIX platforms enable |
| 413 |
more strict warnings. The code might not compile with this option enabled. |
| 414 |
For Clang, enables `-Weverything`. For GCC, enables `-Wpedantic`. |
| 415 |
See [`CMakeLists.txt`](CMakeLists.txt) for details. |
| 416 |
* `SPIRV_WERROR={ON|OFF}`, default `ON` - Forces a compilation error on any |
| 417 |
warnings encountered by enabling the compiler-specific compiler front-end |
| 418 |
option. No compiler front-end options are enabled when this option is OFF. |
| 419 |
|
| 420 |
Additionally, you can pass additional C preprocessor definitions to SPIRV-Tools |
| 421 |
via setting `SPIRV_TOOLS_EXTRA_DEFINITIONS`. For example, by setting it to |
| 422 |
`/D_ITERATOR_DEBUG_LEVEL=0` on Windows, you can disable checked iterators and |
| 423 |
iterator debugging. |
| 424 |
|
| 425 |
### Android |
| 426 |
|
| 427 |
SPIR-V Tools supports building static libraries `libSPIRV-Tools.a` and |
| 428 |
`libSPIRV-Tools-opt.a` for Android: |
| 429 |
|
| 430 |
``` |
| 431 |
cd <spirv-dir> |
| 432 |
|
| 433 |
export ANDROID_NDK=/path/to/your/ndk |
| 434 |
|
| 435 |
mkdir build && cd build |
| 436 |
mkdir libs |
| 437 |
mkdir app |
| 438 |
|
| 439 |
$ANDROID_NDK/ndk-build -C ../android_test \ |
| 440 |
NDK_PROJECT_PATH=. \ |
| 441 |
NDK_LIBS_OUT=`pwd`/libs \ |
| 442 |
NDK_APP_OUT=`pwd`/app |
| 443 |
``` |
| 444 |
|
| 445 |
### Updating DEPS |
| 446 |
Occasionally the entries in DEPS will need to be updated. This is done on demand |
| 447 |
when there is a request to do this, often due to downstream breakages. There is |
| 448 |
a script `utils/roll_deps.sh` provided, which will generate a patch with the |
| 449 |
updated DEPS values. This will still need to be tested in your checkout to |
| 450 |
confirm that there are no integration issues that need to be resolved. |
| 451 |
|
| 452 |
## Library |
| 453 |
|
| 454 |
### Usage |
| 455 |
|
| 456 |
The internals of the library use C++11 features, and are exposed via both a C |
| 457 |
and C++ API. |
| 458 |
|
| 459 |
In order to use the library from an application, the include path should point |
| 460 |
to `<spirv-dir>/include`, which will enable the application to include the |
| 461 |
header `<spirv-dir>/include/spirv-tools/libspirv.h{|pp}` then linking against |
| 462 |
the static library in `<spirv-build-dir>/source/libSPIRV-Tools.a` or |
| 463 |
`<spirv-build-dir>/source/SPIRV-Tools.lib`. |
| 464 |
For optimization, the header file is |
| 465 |
`<spirv-dir>/include/spirv-tools/optimizer.hpp`, and the static library is |
| 466 |
`<spirv-build-dir>/source/libSPIRV-Tools-opt.a` or |
| 467 |
`<spirv-build-dir>/source/SPIRV-Tools-opt.lib`. |
| 468 |
|
| 469 |
* `SPIRV-Tools` CMake target: Creates the static library: |
| 470 |
* `<spirv-build-dir>/source/libSPIRV-Tools.a` on Linux and OS X. |
| 471 |
* `<spirv-build-dir>/source/libSPIRV-Tools.lib` on Windows. |
| 472 |
* `SPIRV-Tools-opt` CMake target: Creates the static library: |
| 473 |
* `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` on Linux and OS X. |
| 474 |
* `<spirv-build-dir>/source/libSPIRV-Tools-opt.lib` on Windows. |
| 475 |
|
| 476 |
#### Entry points |
| 477 |
|
| 478 |
The interfaces are still under development, and are expected to change. |
| 479 |
|
| 480 |
There are five main entry points into the library in the C interface: |
| 481 |
|
| 482 |
* `spvTextToBinary`: An assembler, translating text to a binary SPIR-V module. |
| 483 |
* `spvBinaryToText`: A disassembler, translating a binary SPIR-V module to |
| 484 |
text. |
| 485 |
* `spvBinaryParse`: The entry point to a binary parser API. It issues callbacks |
| 486 |
for the header and each parsed instruction. The disassembler is implemented |
| 487 |
as a client of `spvBinaryParse`. |
| 488 |
* `spvValidate` implements the validator functionality. *Incomplete* |
| 489 |
* `spvValidateBinary` implements the validator functionality. *Incomplete* |
| 490 |
|
| 491 |
The C++ interface is comprised of three classes, `SpirvTools`, `Optimizer` and |
| 492 |
`Linker`, all in the `spvtools` namespace. |
| 493 |
* `SpirvTools` provides `Assemble`, `Disassemble`, and `Validate` methods. |
| 494 |
* `Optimizer` provides methods for registering and running optimization passes. |
| 495 |
* `Linker` provides methods for combining together multiple binaries. |
| 496 |
|
| 497 |
## Command line tools |
| 498 |
|
| 499 |
Command line tools, which wrap the above library functions, are provided to |
| 500 |
assemble or disassemble shader files. It's a convention to name SPIR-V |
| 501 |
assembly and binary files with suffix `.spvasm` and `.spv`, respectively. |
| 502 |
|
| 503 |
### Assembler tool |
| 504 |
|
| 505 |
The assembler reads the assembly language text, and emits the binary form. |
| 506 |
|
| 507 |
The standalone assembler is the executable called `spirv-as`, and is located in |
| 508 |
`<spirv-build-dir>/tools/spirv-as`. The functionality of the assembler is implemented |
| 509 |
by the `spvTextToBinary` library function. |
| 510 |
|
| 511 |
* `spirv-as` - the standalone assembler |
| 512 |
* `<spirv-dir>/tools/as` |
| 513 |
|
| 514 |
Use option `-h` to print help. |
| 515 |
|
| 516 |
### Disassembler tool |
| 517 |
|
| 518 |
The disassembler reads the binary form, and emits assembly language text. |
| 519 |
|
| 520 |
The standalone disassembler is the executable called `spirv-dis`, and is located in |
| 521 |
`<spirv-build-dir>/tools/spirv-dis`. The functionality of the disassembler is implemented |
| 522 |
by the `spvBinaryToText` library function. |
| 523 |
|
| 524 |
* `spirv-dis` - the standalone disassembler |
| 525 |
* `<spirv-dir>/tools/dis` |
| 526 |
|
| 527 |
Use option `-h` to print help. |
| 528 |
|
| 529 |
The output includes syntax colouring when printing to the standard output stream, |
| 530 |
on Linux, Windows, and OS X. |
| 531 |
|
| 532 |
### Linker tool |
| 533 |
|
| 534 |
The linker combines multiple SPIR-V binary modules together, resulting in a single |
| 535 |
binary module as output. |
| 536 |
|
| 537 |
This is a work in progress. |
| 538 |
The linker does not support OpenCL program linking options related to math |
| 539 |
flags. (See section 5.6.5.2 in OpenCL 1.2) |
| 540 |
|
| 541 |
* `spirv-link` - the standalone linker |
| 542 |
* `<spirv-dir>/tools/link` |
| 543 |
|
| 544 |
### Optimizer tool |
| 545 |
|
| 546 |
The optimizer processes a SPIR-V binary module, applying transformations |
| 547 |
in the specified order. |
| 548 |
|
| 549 |
This is a work in progress, with initially only few available transformations. |
| 550 |
|
| 551 |
* `spirv-opt` - the standalone optimizer |
| 552 |
* `<spirv-dir>/tools/opt` |
| 553 |
|
| 554 |
### Validator tool |
| 555 |
|
| 556 |
*Warning:* This functionality is under development, and is incomplete. |
| 557 |
|
| 558 |
The standalone validator is the executable called `spirv-val`, and is located in |
| 559 |
`<spirv-build-dir>/tools/spirv-val`. The functionality of the validator is implemented |
| 560 |
by the `spvValidate` library function. |
| 561 |
|
| 562 |
The validator operates on the binary form. |
| 563 |
|
| 564 |
* `spirv-val` - the standalone validator |
| 565 |
* `<spirv-dir>/tools/val` |
| 566 |
|
| 567 |
### Reducer tool |
| 568 |
|
| 569 |
The reducer shrinks a SPIR-V binary module, guided by a user-supplied |
| 570 |
*interestingness test*. |
| 571 |
|
| 572 |
This is a work in progress, with initially only shrinks a module in a few ways. |
| 573 |
|
| 574 |
* `spirv-reduce` - the standalone reducer |
| 575 |
* `<spirv-dir>/tools/reduce` |
| 576 |
|
| 577 |
Run `spirv-reduce --help` to see how to specify interestingness. |
| 578 |
|
| 579 |
### Fuzzer tool |
| 580 |
|
| 581 |
The fuzzer transforms a SPIR-V binary module into a semantically-equivalent |
| 582 |
SPIR-V binary module by applying transformations in a randomized fashion. |
| 583 |
|
| 584 |
This is a work in progress, with initially only a few semantics-preserving |
| 585 |
transformations. |
| 586 |
|
| 587 |
* `spirv-fuzz` - the standalone fuzzer |
| 588 |
* `<spirv-dir>/tools/fuzz` |
| 589 |
|
| 590 |
Run `spirv-fuzz --help` for a detailed list of options. |
| 591 |
|
| 592 |
### Control flow dumper tool |
| 593 |
|
| 594 |
The control flow dumper prints the control flow graph for a SPIR-V module as a |
| 595 |
[GraphViz](http://www.graphviz.org/) graph. |
| 596 |
|
| 597 |
This is experimental. |
| 598 |
|
| 599 |
* `spirv-cfg` - the control flow graph dumper |
| 600 |
* `<spirv-dir>/tools/cfg` |
| 601 |
|
| 602 |
### Utility filters |
| 603 |
|
| 604 |
* `spirv-lesspipe.sh` - Automatically disassembles `.spv` binary files for the |
| 605 |
`less` program, on compatible systems. For example, set the `LESSOPEN` |
| 606 |
environment variable as follows, assuming both `spirv-lesspipe.sh` and |
| 607 |
`spirv-dis` are on your executable search path: |
| 608 |
``` |
| 609 |
export LESSOPEN='| spirv-lesspipe.sh "%s"' |
| 610 |
``` |
| 611 |
Then you page through a disassembled module as follows: |
| 612 |
``` |
| 613 |
less foo.spv |
| 614 |
``` |
| 615 |
* The `spirv-lesspipe.sh` script will pass through any extra arguments to |
| 616 |
`spirv-dis`. So, for example, you can turn off colours and friendly ID |
| 617 |
naming as follows: |
| 618 |
``` |
| 619 |
export LESSOPEN='| spirv-lesspipe.sh "%s" --no-color --raw-id' |
| 620 |
``` |
| 621 |
|
| 622 |
* [vim-spirv](https://github.com/kbenzie/vim-spirv) - A vim plugin which |
| 623 |
supports automatic disassembly of `.spv` files using the `:edit` command and |
| 624 |
assembly using the `:write` command. The plugin also provides additional |
| 625 |
features which include; syntax highlighting; highlighting of all ID's matching |
| 626 |
the ID under the cursor; and highlighting errors where the `Instruction` |
| 627 |
operand of `OpExtInst` is used without an appropriate `OpExtInstImport`. |
| 628 |
|
| 629 |
* `50spirv-tools.el` - Automatically disassembles '.spv' binary files when |
| 630 |
loaded into the emacs text editor, and re-assembles them when saved, |
| 631 |
provided any modifications to the file are valid. This functionality |
| 632 |
must be explicitly requested by defining the symbol |
| 633 |
SPIRV_TOOLS_INSTALL_EMACS_HELPERS as follows: |
| 634 |
``` |
| 635 |
cmake -DSPIRV_TOOLS_INSTALL_EMACS_HELPERS=true ... |
| 636 |
``` |
| 637 |
|
| 638 |
In addition, this helper is only installed if the directory /etc/emacs/site-start.d |
| 639 |
exists, which is typically true if emacs is installed on the system. |
| 640 |
|
| 641 |
Note that symbol IDs are not currently preserved through a load/edit/save operation. |
| 642 |
This may change if the ability is added to spirv-as. |
| 643 |
|
| 644 |
|
| 645 |
### Tests |
| 646 |
|
| 647 |
Tests are only built when googletest is found. Use `ctest` to run all the |
| 648 |
tests. |
| 649 |
|
| 650 |
## Future Work |
| 651 |
<a name="future"></a> |
| 652 |
|
| 653 |
_See the [projects pages](https://github.com/KhronosGroup/SPIRV-Tools/projects) |
| 654 |
for more information._ |
| 655 |
|
| 656 |
### Assembler and disassembler |
| 657 |
|
| 658 |
* The disassembler could emit helpful annotations in comments. For example: |
| 659 |
* Use variable name information from debug instructions to annotate |
| 660 |
key operations on variables. |
| 661 |
* Show control flow information by annotating `OpLabel` instructions with |
| 662 |
that basic block's predecessors. |
| 663 |
* Error messages could be improved. |
| 664 |
|
| 665 |
### Validator |
| 666 |
|
| 667 |
This is a work in progress. |
| 668 |
|
| 669 |
### Linker |
| 670 |
|
| 671 |
* The linker could accept math transformations such as allowing MADs, or other |
| 672 |
math flags passed at linking-time in OpenCL. |
| 673 |
* Linkage attributes can not be applied through a group. |
| 674 |
* Check decorations of linked functions attributes. |
| 675 |
* Remove dead instructions, such as OpName targeting imported symbols. |
| 676 |
|
| 677 |
## Licence |
| 678 |
<a name="license"></a> |
| 679 |
Full license terms are in [LICENSE](LICENSE) |
| 680 |
``` |
| 681 |
Copyright (c) 2015-2016 The Khronos Group Inc. |
| 682 |
|
| 683 |
Licensed under the Apache License, Version 2.0 (the "License"); |
| 684 |
you may not use this file except in compliance with the License. |
| 685 |
You may obtain a copy of the License at |
| 686 |
|
| 687 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 688 |
|
| 689 |
Unless required by applicable law or agreed to in writing, software |
| 690 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 691 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 692 |
See the License for the specific language governing permissions and |
| 693 |
limitations under the License. |
| 694 |
``` |
| 695 |
|
| 696 |
[spirv-tools-cla]: https://cla-assistant.io/KhronosGroup/SPIRV-Tools |
| 697 |
[spirv-tools-projects]: https://github.com/KhronosGroup/SPIRV-Tools/projects |
| 698 |
[spirv-tools-mailing-list]: https://www.khronos.org/spir/spirv-tools-mailing-list |
| 699 |
[spirv-registry]: https://www.khronos.org/registry/spir-v/ |
| 700 |
[spirv-headers]: https://github.com/KhronosGroup/SPIRV-Headers |
| 701 |
[googletest]: https://github.com/google/googletest |
| 702 |
[googletest-pull-612]: https://github.com/google/googletest/pull/612 |
| 703 |
[googletest-issue-610]: https://github.com/google/googletest/issues/610 |
| 704 |
[effcee]: https://github.com/google/effcee |
| 705 |
[re2]: https://github.com/google/re2 |
| 706 |
[CMake]: https://cmake.org/ |
| 707 |
[cpp-style-guide]: https://google.github.io/styleguide/cppguide.html |
| 708 |
[clang-sanitizers]: http://clang.llvm.org/docs/UsersManual.html#controlling-code-generation |
| 709 |
[master-tot-release]: https://github.com/KhronosGroup/SPIRV-Tools/releases/tag/master-tot |