commit | a4fada390d5b996a7a5c805f6a2c169dcc69a2ac | [log] [tgz] |
---|---|---|
author | David Neto <dneto@google.com> | Tue Oct 22 15:10:18 2019 -0400 |
committer | android-build-prod (mdb) <android-build-team-robot@google.com> | Sat Nov 09 01:10:59 2019 +0000 |
tree | 74fe225e280df50c62390221fdd108b1b85aa621 | |
parent | 3d5e63f5bf6274e7569e9230f8be8371e61df90b [diff] |
Merge remote-tracking branch 'aosp/upstream-master' into update-shaderc Includes: 570582d8 spirv-fuzz: fuzzer pass to adjust memory access operands (#2968) 02910ffd Instrument: Add missing def-use analysis. (#2985) 8357b878 spirv-fuzz: add missing functionality for matrix composites (#2974) 615918c9 Update CHANGES e8c3f9b0 Ensure timestamp does not vary with timezone. (#2982) 6a9be627 Keep NOPs when comparing with original binary (#2931) 2a3cbe7c Check that derivatives operate on 32-bit values (#2983) 3cdd6444 Check text->str before destroying (#2981) e3da3143 Disallow use of OpCompositeExtract/OpCompositeInsert with no indices (#2980) 2ca4fcfd Add fuzzer for spirv-dis call path (#2977) 024417d8 Check binary->code existence before destroying (#2979) 9c0ae6bb Improved CMake install step. (#2963) e99b9182 Support constant-folding UConvert and SConvert (#2960) 8e897785 Add fuzzer for spirv-as call path (#2976) 00170cc5 spirv-fuzz: Refactor 'copy object' and 'construct composite' transformations (#2966) 964dc52d Update SPIR-V binary header test for SPIR-V 1.5 (#2967) 1b6fd37f spirv-fuzz: Refactor 'split blocks' to identify instructions differently (#2961) 2276e597 Validate that selections are structured (#2962) 3eda1b9f spirv-fuzz: Rework id descriptors (#2959) eba98c4e spirv-fuzz: Add fuzzer pass to add NoContraction decorations (#2950) 91232f7f spirv-fuzz: Add fuzzer pass to change function controls (#2951) feb15492 reduce: add large tests and fix (#2947) 253806ad spirv-fuzz: Add fuzzer pass to change loop controls (#2949) 1cea3b78 Fixed include paths and order according to Google style. (#2957) 82f84c4b Use a longer timeout for Bazel tests. (#2956) c705032b Remove non-existent files from BUILD.gn (#2955) c1d42038 Disable scope validation for OpReadClockKHR (#2953) df15a4a3 CMake: Add support for building with emscripten (#2948) c3ca0474 Update CHANGES 32f76efa Link cfg and dominator analysis in the context (#2946) 5910bb8e spirv-fuzz: add transformation and pass to construct composites (#2941) 2f6a87f6 reduce: improve remove unref instr pass (#2945) 81d227f3 spirv-fuzz: add disabled test to document known issue (#2942) 26dba32c spirv-fuzz: Add fuzzer pass to change selection controls (#2944) 3c7ff8d4 Enable OpTypeCooperativeMatrix specialization (#2927) c18c9ff6 Handle OpKill better (#2933) ad3d23f4 Generate null pointer by converting uint64 zero to pointer. (#2935) 8fa0f1a6 spirv-fuzz: option to convert shader into a form that renders red (#2934) bc37fd58 Add SPV_KHR_shader_clock validation (#2879) bd839ca6 reduce/fuzz: improve command line args (#2932) 9d7428b0 Validate physical storage buffer restrictions (#2930) 44b32176 fuzz: add shrinker-temp-file-prefix (#2928) 9eb1c9a4 Add continue construct analysis to struct cfg analysis (#2922) 85c67b5e Record trailing line dbg instructions (#2926) 4075b921 Add removing references to debug instructions when removing them (#2923) ef4679a5 spirv-fuzz: allow interestingness script arguments (#2925) bc84daff Add Kokoro bots for building with Bazel. (#2914) 10951a7c Refactor the InstructionPass (#2924) 84b19760 spirv-fuzz: do not allow a dead break to target an unreachable block (#2917) 27238bcc spirv-fuzz: preserve some analyses when permuting blocks (#2918) 510ca9d6 Only allow previously declared forward refs in structs (#2920) 2a11f365 Handle id overflow in wrap-opkill (#2916) 70097c77 spirv-fuzz: do not replace struct indices with synonyms (#2915) c1e03834 spirv-fuzz: Fixes to preconditions for adding dead break/continue edges (#2904) 7bc114ba spirv-fuzz: do not replace a pointer argument to a function call with a synonym (#2901) 290f6a82 spirv-fuzz: do not replace boolean constant argument to OpPhi instruction (#2903) 527a6893 Remove validate_datarules.cpp (#2911) 55ea57a7 Handle extract with no indexes (#2910) a03cd1f3 Add Bazel build configuration. (#2891) 6f26d9ad Handle id overflow in convert local access chains (#2908) 71e0ba60 Add OpCopyMemory test to SVA. (#2885) 3a762d54 Add missing GN dependency (#2899) 958f7e72 Employ the "swarm testing" idea in spirv-fuzz (#2890) b83535da Fix operand index in spirv-fuzz (#2895) f62ee4a4 Update DEPS: effcee, re2, googletest (#2881) 8d0ca43d Add method comment for opt::Function::WhileEachInst (#2867) 6b072126 Use OpReturn* in wrap-opkill (#2886) 46531272 Fix to CMakeLists for spirv-fuzz tests (#2888) 7275a716 Allow validation during spirv-fuzz replay (#2873) 4eee71e7 Disable long-running fuzzer tests by default (#2887) 61edde52 Revert "Use OpReturn* in wrap-opkill" 87f0fa43 Use OpReturn* in wrap-opkill 08fcf8a4 Fix header include syntax. (#2882) 248c80b0 Handle OpConstantNull in copy-prop-arrays. (#2870) d06fe084 Fix comment typo found by protobufs linter (#2884) 47e354b0 Move docs into docs/ folder (#2872) 605c2e3c Add WebGPU SPIR-V Assembler in JavaScript. (#2876) Change-Id: Ibcc08f2824777a750259c8fc267709bf50cf5e48 Testing: checkbuild.py on Linux; unit tests on Windows (cherry picked from commit 9f200ea27e618e0921f331dfe59844cea5281a6d)
The SPIR-V Tools project provides an API and commands for processing SPIR-V modules.
The project includes an assembler, binary module parser, disassembler, validator, and optimizer for SPIR-V. Except for the optimizer, all are based on a common static library. The library contains all of the implementation details, and is used in the standalone tools whilst also enabling integration into other code bases directly. The optimizer implementation resides in its own library, which depends on the core library.
The interfaces have stabilized: We don't anticipate making a breaking change for existing features.
SPIR-V is defined by the Khronos Group Inc. See the SPIR-V Registry for the SPIR-V specification, headers, and XML registry.
See CHANGES
for a high level summary of recent changes, by version.
SPIRV-Tools project version numbers are of the form v
year.
index and with an optional -dev
suffix to indicate work in progress. For exampe, the following versions are ordered from oldest to newest:
v2016.0
v2016.1-dev
v2016.1
v2016.2-dev
v2016.2
Use the --version
option on each command line tool to see the software version. An API call reports the software version as a C-style string.
OpConstant
, OpSpecConstant
, and OpSwitch
.See docs/syntax.md
for the assembly language syntax.
The validator checks validation rules described by the SPIR-V specification.
Khronos recommends that tools that create or transform SPIR-V modules use the validator to ensure their outputs are valid, and that tools that consume SPIR-V modules optionally use the validator to protect themselves from bad inputs. This is especially encouraged for debug and development scenarios.
The validator has one-sided error: it will only return an error when it has implemented a rule check and the module violates that rule.
The validator is incomplete. See the CHANGES file for reports on completed work, and the Validator sub-project for planned and in-progress work.
Note: The validator checks some Universal Limits, from section 2.17 of the SPIR-V spec. The validator will fail on a module that exceeds those minimum upper bound limits. It is future work to parameterize the validator to allow larger limits accepted by a more than minimally capable SPIR-V consumer.
Note: The optimizer is still under development.
Currently supported optimizations:
OpSpecConstantOp
and OpSpecConstantComposite
For the latest list with detailed documentation, please refer to include/spirv-tools/optimizer.hpp
.
For suggestions on using the code reduction options, please refer to this white paper.
Note: The linker is still under development.
Current features:
See the CHANGES file for reports on completed work, and the General sub-project for planned and in-progress work.
Note: The reducer is still under development.
The reducer simplifies and shrinks a SPIR-V module with respect to a user-supplied interestingness function. For example, given a large SPIR-V module that cause some SPIR-V compiler to fail with a given fatal error message, the reducer could be used to look for a smaller version of the module that causes the compiler to fail with the same fatal error message.
To suggest an additional capability for the reducer, file an issue with “Reducer:” as the start of its title.
spirv-tools-vimsyntax
generates file spvasm.vim
. Copy that file into your $HOME/.vim/syntax
directory to get SPIR-V assembly syntax highlighting in Vim. This build target is not built by default.The SPIR-V Tools project is maintained by members of the The Khronos Group Inc., and is hosted at https://github.com/KhronosGroup/SPIRV-Tools.
Consider joining the public_spirv_tools_dev@khronos.org
mailing list, via https://www.khronos.org/spir/spirv-tools-mailing-list/. The mailing list is used to discuss development plans for the SPIRV-Tools as an open source project. Once discussion is resolved, specific work is tracked via issues and sometimes in one of the projects.
(To provide feedback on the SPIR-V specification, file an issue on the SPIRV-Headers GitHub repository.)
See docs/projects.md
to see how we use the GitHub Project feature to organize planned and in-progress work.
Contributions via merge request are welcome. Changes should:
clang-format
. kokoro/check-format/build.sh shows how to download it. Note that we currently use clang-format version 5.0.0
for SPIRV-Tools. Settings are defined by the included .clang-format file.We intend to maintain a linear history on the GitHub master
branch.
example
: demo code of using SPIRV-Tools APIsexternal/googletest
: Intended location for the googletest sources, not providedexternal/effcee
: Location of Effcee sources, if the effcee
library is not already configured by an enclosing project.external/re2
: Location of RE2 sources, if the re2
library is not already configured by an enclosing project. (The Effcee project already requires RE2.)include/
: API clients should add this directory to the include search pathexternal/spirv-headers
: Intended location for SPIR-V headers, not providedinclude/spirv-tools/libspirv.h
: C API public interfacesource/
: API implementationtest/
: Tests, using the googletest frameworktools/
: Command line executablesExample of getting sources, assuming SPIRV-Tools is configured as a standalone project:
git clone https://github.com/KhronosGroup/SPIRV-Tools.git spirv-tools git clone https://github.com/KhronosGroup/SPIRV-Headers.git spirv-tools/external/spirv-headers git clone https://github.com/google/googletest.git spirv-tools/external/googletest git clone https://github.com/google/effcee.git spirv-tools/external/effcee git clone https://github.com/google/re2.git spirv-tools/external/re2
The project contains a number of tests, used to drive development and ensure correctness. The tests are written using the googletest framework. The googletest
source is not provided with this project. There are two ways to enable tests:
googletest
before configuring SPIR-V Tools.googletest
source into the <spirv-dir>/external/googletest
directory before configuring and building the project.Note: You must use a version of googletest that includes a fix for googletest issue 610. The fix is included on the googletest master branch any time after 2015-11-10. In particular, googletest must be newer than version 1.7.0.
Some tests depend on the Effcee library for stateful matching. Effcee itself depends on RE2.
external/effcee
and RE2 sources to appear in external/re2
.Instead of building manually, you can also download the binaries for your platform directly from the master-tot release on GitHub. Those binaries are automatically uploaded by the buildbots after successful testing and they always reflect the current top of the tree of the master branch.
In order to build the code, you first need to sync the external repositories that it depends on. Assume that <spirv-dir>
is the root directory of the checked out code:
cd <spirv-dir> git clone https://github.com/KhronosGroup/SPIRV-Headers.git external/spirv-headers git clone https://github.com/google/effcee.git external/effcee git clone https://github.com/google/re2.git external/re2 git clone https://github.com/google/googletest.git external/googletest # optional
Note: The script utils/git-sync-deps
can be used to checkout and/or update the contents of the repos under external/
instead of manually maintaining them.
You can build The project using CMake to generate platform-specific build configurations.
cd <spirv-dir> mkdir build && cd build cmake [-G <platform-generator>] <spirv-dir>
Once the build files have been generated, build using your preferred development environment.
You can also use Bazel to build the project.
cd <spirv-dir> bazel build :all
For building and testing SPIRV-Tools, the following tools should be installed regardless of your OS:
SPIRV-Tools is regularly tested with the the following compilers:
On Linux
On MacOS
On Windows
Other compilers or later versions may work, but they are not tested.
The following CMake options are supported:
SPIRV_COLOR_TERMINAL={ON|OFF}
, default ON
- Enables color console output.SPIRV_SKIP_TESTS={ON|OFF}
, default OFF
- Build only the library and the command line tools. This will prevent the tests from being built.SPIRV_SKIP_EXECUTABLES={ON|OFF}
, default OFF
- Build only the library, not the command line tools and tests.SPIRV_USE_SANITIZER=<sanitizer>
, default is no sanitizing - On UNIX platforms with an appropriate version of clang
this option enables the use of the sanitizers documented here. This should only be used with a debug build.SPIRV_WARN_EVERYTHING={ON|OFF}
, default OFF
- On UNIX platforms enable more strict warnings. The code might not compile with this option enabled. For Clang, enables -Weverything
. For GCC, enables -Wpedantic
. See CMakeLists.txt
for details.SPIRV_WERROR={ON|OFF}
, default ON
- Forces a compilation error on any warnings encountered by enabling the compiler-specific compiler front-end option. No compiler front-end options are enabled when this option is OFF.Additionally, you can pass additional C preprocessor definitions to SPIRV-Tools via setting SPIRV_TOOLS_EXTRA_DEFINITIONS
. For example, by setting it to /D_ITERATOR_DEBUG_LEVEL=0
on Windows, you can disable checked iterators and iterator debugging.
SPIR-V Tools supports building static libraries libSPIRV-Tools.a
and libSPIRV-Tools-opt.a
for Android:
cd <spirv-dir> export ANDROID_NDK=/path/to/your/ndk mkdir build && cd build mkdir libs mkdir app $ANDROID_NDK/ndk-build -C ../android_test \ NDK_PROJECT_PATH=. \ NDK_LIBS_OUT=`pwd`/libs \ NDK_APP_OUT=`pwd`/app
Occasionally the entries in DEPS will need to be updated. This is done on demand when there is a request to do this, often due to downstream breakages. There is a script utils/roll_deps.sh
provided, which will generate a patch with the updated DEPS values. This will still need to be tested in your checkout to confirm that there are no integration issues that need to be resolved.
The internals of the library use C++11 features, and are exposed via both a C and C++ API.
In order to use the library from an application, the include path should point to <spirv-dir>/include
, which will enable the application to include the header <spirv-dir>/include/spirv-tools/libspirv.h{|pp}
then linking against the static library in <spirv-build-dir>/source/libSPIRV-Tools.a
or <spirv-build-dir>/source/SPIRV-Tools.lib
. For optimization, the header file is <spirv-dir>/include/spirv-tools/optimizer.hpp
, and the static library is <spirv-build-dir>/source/libSPIRV-Tools-opt.a
or <spirv-build-dir>/source/SPIRV-Tools-opt.lib
.
SPIRV-Tools
CMake target: Creates the static library:<spirv-build-dir>/source/libSPIRV-Tools.a
on Linux and OS X.<spirv-build-dir>/source/libSPIRV-Tools.lib
on Windows.SPIRV-Tools-opt
CMake target: Creates the static library:<spirv-build-dir>/source/libSPIRV-Tools-opt.a
on Linux and OS X.<spirv-build-dir>/source/libSPIRV-Tools-opt.lib
on Windows.The interfaces are still under development, and are expected to change.
There are five main entry points into the library in the C interface:
spvTextToBinary
: An assembler, translating text to a binary SPIR-V module.spvBinaryToText
: A disassembler, translating a binary SPIR-V module to text.spvBinaryParse
: The entry point to a binary parser API. It issues callbacks for the header and each parsed instruction. The disassembler is implemented as a client of spvBinaryParse
.spvValidate
implements the validator functionality. IncompletespvValidateBinary
implements the validator functionality. IncompleteThe C++ interface is comprised of three classes, SpirvTools
, Optimizer
and Linker
, all in the spvtools
namespace.
SpirvTools
provides Assemble
, Disassemble
, and Validate
methods.Optimizer
provides methods for registering and running optimization passes.Linker
provides methods for combining together multiple binaries.Command line tools, which wrap the above library functions, are provided to assemble or disassemble shader files. It's a convention to name SPIR-V assembly and binary files with suffix .spvasm
and .spv
, respectively.
The assembler reads the assembly language text, and emits the binary form.
The standalone assembler is the exectuable called spirv-as
, and is located in <spirv-build-dir>/tools/spirv-as
. The functionality of the assembler is implemented by the spvTextToBinary
library function.
spirv-as
- the standalone assembler<spirv-dir>/tools/as
Use option -h
to print help.
The disassembler reads the binary form, and emits assembly language text.
The standalone disassembler is the executable called spirv-dis
, and is located in <spirv-build-dir>/tools/spirv-dis
. The functionality of the disassembler is implemented by the spvBinaryToText
library function.
spirv-dis
- the standalone disassembler<spirv-dir>/tools/dis
Use option -h
to print help.
The output includes syntax colouring when printing to the standard output stream, on Linux, Windows, and OS X.
The linker combines multiple SPIR-V binary modules together, resulting in a single binary module as output.
This is a work in progress. The linker does not support OpenCL program linking options related to math flags. (See section 5.6.5.2 in OpenCL 1.2)
spirv-link
- the standalone linker<spirv-dir>/tools/link
The optimizer processes a SPIR-V binary module, applying transformations in the specified order.
This is a work in progress, with initially only few available transformations.
spirv-opt
- the standalone optimizer<spirv-dir>/tools/opt
Warning: This functionality is under development, and is incomplete.
The standalone validator is the executable called spirv-val
, and is located in <spirv-build-dir>/tools/spirv-val
. The functionality of the validator is implemented by the spvValidate
library function.
The validator operates on the binary form.
spirv-val
- the standalone validator<spirv-dir>/tools/val
The reducer shrinks a SPIR-V binary module, guided by a user-supplied interestingness test.
This is a work in progress, with initially only shrinks a module in a few ways.
spirv-reduce
- the standalone reducer<spirv-dir>/tools/reduce
Run spirv-reduce --help
to see how to specify interestingness.
The control flow dumper prints the control flow graph for a SPIR-V module as a GraphViz graph.
This is experimental.
spirv-cfg
- the control flow graph dumper<spirv-dir>/tools/cfg
spirv-lesspipe.sh
- Automatically disassembles .spv
binary files for the less
program, on compatible systems. For example, set the LESSOPEN
environment variable as follows, assuming both spirv-lesspipe.sh
and spirv-dis
are on your executable search path:
export LESSOPEN='| spirv-lesspipe.sh "%s"'
Then you page through a disassembled module as follows:
less foo.spv
spirv-lesspipe.sh
script will pass through any extra arguments to spirv-dis
. So, for example, you can turn off colours and friendly ID naming as follows:export LESSOPEN='| spirv-lesspipe.sh "%s" --no-color --raw-id'
vim-spirv - A vim plugin which supports automatic disassembly of .spv
files using the :edit
command and assembly using the :write
command. The plugin also provides additional features which include; syntax highlighting; highlighting of all ID's matching the ID under the cursor; and highlighting errors where the Instruction
operand of OpExtInst
is used without an appropriate OpExtInstImport
.
50spirv-tools.el
- Automatically disassembles ‘.spv’ binary files when loaded into the emacs text editor, and re-assembles them when saved, provided any modifications to the file are valid. This functionality must be explicitly requested by defining the symbol SPIRV_TOOLS_INSTALL_EMACS_HELPERS as follows:
cmake -DSPIRV_TOOLS_INSTALL_EMACS_HELPERS=true ...
In addition, this helper is only installed if the directory /etc/emacs/site-start.d exists, which is typically true if emacs is installed on the system.
Note that symbol IDs are not currently preserved through a load/edit/save operation. This may change if the ability is added to spirv-as.
Tests are only built when googletest is found. Use ctest
to run all the tests.
See the projects pages for more information.
OpLabel
instructions with that basic block's predecessors.This is a work in progress.
Full license terms are in LICENSE
Copyright (c) 2015-2016 The Khronos Group Inc. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.