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