| commit | 00e0af1f8a389359fb1640074e22fbb645c89704 | [log] [tgz] |
|---|---|---|
| author | Alexis Hetu <sugoi@google.com> | Mon Nov 08 08:57:46 2021 -0500 |
| committer | Alexis Hetu <sugoi@google.com> | Mon Nov 08 08:57:46 2021 -0500 |
| tree | 18064c02b60aa66a843da9e7dd6877317ec63d27 | |
| parent | 745997b9afda97a6d6ff5d58473e0aabce911321 [diff] |
Squashed 'third_party/SPIRV-Tools/' changes from f37547c73..339d4475c 339d4475c Improve decoration validation (#4490) 1589720e1 spirv-opt: create OpDecorate for OpMemberDecorate in desc-sroa (#4617) 6b073f899 Run the wasm build on push and pull_request (#4614) 66ef7cb68 Remove publish-to-npm step for Wasm build (#4610) d645ea270 Update CHANGES, README for WebAssembly build (#4609) 0d0013002 Add Wasm build (#3752) 1082de6bb Handle overflowing id in merge return (#4606) 97d449560 Avoid bitwise and in boolean expression (#4603) e3c709810 In generated cmake config file for SPIRV-Tools only access cmake target, if present (#4590) e3a373f2b Make cxx exceptions controllable (#4591) c194bb2a7 spirv-val Update LocalSizeId VUID (#4602) 6c7885dbd Change branch handling in ADCE to fix errors (#4596) bd5bf754b Fix Linker generator ID (#4601) 791f5b463 Only validate workgroup layout for explicit workgroup memory (#4542) 2feb7074d Avoid confusing short-circuiting (#3404) 7c5b17d37 Update passes to handle function declarations (#4599) b2ba019bf Delete decorations before replaces uses in dead branch elim (#4598) 3291b6951 Do not fold snegate feeding sdiv. (#4600) d997c83b1 Add spirv-opt pass to replace descriptor accesses based on variable indices (#4574) d78c1c4cd Make IsLocalVar in ADCE work at any time. (NFC) (#4595) 8c91f14a9 Add libFuzzer target for spirv-fuzz (#4434) 17a5bacfa Handle missing execution modes for limitation check (#4594) 7326b494d opt: set upper bits of spec constant according to spec (#4589) f3fbd98ff opt/spec_constants: fix bit pattern width checks. (#4588) 0f3bc1d9b Fix i386 build issues related to random generation (#4586) 001604bd4 Generate constants directly in CreateDebugInlinedAt (#4572) 7a7a69037 README: Remove appveyor build badge. (#4584) 4578db3c4 README: Update tested versions of compilers (#4579) 387cae472 Opt passes should apply to the exported functions (#4554) 35fd0e17d Consider 0xffffffff offset as missing (#4564) 06ebc4806 Account for strided components in arrays (#4575) 10343e53e Remove Appveyor CI, update README (#4578) 3e6a85303 Mark DebugInfoNone as live in ADCE when DebugInfo present (#4568) e6e77dbdf Enable OpConstFunctionPointerINTEL outside function (#4576) 5ed637caa Fix output of SPIR-V version in diagnostic (#4562) d31218c56 Use max enum instead of static array of legal values (#4571) 0292d6b16 Update SPIRV-Headers (#4573) 6dd73728e Fix merge-block assertions with debugInfo (#4563) e4349dd8f Fix CI failure (#4570) b46995741 Avoid bugprone-move-forwarding-reference warning in Clang (#4560) 0c4deebc9 Include a maximum value for spv_target_env (#4559) 63a391232 Fix ConstantManager to not run AnalyzeInstDefUse if DefUse not valid (#4557) 2d12367ce Stop consuming input in fuzzers to select target environment (#4544) eeb973f50 More ADCE refactoring (#4548) 9529d3c2c Avoid implicit fallthrough, by duplicating code (#4556) 24476c2e3 spirv-opt: Don't eliminate dead members from StructuredBuffer (#4553) 3234daada Do not assume there are execution modes (#4555) ba4b390c3 Suppress protobuf warning (#4551) c3adcb034 Adce refactor (NFC) (#4547) 19dc86c48 Handle NonSemantic.Shader Debug[No]Line (#4530) f125452cf Fix inst_buff_addr_check to handle struct loads (#4489) 134d763f4 GN: Fix build for debuginfo codegen. (#4536) 1d48824ba Update SPIRV-Headers (#4543) a6c5056db Fix checks for offset in nested structs (#4531) 0f4508752 Fix UBSan error in spirv-dis fuzzer (#4517) 59f51bb4f Fix extract with out-of-bounds index (#4529) 1454c95d1 spirv-opt: Switch from Vulkan.DebugInfo to Shader.DebugInfo (#4493) 4ac8e5e54 Add preserve_interface mode to aggressive_dead_code_elim (#4520) 9e65f054d spirv-fuzz: Account for differing signedness in WrapVectorSynonym (#4414) 36ff13534 spirv-opt: Avoid integer overflow during constant folding (#4511) cb6c66917 Roll external/googletest/ b7d472f12..955c7f837 (111 commits) (#4521) 846b032b5 Fix infinite loop in validation (#4523) bf463fe37 Fix UBSan kokoro config (#4522) 5efeaad30 Fix bad order of checks in atomic validation (#4524) 8865b2029 Handle out-of-bounds accesses in VDCE (#4518) 4f4f76037 Change validator boolean tests to avoid asserts (#4503) 912460e46 Fix infinite loop in GetBlockDepth (#4519) 013b1f3d6 Fix validation message for cooperative matrix column type (#4502) 2a938fcfa Add UBSan kokoro configuration (#4512) c16224c68 Add some missing switch validation (#4507) 92868b8f3 spirv-val: Fix ubsan error (#4505) 4db6b8dcc Remove environment features that are never used (#4491) 7e860e383 fix parsing of bad binary exponents in hex floats (#4501) 789de0dc4 Adjust build for fuzzer targets to support OSS-Fuzz (#4498) 0c09258e0 Set threshold for reduce-load-size pass (#4499) bd3a271ce Handle exported functions in ADCE (#4495) 702e6af38 Only add `-DSPIRV_CHECK_CONTEXT` for Debug builds (#4496) b8fce5f9e spirv-lint: Add lint based on divergence analysis (#4488) ee3077365 Add a feature for allowing LocalSizeId (#4492) 2a5cc342f Start SPIRV-Tools v2021.4 1fbed83c8 Finalize SPIRV-Tools v2021.3 3d4246b4a Update CHANGES a1d5d67ae spirv-val: Validate vulkan debug info similarly to opencl debug info (#4466) 937227c76 Add divergence analysis to linter (#4465) d699296b4 spirv-val: Fix WorkgroupSize VUID 04425 (#4482) 1ad8b7135 spirv-lint: add basic CLI argument handling (#4478) a9ce5e07c Fix matrix stride validation (#4468) e172833bd Don't double count variables for location validation (#4474) 926ff6d1b GN: Suppress unreachable code warnings. (#4476) 57e1d8ebe Add spirv-opt convert-to-sampled-image pass (#4340) b2e36b67e Disallow loading a runtime-sized array (#4473) 2c829c415 Fix early-out for Clamp constant folding (#4461) 869a550d2 Don't fold unsigned divides of an constant and a negation (#4457) 881001070 fix SIGSEGV when reading from a non-existant file (#4453) 00b106e76 Limit location validation (#4467) 54524ffa6 Update SPIRV-Headers (#4463) de69f32e8 spirv-opt: Add handling of vulkan debug info to DebugInfoManager (#4423) c4c6f2ba5 spirv-opt: Add dataflow analysis framework (#4402) f9d03bb40 Remove PCH from source/lint/CMakeLists.txt (#4459) 706dc27a6 Add new target for spirv-lint (#4446) 3510a14cf Add a section releases to the README (#4444) 175ecd49e Fix array layout validation slowdown (#4449) 07f130235 spirv-fuzz: Support AtomicStore (#4440) 366d1be5e fuzzers: Disable suggest-destructor-override warning (#4439) 3ab6fb9c0 Add CMake rules for libFuzzer targets (#4445) 0065c5672 spirv-fuzz: support AtomicLoad (#4330) affe280c2 Add GraphicsFuzz shaders to fuzzer corpus (#4429) c5bda7ae5 Fuzzer: Default the new constructor parameter (#4438) 5737dbb06 Fix validator crash (#4418) 17bf44376 spirv-fuzz: Add minimal SPIR-V example to test shaders (#4415) c6422cff3 spirv-opt: Rename ControlDependenceAnalysis::DoesBlockExist to HasBlock (#4412) 983ee2313 spirv-opt: Add specific handling of vulkan debug info differences (#4398) 9c4481419 spirv-fuzz: Allow inapplicable transformations to be ignored (#4407) c9e094cc4 spirv-fuzz: Quit fuzzer pass when no types are available (#4409) 4bcd13ff1 spirv-opt: Add more tests to control dependence (#4410) 7dadcf9c7 Add control dependence analysis to opt (#4380) 11cd875ed spirv-fuzz: Use reference in CanMakeSynonymOf (#4401) 4376a10c1 Fix public deps on generated headers (#4386) b2db20a7e BUILD.gn: introduce finer grained internal targets for Tint (#4399) 63238d4f2 Initialize context in `opt::Instruction`'s move constructor (#4397) 183fb9fe4 spirv-fuzz: Fix problem with instruction context (#4394) 94bcae134 spirv-fuzz: Avoid out-of-bounds access (#4395) cc3fe2b67 spirv-fuzz: Fix vector wrapping fuzzer pass (#4392) 2419f3be8 spirv-fuzz: Tighten checks on null and undef pointers (#4367) 2a7a561c0 Fix local size hint id tests (#4400) d9f892578 spirv-opt: Where possible make code agnostic of opencl/vulkan debuginfo (#4385) 033768c24 spirv-fuzz: TransformationWrapVectorSynonym that rewrites scalar operations using vectors (#4376) f084bcfe2 spirv-fuzz: Support atomic operations opcode (#4348) 3a68a7274 CMake: add ENABLE_RTTI option (#4382) 8966cc2b2 Add common enum for debug info instructions from either opencl or vulkan (#4377) 5427d5cf0 Don't mention VS2013 in PR review instructions (#4384) 7320b9acd Explain how to run tests with CMake and Bazel (#4383) e0937d7fd spirv-fuzz: Don't replace memory semantics / scope operands (#4349) 2685c9a68 Add missing fuzzer header dependency. (#4381) 640b17b5f Fix -Wunreachable-code-aggressive. (#4358) 4baf3affe spirv-opt: support SPV_EXT_shader_image_int64 (#4379) feb05446b Fix BUILD.gn (#4378) 2299b710d spirv-fuzz: support building using gn (#4365) d432bebb1 Fix vendor table build in BUILD.gn for nonsemantic.vulkan.debuginfo.100 (#4375) 3b6abf41c Add non-semantic vulkan extended instruction set (#4362) c26baf4c9 Update SPIRV-Headers deps (#4369) 9ce7a2fb6 spirv-reduce: Eliminate skeletal structured control flow construct (#4360) 4d2832e3c spirv-fuzz: Check updated analyses in transformation tests (#4266) 776336052 spirv-fuzz: Added tests for signedness analysis (#4361) a95bc460f Add remove_unused_interface_variable_pass.* to BUILD.gn (#4363) c67f13208 add tests for SPV_KHR_bit_instructions (#4350) 06f114d48 spirv-fuzz: Avoid out of bounds access (#4355) 74e8105eb Enabled tvOS platform (#4329) f9893c454 spirv-opt: A pass to removed unused input on OpEntryPoint instructions. (#4275) 8442a1812 Bump glob-parent from 5.0.0 to 5.1.2. (#4353) eeff9af1e fix strncpy bound error (#4331) b8587c984 spirv-reduce: Allow merging unreachable blocks (#4303) 4fcdc5894 Add IsReachable function to IRContext (#4323) 237173a07 spirv-reduce: Cleanup a few things (#4352) 8cc8b6562 spirv-fuzz: Add illustrative tests for new issues (#4347) 3a02d1126 Add validation for SPV_EXT_shader_atomic_float16_add (#4325) e065c482c Initial support for SPV_KHR_integer_dot_product (#4327) e992c96c8 fix symbol exports check, for Android build cases (#4342) 0c21e5092 Start SPIRV-Tools v2021.3 e198c6a78 Finalize SPIRV-Tools v2021.2 f8eafd4d8 spirv-val: Label VUID 04780 (#4334) e84bcb251 spirv-val: Add GLCompute to VUID 04644 message (#4333) 5dd2f7691 Update CHANGES file for upcoming release. bcef91374 Update SPIRV-Headers deps (#4328) 4d22f58a8 Support SPV_KHR_subgroup_uniform_control_flow (#4318) ecdd9a3e6 spirv-val: Vulkan Storage Class for Execution Model (#4212) edc3a2478 Add SPV_KHR_vulkan_memory_model to aggressive_dead_code_elim (#4320) bbc660eda Support Intel extensions for fixed point and hls-float (#4321) 9dbca316a spirv-fuzz: Improve TransformationAddBitInstructionSynonym to check integer signedness (#4312) c1a75bfab spirv-fuzz: Support bitwise or and xor in TransformationAddBitInstructionSynonym (#4310) d07505c76 Update lodash (#4317) fb02131cb No error report for variable image offset when before-legal-hlsl is on (#4316) 87a286797 Add kInstErrorMax to instrument.hpp (#4315) c05f74415 Spirv-fuzz: Add tests for MaybeGet* functions in fuzzerutil (#4284) 6d5c5677e Remove VS2013 kokoro build (#4314) 26cdce984 spirv-fuzz: add tests for full coverage of TransformationAccessChain (#4304) c853a9114 spirv-fuzz: Added test to increase coverage of the add_parameter transformation (#4305) 126a826d3 Spirv-fuzz: Achieve coverage of TransformationAddDeadBlock test (#4306) 8b3dc6bbe Check that valid bitcasted constant was returned (#4311) 0861a8fa2 spirv-fuzz: Fix OutlineFunction in presence of unreachable blocks (#4308) 9646c733e spirv-fuzz: Fix def-use update in PermutePhiOperands (#4309) ec1bc3e2e spirv-fuzz: Added extra tests for AddTypeFloat and AddTypeInt transformations (#4292) 94f570d7a spirv-fuzz: Increase test coverage of TransformationCompositeConstruct (#4301) 00ce2bb47 spirv-fuzz: Enhancing permute function variables and its testing (#4295) e2ac64bdf spirv-fuzz: Move ApplyTransformation to .cpp file (#4258) 91931ffcd spirv-fuzz: Enhance test to improve lines covered (#4289) 0afe1f2b3 spirv-fuzz: Cover protobuf message creation in tests (#4285) f0d110e30 Invalidate analyses (#4260) 18d45142e Fix crash when optimizing shaders with DebugPrintf (#4280) 010cd289d Fix continue construct for single block loops (#4277) f6b59599a spirv-fuzz: Respect control flow rules when merging returns (#4279) de1cae069 val test: Update capability dependency (#4268) 1020e394c spirv-fuzz: Fix underflow problem in `fuzzer_pass_swap_two_functions` (#4253) 8ec9f456e Fix export symbol test. (#4254) f30465d2b build: Fix Android build (#4157) f8c78cc53 Updates to the vscode SPIR-V extension (#4246) f82f5af5e Invalidate DefUse analysis (#4255) 089d716d2 Fix dangling phi bug from loop-unroll (#4239) 07ec4f83c Support folding OpBitcast with numeric constants (#4247) 6cdf07d2b spirv-fuzz: Swap positions of two functions in a module (#4236) 1b8341b8b Fix warning in python script. (#4251) 9f23457ee GraphicsRobustAccessPass: Set module_status_.modified (#4167) 8fe39ad58 spirv-fuzz: Permute the order of variables at function scope issue (#4248) 22b82872b Start SPIRV-Tools v2021.2 c2d5375fa Finalize SPIRV-Tools v2021.1 dc72924cb Update CHANGES 693d564db spriv-val: Fix clang-format bug for VUID string (#4238) a02a9205f spirv-fuzz: Accept limitations in AddFunction (#4226) ae6a1e1d2 Fix UWP build (#4235) 6210375e1 Fix clang-format-diff.py URL (#4233) 8da800c4c spirv-reduce: Remove redundant r-value references (#4232) 212895d4c Typo fix (#4225) 48007a5c7 Add interpolate legalization pass (#4220) 61e256c9c spirv-fuzz: Efficiency improvements to fuzzer pass (#4188) 2ee21fbde spirv-fuzz: Avoid invalidating analyses when splitting blocks (#4218) 22eb528f1 spirv-fuzz: Do not add too many dead blocks (#4217) d0c73fcee spirv-fuzz: Optimize transformations (#4216) f22793015 spirv-fuzz: Fix comments #4215 ecc840d30 Add validation for SPV_EXT_shader_atomic_float_min_max (#4105) d20c9c2cf Make spirv-tools-build-version a common dependency (#4210) bed84792f spirv-fuzz: Call by value and move in transformations (#4208) c0833ce62 spirv-fuzz: Remove destructors from FuzzerPass subclasses (#4209) 3d3951796 spirv-fuzz: Improve transformation test oracles (#4207) edb8399b0 spirv-fuzz: Add WGSL compatibility flag to context (#4193) 6382cbb49 spirv-fuzz: Avoid invalidating analyses in various transformations (#4205) 657889978 spirv-fuzz: Manage available instructions efficiently (#4177) 75d7c14cf spirv-fuzz: Remove AddType methods from fuzzerutil (#4204) f2a19b015 spirv-val: Refactor of atomic pass (#4200) 8f421ced3 spirv-val: Label VUID 04643 (#4202) 2b0d16a05 spirv-val: Label VUID 04667 (#4201) a732e4c03 spirv-fuzz: Apply fuzzer pass before checking exit conditions (#4199) a611be778 spirv-val: Fix Int64Atomics check (#4192) 4f498774d Roll deps (#4185) c040bd3ae spirv-val: Add Vulkan Execution Scope checks (#4183) 8866fd7ae spirv-fuzz: Locate instructions more efficiently (#4189) db2a70646 spirv-fuzz: Make adding equation instructions more efficient (#4190) e8ab7101f spirv-fuzz: Make PermutePhiOperands more efficient (#4191) 79ab273f9 Accept OpImageTexelPointer user in scalar-replacement (#4187) 042eff73f spirv-val: Add Vulkan Invocation Sematics check (#4182) 03f23106c spirv-val: Label VUID 04634 (#4181) 4100477e7 Support SPV_KHR_linkonce_odr, SPV_KHR_expect_assume (#4161) 478754c00 spirv-fuzz: Avoid invalidating analyses (#4176) 777990758 spirv-fuzz: Add buggy test (#4180) 9e93b165c Remove usage of std::iterator. (#4171) 5d8c40399 BUILD.gn: fix typo for 'cflags' (#4169) 77eb2b608 Suppress warning (#4168) f7cf3ec2a spirv-fuzz: Avoid unnecessary dependency (#4165) 1746ed39d Add `void` in function declaration to keep some compilers happy (#4160) 4a59fd476 Fix -Wextra-semi-stmt -Wsuggest-destructor-override -Wdeprecated-copy-dtor (#4164) c6da5e343 spirv-val: Vulkan 64-bit OpAtomicStore check (#4163) e6a9f4e43 spirv-fuzz: Fix the bug in TransformationReplaceBranchFromDeadBlockWithExit (#4140) 7d514cf1c spirv-fuzz: Fix PartialCount (#4159) f7043c0de spirv-fuzz: Handle Vulkan SPIR-V versions (#4156) 43cfa9bc1 spirv-fuzz: Add persistent state to the fuzzer (#4137) 939bc0260 Require an OpSelectionMerge before an OpSwitch (#4154) 0bd920eb9 Use standard function to get stdin to binary mode. (#4141) d28186db9 Fixes for the vscode language server extension (#4150) ef3290bbe spirv-opt: Don't call GenerateCopy for mismatched image types (#4126) 1b35745ad Start SPIRV-Tools v2021.0 07383c65d Finalize SPIRV-Tools v2020.7 05cda81ab Update CHANGES c79edd260 Generate differentiated error codes for buffer oob checking (#4144) cfa1dadb1 Update a few virtuals to overrides. (#4143) f0c96f40c spriv-val: Vulkan image gather constant component (#4133) 3ad7e5fcc spirv-val: Fix/Label UniformConstant VUID (#4134) f11f74348 spirv-val: Add Vulkan Invariant Decoration VUID (#4132) c91a25af1 spirv-val: label tests for VUID 04657 (#4119) d61a7d110 spirv-val: Add Vulkan PSB64 convert VUID (#4122) 297723d75 Mark module as modified if convert-to-half removes decorations. (#4127) e8bd26e1f Set correct scope and line info for DebugValue (#4125) b812fd634 Validate SPV_KHR_workgroup_memory_explicit_layout (#4128) cc81f53d3 Validate VK_KHR_zero_initialize_workgroup_memory (#4124) d71ac38b8 spirv-val: Add Vulkan image gather offset VUID (#4118) a4f97da40 Add cmake to windows path for kokoro (#4129) a61600c76 spirv-val: Label Vulkan atomic semantics VUIDs (#4120) 819117cd4 spirv-val: Label VUID 04662 (#4123) 89ad2272b spirv-val: Label VUID 04683 (#4121) 968659aee Remove obsolete GN config (#4110) git-subtree-dir: third_party/SPIRV-Tools git-subtree-split: 339d4475c1a806c187c57678af26733575d1cecd
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.
Some versions of SPIRV-Tools are tagged as stable releases (see tags on github). These versions undergo extra testing. Releases are not directly related to releases (or versions) of SPIRV-Headers. Releases of SPIRV-Tools are tested against the version of SPIRV-Headers listed in the DEPS file. The release generally uses the most recent compatible version of SPIRV-Headers available at the time of release. No version of SPIRV-Headers other than the one listed in the DEPS file is guaranteed to work with the SPIRV-Tools release.
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 of getting sources, assuming SPIRV-Tools is configured as a standalone project:
git clone https://github.com/KhronosGroup/SPIRV-Tools.git spirv-tools cd spirv-tools # Check out sources for dependencies, at versions known to work together, # as listed in the DEPS file. python3 utils/git-sync-deps
For some kinds of development, you may need the latest sources from the third-party projects:
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
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.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 executablesThe 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: Prebuilt binaries are available from the downloads page.
First get the sources. Then build using CMake, Bazel, Android ndk-build, or the Emscripten SDK.
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.1 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
The SPIRV-Tools core library can be built to a WebAssembly node.js module. The resulting SpirvTools WebAssembly module only exports methods to assemble and disassemble SPIR-V modules.
First, make sure you have the Emscripten SDK. Then:
cd <spirv-dir> ./source/wasm/build.sh
The resulting node package, with JavaScript and TypeScript bindings, is written to <spirv-dir>/out/web.
Note: This builds the package locally. It does not publish it to npm.
To test the result:
node ./test/wasm/test.js
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 -j <num threads> to run all the tests. To run tests using all threads:
ctest -j$(nproc)
To run a single test target, use ctest [-j <N>] -R <test regex>. For example, you can run all opt tests with:
ctest -R 'spirv-tools-test_opt'
Use bazel test :all to run all tests. This will run tests in parallel by default.
To run a single test target, specify :my_test_target instead of :all. Test target names get printed when you run bazel test :all. For example, you can run opt_def_use_test with:
bazel test :opt_def_use_test
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.