| commit | 3eb4dd81ca67cedb95fc9830cb4b640caa5f17f8 | [log] [tgz] |
|---|---|---|
| author | Alexis Hetu <sugoi@google.com> | Thu Oct 29 21:37:20 2020 -0400 |
| committer | Alexis Hetu <sugoi@google.com> | Thu Oct 29 21:37:20 2020 -0400 |
| tree | 623db3610194dd594937b367b1875cdddfb25a39 | |
| parent | c00ee6cc1da6df21150c4bbfb866fd6d8458e2b3 [diff] |
Squashed 'third_party/SPIRV-Tools/' changes from 8a5500656..82b378d67 82b378d67 spirv-opt: Add support to prevent functions from being inlined if they have DontInline flag (#3858) 56d0f5035 Propagate OpLine to all applied instructions in spirv-opt (#3951) 7403dfafd CMake: Add SPIRV_TOOLS_BUILD_STATIC flag (#3910) 25ee27576 Avoid copying a ref in a loop (#4000) 5edb328e8 spirv-val: Allow the ViewportIndex and Layer built-ins on SPIR-V 1.5 (#3986) cbd1fa6c4 Simplify logic to decide whether CCP modified the IR (#3997) df4198e50 Add DebugValue for DebugDecl invisible to value assignment (#3973) 34ae8a475 Fix bounds check instrumentation to handle 16-bit values (#3983) abe2eff36 spirv-fuzz: Add expand vector reduction transformation (#3869) 99ad4f1e2 spirv-fuzz: Don't replace irrelevant indices in OpAccessChain (#3988) 895dafcc1 spirv-fuzz: Add FuzzerPassAddCompositeExtract (#3904) 69f07da41 spirv-fuzz: Fix mismatch with shrinker step limit (#3985) 9223493f4 spirv-fuzz: Fix off-by-one error in replayer (#3982) 4f5423187 spirv-fuzz: Get order right for OpSelect arguments (#3974) 88f7bcb6a spirv-fuzz: Do not add synonym-creating loops in dead blocks (#3975) 64eaa9832 spirv-fuzz: Skip OpTypeSampledImage when propagating up (#3976) 53f2a69c1 spirv-fuzz: Pass OpUndef in function call if needed (#3978) de2c0ba20 spirv-fuzz: Fix off-by-one in TransformationCompositeConstruct (#3979) dc4a18228 spirv-fuzz: Tolerate absent ids in data synonym fact management (#3966) 8496780f5 spirv-fuzz: Fix to id availability (#3971) 3b7aebca4 spirv-fuzz: Fix operand types (#3962) 6fe34cdf1 Update SPIRV-Headers revision in DEPS file (#3961) a8d7062fe spirv-fuzz: Don't flatten conditional if condition is irrelevant (#3944) a3d5378df spirv-fuzz: Do not produce OpPhis of type OpTypeSampledImage (#3964) 7edd0525b spirv-fuzz: Restrict fuzzer pass to reachable blocks (#3970) f03779a1a spirv-fuzz: Handle more types when extending OpPhi instructions (#3969) c794b7046 spirv-fuzz: Skip early terminator wrappers when merging returns (#3968) dc9c6407d spirv-fuzz: Avoid irrelevant constants in synonym-creating loops (#3967) 26954c281 spirv-fuzz: Skip dead blocks in FuzzerPassAddOpPhiSynonyms (#3965) 5600fb85b spirv-fuzz: Avoid the type manager when looking for struct types (#3963) ba15b5886 spirv-fuzz: Fix to TransformationDuplicateRegionWithSelection (#3941) 598435004 spirv-fuzz: Skip OpFunction when replacing irrelevant ids (#3932) 8362eae55 spirv-fuzz: Use component-wise selectors when flattening conditional branches (#3921) ebe0ea09f Add SPV_EXT_shader_image_int64 (#3852) a1d38174b Support SPV_KHR_fragment_shading_rate (#3943) 6fac705e7 spirv-val: Fix validation of OpPhi instructions (#3919) b1350659b spirv-fuzz: Avoid void struct member when outlining functions (#3936) fd0f295da spirv-fuzz: Do not allow Block-decorated structs when adding parameters (#3931) 5d7893b37 spirv-fuzz: Fix to operand id type (#3937) cd1d3b6e0 spirv-fuzz: Handle dead blocks in TransformationEquationInstruction (#3933) 6cdae9da7 spirv-fuzz: Do not allow sampled image load when flattening conditionals (#3930) 7e1825a59 spirv-fuzz: Take care of OpPhi instructions when inlining (#3939) 502e98295 spirv-fuzz: Fix to TransformationInlineFunction (#3913) bf1a11dab spirv-fuzz: Wrap early terminators before merging returns (#3925) fd3948e16 Add DebugValue for function param regardless of scope (#3923) 663d050a9 Temporary fix to make GoogleTest compile. (#3922) dd534e877 spirv-fuzz: Lower probability of adding bit instruction synonyms (#3917) 53aeba10c spirv-fuzz: Fix handling of OpPhi in FlattenConditionalBranch (#3916) 5c64374dd spirv-fuzz: Avoid creating blocks without parents (#3908) 57b3723c5 spirv-fuzz: Do not allow creation of constants of block-decorated structs (#3903) 12ca825a6 spirv-fuzz: Fixes related to irrelevant ids (#3901) 2e6cf706e spirv-fuzz: Fix to transformation that adds a synonym via a loop (#3898) 4b884928d spirv-fuzz: Fix to duplicate region with selection (#3896) c2553a315 spirv-fuzz: Do not expose synonym facts for non-existent ids (#3891) 360228785 spirv-fuzz: Do not add synonyms involving irrelevant ids (#3890) d52f79122 spirv-fuzz: Do not replace irrelevant ids that are not in blocks (#3892) e02265992 spirv-fuzz: Wrap OpKill and similar in function calls (#3884) 11d592422 Update val to handle reversed instruction sections. (#3887) fc8264854 spirv-fuzz: Replace dead-block terminators with OpKill etc. (#3882) 63cc22d64 spirv-fuzz: TransformationPropagateInstructionDown (#3692) 65b2a9e81 spirv-fuzz: Transformation to add wrappers for OpKill and similar (#3881) 624b16cd0 spirv-fuzz: Use overflow ids when duplicating regions (#3878) bd0dd9cef spirv-fuzz: Fix rvalue references (#3883) f15133788 spirv-fuzz: Avoid using block-decorated structs in transformations (#3877) 0e8553072 spirv-fuzz: Use overflow ids when inlining functions (#3880) 67f8e2edd Debug info preservation in convert-local-access-chains pass (#3835) d91afd8de spirv-fuzz: Refactor fact manager tests (#3879) b920b620a spirv-fuzz: Integrate spirv-reduce with shrinker (#3849) 74a711a76 spirv-fuzz: Only recommend passes when a pass had an effect (#3863) fc7860e2d spirv-fuzz: Merge the return instructions in a function (#3838) 57abfd88c Debug info preservation in redundancy-elimination pass (#3839) e24603836 Debug info preservation in if-conversion pass (#3861) 16cc197c8 spirv-fuzz: Refactor conditions in the fact manager (#3867) 615fbe6cb spirv-fuzz: TransformationWrapRegionInSelection (#3674) f2b8a4ee5 spirv-fuzz: Enable some passes with high probability (#3860) 50e04f612 spirv-fuzz: Do not add constants for Block-decorated structs (#3862) 8edd79ddc spirv-fuzz: Fix to FuzzerPassFlattenConditionalBranches (#3865) 719bade4f spirv-fuzz: Fix TransformationRecordSynonymousConstants (#3868) 009facc97 spirv-fuzz: Fix flatten conditional branch transformation (#3859) fcb22ecf0 spirv-fuzz: Report fresh ids in transformations (#3856) c6ca885c0 [spirv-dis] Add some context comments to disassembly. (#3847) 446adb05f Fix use-after-move in val/validate.cpp (#3848) 4b07d50cd spirv-fuzz: Fix bug in TransformationDuplicateRegionWithSelection (#3819) fec56146a spirv-fuzz: Support OpNot bit instruction case (#3841) 9e17b9d07 spirv-fuzz: Return IR and transformation context after replay (#3846) e12087d6c spirv-fuzz: fix test (#3845) 9edeeafdb spirv-fuzz: Use unique_ptr<FactManager> in TransformationContext (#3844) 50dacda55 Start SPIRV-Tools v2020.6 b27e039c6 Finalize SPIRV-Tools v2020.5 a5903a969 Update CHANGES 330c72549 spirv-fuzz: Support dead blocks in TransformationAddSynonym (#3832) 36185f8b0 spirv-fuzz: Move IRContext parameter into constructor (#3837) 0e7fe4d35 Add missing backticks around <result-id> (#3840) d1bb98fd4 Validate SPIRV Version number when parsing binary header (#3834) 67525bded spirv-fuzz: Create synonym of int constant using a loop (#3790) 7cc4b4d2c Fix compiler error on macOS with XCode12 (#3836) 5a5b750aa spirv-fuzz: Handle OpPhis in TransformationInlineFunction (#3833) 0a1fb588c Update CHANGES 125b64241 spirv-fuzz: Refactor fuzzer, replayer and shrinker (#3818) 60ce96e2f spirv-fuzz: Add pass recommendations (#3757) 2945963cc spirv-fuzz: Consider all ids from dead blocks irrelevant (#3795) 50ae4c5f4 Fix header guard macros (#3811) 296e9c7bc spirv-fuzz: Fix TransformationDuplicateRegionWithSelection (#3815) 937a757f0 spirv-val: Add DeviceIndex (#3812) 34ef0c3fd Fix missed modification flagging (#3814) 748edbf8c spirv-fuzz: Use an irrelevant id for the unused components (#3810) 8d49fb2f4 spirv-fuzz: Improvements to random number generation (#3809) 7e28d809c Add buffer oob check to bindless instrumentation (#3800) 8fc504110 spirv-fuzz: Remove CanFindOrCreateZeroConstant (#3807) e8ce4355a spirv-fuzz: Add bit instruction synonym transformation (#3775) e7c84feda spirv-fuzz: Skip unreachable blocks (#3729) f20b523cb Fix build errors (#3804) 3131686d2 spirv-fuzz: Handle invalid ids in fact manager (#3742) 4c239bd81 spirv-fuzz: Support memory instructions MoveInstructionDown (#3700) 1e1c308de spirv-fuzz: Pass submanagers to other submanagers when necessary (#3796) f62357e7b spirv-fuzz: Transformation to flatten conditional branch (#3667) 5df930054 spirv-val: Add BaseInstance, BaseVertex, DrawIndex, and ViewIndex (#3782) 286b3095d Properly mark IR changed if instruction folder creates more than one constant. (#3799) 726af6f78 Add missing file to BUILD.gn (#3798) 244e6c1be spirv-fuzz: Add TransformationDuplicateRegionWithSelection (#3773) 5dcb576b6 spirv-reduce: Support reducing a specific function (#3774) de7d57984 spirv-reduce: Refactoring (#3793) ed9863e46 Favour 'integrity' over 'coherence' as a replacement for 'sanity'. (#3619) 8743d385f spirv-fuzz: Fix header guards in transformations/fuzzer passes (#3784) 2de7d3af0 spirv-fuzz: Add SPIRV_FUZZ_PROTOC_COMMAND (#3789) e589d0d57 Add missing include (#3788) a715b1b40 Improve spirv-fuzz CMake code (#3781) a187dd58a Allow SPV_KHR_8bit_storage extension. (#3780) 1ab52e54a spirv-opt: Add function to compute nesting depth of a block (#3771) fd05605be spirv-fuzz: Transformation to convert OpSelect to conditional branch (#3681) 2c60d16a6 spirv-val: Add Vulkan VUID labels to BuiltIn (#3756) c341f7a6c spirv-fuzz: Add support for BuiltIn decoration (#3736) c278dada9 spirv-fuzz: Fix GetIdEquivalenceClasses (#3767) 788468408 spirv-fuzz: Replace id in OpPhi coming from a dead predecessor (#3744) 3daabd321 spirv-fuzz: Transformation to replace the use of an irrelevant id (#3697) d7f078f27 spirv-fuzz: TransformationMutatePointer (#3737) 43a518601 spirv-fuzz: Compute interprocedural loop nesting depth of blocks (#3753) 8a0ebd40f Correctly replace debug lexical scope of instruction (#3718) f428aa39c spirv-fuzz: Remove opaque pointer design pattern (#3755) 08291a3a9 spirv-fuzz: Create synonym via OpPhi and existing synonyms (#3701) 7e4948b2a Add LoopNestingDepth function to StructuredCFGAnalysis (#3754) 50cf38b8c spirv-fuzz: Do not make synonyms of void result ids (#3747) bceab9fab Do not register DebugFunction for functions optimized away. (#3749) e02f178a7 Handle DebugScope in compact-ids pass (#3724) 9e26ae045 spirv-fuzz: Overflow ids (#3734) 2205254cf Fix DebugNoScope to not output InlinedAt operand. (#3748) 230f363e6 spirv-fuzz: Split the fact manager into multiple files (#3699) 5adc5ae64 spirv-fuzz: Add inline function transformation (#3517) 1341b58a8 spirv-fuzz: Fix MaybeGetZeroConstant (#3740) 12df3cafe Fix SSA-rewrite to remove DebugDeclare for variables without loads (#3719) 3f8501de9 Add undef for inlined void function (#3720) 4dd122392 spirv-fuzz: Add words instead of logical operands (#3728) b79773a35 CCP should mark IR changed if it created new constants. (#3732) a711c594b spirv-fuzz: add FuzzerPassAddCompositeInserts (#3606) 582c276d4 spirv-fuzz: Support pointer types in FuzzerPassAddParameters (#3627) 3434cb0b0 Let ADCE pass check DebugScope (#3703) ee7f0c882 spirv-opt: Implement opt::Function::HasEarlyReturn function (#3711) e28436f2b spirv-fuzz: Check termination instructions when donating modules (#3710) 1023dd7a0 Fix -Wrange-loop-analysis warning (#3712) 82f4bf128 spirv-fuzz: Check header dominance when adding dead block (#3694) b8de4f57e Allow DebugTypeTemplate for Type operand (#3702) c20995ef8 spirv-fuzz: Improve code coverage of tests (#3686) eade36db2 spirv-fuzz: Fuzzer pass to randomly apply loop preheaders (#3668) 72ea7bec4 spirv-fuzz: Support identical predecessors in TransformationPropagateInstructionUp (#3689) b4c4da3e7 Improve non-semantic instruction handling in the optimizer (#3693) 948577c5d Fix the bug (#3680) df859f77d spirv-fuzz: Check integer and float width capabilities (#3670) 2641d3351 spirv-fuzz: consider additional access chain instructions (#3672) 5e5929455 spirv-fuzz: Ignore specialization constants (#3664) 1435e427d Fix the bug (#3683) be099cde1 spirv-fuzz: Fix width in FuzzerPassAddEquationInstructions (#3685) f0ca96d12 Preserve debug info in dead-insert-elim pass (#3652) 0d629b903 Validate more OpenCL.DebugInfo.100 instructions (#3684) 13a65b1ae Only validation locations for appropriate execution models (#3656) fd3cabd8b spirv-fuzz: Fix in operand type assertion (#3666) f50553867 spirv-opt: Add spvOpcodeIsAccessChain (#3682) b7056e7e0 spirv-fuzz: FuzzerPassPropagateInstructionsUp (#3478) 8e1380996 Handle no index access chain in local access chain convert (#3678) bdeeae78a Roll 2 dependencies (#3677) 2990a2192 Avoid using /MP4 for clang on windows. (#3662) 7b2dd11dd spirv-fuzz: TransformationReplaceAddSubMulWithCarryingExtended (#3598) 6d7f34fbf spirv-fuzz: Add TransformationMakeVectorOperationDynamic (#3597) d29eac95a spirv-fuzz: iterate over blocks in replace linear algebra pass (#3654) efc85ff66 spirv-fuzz: make outliner pass use additional transformations (#3604) 5fd92a7e0 OpenCL.DebugInfo.100 DebugTypeArray with variable size (#3549) 3f33a9aa5 spirv-opt: Improve the code of the Instruction class (#3610) 0419751b0 spirv-fuzz: Handle OpPhis in livesafe functions (#3642) a10e76059 spirv-fuzz: Handle OpPhi during constant obfuscation (#3640) 28f32ca53 spirv-fuzz: Fix FuzzerPassCopyObjects (#3638) 8bc27a1cf spirv-fuzz: Remove OpFunctionCall operands in correct order (#3630) d9c73ebd9 spirv-fuzz: Handle capabilities during module donation (#3651) 9f2223602 spirv-fuzz: Refactor boilerplate in TransformationAddParameter (#3625) 92a71657f spirv-fuzz: TransformationMoveInstructionDown (#3477) b78f4b151 Remove DebugDeclare only for target variables in ssa-rewrite (#3511) 91cea06ab Fix typo in ASAN CI build (#3623) 2aaa8653d spirv-fuzz: Transformation to add loop preheader (#3599) 96bcc8274 spirv-fuzz: Pass to replace int operands with ints of opposite signedness (#3612) ebaefda66 Debug info preservation in loop-unroll pass (#3548) 50300450a Validator support for non-semantic clspv reflection (#3618) ab4fe12a4 spirv-fuzz: Fix memory bugs (#3622) c6e6597c4 spirv-fuzz: Implement the OpOuterProduct linear algebra case (#3617) 054f034ea spirv-fuzz: Compute corollary facts from OpBitcast (#3538) a1ea15c90 Update some language usage. (#3611) 863b8e3d3 spirv-fuzz: Relax type constraints in DataSynonym facts (#3602) 7e75fea9e spirv-fuzz: Remove non-deterministic behaviour (#3608) f9b088fe0 Avoid use of 'sanity' and 'sanity check' in the code base (#3585) 150be20d4 spirv-fuzz: Add condition to make functions livesafe (#3587) ce16ccf38 Rolling 4 dependencies (#3601) 1dfc6fc7e spirv-fuzz: Implement the OpTranspose linear algebra case (#3589) b63f0e5ed Fix SyntaxWarning in Python 3.8 (#3388) 6aed7ffbc CMake: Enable building with BUILD_SHARED_LIBS=1 (#3490) 31c821393 Avoid operand type range checks (#3379) 6a3eb679b Preserve debug info in scalar replacement pass (#3461) 2796840d2 Update OpenCL capabilities validation (#3149) b25ee93c2 build(deps): bump lodash from 4.17.15 to 4.17.19 in /tools/sva (#3596) git-subtree-dir: third_party/SPIRV-Tools git-subtree-split: 82b378d671836b51343b010ca9ec32db14485147
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 vyear.index and with an optional -dev suffix to indicate work in progress. For example, the following versions are ordered from oldest to newest:
v2016.0v2016.1-devv2016.1v2016.2-devv2016.2Use 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.
The optimizer is a collection of code transforms, or “passes”. Transforms are written for a diverse set of reasons:
As of this writing, there are 67 transforms including examples such as:
OpSpecConstantOp and OpSpecConstantCompositeAdditionally, certain sets of transformations have been packaged into higher-level recipes. These include:
spirv-opt -Os)spirv-opt -O)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.
Note: The fuzzer is still under development.
The fuzzer applies semantics-preserving transformations to a SPIR-V binary module, to produce an equivalent module. The original and transformed modules should produce essentially identical results when executed on identical inputs: their results should differ only due to floating-point round-off, if at all. Significant differences in results can pinpoint bugs in tools that process SPIR-V binaries, such as miscompilations. This metamorphic testing approach is similar to the method used by the GraphicsFuzz project for fuzzing of GLSL shaders.
To suggest an additional capability for the fuzzer, file an issue with “Fuzzer:” 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:
cd <spirv-dir> mkdir build && cd build cmake [-G <platform-generator>] <spirv-dir>
Once the build files have been generated, build using the appropriate build command (e.g. ninja, make, msbuild, etc.; this depends on the platform generator used above), or use your IDE, or use CMake to run the appropriate build command for you:
cmake --build . [--config Debug] # runs `make` or `ninja` or `msbuild` etc.
The SPIR-V fuzzer, spirv-fuzz, can only be built via CMake, and is disabled by default. To build it, clone protobuf and use the SPIRV_BUILD_FUZZER CMake option, like so:
# In <spirv-dir> (the SPIRV-Tools repo root): git clone --depth=1 --branch v3.13.0 https://github.com/protocolbuffers/protobuf external/protobuf # In your build directory: cmake [-G <platform-generator>] <spirv-dir> -DSPIRV_BUILD_FUZZER=ON cmake --build . --config Debug
You can also add -DSPIRV_ENABLE_LONG_FUZZER_TESTS=ON to build additional fuzzer tests.
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 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_BUILD_FUZZER={ON|OFF}, default OFF - Build the spirv-fuzz tool.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 executable 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/asUse 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/disUse 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/linkThe 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/optWarning: 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/valThe 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/reduceRun spirv-reduce --help to see how to specify interestingness.
The fuzzer transforms a SPIR-V binary module into a semantically-equivalent SPIR-V binary module by applying transformations in a randomized fashion.
This is a work in progress, with initially only a few semantics-preserving transformations.
spirv-fuzz - the standalone fuzzer<spirv-dir>/tools/fuzzRun spirv-fuzz --help for a detailed list of options.
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/cfgspirv-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.