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 The project uses [CMake][cmake] to generate platform-specific build
 228 configurations. Assume that `<spirv-dir>` is the root directory of the checked
 229 out code:
 230
 231 ```sh
 232 cd <spirv-dir>
 233 git clone https://github.com/KhronosGroup/SPIRV-Headers.git external/spirv-headers
 234 git clone https://github.com/google/googletest.git external/googletest # optional
 235
 236 mkdir build && cd build
 237 cmake [-G <platform-generator>] <spirv-dir>
 238 ```
 239
 240 Once the build files have been generated, build using your preferred
 241 development environment.
 242
 243 ### CMake options
 244
 245 The following CMake options are supported:
 246
 247 * `SPIRV_COLOR_TERMINAL={ON|OFF}`, default `ON` - Enables color console output.
 248 * `SPIRV_SKIP_TESTS={ON|OFF}`, default `OFF`- Build only the library and
 249   the command line tools.  This will prevent the tests from being built.
 250 * `SPIRV_SKIP_EXECUTABLES={ON|OFF}`, default `OFF`- Build only the library, not
 251   the command line tools and tests.
 252 * `SPIRV_BUILD_COMPRESSION={ON|OFF}`, default `OFF`- Build SPIR-V compressing
 253   codec.
 254 * `SPIRV_USE_SANITIZER=<sanitizer>`, default is no sanitizing - On UNIX
 255   platforms with an appropriate version of `clang` this option enables the use
 256   of the sanitizers documented [here][clang-sanitizers].
 257   This should only be used with a debug build.
 258 * `SPIRV_WARN_EVERYTHING={ON|OFF}`, default `OFF` - On UNIX platforms enable
 259   more strict warnings.  The code might not compile with this option enabled.
 260   For Clang, enables `-Weverything`.  For GCC, enables `-Wpedantic`.
 261   See [`CMakeLists.txt`](CMakeLists.txt) for details.
 262 * `SPIRV_WERROR={ON|OFF}`, default `ON` - Forces a compilation error on any
 263   warnings encountered by enabling the compiler-specific compiler front-end
 264   option.
 265
 266 Additionally, you can pass additional C preprocessor definitions to SPIRV-Tools
 267 via setting `SPIRV_TOOLS_EXTRA_DEFINITIONS`. For example, by setting it to
 268 `/D_ITERATOR_DEBUG_LEVEL=0` on Windows, you can disable checked iterators and
 269 iterator debugging.
 270
 271 ## Library
 272
 273 ### Usage
 274
 275 The internals of the library use C++11 features, and are exposed via both a C
 276 and C++ API.
 277
 278 In order to use the library from an application, the include path should point
 279 to `<spirv-dir>/include`, which will enable the application to include the
 280 header `<spirv-dir>/include/spirv-tools/libspirv.h{|pp}` then linking against
 281 the static library in `<spirv-build-dir>/source/libSPIRV-Tools.a` or
 282 `<spirv-build-dir>/source/SPIRV-Tools.lib`.
 283 For optimization, the header file is
 284 `<spirv-dir>/include/spirv-tools/optimizer.hpp`, and the static library is
 285 `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` or
 286 `<spirv-build-dir>/source/SPIRV-Tools-opt.lib`.
 287
 288 * `SPIRV-Tools` CMake target: Creates the static library:
 289   * `<spirv-build-dir>/source/libSPIRV-Tools.a` on Linux and OS X.
 290   * `<spirv-build-dir>/source/libSPIRV-Tools.lib` on Windows.
 291 * `SPIRV-Tools-opt` CMake target: Creates the static library:
 292   * `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` on Linux and OS X.
 293   * `<spirv-build-dir>/source/libSPIRV-Tools-opt.lib` on Windows.
 294
 295 #### Entry points
 296
 297 The interfaces are still under development, and are expected to change.
 298
 299 There are five main entry points into the library in the C interface:
 300
 301 * `spvTextToBinary`: An assembler, translating text to a binary SPIR-V module.
 302 * `spvBinaryToText`: A disassembler, translating a binary SPIR-V module to
 303   text.
 304 * `spvBinaryParse`: The entry point to a binary parser API.  It issues callbacks
 305   for the header and each parsed instruction.  The disassembler is implemented
 306   as a client of `spvBinaryParse`.
 307 * `spvValidate` implements the validator functionality. *Incomplete*
 308 * `spvValidateBinary` implements the validator functionality. *Incomplete*
 309
 310 The C++ interface is comprised of three classes, `SpirvTools`, `Optimizer` and
 311 `Linker`, all in the `spvtools` namespace.
 312 * `SpirvTools` provides `Assemble`, `Disassemble`, and `Validate` methods.
 313 * `Optimizer` provides methods for registering and running optimization passes.
 314 * `Linker` provides methods for combining together multiple binaries.
 315
 316 ## Command line tools
 317
 318 Command line tools, which wrap the above library functions, are provided to
 319 assemble or disassemble shader files.  It's a convention to name SPIR-V
 320 assembly and binary files with suffix `.spvasm` and `.spv`, respectively.
 321
 322 ### Assembler tool
 323
 324 The assembler reads the assembly language text, and emits the binary form.
 325
 326 The standalone assembler is the exectuable called `spirv-as`, and is located in
 327 `<spirv-build-dir>/tools/spirv-as`.  The functionality of the assembler is implemented
 328 by the `spvTextToBinary` library function.
 329
 330 * `spirv-as` - the standalone assembler
 331   * `<spirv-dir>/tools/as`
 332
 333 Use option `-h` to print help.
 334
 335 ### Disassembler tool
 336
 337 The disassembler reads the binary form, and emits assembly language text.
 338
 339 The standalone disassembler is the executable called `spirv-dis`, and is located in
 340 `<spirv-build-dir>/tools/spirv-dis`. The functionality of the disassembler is implemented
 341 by the `spvBinaryToText` library function.
 342
 343 * `spirv-dis` - the standalone disassembler
 344   * `<spirv-dir>/tools/dis`
 345
 346 Use option `-h` to print help.
 347
 348 The output includes syntax colouring when printing to the standard output stream,
 349 on Linux, Windows, and OS X.
 350
 351 ### Linker tool
 352
 353 The linker combines multiple SPIR-V binary modules together, resulting in a single
 354 binary module as output.
 355
 356 This is a work in progress.
 357 The linker does not support OpenCL program linking options related to math
 358 flags. (See section 5.6.5.2 in OpenCL 1.2)
 359
 360 * `spirv-link` - the standalone linker
 361   * `<spirv-dir>/tools/link`
 362
 363 ### Optimizer tool
 364
 365 The optimizer processes a SPIR-V binary module, applying transformations
 366 in the specified order.
 367
 368 This is a work in progress, with initially only few available transformations.
 369
 370 * `spirv-opt` - the standalone optimizer
 371   * `<spirv-dir>/tools/opt`
 372
 373 ### Validator tool
 374
 375 *Warning:* This functionality is under development, and is incomplete.
 376
 377 The standalone validator is the executable called `spirv-val`, and is located in
 378 `<spirv-build-dir>/tools/spirv-val`. The functionality of the validator is implemented
 379 by the `spvValidate` library function.
 380
 381 The validator operates on the binary form.
 382
 383 * `spirv-val` - the standalone validator
 384   * `<spirv-dir>/tools/val`
 385
 386 ### Control flow dumper tool
 387
 388 The control flow dumper prints the control flow graph for a SPIR-V module as a
 389 [GraphViz](http://www.graphviz.org/) graph.
 390
 391 This is experimental.
 392
 393 * `spirv-cfg` - the control flow graph dumper
 394   * `<spirv-dir>/tools/cfg`
 395
 396 ### Utility filters
 397
 398 * `spirv-lesspipe.sh` - Automatically disassembles `.spv` binary files for the
 399   `less` program, on compatible systems.  For example, set the `LESSOPEN`
 400   environment variable as follows, assuming both `spirv-lesspipe.sh` and
 401   `spirv-dis` are on your executable search path:
 402   ```
 403    export LESSOPEN='| spirv-lesspipe.sh "%s"'
 404   ```
 405   Then you page through a disassembled module as follows:
 406   ```
 407   less foo.spv
 408   ```
 409   * The `spirv-lesspipe.sh` script will pass through any extra arguments to
 410     `spirv-dis`.  So, for example, you can turn off colours and friendly ID
 411     naming as follows:
 412     ```
 413     export LESSOPEN='| spirv-lesspipe.sh "%s" --no-color --raw-id'
 414     ```
 415
 416 * [vim-spirv](https://github.com/kbenzie/vim-spirv) - A vim plugin which
 417   supports automatic disassembly of `.spv` files using the `:edit` command and
 418   assembly using the `:write` command. The plugin also provides additional
 419   features which include; syntax highlighting; highlighting of all ID's matching
 420   the ID under the cursor; and highlighting errors where the `Instruction`
 421   operand of `OpExtInst` is used without an appropriate `OpExtInstImport`.
 422
 423 * `50spirv-tools.el` - Automatically disassembles '.spv' binary files when
 424   loaded into the emacs text editor, and re-assembles them when saved,
 425   provided any modifications to the file are valid.  This functionality
 426   must be explicitly requested by defining the symbol
 427   SPIRV_TOOLS_INSTALL_EMACS_HELPERS as follows:
 428   ```
 429   cmake -DSPIRV_TOOLS_INSTALL_EMACS_HELPERS=true ...
 430   ```
 431
 432   In addition, this helper is only installed if the directory /etc/emacs/site-start.d
 433   exists, which is typically true if emacs is installed on the system.
 434
 435   Note that symbol IDs are not currently preserved through a load/edit/save operation.
 436   This may change if the ability is added to spirv-as.
 437
 438
 439 ### Tests
 440
 441 Tests are only built when googletest is found. Use `ctest` to run all the
 442 tests.
 443
 444 ## Future Work
 445 <a name="future"></a>
 446
 447 _See the [projects pages](https://github.com/KhronosGroup/SPIRV-Tools/projects)
 448 for more information._
 449
 450 ### Assembler and disassembler
 451
 452 * The disassembler could emit helpful annotations in comments.  For example:
 453   * Use variable name information from debug instructions to annotate
 454     key operations on variables.
 455   * Show control flow information by annotating `OpLabel` instructions with
 456     that basic block's predecessors.
 457 * Error messages could be improved.
 458
 459 ### Validator
 460
 461 This is a work in progress.
 462
 463 ### Linker
 464
 465 * The linker could accept math transformations such as allowing MADs, or other
 466   math flags passed at linking-time in OpenCL.
 467 * Linkage attributes can not be applied through a group.
 468 * Check decorations of linked functions attributes.
 469 * Remove dead instructions, such as OpName targeting imported symbols.
 470
 471 ## Licence
 472 <a name="license"></a>
 473 Full license terms are in [LICENSE](LICENSE)
 474 ```
 475 Copyright (c) 2015-2016 The Khronos Group Inc.
 476
 477 Licensed under the Apache License, Version 2.0 (the "License");
 478 you may not use this file except in compliance with the License.
 479 You may obtain a copy of the License at
 480
 481     http://www.apache.org/licenses/LICENSE-2.0
 482
 483 Unless required by applicable law or agreed to in writing, software
 484 distributed under the License is distributed on an "AS IS" BASIS,
 485 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 486 See the License for the specific language governing permissions and
 487 limitations under the License.
 488 ```
 489
 490 [spirv-tools-cla]: https://cla-assistant.io/KhronosGroup/SPIRV-Tools
 491 [spirv-tools-projects]: https://github.com/KhronosGroup/SPIRV-Tools/projects
 492 [spirv-tools-mailing-list]: https://www.khronos.org/spir/spirv-tools-mailing-list
 493 [spirv-registry]: https://www.khronos.org/registry/spir-v/
 494 [spirv-headers]: https://github.com/KhronosGroup/SPIRV-Headers
 495 [googletest]: https://github.com/google/googletest
 496 [googletest-pull-612]: https://github.com/google/googletest/pull/612
 497 [googletest-issue-610]: https://github.com/google/googletest/issues/610
 498 [effcee]: https://github.com/google/effcee
 499 [re2]: https://github.com/google/re2
 500 [CMake]: https://cmake.org/
 501 [cpp-style-guide]: https://google.github.io/styleguide/cppguide.html
 502 [clang-sanitizers]: http://clang.llvm.org/docs/UsersManual.html#controlling-code-generation