README.md

   1 # SPIR-V Headers
   2
   3 This repository contains machine-readable files for the
   4 [SPIR-V Registry](https://www.khronos.org/registry/spir-v/).
   5 This 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
  13 Headers are provided in the [include](include) directory, with up-to-date
  14 headers in the `unified1` subdirectory. Older headers are provided according to
  15 their version.
  16
  17 In contrast, the XML registry file has a linear history, so it is
  18 not tied to SPIR-V specification versions.
  19
  20 ## How is this repository updated?
  21
  22 When a new version or revision of the SPIR-V specification is published,
  23 the SPIR-V Working Group will push new commits onto master, updating
  24 the files under [include](include).
  25
  26 [The SPIR-V XML registry file](include/spirv/spir-v.xml)
  27 is updated by Khronos whenever a new enum range is allocated.
  28
  29 Pull 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
  36 Tools that generate SPIR-V should use a magic number in the SPIR-V to help identify the
  37 generator.
  38
  39 Care should be taken to follow existing precedent in populating the details of reserved tokens.
  40 This includes:
  41 - keeping generator numbers in numeric order
  42 - filling out all the existing fields
  43
  44 ### Reserving tokens in the JSON grammar
  45
  46 Care should be taken to follow existing precedent in populating the details of reserved tokens.
  47 This 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 ```
  56 mkdir build
  57 cd build
  58 cmake ..
  59 cmake --build . --target install
  60 ```
  61
  62 Then, for example, you will have `/usr/local/include/spirv/unified1/spirv.h`
  63
  64 If 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
  70 A CMake-based project can use the headers without installing, as follows:
  71
  72 1. Add an `add_subdirectory` directive to include this source tree.
  73 2. Use `${SPIRV-Headers_SOURCE_DIR}/include}` in a `target_include_directories`
  74    directive.
  75 3. 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
  83 See 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
  87 A Bazel-based project can use the headers without installing, as follows:
  88
  89 1. Add SPIRV-Headers as a submodule of your project, and add a
  90 `local_repository` to your `WORKSPACE` file. For example, if you place
  91 SPIRV-Headers under `external/spirv-headers`, then add the following to your
  92 `WORKSPACE` file:
  93
  94 ```
  95 local_repository(
  96     name = "spirv_headers",
  97     path = "external/spirv-headers",
  98 )
  99 ```
 100
 101 2. Add one of the following to the `deps` attribute of your build target based
 102 on your needs:
 103 ```
 104 @spirv_headers//:spirv_c_headers
 105 @spirv_headers//:spirv_cpp_headers
 106 @spirv_headers//:spirv_cpp11_headers
 107 ```
 108
 109 For example:
 110
 111 ```
 112 cc_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
 127 3. 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
 137 This will generally be done by Khronos, for a change to the JSON grammar.
 138 However, the project for the tool to do this is included in this repository,
 139 and can be used to test a PR, or even to include the results in the PR.
 140 This is not required though.
 141
 142 The header-generation project is under the `tools/buildHeaders` directory.
 143 Use CMake to build and install the project, in a `build` subdirectory (under `tools/buildHeaders`).
 144 There is then a bash script at `bin/makeHeaders` that shows how to use the built
 145 header-generator binary to generate the headers from the JSON grammar.
 146 (Execute `bin/makeHeaders` from the `tools/buildHeaders` directory.)
 147 Here's a complete example:
 148
 149 ```
 150 cd tools/buildHeaders
 151 mkdir build
 152 cd build
 153 cmake ..
 154 cmake --build . --target install
 155 cd ..
 156 ./bin/makeHeaders
 157 ```
 158
 159 Notes:
 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
 166 The [GLSL.std.450.h](include/spirv/unified1/GLSL.std.450.h)
 167 and [OpenCL.std.h](include/spirv/unified1/OpenCL.std.h) extended instruction set headers
 168 are maintained manually.
 169
 170 The C/C++ header for each of the other extended instruction sets
 171 is generated from the corresponding JSON grammar file.  For example, the
 172 [OpenCLDebugInfo100.h](include/spirv/unified1/OpenCLDebugInfo100.h) header
 173 is generated from the
 174 [extinst.opencl.debuginfo.100.grammar.json](include/spirv/unified1/extinst.opencl.debuginfo.100.grammar.json)
 175 grammar file.
 176
 177 To generate these C/C++ headers, first make sure `python3` is in your PATH, then
 178 invoke the build script as follows:
 179 ```
 180 cd tools/buildHeaders
 181 python3 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 ```
 201 Copyright (c) 2015-2018 The Khronos Group Inc.
 202
 203 Permission is hereby granted, free of charge, to any person obtaining a
 204 copy of this software and/or associated documentation files (the
 205 "Materials"), to deal in the Materials without restriction, including
 206 without limitation the rights to use, copy, modify, merge, publish,
 207 distribute, sublicense, and/or sell copies of the Materials, and to
 208 permit persons to whom the Materials are furnished to do so, subject to
 209 the following conditions:
 210
 211 The above copyright notice and this permission notice shall be included
 212 in all copies or substantial portions of the Materials.
 213
 214 MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS
 215 KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS
 216 SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT
 217    https://www.khronos.org/registry/
 218
 219 THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 220 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 221 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 222 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 223 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 224 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 225 MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
 226 ```