Debian Codegraph @

third_party/spirv-tools/README.md

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