Squashed 'third_party/SPIRV-Headers/' changes from 104ecc356c1..8bb2420b44a

8bb2420b44a Merge pull request #176 from MrSidims/private/MrSidims/OtherExtensions
0dd29fb93ac Apply suggestions to Intel extensions PR
b690b3e2174 Update generated files
f9797ef9c1b Add SPV_INTEL_long_constant_composite extension
8987518da9e Add SPV_INTEL_loop_fuse extension
3fad4b35436 Add SPV_INTEL_fpga_cluster_attributes and SPV_INTEL_fp_fast_math_mode
b6be746fc77 Update SPV_INTEL_fpga_loop_controls extension
ad00ca3b55b Update SPV_INTEL_kernel_attributes extension
0c290562414 Update SPV_INTEL_function_pointers extension
ea791133ee4 Upstream SPV_INTEL_float_controls2 extension
24e9c63e6dd Upstream SPV_INTEL_vector_compute extension
2b76471587f Upstream SPV_INTEL_fpga_memory_accesses extension
0e756817218 Upstream SPV_INTEL_io_pipes extension
ef87dd18967 Upstream SPV_INTEL_variable_length_array extension
e202eb89141 Upstream SPV_INTEL_usm_storage_classes extension
a001134e417 Upstream SPV_INTEL_arbitrary_precision_integers extensions
7669e05273b Upstream SPV_INTEL_inline_assembly extension
d5035de3d31 Upstream SPV_INTEL_fpga_buffer_location extension
f027d53ded7 Merge pull request #184 from dgkoch/dkoch_remove_hittkhr
bdd2aa34c45 remove HitTKHR

git-subtree-dir: third_party/SPIRV-Headers
git-subtree-split: 8bb2420b44af3c514480e63ac24439044706b583
11 files changed
tree: 6a3c4d490115f0fcacce26b1abd005a0774c70b1
  1. cmake/
  2. example/
  3. include/
  4. tools/
  5. .gitattributes
  6. .gitignore
  7. BUILD.bazel
  8. BUILD.gn
  9. CMakeLists.txt
  10. CODE_OF_CONDUCT.md
  11. LICENSE
  12. README.md
  13. WORKSPACE
README.md

SPIR-V Headers

This repository contains machine-readable files for the SPIR-V Registry. This includes:

  • Header files for various languages.
  • JSON files describing the grammar for the SPIR-V core instruction set and the extended instruction sets.
  • The XML registry file.
  • A tool to build the headers from the JSON grammar.

Headers are provided in the include directory, with up-to-date headers in the unified1 subdirectory. Older headers are provided according to their version.

In contrast, the XML registry file has a linear history, so it is not tied to SPIR-V specification versions.

How is this repository updated?

When a new version or revision of the SPIR-V specification is published, the SPIR-V Working Group will push new commits onto master, updating the files under include.

The SPIR-V XML registry file is updated by Khronos whenever a new enum range is allocated.

Pull requests can be made to

  • request allocation of new enum ranges in the XML registry file
  • register a new magic number for a SPIR-V generator
  • reserve specific tokens in the JSON grammar

Registering a SPIR-V Generator Magic Number

Tools that generate SPIR-V should use a magic number in the SPIR-V to help identify the generator.

Care should be taken to follow existing precedent in populating the details of reserved tokens. This includes:

  • keeping generator numbers in numeric order
  • filling out all the existing fields

Reserving tokens in the JSON grammar

Care should be taken to follow existing precedent in populating the details of reserved tokens. This includes:

  • pointing to what extension has more information, when possible
  • keeping enumerants in numeric order
  • when there are aliases, listing the preferred spelling first
  • adding the statement "version" : "None"

How to install the headers

mkdir build
cd build
cmake ..
cmake --build . --target install

Then, for example, you will have /usr/local/include/spirv/unified1/spirv.h

If you want to install them somewhere else, then use -DCMAKE_INSTALL_PREFIX=/other/path on the first cmake command.

Using the headers without installing

Using CMake

A CMake-based project can use the headers without installing, as follows:

  1. Add an add_subdirectory directive to include this source tree.
  2. Use ${SPIRV-Headers_SOURCE_DIR}/include} in a target_include_directories directive.
  3. In your C or C++ source code use #include directives that explicitly mention the spirv path component.
#include "spirv/unified1/GLSL.std.450.h"
#include "spirv/unified1/OpenCL.std.h"
#include "spirv/unified1/spirv.hpp"

See also the example subdirectory. But since that example is inside this repostory, it doesn't use and add_subdirectory directive.

Using Bazel

A Bazel-based project can use the headers without installing, as follows:

  1. Add SPIRV-Headers as a submodule of your project, and add a local_repository to your WORKSPACE file. For example, if you place SPIRV-Headers under external/spirv-headers, then add the following to your WORKSPACE file:
local_repository(
    name = "spirv_headers",
    path = "external/spirv-headers",
)
  1. Add one of the following to the deps attribute of your build target based on your needs:
@spirv_headers//:spirv_c_headers
@spirv_headers//:spirv_cpp_headers
@spirv_headers//:spirv_cpp11_headers

For example:

cc_library(
  name = "project",
  srcs = [
    # Path to project sources
  ],
  hdrs = [
    # Path to project headers
  ],
  deps = [
    "@spirv_tools//:spirv_c_headers",
    # Other dependencies,
  ],
)
  1. In your C or C++ source code use #include directives that explicitly mention the spirv path component.
#include "spirv/unified1/GLSL.std.450.h"
#include "spirv/unified1/OpenCL.std.h"
#include "spirv/unified1/spirv.hpp"

Generating headers from the JSON grammar for the SPIR-V core instruction set

This will generally be done by Khronos, for a change to the JSON grammar. However, the project for the tool to do this is included in this repository, and can be used to test a PR, or even to include the results in the PR. This is not required though.

The header-generation project is under the tools/buildHeaders directory. Use CMake to build the project, in a build subdirectory (under tools/buildHeaders). There is then a bash script at bin/makeHeaders that shows how to use the built header-generator binary to generate the headers from the JSON grammar. (Execute bin/makeHeaders from the tools/buildHeaders directory.)

Notes:

  • this generator is used in a broader context within Khronos to generate the specification, and that influences the languages used, for legacy reasons
  • the C++ structures built may similarly include more than strictly necessary, for the same reason

Generating C headers for extended instruction sets

The GLSL.std.450.h and OpenCL.std.h extended instruction set headers are maintained manually.

The C/C++ header for each of the other extended instruction sets is generated from the corresponding JSON grammar file. For example, the OpenCLDebugInfo100.h header is generated from the extinst.opencl.debuginfo.100.grammar.json grammar file.

To generate these C/C++ headers, first make sure python3 is in your PATH, then invoke the build script as follows:

cd tools/buildHeaders
python3 bin/makeExtinstHeaders.py

FAQ

  • How are different versions published?

    The multiple versions of the headers have been simplified into a single unified1 view. The JSON grammar has a “version” field saying what version things first showed up in.

  • How do you handle the evolution of extended instruction sets?

    Extended instruction sets evolve asynchronously from the core spec. Right now there is only a single version of both the GLSL and OpenCL headers. So we don't yet have a problematic example to resolve.

License

Copyright (c) 2015-2018 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.