1# SPIR-V Tools 2 3## Overview 4 5The SPIR-V Tools project provides an API and commands for processing SPIR-V 6modules. 7 8The project includes an assembler, binary module parser, disassembler, 9validator, and optimizer for SPIR-V. Except for the optimizer, all are based 10on a common static library. The library contains all of the implementation 11details, and is used in the standalone tools whilst also enabling integration 12into other code bases directly. The optimizer implementation resides in its 13own library, which depends on the core library. 14 15The interfaces have stabilized: 16We don't anticipate making a breaking change for existing features. 17 18SPIR-V is defined by the Khronos Group Inc. 19See the [SPIR-V Registry][spirv-registry] for the SPIR-V specification, 20headers, and XML registry. 21 22## Downloads 23 24[![Build status](https://ci.appveyor.com/api/projects/status/gpue87cesrx3pi0d/branch/master?svg=true)](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"/>[![Linux Build Status](https://storage.googleapis.com/spirv-tools/badges/build_status_linux_clang_release.svg)](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"/>[![MacOS Build Status](https://storage.googleapis.com/spirv-tools/badges/build_status_macos_clang_release.svg)](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"/>[![Windows Build Status](https://storage.googleapis.com/spirv-tools/badges/build_status_windows_release.svg)](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 33See [`CHANGES`](CHANGES) for a high level summary of recent changes, by version. 34 35SPIRV-Tools project version numbers are of the form `v`*year*`.`*index* and with 36an optional `-dev` suffix to indicate work in progress. For example, the 37following 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 45Use the `--version` option on each command line tool to see the software 46version. 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 64See [`docs/syntax.md`](docs/syntax.md) for the assembly language syntax. 65 66### Validator 67 68The validator checks validation rules described by the SPIR-V specification. 69 70Khronos recommends that tools that create or transform SPIR-V modules use the 71validator to ensure their outputs are valid, and that tools that consume SPIR-V 72modules optionally use the validator to protect themselves from bad inputs. 73This is especially encouraged for debug and development scenarios. 74 75The validator has one-sided error: it will only return an error when it has 76implemented a rule check and the module violates that rule. 77 78The validator is incomplete. 79See the [CHANGES](CHANGES) file for reports on completed work, and 80the [Validator 81sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/1) for planned 82and in-progress work. 83 84*Note*: The validator checks some Universal Limits, from section 2.17 of the SPIR-V spec. 85The validator will fail on a module that exceeds those minimum upper bound limits. 86It is [future work](https://github.com/KhronosGroup/SPIRV-Tools/projects/1#card-1052403) 87to parameterize the validator to allow larger 88limits accepted by a more than minimally capable SPIR-V consumer. 89 90 91### Optimizer 92 93The optimizer is a collection of code transforms, or "passes". 94Transforms 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 102As 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 143Additionally, certain sets of transformations have been packaged into 144higher-level recipes. These include: 145 146* Optimization for size (`spirv-opt -Os`) 147* Optimization for performance (`spirv-opt -O`) 148 149For the latest list with detailed documentation, please refer to 150[`include/spirv-tools/optimizer.hpp`](include/spirv-tools/optimizer.hpp). 151 152For 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 159Current 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 164See the [CHANGES](CHANGES) file for reports on completed work, and the [General 165sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/2) for 166planned and in-progress work. 167 168 169### Reducer 170 171*Note:* The reducer is still under development. 172 173The reducer simplifies and shrinks a SPIR-V module with respect to a 174user-supplied *interestingness function*. For example, given a large 175SPIR-V module that cause some SPIR-V compiler to fail with a given 176fatal error message, the reducer could be used to look for a smaller 177version of the module that causes the compiler to fail with the same 178fatal error message. 179 180To suggest an additional capability for the reducer, [file an 181issue](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 189The fuzzer applies semantics-preserving transformations to a SPIR-V binary 190module, to produce an equivalent module. The original and transformed modules 191should produce essentially identical results when executed on identical inputs: 192their results should differ only due to floating-point round-off, if at all. 193Significant differences in results can pinpoint bugs in tools that process 194SPIR-V binaries, such as miscompilations. This *metamorphic testing* approach 195is similar to the method used by the [GraphicsFuzz 196project](https://github.com/google/graphicsfuzz) for fuzzing of GLSL shaders. 197 198To suggest an additional capability for the fuzzer, [file an 199issue](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 212The SPIR-V Tools project is maintained by members of the The Khronos Group Inc., 213and is hosted at https://github.com/KhronosGroup/SPIRV-Tools. 214 215Consider joining the `public_spirv_tools_dev@khronos.org` mailing list, via 216[https://www.khronos.org/spir/spirv-tools-mailing-list/](https://www.khronos.org/spir/spirv-tools-mailing-list/). 217The mailing list is used to discuss development plans for the SPIRV-Tools as an open source project. 218Once discussion is resolved, 219specific 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 225See [`docs/projects.md`](docs/projects.md) to see how we use the 226[GitHub Project 227feature](https://help.github.com/articles/tracking-the-progress-of-your-work-with-projects/) 228to organize planned and in-progress work. 229 230Contributions 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 244We 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 264Example 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 274The project contains a number of tests, used to drive development 275and ensure correctness. The tests are written using the 276[googletest][googletest] framework. The `googletest` 277source is not provided with this project. There are two ways to enable 278tests: 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]. 287The fix is included on the googletest master branch any time after 2015-11-10. 288In particular, googletest must be newer than version 1.7.0. 289 290### Dependency on Effcee 291 292Some tests depend on the [Effcee][effcee] library for stateful matching. 293Effcee 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 303Instead of building manually, you can also download the binaries for your 304platform directly from the [master-tot release][master-tot-release] on GitHub. 305Those binaries are automatically uploaded by the buildbots after successful 306testing and they always reflect the current top of the tree of the master 307branch. 308 309In order to build the code, you first need to sync the external repositories 310that it depends on. Assume that `<spirv-dir>` is the root directory of the 311checked out code: 312 313```sh 314cd <spirv-dir> 315git clone https://github.com/KhronosGroup/SPIRV-Headers.git external/spirv-headers 316git clone https://github.com/google/effcee.git external/effcee 317git clone https://github.com/google/re2.git external/re2 318git clone https://github.com/google/googletest.git external/googletest # optional 319 320``` 321 322*Note*: 323The script `utils/git-sync-deps` can be used to checkout and/or update the 324contents of the repos under `external/` instead of manually maintaining them. 325 326### Build using CMake 327You can build the project using [CMake][cmake]: 328 329```sh 330cd <spirv-dir> 331mkdir build && cd build 332cmake [-G <platform-generator>] <spirv-dir> 333``` 334 335Once the build files have been generated, build using the appropriate build 336command (e.g. `ninja`, `make`, `msbuild`, etc.; this depends on the platform 337generator used above), or use your IDE, or use CMake to run the appropriate build 338command for you: 339 340```sh 341cmake --build . [--config Debug] # runs `make` or `ninja` or `msbuild` etc. 342``` 343 344#### Note about the fuzzer 345 346The SPIR-V fuzzer, `spirv-fuzz`, can only be built via CMake, and is disabled by 347default. To build it, clone protobuf and use the `SPIRV_BUILD_FUZZER` CMake 348option, like so: 349 350```sh 351# In <spirv-dir> (the SPIRV-Tools repo root): 352git clone --depth=1 --branch v3.13.0 https://github.com/protocolbuffers/protobuf external/protobuf 353 354# In your build directory: 355cmake [-G <platform-generator>] <spirv-dir> -DSPIRV_BUILD_FUZZER=ON 356cmake --build . --config Debug 357``` 358 359You can also add `-DSPIRV_ENABLE_LONG_FUZZER_TESTS=ON` to build additional 360fuzzer tests. 361 362 363### Build using Bazel 364You can also use [Bazel](https://bazel.build/) to build the project. 365```sh 366cd <spirv-dir> 367bazel build :all 368``` 369 370### Tools you'll need 371 372For building and testing SPIRV-Tools, the following tools should be 373installed regardless of your OS: 374 375- [CMake](http://www.cmake.org/): if using CMake for generating compilation 376targets, 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 378suite. 379- [Bazel](https://bazel.build/) (optional): if building the source with Bazel, 380you need to install Bazel Version 0.29.1 on your machine. Other versions may 381also work, but are not verified. 382 383SPIRV-Tools is regularly tested with the following compilers: 384 385On Linux 386- GCC version 4.8.5 387- Clang version 3.8 388 389On MacOS 390- AppleClang 10.0 391 392On Windows 393- Visual Studio 2015 394- Visual Studio 2017 395 396Other compilers or later versions may work, but they are not tested. 397 398### CMake options 399 400The 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 420Additionally, you can pass additional C preprocessor definitions to SPIRV-Tools 421via 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 423iterator debugging. 424 425### Android 426 427SPIR-V Tools supports building static libraries `libSPIRV-Tools.a` and 428`libSPIRV-Tools-opt.a` for Android: 429 430``` 431cd <spirv-dir> 432 433export ANDROID_NDK=/path/to/your/ndk 434 435mkdir build && cd build 436mkdir libs 437mkdir 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 446Occasionally the entries in DEPS will need to be updated. This is done on demand 447when there is a request to do this, often due to downstream breakages. There is 448a script `utils/roll_deps.sh` provided, which will generate a patch with the 449updated DEPS values. This will still need to be tested in your checkout to 450confirm that there are no integration issues that need to be resolved. 451 452## Library 453 454### Usage 455 456The internals of the library use C++11 features, and are exposed via both a C 457and C++ API. 458 459In order to use the library from an application, the include path should point 460to `<spirv-dir>/include`, which will enable the application to include the 461header `<spirv-dir>/include/spirv-tools/libspirv.h{|pp}` then linking against 462the static library in `<spirv-build-dir>/source/libSPIRV-Tools.a` or 463`<spirv-build-dir>/source/SPIRV-Tools.lib`. 464For 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 478The interfaces are still under development, and are expected to change. 479 480There 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 491The 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 499Command line tools, which wrap the above library functions, are provided to 500assemble or disassemble shader files. It's a convention to name SPIR-V 501assembly and binary files with suffix `.spvasm` and `.spv`, respectively. 502 503### Assembler tool 504 505The assembler reads the assembly language text, and emits the binary form. 506 507The 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 509by the `spvTextToBinary` library function. 510 511* `spirv-as` - the standalone assembler 512 * `<spirv-dir>/tools/as` 513 514Use option `-h` to print help. 515 516### Disassembler tool 517 518The disassembler reads the binary form, and emits assembly language text. 519 520The 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 522by the `spvBinaryToText` library function. 523 524* `spirv-dis` - the standalone disassembler 525 * `<spirv-dir>/tools/dis` 526 527Use option `-h` to print help. 528 529The output includes syntax colouring when printing to the standard output stream, 530on Linux, Windows, and OS X. 531 532### Linker tool 533 534The linker combines multiple SPIR-V binary modules together, resulting in a single 535binary module as output. 536 537This is a work in progress. 538The linker does not support OpenCL program linking options related to math 539flags. (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 546The optimizer processes a SPIR-V binary module, applying transformations 547in the specified order. 548 549This 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 558The 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 560by the `spvValidate` library function. 561 562The validator operates on the binary form. 563 564* `spirv-val` - the standalone validator 565 * `<spirv-dir>/tools/val` 566 567### Reducer tool 568 569The reducer shrinks a SPIR-V binary module, guided by a user-supplied 570*interestingness test*. 571 572This 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 577Run `spirv-reduce --help` to see how to specify interestingness. 578 579### Fuzzer tool 580 581The fuzzer transforms a SPIR-V binary module into a semantically-equivalent 582SPIR-V binary module by applying transformations in a randomized fashion. 583 584This is a work in progress, with initially only a few semantics-preserving 585transformations. 586 587* `spirv-fuzz` - the standalone fuzzer 588 * `<spirv-dir>/tools/fuzz` 589 590Run `spirv-fuzz --help` for a detailed list of options. 591 592### Control flow dumper tool 593 594The control flow dumper prints the control flow graph for a SPIR-V module as a 595[GraphViz](http://www.graphviz.org/) graph. 596 597This 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 647Tests are only built when googletest is found. Use `ctest` to run all the 648tests. 649 650## Future Work 651<a name="future"></a> 652 653_See the [projects pages](https://github.com/KhronosGroup/SPIRV-Tools/projects) 654for 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 667This 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> 679Full license terms are in [LICENSE](LICENSE) 680``` 681Copyright (c) 2015-2016 The Khronos Group Inc. 682 683Licensed under the Apache License, Version 2.0 (the "License"); 684you may not use this file except in compliance with the License. 685You may obtain a copy of the License at 686 687 http://www.apache.org/licenses/LICENSE-2.0 688 689Unless required by applicable law or agreed to in writing, software 690distributed under the License is distributed on an "AS IS" BASIS, 691WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 692See the License for the specific language governing permissions and 693limitations 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 710