Name |
Date |
Size |
#Lines |
LOC |
||
---|---|---|---|---|---|---|
.. | - | - | ||||
cmake/ | 03-May-2024 | - | 5 | 3 | ||
example/ | 03-May-2024 | - | 91 | 25 | ||
include/spirv/ | 03-May-2024 | - | 75,430 | 72,644 | ||
tools/buildHeaders/ | 03-May-2024 | - | 9,509 | 6,666 | ||
.gitattributes | D | 03-May-2024 | 72 | 8 | 7 | |
.gitignore | D | 03-May-2024 | 20 | 4 | 3 | |
BUILD.bazel | D | 03-May-2024 | 3 KiB | 126 | 105 | |
BUILD.gn | D | 03-May-2024 | 1.8 KiB | 44 | 40 | |
CMakeLists.txt | D | 03-May-2024 | 4.2 KiB | 128 | 107 | |
CODE_OF_CONDUCT.md | D | 03-May-2024 | 280 | 2 | 1 | |
LICENSE | D | 03-May-2024 | 1.3 KiB | 26 | 21 | |
README.md | D | 03-May-2024 | 7 KiB | 203 | 159 | |
WORKSPACE | D | 03-May-2024 | 0 |
README.md
1# SPIR-V Headers 2 3This repository contains machine-readable files for the 4[SPIR-V Registry](https://www.khronos.org/registry/spir-v/). 5This includes: 6 7* Header files for various languages. 8* JSON files describing the grammar for the SPIR-V core instruction set 9 and the extended instruction sets. 10* The XML registry file. 11* A tool to build the headers from the JSON grammar. 12 13Headers are provided in the [include](include) directory, with up-to-date 14headers in the `unified1` subdirectory. Older headers are provided according to 15their version. 16 17In contrast, the XML registry file has a linear history, so it is 18not tied to SPIR-V specification versions. 19 20## How is this repository updated? 21 22When a new version or revision of the SPIR-V specification is published, 23the SPIR-V Working Group will push new commits onto master, updating 24the files under [include](include). 25 26The SPIR-V XML registry file is updated by Khronos whenever a new enum range is allocated. 27 28Pull requests can be made to 29- request allocation of new enum ranges in the XML registry file 30- reserve specific tokens in the JSON grammar 31 32### Reserving tokens in the JSON grammar 33 34Care should be taken to follow existing precedent in populating the details of reserved tokens. This includes: 35- pointing to what extension has more information, when possible 36- keeping enumerants in numeric order 37- when there are aliases, listing the preferred spelling first 38- adding the statement `"version" : "None"` 39 40## How to install the headers 41 42``` 43mkdir build 44cd build 45cmake .. 46cmake --build . --target install 47``` 48 49Then, for example, you will have `/usr/local/include/spirv/unified1/spirv.h` 50 51If you want to install them somewhere else, then use 52`-DCMAKE_INSTALL_PREFIX=/other/path` on the first `cmake` command. 53 54## Using the headers without installing 55 56### Using CMake 57A CMake-based project can use the headers without installing, as follows: 58 591. Add an `add_subdirectory` directive to include this source tree. 602. Use `${SPIRV-Headers_SOURCE_DIR}/include}` in a `target_include_directories` 61 directive. 623. In your C or C++ source code use `#include` directives that explicitly mention 63 the `spirv` path component. 64``` 65#include "spirv/unified1/GLSL.std.450.h" 66#include "spirv/unified1/OpenCL.std.h" 67#include "spirv/unified1/spirv.hpp" 68``` 69 70See also the [example](example/) subdirectory. But since that example is 71*inside* this repostory, it doesn't use and `add_subdirectory` directive. 72 73### Using Bazel 74A Bazel-based project can use the headers without installing, as follows: 75 761. Add SPIRV-Headers as a submodule of your project, and add a 77`local_repository` to your `WORKSPACE` file. For example, if you place 78SPIRV-Headers under `external/spirv-headers`, then add the following to your 79`WORKSPACE` file: 80 81``` 82local_repository( 83 name = "spirv_headers", 84 path = "external/spirv-headers", 85) 86``` 87 882. Add one of the following to the `deps` attribute of your build target based 89on your needs: 90``` 91@spirv_headers//:spirv_c_headers 92@spirv_headers//:spirv_cpp_headers 93@spirv_headers//:spirv_cpp11_headers 94``` 95 96For example: 97 98``` 99cc_library( 100 name = "project", 101 srcs = [ 102 # Path to project sources 103 ], 104 hdrs = [ 105 # Path to project headers 106 ], 107 deps = [ 108 "@spirv_tools//:spirv_c_headers", 109 # Other dependencies, 110 ], 111) 112``` 113 1143. In your C or C++ source code use `#include` directives that explicitly mention 115 the `spirv` path component. 116``` 117#include "spirv/unified1/GLSL.std.450.h" 118#include "spirv/unified1/OpenCL.std.h" 119#include "spirv/unified1/spirv.hpp" 120``` 121 122## Generating headers from the JSON grammar for the SPIR-V core instruction set 123 124This will generally be done by Khronos, for a change to the JSON grammar. 125However, the project for the tool to do this is included in this repository, 126and can be used to test a PR, or even to include the results in the PR. 127This is not required though. 128 129The header-generation project is under the `tools/buildHeaders` directory. 130Use CMake to build the project, in a `build` subdirectory (under `tools/buildHeaders`). 131There is then a bash script at `bin/makeHeaders` that shows how to use the built 132header-generator binary to generate the headers from the JSON grammar. 133(Execute `bin/makeHeaders` from the `tools/buildHeaders` directory.) 134 135Notes: 136- this generator is used in a broader context within Khronos to generate the specification, 137 and that influences the languages used, for legacy reasons 138- the C++ structures built may similarly include more than strictly necessary, for the same reason 139 140## Generating C headers for extended instruction sets 141 142The [GLSL.std.450.h](include/spirv/unified1/GLSL.std.450.h) 143and [OpenCL.std.h](include/spirv/unified1/OpenCL.std.h) extended instruction set headers 144are maintained manually. 145 146The C/C++ header for each of the other extended instruction sets 147is generated from the corresponding JSON grammar file. For example, the 148[OpenCLDebugInfo100.h](include/spirv/unified1/OpenCLDebugInfo100.h) header 149is generated from the 150[extinst.opencl.debuginfo.100.grammar.json](include/spirv/unified1/extinst.opencl.debuginfo.100.grammar.json) 151grammar file. 152 153To generate these C/C++ headers, first make sure `python3` is in your PATH, then 154invoke the build script as follows: 155``` 156cd tools/buildHeaders 157python3 bin/makeExtinstHeaders.py 158``` 159 160## FAQ 161 162* *How are different versions published?* 163 164 The multiple versions of the headers have been simplified into a 165 single `unified1` view. The JSON grammar has a "version" field saying 166 what version things first showed up in. 167 168* *How do you handle the evolution of extended instruction sets?* 169 170 Extended instruction sets evolve asynchronously from the core spec. 171 Right now there is only a single version of both the GLSL and OpenCL 172 headers. So we don't yet have a problematic example to resolve. 173 174## License 175<a name="license"></a> 176``` 177Copyright (c) 2015-2018 The Khronos Group Inc. 178 179Permission is hereby granted, free of charge, to any person obtaining a 180copy of this software and/or associated documentation files (the 181"Materials"), to deal in the Materials without restriction, including 182without limitation the rights to use, copy, modify, merge, publish, 183distribute, sublicense, and/or sell copies of the Materials, and to 184permit persons to whom the Materials are furnished to do so, subject to 185the following conditions: 186 187The above copyright notice and this permission notice shall be included 188in all copies or substantial portions of the Materials. 189 190MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS 191KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS 192SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT 193 https://www.khronos.org/registry/ 194 195THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 196EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 197MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 198IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 199CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 200TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 201MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS. 202``` 203