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)
8 The SPIR-V Tools project provides an API and commands for processing SPIR-V
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.
18 The interfaces have stabilized:
19 We don't anticipate making a breaking change for existing features.
21 See [`projects.md`](projects.md) to see how we use the
23 feature](https://help.github.com/articles/tracking-the-progress-of-your-work-with-projects/)
24 to organize planned and in-progress work.
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.
30 ## Verisoning SPIRV-Tools
32 See [`CHANGES`](CHANGES) for a high level summary of recent changes, by version.
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:
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.
49 ### Assembler, binary parser, and disassembler
51 * Support for SPIR-V 1.0, 1.1, 1.2
52 * Based on SPIR-V syntax described by JSON grammar files in the
53 [SPIRV-Headers](spirv-headers) repository.
54 * Support for extended instruction sets:
55 * GLSL std450 version 1.0 Rev 3
56 * OpenCL version 1.0 Rev 2
57 * Assembler only does basic syntax checking. No cross validation of
58 IDs or types is performed, except to check literal arguments to
59 `OpConstant`, `OpSpecConstant`, and `OpSwitch`.
61 See [`syntax.md`](syntax.md) for the assembly language syntax.
65 The validator checks validation rules described by the SPIR-V specification.
67 Khronos recommends that tools that create or transform SPIR-V modules use the
68 validator to ensure their outputs are valid, and that tools that consume SPIR-V
69 modules optionally use the validator to protect themselves from bad inputs.
70 This is especially encouraged for debug and development scenarios.
72 The validator has one-sided error: it will only return an error when it has
73 implemented a rule check and the module violates that rule.
75 The validator is incomplete.
76 See the [CHANGES](CHANGES) file for reports on completed work, and
78 sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/1) for planned
81 *Note*: The validator checks some Universal Limits, from section 2.17 of the SPIR-V spec.
82 The validator will fail on a module that exceeds those minimum upper bound limits.
83 It is [future work](https://github.com/KhronosGroup/SPIRV-Tools/projects/1#card-1052403)
84 to parameterize the validator to allow larger
85 limits accepted by a more than minimally capable SPIR-V consumer.
90 *Note:* The optimizer is still under development.
92 Currently supported optimizations:
95 * Specialization Constants
96 * Set spec constant default value
97 * Freeze spec constant
98 * Fold `OpSpecConstantOp` and `OpSpecConstantComposite`
100 * Eliminate dead constant
102 * Inline all function calls exhaustively
103 * Convert local access chains to inserts/extracts
104 * Eliminate local load/store in single block
105 * Eliminate local load/store with single store
106 * Eliminate local load/store with multiple stores
107 * Eliminate local extract from insert
108 * Eliminate dead instructions (aggressive)
109 * Eliminate dead branches
110 * Merge single successor / single predecessor block pairs
111 * Eliminate common uniform loads
113 For the latest list with detailed documentation, please refer to
114 [`include/spirv-tools/optimizer.hpp`](include/spirv-tools/optimizer.hpp).
116 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/).
120 * [Utility filters](#utility-filters)
121 * Build target `spirv-tools-vimsyntax` generates file `spvasm.vim`.
122 Copy that file into your `$HOME/.vim/syntax` directory to get SPIR-V assembly syntax
123 highlighting in Vim. This build target is not built by default.
127 The SPIR-V Tools are maintained by members of the The Khronos Group Inc.,
128 at https://github.com/KhronosGroup/SPIRV-Tools.
130 Contributions via merge request are welcome. Changes should:
131 * Be provided under the [Apache 2.0](#license).
132 You'll be prompted with a one-time "click-through" Contributor's License
133 Agreement (CLA) dialog as part of submitting your pull request or
134 other contribution to GitHub.
135 * Include tests to cover updated functionality.
136 * C++ code should follow the [Google C++ Style Guide][cpp-style-guide].
137 * Code should be formatted with `clang-format`. Settings are defined by
138 the included [.clang-format](.clang-format) file.
140 We intend to maintain a linear history on the GitHub `master` branch.
142 ### Source code organization
144 * `example`: demo code of using SPIRV-Tools APIs
145 * `external/googletest`: Intended location for the
146 [googletest][googletest] sources, not provided
147 * `include/`: API clients should add this directory to the include search path
148 * `external/spirv-headers`: Intended location for
149 [SPIR-V headers][spirv-headers], not provided
150 * `include/spirv-tools/libspirv.h`: C API public interface
151 * `source/`: API implementation
152 * `test/`: Tests, using the [googletest][googletest] framework
153 * `tools/`: Command line executables
157 The project contains a number of tests, used to drive development
158 and ensure correctness. The tests are written using the
159 [googletest][googletest] framework. The `googletest`
160 source is not provided with this project. There are two ways to enable
162 * If SPIR-V Tools is configured as part of an enclosing project, then the
163 enclosing project should configure `googletest` before configuring SPIR-V Tools.
164 * If SPIR-V Tools is configured as a standalone project, then download the
165 `googletest` source into the `<spirv-dir>/external/googletest` directory before
166 configuring and building the project.
168 *Note*: You must use a version of googletest that includes
169 [a fix][googletest-pull-612] for [googletest issue 610][googletest-issue-610].
170 The fix is included on the googletest master branch any time after 2015-11-10.
171 In particular, googletest must be newer than version 1.7.0.
175 The project uses [CMake][cmake] to generate platform-specific build
176 configurations. Assume that `<spirv-dir>` is the root directory of the checked
181 git clone https://github.com/KhronosGroup/SPIRV-Headers.git external/spirv-headers
182 git clone https://github.com/google/googletest.git external/googletest # optional
184 mkdir build && cd build
185 cmake [-G <platform-generator>] <spirv-dir>
188 Once the build files have been generated, build using your preferred
189 development environment.
193 The following CMake options are supported:
195 * `SPIRV_COLOR_TERMINAL={ON|OFF}`, default `ON` - Enables color console output.
196 * `SPIRV_SKIP_TESTS={ON|OFF}`, default `OFF`- Build only the library and
197 the command line tools. This will prevent the tests from being built.
198 * `SPIRV_SKIP_EXECUTABLES={ON|OFF}`, default `OFF`- Build only the library, not
199 the command line tools and tests.
200 * `SPIRV_BUILD_COMPRESSION={ON|OFF}`, default `OFF`- Build SPIR-V compressing
202 * `SPIRV_USE_SANITIZER=<sanitizer>`, default is no sanitizing - On UNIX
203 platforms with an appropriate version of `clang` this option enables the use
204 of the sanitizers documented [here][clang-sanitizers].
205 This should only be used with a debug build.
206 * `SPIRV_WARN_EVERYTHING={ON|OFF}`, default `OFF` - On UNIX platforms enable
207 more strict warnings. The code might not compile with this option enabled.
208 For Clang, enables `-Weverything`. For GCC, enables `-Wpedantic`.
209 See [`CMakeLists.txt`](CMakeLists.txt) for details.
210 * `SPIRV_WERROR={ON|OFF}`, default `ON` - Forces a compilation error on any
211 warnings encountered by enabling the compiler-specific compiler front-end
214 Additionally, you can pass additional C preprocessor definitions to SPIRV-Tools
215 via setting `SPIRV_TOOLS_EXTRA_DEFINITIONS`. For example, by setting it to
216 `/D_ITERATOR_DEBUG_LEVEL=0` on Windows, you can disable checked iterators and
223 The internals of the library use C++11 features, and are exposed via both a C
226 In order to use the library from an application, the include path should point
227 to `<spirv-dir>/include`, which will enable the application to include the
228 header `<spirv-dir>/include/spirv-tools/libspirv.h{|pp}` then linking against
229 the static library in `<spirv-build-dir>/source/libSPIRV-Tools.a` or
230 `<spirv-build-dir>/source/SPIRV-Tools.lib`.
231 For optimization, the header file is
232 `<spirv-dir>/include/spirv-tools/optimizer.hpp`, and the static library is
233 `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` or
234 `<spirv-build-dir>/source/SPIRV-Tools-opt.lib`.
236 * `SPIRV-Tools` CMake target: Creates the static library:
237 * `<spirv-build-dir>/source/libSPIRV-Tools.a` on Linux and OS X.
238 * `<spirv-build-dir>/source/libSPIRV-Tools.lib` on Windows.
239 * `SPIRV-Tools-opt` CMake target: Creates the static library:
240 * `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` on Linux and OS X.
241 * `<spirv-build-dir>/source/libSPIRV-Tools-opt.lib` on Windows.
245 The interfaces are still under development, and are expected to change.
247 There are five main entry points into the library in the C interface:
249 * `spvTextToBinary`: An assembler, translating text to a binary SPIR-V module.
250 * `spvBinaryToText`: A disassembler, translating a binary SPIR-V module to
252 * `spvBinaryParse`: The entry point to a binary parser API. It issues callbacks
253 for the header and each parsed instruction. The disassembler is implemented
254 as a client of `spvBinaryParse`.
255 * `spvValidate` implements the validator functionality. *Incomplete*
256 * `spvValidateBinary` implements the validator functionality. *Incomplete*
258 The C++ interface is comprised of two classes, `SpirvTools` and `Optimizer`,
259 both in the `spvtools` namespace.
260 * `SpirvTools` provides `Assemble`, `Disassemble`, and `Validate` methods.
261 * `Optimizer` provides methods for registering and running optimization passes.
263 ## Command line tools
265 Command line tools, which wrap the above library functions, are provided to
266 assemble or disassemble shader files. It's a convention to name SPIR-V
267 assembly and binary files with suffix `.spvasm` and `.spv`, respectively.
271 The assembler reads the assembly language text, and emits the binary form.
273 The standalone assembler is the exectuable called `spirv-as`, and is located in
274 `<spirv-build-dir>/tools/spirv-as`. The functionality of the assembler is implemented
275 by the `spvTextToBinary` library function.
277 * `spirv-as` - the standalone assembler
278 * `<spirv-dir>/tools/as`
280 Use option `-h` to print help.
282 ### Disassembler tool
284 The disassembler reads the binary form, and emits assembly language text.
286 The standalone disassembler is the executable called `spirv-dis`, and is located in
287 `<spirv-build-dir>/tools/spirv-dis`. The functionality of the disassembler is implemented
288 by the `spvBinaryToText` library function.
290 * `spirv-dis` - the standalone disassembler
291 * `<spirv-dir>/tools/dis`
293 Use option `-h` to print help.
295 The output includes syntax colouring when printing to the standard output stream,
296 on Linux, Windows, and OS X.
300 The optimizer processes a SPIR-V binary module, applying transformations
301 in the specified order.
303 This is a work in progress, with initially only few available transformations.
305 * `spirv-opt` - the standalone optimizer
306 * `<spirv-dir>/tools/opt`
310 *Warning:* This functionality is under development, and is incomplete.
312 The standalone validator is the executable called `spirv-val`, and is located in
313 `<spirv-build-dir>/tools/spirv-val`. The functionality of the validator is implemented
314 by the `spvValidate` library function.
316 The validator operates on the binary form.
318 * `spirv-val` - the standalone validator
319 * `<spirv-dir>/tools/val`
321 ### Control flow dumper tool
323 The control flow dumper prints the control flow graph for a SPIR-V module as a
324 [GraphViz](http://www.graphviz.org/) graph.
326 This is experimental.
328 * `spirv-cfg` - the control flow graph dumper
329 * `<spirv-dir>/tools/cfg`
333 * `spirv-lesspipe.sh` - Automatically disassembles `.spv` binary files for the
334 `less` program, on compatible systems. For example, set the `LESSOPEN`
335 environment variable as follows, assuming both `spirv-lesspipe.sh` and
336 `spirv-dis` are on your executable search path:
338 export LESSOPEN='| spirv-lesspipe.sh "%s"'
340 Then you page through a disassembled module as follows:
344 * The `spirv-lesspipe.sh` script will pass through any extra arguments to
345 `spirv-dis`. So, for example, you can turn off colours and friendly ID
348 export LESSOPEN='| spirv-lesspipe.sh "%s" --no-color --raw-id'
351 * [vim-spirv](https://github.com/kbenzie/vim-spirv) - A vim plugin which
352 supports automatic disassembly of `.spv` files using the `:edit` command and
353 assembly using the `:write` command. The plugin also provides additional
354 features which include; syntax highlighting; highlighting of all ID's matching
355 the ID under the cursor; and highlighting errors where the `Instruction`
356 operand of `OpExtInst` is used without an appropriate `OpExtInstImport`.
358 * `50spirv-tools.el` - Automatically disassembles '.spv' binary files when
359 loaded into the emacs text editor, and re-assembles them when saved,
360 provided any modifications to the file are valid. This functionality
361 must be explicitly requested by defining the symbol
362 SPIRV_TOOLS_INSTALL_EMACS_HELPERS as follows:
364 cmake -DSPIRV_TOOLS_INSTALL_EMACS_HELPERS=true ...
367 In addition, this helper is only installed if the directory /etc/emacs/site-start.d
368 exists, which is typically true if emacs is installed on the system.
370 Note that symbol IDs are not currently preserved through a load/edit/save operation.
371 This may change if the ability is added to spirv-as.
376 Tests are only built when googletest is found. Use `ctest` to run all the
380 <a name="future"></a>
382 _See the [projects pages](https://github.com/KhronosGroup/SPIRV-Tools/projects)
383 for more information._
385 ### Assembler and disassembler
387 * The disassembler could emit helpful annotations in comments. For example:
388 * Use variable name information from debug instructions to annotate
389 key operations on variables.
390 * Show control flow information by annotating `OpLabel` instructions with
391 that basic block's predecessors.
392 * Error messages could be improved.
396 This is a work in progress.
399 <a name="license"></a>
400 Full license terms are in [LICENSE](LICENSE)
402 Copyright (c) 2015-2016 The Khronos Group Inc.
404 Licensed under the Apache License, Version 2.0 (the "License");
405 you may not use this file except in compliance with the License.
406 You may obtain a copy of the License at
408 http://www.apache.org/licenses/LICENSE-2.0
410 Unless required by applicable law or agreed to in writing, software
411 distributed under the License is distributed on an "AS IS" BASIS,
412 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
413 See the License for the specific language governing permissions and
414 limitations under the License.
417 [spirv-registry]: https://www.khronos.org/registry/spir-v/
418 [spirv-headers]: https://github.com/KhronosGroup/SPIRV-Headers
419 [googletest]: https://github.com/google/googletest
420 [googletest-pull-612]: https://github.com/google/googletest/pull/612
421 [googletest-issue-610]: https://github.com/google/googletest/issues/610
422 [CMake]: https://cmake.org/
423 [cpp-style-guide]: https://google.github.io/styleguide/cppguide.html
424 [clang-sanitizers]: http://clang.llvm.org/docs/UsersManual.html#controlling-code-generation