1 // Copyright (c) 2015-2016 The Khronos Group Inc. 2 // 3 // Permission is hereby granted, free of charge, to any person obtaining a 4 // copy of this software and/or associated documentation files (the 5 // "Materials"), to deal in the Materials without restriction, including 6 // without limitation the rights to use, copy, modify, merge, publish, 7 // distribute, sublicense, and/or sell copies of the Materials, and to 8 // permit persons to whom the Materials are furnished to do so, subject to 9 // the following conditions: 10 // 11 // The above copyright notice and this permission notice shall be included 12 // in all copies or substantial portions of the Materials. 13 // 14 // MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS 15 // KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS 16 // SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT 17 // https://www.khronos.org/registry/ 18 // 19 // THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 20 // EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 21 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 22 // IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 23 // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 24 // TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 25 // MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS. 26 27 #ifndef SPIRV_TOOLS_LIBSPIRV_H_ 28 #define SPIRV_TOOLS_LIBSPIRV_H_ 29 30 #ifdef __cplusplus 31 extern "C" { 32 #else 33 #include <stdbool.h> 34 #endif 35 36 #include <stddef.h> 37 #include <stdint.h> 38 39 // Helpers 40 41 #define SPV_BIT(shift) (1 << (shift)) 42 43 #define SPV_FORCE_16_BIT_ENUM(name) _##name = 0x7fff 44 #define SPV_FORCE_32_BIT_ENUM(name) _##name = 0x7fffffff 45 46 // Enumerations 47 48 typedef enum spv_result_t { 49 SPV_SUCCESS = 0, 50 SPV_UNSUPPORTED = 1, 51 SPV_END_OF_STREAM = 2, 52 SPV_WARNING = 3, 53 SPV_FAILED_MATCH = 4, 54 SPV_REQUESTED_TERMINATION = 5, // Success, but signals early termination. 55 SPV_ERROR_INTERNAL = -1, 56 SPV_ERROR_OUT_OF_MEMORY = -2, 57 SPV_ERROR_INVALID_POINTER = -3, 58 SPV_ERROR_INVALID_BINARY = -4, 59 SPV_ERROR_INVALID_TEXT = -5, 60 SPV_ERROR_INVALID_TABLE = -6, 61 SPV_ERROR_INVALID_VALUE = -7, 62 SPV_ERROR_INVALID_DIAGNOSTIC = -8, 63 SPV_ERROR_INVALID_LOOKUP = -9, 64 SPV_ERROR_INVALID_ID = -10, 65 SPV_ERROR_INVALID_CFG = -11, 66 SPV_ERROR_INVALID_LAYOUT = -12, 67 SPV_ERROR_INVALID_CAPABILITY = -13, 68 SPV_FORCE_32_BIT_ENUM(spv_result_t) 69 } spv_result_t; 70 71 typedef enum spv_endianness_t { 72 SPV_ENDIANNESS_LITTLE, 73 SPV_ENDIANNESS_BIG, 74 SPV_FORCE_32_BIT_ENUM(spv_endianness_t) 75 } spv_endianness_t; 76 77 // The kinds of operands that an instruction may have. 78 // 79 // Some operand types are "concrete". The binary parser uses a concrete 80 // operand type to describe an operand of a parsed instruction. 81 // 82 // The assembler uses all operand types. In addition to determining what 83 // kind of value an operand may be, non-concrete operand types capture the 84 // fact that an operand might be optional (may be absent, or present exactly 85 // once), or might occur zero or more times. 86 // 87 // Sometimes we also need to be able to express the fact that an operand 88 // is a member of an optional tuple of values. In that case the first member 89 // would be optional, and the subsequent members would be required. 90 typedef enum spv_operand_type_t { 91 // A sentinel value. 92 SPV_OPERAND_TYPE_NONE = 0, 93 94 #define FIRST_CONCRETE(ENUM) ENUM, SPV_OPERAND_TYPE_FIRST_CONCRETE_TYPE = ENUM 95 #define LAST_CONCRETE(ENUM) ENUM, SPV_OPERAND_TYPE_LAST_CONCRETE_TYPE = ENUM 96 97 // Set 1: Operands that are IDs. 98 FIRST_CONCRETE(SPV_OPERAND_TYPE_ID), 99 SPV_OPERAND_TYPE_TYPE_ID, 100 SPV_OPERAND_TYPE_RESULT_ID, 101 SPV_OPERAND_TYPE_MEMORY_SEMANTICS_ID, // SPIR-V Sec 3.25 102 SPV_OPERAND_TYPE_SCOPE_ID, // SPIR-V Sec 3.27 103 104 // Set 2: Operands that are literal numbers. 105 SPV_OPERAND_TYPE_LITERAL_INTEGER, // Always unsigned 32-bits. 106 // The Instruction argument to OpExtInst. It's an unsigned 32-bit literal 107 // number indicating which instruction to use from an extended instruction 108 // set. 109 SPV_OPERAND_TYPE_EXTENSION_INSTRUCTION_NUMBER, 110 // The Opcode argument to OpSpecConstantOp. It determines the operation 111 // to be performed on constant operands to compute a specialization constant 112 // result. 113 SPV_OPERAND_TYPE_SPEC_CONSTANT_OP_NUMBER, 114 // A literal number whose format and size are determined by a previous operand 115 // in the same instruction. It's a signed integer, an unsigned integer, or a 116 // floating point number. It also has a specified bit width. The width 117 // may be larger than 32, which would require such a typed literal value to 118 // occupy multiple SPIR-V words. 119 SPV_OPERAND_TYPE_TYPED_LITERAL_NUMBER, 120 121 // Set 3: The literal string operand type. 122 SPV_OPERAND_TYPE_LITERAL_STRING, 123 124 // Set 4: Operands that are a single word enumerated value. 125 SPV_OPERAND_TYPE_SOURCE_LANGUAGE, // SPIR-V Sec 3.2 126 SPV_OPERAND_TYPE_EXECUTION_MODEL, // SPIR-V Sec 3.3 127 SPV_OPERAND_TYPE_ADDRESSING_MODEL, // SPIR-V Sec 3.4 128 SPV_OPERAND_TYPE_MEMORY_MODEL, // SPIR-V Sec 3.5 129 SPV_OPERAND_TYPE_EXECUTION_MODE, // SPIR-V Sec 3.6 130 SPV_OPERAND_TYPE_STORAGE_CLASS, // SPIR-V Sec 3.7 131 SPV_OPERAND_TYPE_DIMENSIONALITY, // SPIR-V Sec 3.8 132 SPV_OPERAND_TYPE_SAMPLER_ADDRESSING_MODE, // SPIR-V Sec 3.9 133 SPV_OPERAND_TYPE_SAMPLER_FILTER_MODE, // SPIR-V Sec 3.10 134 SPV_OPERAND_TYPE_SAMPLER_IMAGE_FORMAT, // SPIR-V Sec 3.11 135 SPV_OPERAND_TYPE_IMAGE_CHANNEL_ORDER, // SPIR-V Sec 3.12 136 SPV_OPERAND_TYPE_IMAGE_CHANNEL_DATA_TYPE, // SPIR-V Sec 3.13 137 SPV_OPERAND_TYPE_FP_ROUNDING_MODE, // SPIR-V Sec 3.16 138 SPV_OPERAND_TYPE_LINKAGE_TYPE, // SPIR-V Sec 3.17 139 SPV_OPERAND_TYPE_ACCESS_QUALIFIER, // SPIR-V Sec 3.18 140 SPV_OPERAND_TYPE_FUNCTION_PARAMETER_ATTRIBUTE, // SPIR-V Sec 3.19 141 SPV_OPERAND_TYPE_DECORATION, // SPIR-V Sec 3.20 142 SPV_OPERAND_TYPE_BUILT_IN, // SPIR-V Sec 3.21 143 SPV_OPERAND_TYPE_GROUP_OPERATION, // SPIR-V Sec 3.28 144 SPV_OPERAND_TYPE_KERNEL_ENQ_FLAGS, // SPIR-V Sec 3.29 145 SPV_OPERAND_TYPE_KERNEL_PROFILING_INFO, // SPIR-V Sec 3.30 146 SPV_OPERAND_TYPE_CAPABILITY, // SPIR-V Sec 3.31 147 148 // Set 5: Operands that are a single word bitmask. 149 // Sometimes a set bit indicates the instruction requires still more operands. 150 #define FIRST_CONCRETE_MASK(ENUM) \ 151 ENUM, SPV_OPERAND_TYPE_FIRST_CONCRETE_MASK_TYPE = ENUM 152 FIRST_CONCRETE_MASK(SPV_OPERAND_TYPE_IMAGE), // SPIR-V Sec 3.14 153 SPV_OPERAND_TYPE_FP_FAST_MATH_MODE, // SPIR-V Sec 3.15 154 SPV_OPERAND_TYPE_SELECTION_CONTROL, // SPIR-V Sec 3.22 155 SPV_OPERAND_TYPE_LOOP_CONTROL, // SPIR-V Sec 3.23 156 SPV_OPERAND_TYPE_FUNCTION_CONTROL, // SPIR-V Sec 3.24 157 LAST_CONCRETE(SPV_OPERAND_TYPE_MEMORY_ACCESS), // SPIR-V Sec 3.26 158 SPV_OPERAND_TYPE_LAST_CONCRETE_MASK_TYPE = 159 SPV_OPERAND_TYPE_LAST_CONCRETE_TYPE, 160 #undef FIRST_CONCRETE_MASK 161 #undef FIRST_CONCRETE 162 #undef LAST_CONCRETE 163 164 // The remaining operand types are only used internally by the assembler. 165 // There are two categories: 166 // Optional : expands to 0 or 1 operand, like ? in regular expressions. 167 // Variable : expands to 0, 1 or many operands or pairs of operands. 168 // This is similar to * in regular expressions. 169 170 // Macros for defining bounds on optional and variable operand types. 171 // Any variable operand type is also optional. 172 #define FIRST_OPTIONAL(ENUM) ENUM, SPV_OPERAND_TYPE_FIRST_OPTIONAL_TYPE = ENUM 173 #define FIRST_VARIABLE(ENUM) ENUM, SPV_OPERAND_TYPE_FIRST_VARIABLE_TYPE = ENUM 174 #define LAST_VARIABLE(ENUM) \ 175 ENUM, SPV_OPERAND_TYPE_LAST_VARIABLE_TYPE = ENUM, \ 176 SPV_OPERAND_TYPE_LAST_OPTIONAL_TYPE = ENUM 177 178 // An optional operand represents zero or one logical operands. 179 // In an instruction definition, this may only appear at the end of the 180 // operand types. 181 FIRST_OPTIONAL(SPV_OPERAND_TYPE_OPTIONAL_ID), 182 // An optional image operand type. 183 SPV_OPERAND_TYPE_OPTIONAL_IMAGE, 184 // An optional memory access type. 185 SPV_OPERAND_TYPE_OPTIONAL_MEMORY_ACCESS, 186 // An optional literal integer. 187 SPV_OPERAND_TYPE_OPTIONAL_LITERAL_INTEGER, 188 // An optional literal number, which may be either integer or floating point. 189 SPV_OPERAND_TYPE_OPTIONAL_LITERAL_NUMBER, 190 // Like SPV_OPERAND_TYPE_TYPED_LITERAL_NUMBER, but optional, and integral. 191 SPV_OPERAND_TYPE_OPTIONAL_TYPED_LITERAL_INTEGER, 192 // An optional literal string. 193 SPV_OPERAND_TYPE_OPTIONAL_LITERAL_STRING, 194 // An optional access qualifier 195 SPV_OPERAND_TYPE_OPTIONAL_ACCESS_QUALIFIER, 196 // An optional context-independent value, or CIV. CIVs are tokens that we can 197 // assemble regardless of where they occur -- literals, IDs, immediate 198 // integers, etc. 199 SPV_OPERAND_TYPE_OPTIONAL_CIV, 200 201 // A variable operand represents zero or more logical operands. 202 // In an instruction definition, this may only appear at the end of the 203 // operand types. 204 FIRST_VARIABLE(SPV_OPERAND_TYPE_VARIABLE_ID), 205 SPV_OPERAND_TYPE_VARIABLE_LITERAL_INTEGER, 206 // A sequence of zero or more pairs of (typed literal integer, Id). 207 // Expands to zero or more: 208 // (SPV_OPERAND_TYPE_TYPED_LITERAL_INTEGER, SPV_OPERAND_TYPE_ID) 209 // where the literal number must always be an integer of some sort. 210 SPV_OPERAND_TYPE_VARIABLE_LITERAL_INTEGER_ID, 211 // A sequence of zero or more pairs of (Id, Literal integer) 212 LAST_VARIABLE(SPV_OPERAND_TYPE_VARIABLE_ID_LITERAL_INTEGER), 213 214 // This is a sentinel value, and does not represent an operand type. 215 // It should come last. 216 SPV_OPERAND_TYPE_NUM_OPERAND_TYPES, 217 218 SPV_FORCE_32_BIT_ENUM(spv_operand_type_t) 219 } spv_operand_type_t; 220 221 typedef enum spv_ext_inst_type_t { 222 SPV_EXT_INST_TYPE_NONE = 0, 223 SPV_EXT_INST_TYPE_GLSL_STD_450, 224 SPV_EXT_INST_TYPE_OPENCL_STD, 225 226 SPV_FORCE_32_BIT_ENUM(spv_ext_inst_type_t) 227 } spv_ext_inst_type_t; 228 229 // This determines at a high level the kind of a binary-encoded literal 230 // number, but not the bit width. 231 // In principle, these could probably be folded into new entries in 232 // spv_operand_type_t. But then we'd have some special case differences 233 // between the assembler and disassembler. 234 typedef enum spv_number_kind_t { 235 SPV_NUMBER_NONE = 0, // The default for value initialization. 236 SPV_NUMBER_UNSIGNED_INT, 237 SPV_NUMBER_SIGNED_INT, 238 SPV_NUMBER_FLOATING, 239 } spv_number_kind_t; 240 241 typedef enum spv_binary_to_text_options_t { 242 SPV_BINARY_TO_TEXT_OPTION_NONE = SPV_BIT(0), 243 SPV_BINARY_TO_TEXT_OPTION_PRINT = SPV_BIT(1), 244 SPV_BINARY_TO_TEXT_OPTION_COLOR = SPV_BIT(2), 245 SPV_BINARY_TO_TEXT_OPTION_INDENT = SPV_BIT(3), 246 SPV_BINARY_TO_TEXT_OPTION_SHOW_BYTE_OFFSET = SPV_BIT(4), 247 // Do not output the module header as leading comments in the assembly. 248 SPV_BINARY_TO_TEXT_OPTION_NO_HEADER = SPV_BIT(5), 249 // Use friendly names where possible. The heuristic may expand over 250 // time, but will use common names for scalar types, and debug names from 251 // OpName instructions. 252 SPV_BINARY_TO_TEXT_OPTION_FRIENDLY_NAMES = SPV_BIT(6), 253 SPV_FORCE_32_BIT_ENUM(spv_binary_to_text_options_t) 254 } spv_binary_to_text_options_t; 255 256 // Structures 257 258 // Information about an operand parsed from a binary SPIR-V module. 259 // Note that the values are not included. You still need access to the binary 260 // to extract the values. 261 typedef struct spv_parsed_operand_t { 262 // Location of the operand, in words from the start of the instruction. 263 uint16_t offset; 264 // Number of words occupied by this operand. 265 uint16_t num_words; 266 // The "concrete" operand type. See the definition of spv_operand_type_t 267 // for details. 268 spv_operand_type_t type; 269 // If type is a literal number type, then number_kind says whether it's 270 // a signed integer, an unsigned integer, or a floating point number. 271 spv_number_kind_t number_kind; 272 // The number of bits for a literal number type. 273 uint32_t number_bit_width; 274 } spv_parsed_operand_t; 275 276 // An instruction parsed from a binary SPIR-V module. 277 typedef struct spv_parsed_instruction_t { 278 // An array of words for this instruction, in native endianness. 279 const uint32_t* words; 280 // The number of words in this instruction. 281 uint16_t num_words; 282 uint16_t opcode; 283 // The extended instruction type, if opcode is OpExtInst. Otherwise 284 // this is the "none" value. 285 spv_ext_inst_type_t ext_inst_type; 286 // The type id, or 0 if this instruction doesn't have one. 287 uint32_t type_id; 288 // The result id, or 0 if this instruction doesn't have one. 289 uint32_t result_id; 290 // The array of parsed operands. 291 const spv_parsed_operand_t* operands; 292 uint16_t num_operands; 293 } spv_parsed_instruction_t; 294 295 typedef struct spv_const_binary_t { 296 const uint32_t* code; 297 const size_t wordCount; 298 } spv_const_binary_t; 299 300 typedef struct spv_binary_t { 301 uint32_t* code; 302 size_t wordCount; 303 } spv_binary_t; 304 305 typedef struct spv_text_t { 306 const char* str; 307 size_t length; 308 } spv_text_t; 309 310 typedef struct spv_position_t { 311 size_t line; 312 size_t column; 313 size_t index; 314 } spv_position_t; 315 316 typedef struct spv_diagnostic_t { 317 spv_position_t position; 318 char* error; 319 bool isTextSource; 320 } spv_diagnostic_t; 321 322 // Opaque struct containing the context used to operate on a SPIR-V module. 323 // Its object is used by various translation API functions. 324 typedef struct spv_context_t spv_context_t; 325 326 // Type Definitions 327 328 typedef spv_const_binary_t* spv_const_binary; 329 typedef spv_binary_t* spv_binary; 330 typedef spv_text_t* spv_text; 331 typedef spv_position_t* spv_position; 332 typedef spv_diagnostic_t* spv_diagnostic; 333 typedef const spv_context_t* spv_const_context; 334 typedef spv_context_t* spv_context; 335 336 // Platform API 337 338 // Returns the SPIRV-Tools software version as a null-terminated string. 339 // The contents of the underlying storage is valid for the remainder of 340 // the process. 341 const char* spvSoftwareVersionString(); 342 // Returns a null-terminated string containing the name of the project, 343 // the software version string, and commit details. 344 // The contents of the underlying storage is valid for the remainder of 345 // the process. 346 const char* spvSoftwareVersionDetailsString(); 347 348 // Certain target environments impose additional restrictions on SPIR-V, so it's 349 // often necessary to specify which one applies. SPV_ENV_UNIVERSAL means 350 // environment-agnostic SPIR-V. 351 typedef enum { 352 SPV_ENV_UNIVERSAL_1_0, // SPIR-V 1.0 latest revision, no other restrictions. 353 SPV_ENV_VULKAN_1_0, // Vulkan 1.0 latest revision. 354 SPV_ENV_UNIVERSAL_1_1, // SPIR-V 1.1 latest revision, no other restrictions. 355 } spv_target_env; 356 357 // Returns a string describing the given SPIR-V target environment. 358 const char* spvTargetEnvDescription(spv_target_env env); 359 360 // Creates a context object. Returns null if env is invalid. 361 spv_context spvContextCreate(spv_target_env env); 362 363 // Destroys the given context object. 364 void spvContextDestroy(spv_context context); 365 366 // Encodes the given SPIR-V assembly text to its binary representation. The 367 // length parameter specifies the number of bytes for text. Encoded binary will 368 // be stored into *binary. Any error will be written into *diagnostic. The 369 // generated binary is independent of the context and may outlive it. 370 spv_result_t spvTextToBinary(const spv_const_context context, const char* text, 371 const size_t length, spv_binary* binary, 372 spv_diagnostic* diagnostic); 373 374 // Frees an allocated text stream. This is a no-op if the text parameter 375 // is a null pointer. 376 void spvTextDestroy(spv_text text); 377 378 // Decodes the given SPIR-V binary representation to its assembly text. The 379 // word_count parameter specifies the number of words for binary. The options 380 // parameter is a bit field of spv_binary_to_text_options_t. Decoded text will 381 // be stored into *text. Any error will be written into *diagnostic. 382 spv_result_t spvBinaryToText(const spv_const_context context, 383 const uint32_t* binary, const size_t word_count, 384 const uint32_t options, spv_text* text, 385 spv_diagnostic* diagnostic); 386 387 // Frees a binary stream from memory. This is a no-op if binary is a null 388 // pointer. 389 void spvBinaryDestroy(spv_binary binary); 390 391 // Validates a SPIR-V binary for correctness. Any errors will be written into 392 // *diagnostic. 393 spv_result_t spvValidate(const spv_const_context context, 394 const spv_const_binary binary, 395 spv_diagnostic* diagnostic); 396 397 // Creates a diagnostic object. The position parameter specifies the location in 398 // the text/binary stream. The message parameter, copied into the diagnostic 399 // object, contains the error message to display. 400 spv_diagnostic spvDiagnosticCreate(const spv_position position, 401 const char* message); 402 403 // Destroys a diagnostic object. This is a no-op if diagnostic is a null 404 // pointer. 405 void spvDiagnosticDestroy(spv_diagnostic diagnostic); 406 407 // Prints the diagnostic to stderr. 408 spv_result_t spvDiagnosticPrint(const spv_diagnostic diagnostic); 409 410 // The binary parser interface. 411 412 // A pointer to a function that accepts a parsed SPIR-V header. 413 // The integer arguments are the 32-bit words from the header, as specified 414 // in SPIR-V 1.0 Section 2.3 Table 1. 415 // The function should return SPV_SUCCESS if parsing should continue. 416 typedef spv_result_t (*spv_parsed_header_fn_t)( 417 void* user_data, spv_endianness_t endian, uint32_t magic, uint32_t version, 418 uint32_t generator, uint32_t id_bound, uint32_t reserved); 419 420 // A pointer to a function that accepts a parsed SPIR-V instruction. 421 // The parsed_instruction value is transient: it may be overwritten 422 // or released immediately after the function has returned. That also 423 // applies to the words array member of the parsed instruction. The 424 // function should return SPV_SUCCESS if and only if parsing should 425 // continue. 426 typedef spv_result_t (*spv_parsed_instruction_fn_t)( 427 void* user_data, const spv_parsed_instruction_t* parsed_instruction); 428 429 // Parses a SPIR-V binary, specified as counted sequence of 32-bit words. 430 // Parsing feedback is provided via two callbacks provided as function 431 // pointers. Each callback function pointer can be a null pointer, in 432 // which case it is never called. Otherwise, in a valid parse the 433 // parsed-header callback is called once, and then the parsed-instruction 434 // callback once for each instruction in the stream. The user_data parameter 435 // is supplied as context to the callbacks. Returns SPV_SUCCESS on successful 436 // parse where the callbacks always return SPV_SUCCESS. For an invalid parse, 437 // returns a status code other than SPV_SUCCESS and emits a diagnostic. If a 438 // callback returns anything other than SPV_SUCCESS, then that status code 439 // is returned, no further callbacks are issued, and no additional diagnostics 440 // are emitted. 441 spv_result_t spvBinaryParse(const spv_const_context context, void* user_data, 442 const uint32_t* words, const size_t num_words, 443 spv_parsed_header_fn_t parse_header, 444 spv_parsed_instruction_fn_t parse_instruction, 445 spv_diagnostic* diagnostic); 446 447 #ifdef __cplusplus 448 } 449 #endif 450 451 #endif // SPIRV_TOOLS_LIBSPIRV_H_ 452
