commit	5297bfda4a0f78f863f853f6eee72614222e81aa	[log] [tgz]
author	Ben Clayton <bclayton@google.com>	Mon May 15 13:24:10 2023 +0100
committer	Ben Clayton <bclayton@google.com>	Mon May 15 13:24:10 2023 +0100
tree	1718b4cc0f5697858893a43ab2a676c936e33789
parent	7fcf28dc09660cfcacab9ea89c796b0cefda37f3 [diff]

Squashed 'third_party/SPIRV-Headers/' changes from aa331ab0f..268a06176

268a06176 Reserve a single block of opcodes and enumerants for Saarland University (#343)
f7e1a2ef5 Merge pull request #336 from DBDuncan/shift-codeplay-range
7f1d2f415 Merge pull request #344 from ewerness-nv/SPV_KHR_ray_tracing_position_fetch
131fddea3 SPV_KHR_ray_tracing_position_fetch
e08a279cf Merge pull request #340 from MrSidims/fix-tile-image-error
a53bc4bf6 Merge pull request #342 from joycebrum/main
d4461bc88 chore: Set minimal permissions to presubmit
c8f869ffb Fix TileImage capabilities order
cfbe4feef Merge pull request #335 from janharaldfredriksen-arm/SPV_EXT_shader_tile_image
7c862b551 Shift Codeplay opcode range to preserve alignment of opcodes and non-opcodes
80cea00f6 Add back version field for new enumerants and operands, but set to None.
862efd55a Address feedback on incorrect use of version and extension fields.
d218c4ab7 Add SPV_EXT_shader_tile_image.
29ba24931 Merge pull request #329 from DBDuncan/reserve-ranges-codeplay
90547c54e Merge pull request #331 from juan-lunarg/juaramos/fix_cmake_again_part_2
295ac7e34 Reserve SPIR-V blocks for Codeplay
e90684a05 cmake: Overally cleanup/testing update
5b21f14b2 Merge pull request #330 from dneto0/revert-cmake-changes
e0087ad2c Revert "Merge pull request #326 from juan-lunarg/juaramos/cmake"
a41cf67df Merge pull request #326 from juan-lunarg/juaramos/cmake
3834d4128 Merge pull request #327 from gnl21/gnl-image-dims
2666ce79a Simplify enabling capabilities for image Dim
4b5bf03e8 cmake: Overally cleanup/testing update
1feaf4414 Merge pull request #320 from CodeLinaro/spv-qcom-image-processing
9f8e16aa5 Merge pull request #321 from asudarsa/asudarsa/add_fpga_latency_control_ext
647dec7f8 Merge pull request #322 from bashbaug/SPV_INTEL_bfloat16_conversion
738a7cc08 Fix error in merge conflict resolution
391c49035 Merge remote-tracking branch 'real-origin/main' into asudarsa/add_fpga_latency_control_ext
e65c5d143 headers support for SPV_INTEL_bfloat16_conversion
78a1e8aaa Add parameters
0e9e42f65 Remove redundant extensions entry
afe1c65aa Add support for SPV_INTEL_fpga_latency_control extension
3228364ff SPV_QCOM_image_processing
8917a8619 SPV_QCOM_image_processing
2c3cfe20d Merge branch 'KhronosGroup:main' into spv-qcom-image-processing
295cf5fb3 Merge pull request #317 from tiwaria1/register_map_interface
317010351 update parameter name to match spec in grammar file
8a0d0b6b7 move FPGAKernelAttributesv2INTEL to capability section in all files
f5fc87239 SPV_QCOM_image_processing
e01ade256 SPV_QCOM_image_processing
e72e3c372 correct file entry position for FPGAKernelAttributesv2INTEL
9e24e0684 Merge branch 'register_map_interface' of https://github.com/tiwaria1/SPIRV-Headers into register_map_interface
606e22312 add FPGAKernelAttributesv2INTEL to all files
29cd8f66a address review comment
32a226085 add RegisterMapInterfaceINTEL

git-subtree-dir: third_party/SPIRV-Headers
git-subtree-split: 268a061764ee69f09a477a695bf6a11ffe311b8d
Change-Id: Idf3bc635742a9c8a66403b7fa43861f746fc7269

.github/workflows/presubmit.yml[diff]
CMakeLists.txt[diff]
cmake/Config.cmake.in[Deleted - diff]
cmake/SPIRV-Headers.pc.in[Renamed from SPIRV-Headers.pc.in - diff]
example/CMakeLists.txt[Deleted - diff]
include/spirv/spir-v.xml[diff]
include/spirv/unified1/spirv.bf[diff]
include/spirv/unified1/spirv.core.grammar.json[diff]
include/spirv/unified1/spirv.cs[diff]
include/spirv/unified1/spirv.h[diff]
include/spirv/unified1/spirv.hpp[diff]
include/spirv/unified1/spirv.hpp11[diff]
include/spirv/unified1/spirv.json[diff]
include/spirv/unified1/spirv.lua[diff]
include/spirv/unified1/spirv.py[diff]
include/spirv/unified1/spv.d[diff]
tests/CMakeLists.txt[Added - diff]
tests/example.cpp[Renamed from example/example.cpp - diff]
tests/find_package/CMakeLists.txt[Added - diff]
tests/pkg_config/CMakeLists.txt[Added - diff]

20 files changed

tree: 1718b4cc0f5697858893a43ab2a676c936e33789

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:

Add an add_subdirectory directive to include this source tree.
Use ${SPIRV-Headers_SOURCE_DIR}/include} in a target_include_directories directive.
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:

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",
)

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,
  ],
)

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 and install 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.) Here's a complete example:

cd tools/buildHeaders
mkdir build
cd build
cmake ..
cmake --build . --target install
cd ..
./bin/makeHeaders

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.