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