README.md

   1 # SPIR-V Tools
   2
   3 [![Build Status](https://travis-ci.org/KhronosGroup/SPIRV-Tools.svg?branch=master)](https://travis-ci.org/KhronosGroup/SPIRV-Tools)
   4 [![Build status](https://ci.appveyor.com/api/projects/status/gpue87cesrx3pi0d/branch/master?svg=true)](https://ci.appveyor.com/project/Khronoswebmaster/spirv-tools/branch/master)
   5
   6 ## Overview
   7
   8 The SPIR-V Tools project provides an API and commands for processing SPIR-V
   9 modules.
  10
  11 The project includes an assembler, binary module parser, disassembler,
  12 validator, and optimizer for SPIR-V. Except for the optimizer, all are based
  13 on a common static library.  The library contains all of the implementation
  14 details, and is used in the standalone tools whilst also enabling integration
  15 into other code bases directly. The optimizer implementation resides in its
  16 own library, which depends on the core library.
  17
  18 The interfaces have stabilized:
  19 We don't anticipate making a breaking change for existing features.
  20
  21 SPIR-V is defined by the Khronos Group Inc.
  22 See the [SPIR-V Registry][spirv-registry] for the SPIR-V specification,
  23 headers, and XML registry.
  24
  25 ## Verisoning SPIRV-Tools
  26
  27 See [`CHANGES`](CHANGES) for a high level summary of recent changes, by version.
  28
  29 SPIRV-Tools project version numbers are of the form `v`*year*`.`*index* and with
  30 an optional `-dev` suffix to indicate work in progress.  For exampe, the
  31 following versions are ordered from oldest to newest:
  32
  33 * `v2016.0`
  34 * `v2016.1-dev`
  35 * `v2016.1`
  36 * `v2016.2-dev`
  37 * `v2016.2`
  38
  39 Use the `--version` option on each command line tool to see the software
  40 version.  An API call reports the software version as a C-style string.
  41
  42 ## Supported features
  43
  44 ### Assembler, binary parser, and disassembler
  45
  46 * Support for SPIR-V 1.0, 1.1, 1.2
  47   * Based on SPIR-V syntax described by JSON grammar files in the
  48     [SPIRV-Headers](spirv-headers) repository.
  49 * Support for extended instruction sets:
  50   * GLSL std450 version 1.0 Rev 3
  51   * OpenCL version 1.0 Rev 2
  52 * Assembler only does basic syntax checking.  No cross validation of
  53   IDs or types is performed, except to check literal arguments to
  54   `OpConstant`, `OpSpecConstant`, and `OpSwitch`.
  55
  56 See [`syntax.md`](syntax.md) for the assembly language syntax.
  57
  58 ### Validator
  59
  60 The validator checks validation rules described by the SPIR-V specification.
  61
  62 Khronos recommends that tools that create or transform SPIR-V modules use the
  63 validator to ensure their outputs are valid, and that tools that consume SPIR-V
  64 modules optionally use the validator to protect themselves from bad inputs.
  65 This is especially encouraged for debug and development scenarios.
  66
  67 The validator has one-sided error: it will only return an error when it has
  68 implemented a rule check and the module violates that rule.
  69
  70 The validator is incomplete.
  71 See the [CHANGES](CHANGES) file for reports on completed work, and
  72 the [Validator
  73 sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/1) for planned
  74 and in-progress work.
  75
  76 *Note*: The validator checks some Universal Limits, from section 2.17 of the SPIR-V spec.
  77 The validator will fail on a module that exceeds those minimum upper bound limits.
  78 It is [future work](https://github.com/KhronosGroup/SPIRV-Tools/projects/1#card-1052403)
  79 to parameterize the validator to allow larger
  80 limits accepted by a more than minimally capable SPIR-V consumer.
  81
  82
  83 ### Optimizer
  84
  85 *Note:* The optimizer is still under development.
  86
  87 Currently supported optimizations:
  88 * General
  89   * Strip debug info
  90 * Specialization Constants
  91   * Set spec constant default value
  92   * Freeze spec constant
  93   * Fold `OpSpecConstantOp` and `OpSpecConstantComposite`
  94   * Unify constants
  95   * Eliminate dead constant
  96 * Code Reduction
  97   * Inline all function calls exhaustively
  98   * Convert local access chains to inserts/extracts
  99   * Eliminate local load/store in single block
 100   * Eliminate local load/store with single store
 101   * Eliminate local load/store with multiple stores
 102   * Eliminate local extract from insert
 103   * Eliminate dead instructions (aggressive)
 104   * Eliminate dead branches
 105   * Merge single successor / single predecessor block pairs
 106   * Eliminate common uniform loads
 107   * Remove duplicates: Capabilities, extended instruction imports, types, and
 108     decorations.
 109
 110 For the latest list with detailed documentation, please refer to
 111 [`include/spirv-tools/optimizer.hpp`](include/spirv-tools/optimizer.hpp).
 112
 113 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/).
 114
 115
 116 ### Linker
 117
 118 *Note:* The linker is still under development.
 119
 120 Current features:
 121 * Combine multiple SPIR-V binary modules together.
 122 * Combine into a library (exports are retained) or an executable (no symbols
 123   are exported).
 124
 125 See the [CHANGES](CHANGES) file for reports on completed work, and the [General
 126 sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/2) for
 127 planned and in-progress work.
 128
 129 ### Extras
 130
 131 * [Utility filters](#utility-filters)
 132 * Build target `spirv-tools-vimsyntax` generates file `spvasm.vim`.
 133   Copy that file into your `$HOME/.vim/syntax` directory to get SPIR-V assembly syntax
 134   highlighting in Vim.  This build target is not built by default.
 135
 136 ## Contributing
 137
 138 The SPIR-V Tools project is maintained by members of the The Khronos Group Inc.,
 139 and is hosted at https://github.com/KhronosGroup/SPIRV-Tools.
 140
 141 Consider joining the `public_spirv_tools_dev@khronos.org` mailing list, via
 142 [https://www.khronos.org/spir/spirv-tools-mailing-list/](https://www.khronos.org/spir/spirv-tools-mailing-list/).
 143 The mailing list is used to discuss development plans for the SPIRV-Tools as an open source project.
 144 Once discussion is resolved,
 145 specific work is tracked via issues and sometimes in one of the
 146 [projects][spirv-tools-projects].
 147
 148 (To provide feedback on the SPIR-V _specification_, file an issue on the
 149 [SPIRV-Headers][spirv-headers] GitHub repository.)
 150
 151 See [`projects.md`](projects.md) to see how we use the
 152 [GitHub Project
 153 feature](https://help.github.com/articles/tracking-the-progress-of-your-work-with-projects/)
 154 to organize planned and in-progress work.
 155
 156 Contributions via merge request are welcome. Changes should:
 157 * Be provided under the [Apache 2.0](#license).
 158 * You'll be prompted with a one-time "click-through"
 159   [Khronos Open Source Contributor License Agreement][spirv-tools-cla]
 160   (CLA) dialog as part of submitting your pull request or
 161   other contribution to GitHub.
 162 * Include tests to cover updated functionality.
 163 * C++ code should follow the [Google C++ Style Guide][cpp-style-guide].
 164 * Code should be formatted with `clang-format`.  Settings are defined by
 165   the included [.clang-format](.clang-format) file.
 166
 167 We intend to maintain a linear history on the GitHub `master` branch.
 168
 169 ### Source code organization
 170
 171 * `example`: demo code of using SPIRV-Tools APIs
 172 * `external/googletest`: Intended location for the
 173   [googletest][googletest] sources, not provided
 174 * `external/effcee`: Location of [Effcee][effcee] sources, if the `effcee` library
 175   is not already configured by an enclosing project.
 176 * `external/re2`: Location of [RE2][re2] sources, if the `effcee` library is not already
 177   configured by an enclosing project.
 178   (The Effcee project already requires RE2.)
 179 * `include/`: API clients should add this directory to the include search path
 180 * `external/spirv-headers`: Intended location for
 181   [SPIR-V headers][spirv-headers], not provided
 182 * `include/spirv-tools/libspirv.h`: C API public interface
 183 * `source/`: API implementation
 184 * `test/`: Tests, using the [googletest][googletest] framework
 185 * `tools/`: Command line executables
 186
 187 Example of getting sources, assuming SPIRV-Tools is configured as a standalone project:
 188
 189     git clone https://github.com/KhronosGroup/SPIRV-Tools.git   spirv-tools
 190     git clone https://github.com/KhronosGroup/SPIRV-Headers.git spirv-tools/external/spirv-headers
 191     git clone https://github.com/google/googletest.git          spirv-tools/external/googletest
 192     git clone https://github.com/google/effcee.git              spirv-tools/external/effcee
 193     git clone https://github.com/google/re2.git                 spirv-tools/external/re2
 194
 195 ### Tests
 196
 197 The project contains a number of tests, used to drive development
 198 and ensure correctness.  The tests are written using the
 199 [googletest][googletest] framework.  The `googletest`
 200 source is not provided with this project.  There are two ways to enable
 201 tests:
 202 * If SPIR-V Tools is configured as part of an enclosing project, then the
 203   enclosing project should configure `googletest` before configuring SPIR-V Tools.
 204 * If SPIR-V Tools is configured as a standalone project, then download the
 205   `googletest` source into the `<spirv-dir>/external/googletest` directory before
 206   configuring and building the project.
 207
 208 *Note*: You must use a version of googletest that includes
 209 [a fix][googletest-pull-612] for [googletest issue 610][googletest-issue-610].
 210 The fix is included on the googletest master branch any time after 2015-11-10.
 211 In particular, googletest must be newer than version 1.7.0.
 212
 213 ### Optional dependency on Effcee
 214
 215 Some tests depend on the [Effcee][effcee] library for stateful matching.
 216 Effcee itself depends on [RE2][re2].
 217
 218 * If SPIRV-Tools is configured as part of a larger project that already uses
 219   Effcee, then that project should include Effcee before SPIRV-Tools.
 220 * Otherwise, SPIRV-Tools expects Effcee sources to appear in `external/effcee`
 221   and RE2 sources to appear in `external/re2`.
 222
 223 Currently Effcee is an optional dependency, but soon it will be required.
 224
 225 ## Build
 226
 227 Instead of building manually, you can also download the binaries for your
 228 platform directly from the [master-tot release][master-tot-release] on GitHub.
 229 Those binaries are automatically uploaded by the buildbots after successful
 230 testing and they always reflect the current top of the tree of the master
 231 branch.
 232
 233 The project uses [CMake][cmake] to generate platform-specific build
 234 configurations. Assume that `<spirv-dir>` is the root directory of the checked
 235 out code:
 236
 237 ```sh
 238 cd <spirv-dir>
 239 git clone https://github.com/KhronosGroup/SPIRV-Headers.git external/spirv-headers
 240 git clone https://github.com/google/googletest.git external/googletest # optional
 241
 242 mkdir build && cd build
 243 cmake [-G <platform-generator>] <spirv-dir>
 244 ```
 245
 246 Once the build files have been generated, build using your preferred
 247 development environment.
 248
 249 ### CMake options
 250
 251 The following CMake options are supported:
 252
 253 * `SPIRV_COLOR_TERMINAL={ON|OFF}`, default `ON` - Enables color console output.
 254 * `SPIRV_SKIP_TESTS={ON|OFF}`, default `OFF`- Build only the library and
 255   the command line tools.  This will prevent the tests from being built.
 256 * `SPIRV_SKIP_EXECUTABLES={ON|OFF}`, default `OFF`- Build only the library, not
 257   the command line tools and tests.
 258 * `SPIRV_BUILD_COMPRESSION={ON|OFF}`, default `OFF`- Build SPIR-V compressing
 259   codec.
 260 * `SPIRV_USE_SANITIZER=<sanitizer>`, default is no sanitizing - On UNIX
 261   platforms with an appropriate version of `clang` this option enables the use
 262   of the sanitizers documented [here][clang-sanitizers].
 263   This should only be used with a debug build.
 264 * `SPIRV_WARN_EVERYTHING={ON|OFF}`, default `OFF` - On UNIX platforms enable
 265   more strict warnings.  The code might not compile with this option enabled.
 266   For Clang, enables `-Weverything`.  For GCC, enables `-Wpedantic`.
 267   See [`CMakeLists.txt`](CMakeLists.txt) for details.
 268 * `SPIRV_WERROR={ON|OFF}`, default `ON` - Forces a compilation error on any
 269   warnings encountered by enabling the compiler-specific compiler front-end
 270   option.
 271
 272 Additionally, you can pass additional C preprocessor definitions to SPIRV-Tools
 273 via setting `SPIRV_TOOLS_EXTRA_DEFINITIONS`. For example, by setting it to
 274 `/D_ITERATOR_DEBUG_LEVEL=0` on Windows, you can disable checked iterators and
 275 iterator debugging.
 276
 277 ## Library
 278
 279 ### Usage
 280
 281 The internals of the library use C++11 features, and are exposed via both a C
 282 and C++ API.
 283
 284 In order to use the library from an application, the include path should point
 285 to `<spirv-dir>/include`, which will enable the application to include the
 286 header `<spirv-dir>/include/spirv-tools/libspirv.h{|pp}` then linking against
 287 the static library in `<spirv-build-dir>/source/libSPIRV-Tools.a` or
 288 `<spirv-build-dir>/source/SPIRV-Tools.lib`.
 289 For optimization, the header file is
 290 `<spirv-dir>/include/spirv-tools/optimizer.hpp`, and the static library is
 291 `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` or
 292 `<spirv-build-dir>/source/SPIRV-Tools-opt.lib`.
 293
 294 * `SPIRV-Tools` CMake target: Creates the static library:
 295   * `<spirv-build-dir>/source/libSPIRV-Tools.a` on Linux and OS X.
 296   * `<spirv-build-dir>/source/libSPIRV-Tools.lib` on Windows.
 297 * `SPIRV-Tools-opt` CMake target: Creates the static library:
 298   * `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` on Linux and OS X.
 299   * `<spirv-build-dir>/source/libSPIRV-Tools-opt.lib` on Windows.
 300
 301 #### Entry points
 302
 303 The interfaces are still under development, and are expected to change.
 304
 305 There are five main entry points into the library in the C interface:
 306
 307 * `spvTextToBinary`: An assembler, translating text to a binary SPIR-V module.
 308 * `spvBinaryToText`: A disassembler, translating a binary SPIR-V module to
 309   text.
 310 * `spvBinaryParse`: The entry point to a binary parser API.  It issues callbacks
 311   for the header and each parsed instruction.  The disassembler is implemented
 312   as a client of `spvBinaryParse`.
 313 * `spvValidate` implements the validator functionality. *Incomplete*
 314 * `spvValidateBinary` implements the validator functionality. *Incomplete*
 315
 316 The C++ interface is comprised of three classes, `SpirvTools`, `Optimizer` and
 317 `Linker`, all in the `spvtools` namespace.
 318 * `SpirvTools` provides `Assemble`, `Disassemble`, and `Validate` methods.
 319 * `Optimizer` provides methods for registering and running optimization passes.
 320 * `Linker` provides methods for combining together multiple binaries.
 321
 322 ## Command line tools
 323
 324 Command line tools, which wrap the above library functions, are provided to
 325 assemble or disassemble shader files.  It's a convention to name SPIR-V
 326 assembly and binary files with suffix `.spvasm` and `.spv`, respectively.
 327
 328 ### Assembler tool
 329
 330 The assembler reads the assembly language text, and emits the binary form.
 331
 332 The standalone assembler is the exectuable called `spirv-as`, and is located in
 333 `<spirv-build-dir>/tools/spirv-as`.  The functionality of the assembler is implemented
 334 by the `spvTextToBinary` library function.
 335
 336 * `spirv-as` - the standalone assembler
 337   * `<spirv-dir>/tools/as`
 338
 339 Use option `-h` to print help.
 340
 341 ### Disassembler tool
 342
 343 The disassembler reads the binary form, and emits assembly language text.
 344
 345 The standalone disassembler is the executable called `spirv-dis`, and is located in
 346 `<spirv-build-dir>/tools/spirv-dis`. The functionality of the disassembler is implemented
 347 by the `spvBinaryToText` library function.
 348
 349 * `spirv-dis` - the standalone disassembler
 350   * `<spirv-dir>/tools/dis`
 351
 352 Use option `-h` to print help.
 353
 354 The output includes syntax colouring when printing to the standard output stream,
 355 on Linux, Windows, and OS X.
 356
 357 ### Linker tool
 358
 359 The linker combines multiple SPIR-V binary modules together, resulting in a single
 360 binary module as output.
 361
 362 This is a work in progress.
 363 The linker does not support OpenCL program linking options related to math
 364 flags. (See section 5.6.5.2 in OpenCL 1.2)
 365
 366 * `spirv-link` - the standalone linker
 367   * `<spirv-dir>/tools/link`
 368
 369 ### Optimizer tool
 370
 371 The optimizer processes a SPIR-V binary module, applying transformations
 372 in the specified order.
 373
 374 This is a work in progress, with initially only few available transformations.
 375
 376 * `spirv-opt` - the standalone optimizer
 377   * `<spirv-dir>/tools/opt`
 378
 379 ### Validator tool
 380
 381 *Warning:* This functionality is under development, and is incomplete.
 382
 383 The standalone validator is the executable called `spirv-val`, and is located in
 384 `<spirv-build-dir>/tools/spirv-val`. The functionality of the validator is implemented
 385 by the `spvValidate` library function.
 386
 387 The validator operates on the binary form.
 388
 389 * `spirv-val` - the standalone validator
 390   * `<spirv-dir>/tools/val`
 391
 392 ### Control flow dumper tool
 393
 394 The control flow dumper prints the control flow graph for a SPIR-V module as a
 395 [GraphViz](http://www.graphviz.org/) graph.
 396
 397 This is experimental.
 398
 399 * `spirv-cfg` - the control flow graph dumper
 400   * `<spirv-dir>/tools/cfg`
 401
 402 ### Utility filters
 403
 404 * `spirv-lesspipe.sh` - Automatically disassembles `.spv` binary files for the
 405   `less` program, on compatible systems.  For example, set the `LESSOPEN`
 406   environment variable as follows, assuming both `spirv-lesspipe.sh` and
 407   `spirv-dis` are on your executable search path:
 408   ```
 409    export LESSOPEN='| spirv-lesspipe.sh "%s"'
 410   ```
 411   Then you page through a disassembled module as follows:
 412   ```
 413   less foo.spv
 414   ```
 415   * The `spirv-lesspipe.sh` script will pass through any extra arguments to
 416     `spirv-dis`.  So, for example, you can turn off colours and friendly ID
 417     naming as follows:
 418     ```
 419     export LESSOPEN='| spirv-lesspipe.sh "%s" --no-color --raw-id'
 420     ```
 421
 422 * [vim-spirv](https://github.com/kbenzie/vim-spirv) - A vim plugin which
 423   supports automatic disassembly of `.spv` files using the `:edit` command and
 424   assembly using the `:write` command. The plugin also provides additional
 425   features which include; syntax highlighting; highlighting of all ID's matching
 426   the ID under the cursor; and highlighting errors where the `Instruction`
 427   operand of `OpExtInst` is used without an appropriate `OpExtInstImport`.
 428
 429 * `50spirv-tools.el` - Automatically disassembles '.spv' binary files when
 430   loaded into the emacs text editor, and re-assembles them when saved,
 431   provided any modifications to the file are valid.  This functionality
 432   must be explicitly requested by defining the symbol
 433   SPIRV_TOOLS_INSTALL_EMACS_HELPERS as follows:
 434   ```
 435   cmake -DSPIRV_TOOLS_INSTALL_EMACS_HELPERS=true ...
 436   ```
 437
 438   In addition, this helper is only installed if the directory /etc/emacs/site-start.d
 439   exists, which is typically true if emacs is installed on the system.
 440
 441   Note that symbol IDs are not currently preserved through a load/edit/save operation.
 442   This may change if the ability is added to spirv-as.
 443
 444
 445 ### Tests
 446
 447 Tests are only built when googletest is found. Use `ctest` to run all the
 448 tests.
 449
 450 ## Future Work
 451 <a name="future"></a>
 452
 453 _See the [projects pages](https://github.com/KhronosGroup/SPIRV-Tools/projects)
 454 for more information._
 455
 456 ### Assembler and disassembler
 457
 458 * The disassembler could emit helpful annotations in comments.  For example:
 459   * Use variable name information from debug instructions to annotate
 460     key operations on variables.
 461   * Show control flow information by annotating `OpLabel` instructions with
 462     that basic block's predecessors.
 463 * Error messages could be improved.
 464
 465 ### Validator
 466
 467 This is a work in progress.
 468
 469 ### Linker
 470
 471 * The linker could accept math transformations such as allowing MADs, or other
 472   math flags passed at linking-time in OpenCL.
 473 * Linkage attributes can not be applied through a group.
 474 * Check decorations of linked functions attributes.
 475 * Remove dead instructions, such as OpName targeting imported symbols.
 476
 477 ## Licence
 478 <a name="license"></a>
 479 Full license terms are in [LICENSE](LICENSE)
 480 ```
 481 Copyright (c) 2015-2016 The Khronos Group Inc.
 482
 483 Licensed under the Apache License, Version 2.0 (the "License");
 484 you may not use this file except in compliance with the License.
 485 You may obtain a copy of the License at
 486
 487     http://www.apache.org/licenses/LICENSE-2.0
 488
 489 Unless required by applicable law or agreed to in writing, software
 490 distributed under the License is distributed on an "AS IS" BASIS,
 491 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 492 See the License for the specific language governing permissions and
 493 limitations under the License.
 494 ```
 495
 496 [spirv-tools-cla]: https://cla-assistant.io/KhronosGroup/SPIRV-Tools
 497 [spirv-tools-projects]: https://github.com/KhronosGroup/SPIRV-Tools/projects
 498 [spirv-tools-mailing-list]: https://www.khronos.org/spir/spirv-tools-mailing-list
 499 [spirv-registry]: https://www.khronos.org/registry/spir-v/
 500 [spirv-headers]: https://github.com/KhronosGroup/SPIRV-Headers
 501 [googletest]: https://github.com/google/googletest
 502 [googletest-pull-612]: https://github.com/google/googletest/pull/612
 503 [googletest-issue-610]: https://github.com/google/googletest/issues/610
 504 [effcee]: https://github.com/google/effcee
 505 [re2]: https://github.com/google/re2
 506 [CMake]: https://cmake.org/
 507 [cpp-style-guide]: https://google.github.io/styleguide/cppguide.html
 508 [clang-sanitizers]: http://clang.llvm.org/docs/UsersManual.html#controlling-code-generation
 509 [master-tot-release]: https://github.com/KhronosGroup/SPIRV-Tools/releases/tag/master-tot