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 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.)
147
148Notes:
149- this generator is used in a broader context within Khronos to generate the specification,
150  and that influences the languages used, for legacy reasons
151- the C++ structures built may similarly include more than strictly necessary, for the same reason
152
153## Generating C headers for extended instruction sets
154
155The [GLSL.std.450.h](include/spirv/unified1/GLSL.std.450.h)
156and [OpenCL.std.h](include/spirv/unified1/OpenCL.std.h) extended instruction set headers
157are maintained manually.
158
159The C/C++ header for each of the other extended instruction sets
160is generated from the corresponding JSON grammar file.  For example, the
161[OpenCLDebugInfo100.h](include/spirv/unified1/OpenCLDebugInfo100.h) header
162is generated from the
163[extinst.opencl.debuginfo.100.grammar.json](include/spirv/unified1/extinst.opencl.debuginfo.100.grammar.json)
164grammar file.
165
166To generate these C/C++ headers, first make sure `python3` is in your PATH, then
167invoke the build script as follows:
168```
169cd tools/buildHeaders
170python3 bin/makeExtinstHeaders.py
171```
172
173## FAQ
174
175* *How are different versions published?*
176
177  The multiple versions of the headers have been simplified into a
178  single `unified1` view. The JSON grammar has a "version" field saying
179  what version things first showed up in.
180
181* *How do you handle the evolution of extended instruction sets?*
182
183  Extended instruction sets evolve asynchronously from the core spec.
184  Right now there is only a single version of both the GLSL and OpenCL
185  headers.  So we don't yet have a problematic example to resolve.
186
187## License
188<a name="license"></a>
189```
190Copyright (c) 2015-2018 The Khronos Group Inc.
191
192Permission is hereby granted, free of charge, to any person obtaining a
193copy of this software and/or associated documentation files (the
194"Materials"), to deal in the Materials without restriction, including
195without limitation the rights to use, copy, modify, merge, publish,
196distribute, sublicense, and/or sell copies of the Materials, and to
197permit persons to whom the Materials are furnished to do so, subject to
198the following conditions:
199
200The above copyright notice and this permission notice shall be included
201in all copies or substantial portions of the Materials.
202
203MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS
204KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS
205SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT
206   https://www.khronos.org/registry/
207
208THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
209EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
210MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
211IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
212CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
213TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
214MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
215```
216