Google Git
Sign in
skia / external / github.com / KhronosGroup / SPIRV-Tools.git / f76e0f5231302e4f0ae45910f728eaa9c3c76b65
commitf76e0f5231302e4f0ae45910f728eaa9c3c76b65[log] [tgz]
authorUmar Arshad <umar@arrayfire.com>Wed Nov 18 15:43:43 2015 -0500
committerDavid Neto <dneto@google.com>Wed Dec 09 16:15:00 2015 -0500
tree575a99735218ef60690df4a235bdc44b0a50ac9d
parent4e5bc928c0430b6015bd7836c598113f7076af20 [diff]
Basic SSA Validation

Most uses of an ID must occur after the definition
of the ID.  Forward references are allowed for
things like OpName, OpDecorate, and various cases
of control-flow instructions such as OpBranch, OpPhi,
and OpFunctionCall.

TODO: Use CFG analysis for SSA checks.  In particular,
an ID defined inside a function body is only usable inside
that function body.  Also, use dominator info to catch
some failing cases.

Also:
* Validator test cases use (standard) assignment form.
* Update style to more closely follow the Google C++ style guide
* Remove color-diagnostics flag.
  This is enabled by default on terminals with color. Prints
  hidden ASCII for terminals that can't handle color(Emacs)
* Pass functors to SSAPass to check if the
  operand can be forward referenced based on its index value
* Return SPV_ERROR_INVALID_ID for ID related errors
  spvBinaryParse returned SPV_ERROR_INVALID_BINARY for all types of
  errors. Since spvBinaryParse does some ID validation, this was
  returning inappropriate error codes for some tests.
* Common fixture for validation tests.
  It only runs certian validation passes.
* Add a SPV_VALIDATE_SSA_BIT for testing purposes
* Fixtures now return error codes
* Add OpName support in diag message and unit tests
* Binary parsing can fail with invalid ID or invalid binary error code

Tests include:
* OpDecorate
* OpName
* OpMemberName
* OpBranchConditional
* OpSelectionMerge
* OpMemberDecorate
* OpGroupDecorate
* OpDeviceEnqueue
* Enable several tests failing in ID validation.
12 files changed
tree: 575a99735218ef60690df4a235bdc44b0a50ac9d
  1. external/
  2. include/
  3. source/
  4. test/
  5. tools/
  6. .clang-format
  7. .gitignore
  8. CMakeLists.txt
  9. LICENSE
  10. README.md
  11. syntax.md
README.md

SPIR-V Tools

Overview

The SPIR-V Tools project provides an API and commands for processing SPIR-V modules.

The project includes an assembler, binary module parser, disassembler, and validator for SPIR-V, all 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 interfaces are still under development, and are expected to change.

SPIR-V is defined by the Khronos Group Inc. See the SPIR-V Registry for the SPIR-V specification, headers, and XML registry.

Supported features

Assembler, binary parser, and disassembler

  • Based on SPIR-V 1.0 Revision 2.
    • Supports GLSL std450 extended instructions.
    • Supports OpenCL extended instructions.
  • Assembler only does basic syntax checking. No cross validation of IDs or types is performed, except to check literal arguments to OpConstant, OpSpecConstant, and OpSwitch.

See syntax.md for the assembly language syntax.

Validator

Warning: The validator is incomplete.

Source code

The SPIR-V Tools are maintained by members of the The Khronos Group Inc., at https://github.com/KhronosGroup/SPIRV-Tools.

Contributions via merge request are welcome. Changes should:

We intend to maintain a linear history on the GitHub master branch.

Source code organization

  • external/headers: Standard SPIR-V header files used by the implementation, from the SPIR-V Registry
  • external/googletest: Intended location for the googletest sources, not provided.
  • include/libspirv/libspirv.h: C API public interface
  • source/: API implementation
  • test/: Tests, using the googletest framework.
  • tools/: Command line executables

Tests

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. Download the 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.

Build

The project uses CMake to generate platform-specific build configurations. To generate these build files, issue the following commands:

mkdir <spirv-dir>/build
cd <spirv-dir>/build
cmake [-G <platform-generator>] <spirv-dir>

Once the build files have been generated, build using your preferred development environment.

CMake options

The following CMake options are supported:

  • SPIRV_COLOR_TERMINAL=ON - Enables color console output, enabled by default.
  • SPIRV_SKIP_EXECUTABLES=ON - Build only the library, not the command line tools. This will also prevent the tests from being built.
  • SPIRV_USE_SANITIZER=<sanitizer> - 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. Disabled by default.
  • SPIRV_WARN_EVERYTHING=OFF - On UNIX platforms enable the -Weverything compiler front end option, disabled by default.
  • SPIRV_WERROR=ON - Forces a compilation error on any warnings encountered by enabling the compiler-specific compiler front-end option, enabled by default.

Library

Usage

The library provides a C API, but the internals use C++11.

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/libspirv/libspirv.h then linking against the static library in <spirv-build-dir>/libSPIRV-Tools.a or <spirv-build-dir>/SPIRV-Tools.lib.

  • SPIRV-Tools CMake target: Creates the static library:
    • <spirv-build-dir>/libSPIRV-Tools.a on Linux and OS X.
    • <spirv-build-dir>/libSPIRV-Tools.lib on Windows.

Entry points

The interfaces are still under development, and are expected to change.

There are three main entry points into the library.

  • 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. Incomplete

Command line tools

Assembler tool

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>/spirv-as. The functionality of the assembler is implemented by the spvTextToBinary library function.

  • spirv-as - the standalone assembler
    • <spirv-dir>/spirv-as

Use option -h to print help.

Disassembler tool

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>/spirv-dis. The functionality of the disassembler is implemented by the spvBinaryToText library function.

  • spirv-dis - the standalone disassembler
    • <spirv-dir>/spirv-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.

Validator tool

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>/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>/spirv-val

UnitSPIRV tool

The <spirv-build-dir>/UnitSPIRV executable runs the project tests. It supports the standard googletest command line options.

Future Work

Assembler and disassembler

  • Support 16-bit floating point literals.
  • The disassembler could emit helpful annotations in comments. For example:
    • Use variable name information from debug instructions to annotate key operations on variables.
    • Show control flow information by annotating OpLabel instructions with that basic block's predecessors.
  • Error messages could be improved.

Validator

This is a work in progress.

Licence

Copyright (c) 2015 The Khronos Group Inc.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and/or associated documentation files (the
"Materials"), to deal in the Materials without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Materials, and to
permit persons to whom the Materials are furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Materials.

MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS
KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS
SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT
   https://www.khronos.org/registry/

THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.