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 See [`projects.md`](projects.md) to see how we use the
  22 [GitHub Project
  23 feature](https://help.github.com/articles/tracking-the-progress-of-your-work-with-projects/)
  24 to organize planned and in-progress work.
  25
  26 SPIR-V is defined by the Khronos Group Inc.
  27 See the [SPIR-V Registry][spirv-registry] for the SPIR-V specification,
  28 headers, and XML registry.
  29
  30 ## Verisoning SPIRV-Tools
  31
  32 See [`CHANGES`](CHANGES) for a high level summary of recent changes, by version.
  33
  34 SPIRV-Tools project version numbers are of the form `v`*year*`.`*index* and with
  35 an optional `-dev` suffix to indicate work in progress.  For exampe, the
  36 following versions are ordered from oldest to newest:
  37
  38 * `v2016.0`
  39 * `v2016.1-dev`
  40 * `v2016.1`
  41 * `v2016.2-dev`
  42 * `v2016.2`
  43
  44 Use the `--version` option on each command line tool to see the software
  45 version.  An API call reports the software version as a C-style string.
  46
  47 ## Supported features
  48
  49 ### Assembler, binary parser, and disassembler
  50
  51 * Based on SPIR-V version 1.1 Rev 3
  52 * Support for extended instruction sets:
  53   * GLSL std450 version 1.0 Rev 3
  54   * OpenCL version 1.0 Rev 2
  55 * Support for SPIR-V 1.0 (with or without additional restrictions from Vulkan 1.0)
  56 * Assembler only does basic syntax checking.  No cross validation of
  57   IDs or types is performed, except to check literal arguments to
  58   `OpConstant`, `OpSpecConstant`, and `OpSwitch`.
  59
  60 See [`syntax.md`](syntax.md) for the assembly language syntax.
  61
  62 ### Validator
  63
  64 *Warning:* The validator is incomplete.
  65 Check the [CHANGES](CHANGES) file for reports on completed work, and
  66 the [Validator
  67 sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/1) for planned
  68 and in-progress work.
  69
  70 *Note*: The validator checks some Universal Limits, from section 2.17 of the SPIR-V spec.
  71 The validator will fail on a module that exceeds those minimum upper bound limits.
  72 It is [future work](https://github.com/KhronosGroup/SPIRV-Tools/projects/1#card-1052403)
  73 to parameterize the validator to allow larger
  74 limits accepted by a more than minimally capable SPIR-V consumer.
  75
  76
  77 ### Optimizer
  78
  79 *Warning:* The optimizer is still under development.
  80
  81 Currently supported optimizations:
  82 * Strip debug info
  83 * Set spec constant default value
  84 * Freeze spec constant
  85 * Fold `OpSpecConstantOp` and `OpSpecConstantComposite`
  86 * Unify constants
  87 * Eliminate dead constant
  88
  89 For the latest list with detailed documentation, please refer to
  90 [`include/spirv-tools/optimizer.hpp`](include/spirv-tools/optimizer.hpp).
  91
  92 ## Source code
  93
  94 The SPIR-V Tools are maintained by members of the The Khronos Group Inc.,
  95 at https://github.com/KhronosGroup/SPIRV-Tools.
  96
  97 Contributions via merge request are welcome. Changes should:
  98 * Be provided under the [Apache 2.0](#license).
  99   You'll be prompted with a one-time "click-through" Contributor's License
 100   Agreement (CLA) dialog as part of submitting your pull request or
 101   other contribution to GitHub.
 102 * Include tests to cover updated functionality.
 103 * C++ code should follow the [Google C++ Style Guide][cpp-style-guide].
 104 * Code should be formatted with `clang-format`.  Settings are defined by
 105   the included [.clang-format](.clang-format) file.
 106
 107 We intend to maintain a linear history on the GitHub `master` branch.
 108
 109 ### Source code organization
 110
 111 * `example`: demo code of using SPIRV-Tools APIs
 112 * `external/googletest`: Intended location for the
 113   [googletest][googletest] sources, not provided
 114 * `include/`: API clients should add this directory to the include search path
 115 * `external/spirv-headers`: Intended location for
 116   [SPIR-V headers][spirv-headers], not provided
 117 * `include/spirv-tools/libspirv.h`: C API public interface
 118 * `source/`: API implementation
 119 * `test/`: Tests, using the [googletest][googletest] framework
 120 * `tools/`: Command line executables
 121
 122 ### Tests
 123
 124 The project contains a number of tests, used to drive development
 125 and ensure correctness.  The tests are written using the
 126 [googletest][googletest] framework.  The `googletest`
 127 source is not provided with this project.  There are two ways to enable
 128 tests:
 129 * If SPIR-V Tools is configured as part of an enclosing project, then the
 130   enclosing project should configure `googletest` before configuring SPIR-V Tools.
 131 * If SPIR-V Tools is configured as a standalone project, then download the
 132   `googletest` source into the `<spirv-dir>/external/googletest` directory before
 133   configuring and building the project.
 134
 135 *Note*: You must use a version of googletest that includes
 136 [a fix][googletest-pull-612] for [googletest issue 610][googletest-issue-610].
 137 The fix is included on the googletest master branch any time after 2015-11-10.
 138 In particular, googletest must be newer than version 1.7.0.
 139
 140 ## Build
 141
 142 The project uses [CMake][cmake] to generate platform-specific build
 143 configurations. Assume that `<spirv-dir>` is the root directory of the checked
 144 out code:
 145
 146 ```sh
 147 cd <spirv-dir>
 148 git clone https://github.com/KhronosGroup/SPIRV-Headers.git external/spirv-headers
 149 git clone https://github.com/google/googletest.git external/googletest # optional
 150
 151 mkdir build && cd build
 152 cmake [-G <platform-generator>] <spirv-dir>
 153 ```
 154
 155 Once the build files have been generated, build using your preferred
 156 development environment.
 157
 158 ### CMake options
 159
 160 The following CMake options are supported:
 161
 162 * `SPIRV_COLOR_TERMINAL={ON|OFF}`, default `ON` - Enables color console output.
 163 * `SPIRV_SKIP_TESTS={ON|OFF}`, default `OFF`- Build only the library and
 164   the command line tools.  This will prevent the tests from being built.
 165 * `SPIRV_SKIP_EXECUTABLES={ON|OFF}`, default `OFF`- Build only the library, not
 166   the command line tools and tests.
 167 * `SPIRV_USE_SANITIZER=<sanitizer>`, default is no sanitizing - On UNIX
 168   platforms with an appropriate version of `clang` this option enables the use
 169   of the sanitizers documented [here][clang-sanitizers].
 170   This should only be used with a debug build.
 171 * `SPIRV_WARN_EVERYTHING={ON|OFF}`, default `OFF` - On UNIX platforms enable
 172   more strict warnings.  The code might not compile with this option enabled.
 173   For Clang, enables `-Weverything`.  For GCC, enables `-Wpedantic`.
 174   See [`CMakeLists.txt`](CMakeLists.txt) for details.
 175 * `SPIRV_WERROR={ON|OFF}`, default `ON` - Forces a compilation error on any
 176   warnings encountered by enabling the compiler-specific compiler front-end
 177   option.
 178
 179 ## Library
 180
 181 ### Usage
 182
 183 The internals of the library use C++11 features, and are exposed via both a C
 184 and C++ API.
 185
 186 In order to use the library from an application, the include path should point
 187 to `<spirv-dir>/include`, which will enable the application to include the
 188 header `<spirv-dir>/include/spirv-tools/libspirv.h{|pp}` then linking against
 189 the static library in `<spirv-build-dir>/source/libSPIRV-Tools.a` or
 190 `<spirv-build-dir>/source/SPIRV-Tools.lib`.
 191 For optimization, the header file is
 192 `<spirv-dir>/include/spirv-tools/optimizer.hpp`, and the static library is
 193 `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` or
 194 `<spirv-build-dir>/source/SPIRV-Tools-opt.lib`.
 195
 196 * `SPIRV-Tools` CMake target: Creates the static library:
 197   * `<spirv-build-dir>/source/libSPIRV-Tools.a` on Linux and OS X.
 198   * `<spirv-build-dir>/source/libSPIRV-Tools.lib` on Windows.
 199 * `SPIRV-Tools-opt` CMake target: Creates the static library:
 200   * `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` on Linux and OS X.
 201   * `<spirv-build-dir>/source/libSPIRV-Tools-opt.lib` on Windows.
 202
 203 #### Entry points
 204
 205 The interfaces are still under development, and are expected to change.
 206
 207 There are five main entry points into the library in the C interface:
 208
 209 * `spvTextToBinary`: An assembler, translating text to a binary SPIR-V module.
 210 * `spvBinaryToText`: A disassembler, translating a binary SPIR-V module to
 211   text.
 212 * `spvBinaryParse`: The entry point to a binary parser API.  It issues callbacks
 213   for the header and each parsed instruction.  The disassembler is implemented
 214   as a client of `spvBinaryParse`.
 215 * `spvValidate` implements the validator functionality. *Incomplete*
 216 * `spvValidateBinary` implements the validator functionality. *Incomplete*
 217
 218 The C++ interface is comprised of two classes, `SpirvTools` and `Optimizer`,
 219 both in the `spvtools` namespace.
 220 * `SpirvTools` provides `Assemble`, `Disassemble`, and `Validate` methods.
 221 * `Optimizer` provides methods for registering and running optimization passes.
 222
 223 ## Command line tools
 224
 225 Command line tools, which wrap the above library functions, are provided to
 226 assemble or disassemble shader files.  It's a convention to name SPIR-V
 227 assembly and binary files with suffix `.spvasm` and `.spv`, respectively.
 228
 229 ### Assembler tool
 230
 231 The assembler reads the assembly language text, and emits the binary form.
 232
 233 The standalone assembler is the exectuable called `spirv-as`, and is located in
 234 `<spirv-build-dir>/tools/spirv-as`.  The functionality of the assembler is implemented
 235 by the `spvTextToBinary` library function.
 236
 237 * `spirv-as` - the standalone assembler
 238   * `<spirv-dir>/tools/as`
 239
 240 Use option `-h` to print help.
 241
 242 ### Disassembler tool
 243
 244 The disassembler reads the binary form, and emits assembly language text.
 245
 246 The standalone disassembler is the executable called `spirv-dis`, and is located in
 247 `<spirv-build-dir>/tools/spirv-dis`. The functionality of the disassembler is implemented
 248 by the `spvBinaryToText` library function.
 249
 250 * `spirv-dis` - the standalone disassembler
 251   * `<spirv-dir>/tools/dis`
 252
 253 Use option `-h` to print help.
 254
 255 The output includes syntax colouring when printing to the standard output stream,
 256 on Linux, Windows, and OS X.
 257
 258 ### Optimizer tool
 259
 260 The optimizer processes a SPIR-V binary module, applying transformations
 261 in the specified order.
 262
 263 This is a work in progress, with initially only few available transformations.
 264
 265 * `spirv-opt` - the standalone optimizer
 266   * `<spirv-dir>/tools/opt`
 267
 268 ### Validator tool
 269
 270 *Warning:* This functionality is under development, and is incomplete.
 271
 272 The standalone validator is the executable called `spirv-val`, and is located in
 273 `<spirv-build-dir>/tools/spirv-val`. The functionality of the validator is implemented
 274 by the `spvValidate` library function.
 275
 276 The validator operates on the binary form.
 277
 278 * `spirv-val` - the standalone validator
 279   * `<spirv-dir>/tools/val`
 280
 281 ### Control flow dumper tool
 282
 283 The control flow dumper prints the control flow graph for a SPIR-V module as a
 284 [GraphViz](http://www.graphviz.org/) graph.
 285
 286 This is experimental.
 287
 288 * `spirv-cfg` - the control flow graph dumper
 289   * `<spirv-dir>/tools/cfg`
 290
 291 ### Utility filters
 292
 293 * `spirv-lesspipe.sh` - Automatically disassembles `.spv` binary files for the
 294   `less` program, on compatible systems.  For example, set the `LESSOPEN`
 295   environment variable as follows, assuming both `spirv-lesspipe.sh` and
 296   `spirv-dis` are on your executable search path:
 297   ```
 298    export LESSOPEN='| spirv-lesspipe.sh "%s"'
 299   ```
 300   Then you page through a disassembled module as follows:
 301   ```
 302   less foo.spv
 303   ```
 304   * The `spirv-lesspipe.sh` script will pass through any extra arguments to
 305     `spirv-dis`.  So, for example, you can turn off colours and friendly ID
 306     naming as follows:
 307     ```
 308     export LESSOPEN='| spirv-lesspipe.sh "%s" --no-color --raw-id'
 309     ```
 310
 311 * `50spirv-tools.el` - Automatically disassembles '.spv' binary files when
 312   loaded into the emacs text editor, and re-assembles them when saved,
 313   provided any modifications to the file are valid.  This functionality
 314   must be explicitly requested by defining the symbol
 315   SPIRV_TOOLS_INSTALL_EMACS_HELPERS as follows:
 316   ```
 317   cmake -DSPIRV_TOOLS_INSTALL_EMACS_HELPERS=true ...
 318   ```
 319
 320   In addition, this helper is only installed if the directory /etc/emacs/site-start.d
 321   exists, which is typically true if emacs is installed on the system.
 322
 323   Note that symbol IDs are not currently preserved through a load/edit/save operation.
 324   This may change if the ability is added to spirv-as.
 325
 326
 327 ### Tests
 328
 329 Tests are only built when googletest is found. Use `ctest` to run all the
 330 tests.
 331
 332 ## Future Work
 333 <a name="future"></a>
 334
 335 ### Assembler and disassembler
 336
 337 * The disassembler could emit helpful annotations in comments.  For example:
 338   * Use variable name information from debug instructions to annotate
 339     key operations on variables.
 340   * Show control flow information by annotating `OpLabel` instructions with
 341     that basic block's predecessors.
 342 * Error messages could be improved.
 343
 344 ### Validator
 345
 346 This is a work in progress.
 347
 348 ## Licence
 349 <a name="license"></a>
 350 Full license terms are in [LICENSE](LICENSE)
 351 ```
 352 Copyright (c) 2015-2016 The Khronos Group Inc.
 353
 354 Licensed under the Apache License, Version 2.0 (the "License");
 355 you may not use this file except in compliance with the License.
 356 You may obtain a copy of the License at
 357
 358     http://www.apache.org/licenses/LICENSE-2.0
 359
 360 Unless required by applicable law or agreed to in writing, software
 361 distributed under the License is distributed on an "AS IS" BASIS,
 362 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 363 See the License for the specific language governing permissions and
 364 limitations under the License.
 365 ```
 366
 367 [spirv-registry]: https://www.khronos.org/registry/spir-v/
 368 [spirv-headers]: https://github.com/KhronosGroup/SPIRV-Headers
 369 [googletest]: https://github.com/google/googletest
 370 [googletest-pull-612]: https://github.com/google/googletest/pull/612
 371 [googletest-issue-610]: https://github.com/google/googletest/issues/610
 372 [CMake]: https://cmake.org/
 373 [cpp-style-guide]: https://google.github.io/styleguide/cppguide.html
 374 [clang-sanitizers]: http://clang.llvm.org/docs/UsersManual.html#controlling-code-generation