1 // Copyright (c) 2015-2016 The Khronos Group Inc. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef SPIRV_TOOLS_LIBSPIRV_H_ 16 #define SPIRV_TOOLS_LIBSPIRV_H_ 17 18 #ifdef __cplusplus 19 extern "C" { 20 #else 21 #include <stdbool.h> 22 #endif 23 24 #include <stddef.h> 25 #include <stdint.h> 26 27 #if defined(SPIRV_TOOLS_SHAREDLIB) 28 #if defined(_WIN32) 29 #if defined(SPIRV_TOOLS_IMPLEMENTATION) 30 #define SPIRV_TOOLS_EXPORT __declspec(dllexport) 31 #else 32 #define SPIRV_TOOLS_EXPORT __declspec(dllimport) 33 #endif 34 #else 35 #if defined(SPIRV_TOOLS_IMPLEMENTATION) 36 #define SPIRV_TOOLS_EXPORT __attribute__((visibility("default"))) 37 #else 38 #define SPIRV_TOOLS_EXPORT 39 #endif 40 #endif 41 #else 42 #define SPIRV_TOOLS_EXPORT 43 #endif 44 45 // Helpers 46 47 #define SPV_BIT(shift) (1 << (shift)) 48 49 #define SPV_FORCE_16_BIT_ENUM(name) _##name = 0x7fff 50 #define SPV_FORCE_32_BIT_ENUM(name) _##name = 0x7fffffff 51 52 // Enumerations 53 54 typedef enum spv_result_t { 55 SPV_SUCCESS = 0, 56 SPV_UNSUPPORTED = 1, 57 SPV_END_OF_STREAM = 2, 58 SPV_WARNING = 3, 59 SPV_FAILED_MATCH = 4, 60 SPV_REQUESTED_TERMINATION = 5, // Success, but signals early termination. 61 SPV_ERROR_INTERNAL = -1, 62 SPV_ERROR_OUT_OF_MEMORY = -2, 63 SPV_ERROR_INVALID_POINTER = -3, 64 SPV_ERROR_INVALID_BINARY = -4, 65 SPV_ERROR_INVALID_TEXT = -5, 66 SPV_ERROR_INVALID_TABLE = -6, 67 SPV_ERROR_INVALID_VALUE = -7, 68 SPV_ERROR_INVALID_DIAGNOSTIC = -8, 69 SPV_ERROR_INVALID_LOOKUP = -9, 70 SPV_ERROR_INVALID_ID = -10, 71 SPV_ERROR_INVALID_CFG = -11, 72 SPV_ERROR_INVALID_LAYOUT = -12, 73 SPV_ERROR_INVALID_CAPABILITY = -13, 74 SPV_ERROR_INVALID_DATA = -14, // Indicates data rules validation failure. 75 SPV_ERROR_MISSING_EXTENSION = -15, 76 SPV_ERROR_WRONG_VERSION = -16, // Indicates wrong SPIR-V version 77 SPV_FORCE_32_BIT_ENUM(spv_result_t) 78 } spv_result_t; 79 80 // Severity levels of messages communicated to the consumer. 81 typedef enum spv_message_level_t { 82 SPV_MSG_FATAL, // Unrecoverable error due to environment. 83 // Will exit the program immediately. E.g., 84 // out of memory. 85 SPV_MSG_INTERNAL_ERROR, // Unrecoverable error due to SPIRV-Tools 86 // internals. 87 // Will exit the program immediately. E.g., 88 // unimplemented feature. 89 SPV_MSG_ERROR, // Normal error due to user input. 90 SPV_MSG_WARNING, // Warning information. 91 SPV_MSG_INFO, // General information. 92 SPV_MSG_DEBUG, // Debug information. 93 } spv_message_level_t; 94 95 typedef enum spv_endianness_t { 96 SPV_ENDIANNESS_LITTLE, 97 SPV_ENDIANNESS_BIG, 98 SPV_FORCE_32_BIT_ENUM(spv_endianness_t) 99 } spv_endianness_t; 100 101 // The kinds of operands that an instruction may have. 102 // 103 // Some operand types are "concrete". The binary parser uses a concrete 104 // operand type to describe an operand of a parsed instruction. 105 // 106 // The assembler uses all operand types. In addition to determining what 107 // kind of value an operand may be, non-concrete operand types capture the 108 // fact that an operand might be optional (may be absent, or present exactly 109 // once), or might occur zero or more times. 110 // 111 // Sometimes we also need to be able to express the fact that an operand 112 // is a member of an optional tuple of values. In that case the first member 113 // would be optional, and the subsequent members would be required. 114 typedef enum spv_operand_type_t { 115 // A sentinel value. 116 SPV_OPERAND_TYPE_NONE = 0, 117 118 // Set 1: Operands that are IDs. 119 SPV_OPERAND_TYPE_ID, 120 SPV_OPERAND_TYPE_TYPE_ID, 121 SPV_OPERAND_TYPE_RESULT_ID, 122 SPV_OPERAND_TYPE_MEMORY_SEMANTICS_ID, // SPIR-V Sec 3.25 123 SPV_OPERAND_TYPE_SCOPE_ID, // SPIR-V Sec 3.27 124 125 // Set 2: Operands that are literal numbers. 126 SPV_OPERAND_TYPE_LITERAL_INTEGER, // Always unsigned 32-bits. 127 // The Instruction argument to OpExtInst. It's an unsigned 32-bit literal 128 // number indicating which instruction to use from an extended instruction 129 // set. 130 SPV_OPERAND_TYPE_EXTENSION_INSTRUCTION_NUMBER, 131 // The Opcode argument to OpSpecConstantOp. It determines the operation 132 // to be performed on constant operands to compute a specialization constant 133 // result. 134 SPV_OPERAND_TYPE_SPEC_CONSTANT_OP_NUMBER, 135 // A literal number whose format and size are determined by a previous operand 136 // in the same instruction. It's a signed integer, an unsigned integer, or a 137 // floating point number. It also has a specified bit width. The width 138 // may be larger than 32, which would require such a typed literal value to 139 // occupy multiple SPIR-V words. 140 SPV_OPERAND_TYPE_TYPED_LITERAL_NUMBER, 141 142 // Set 3: The literal string operand type. 143 SPV_OPERAND_TYPE_LITERAL_STRING, 144 145 // Set 4: Operands that are a single word enumerated value. 146 SPV_OPERAND_TYPE_SOURCE_LANGUAGE, // SPIR-V Sec 3.2 147 SPV_OPERAND_TYPE_EXECUTION_MODEL, // SPIR-V Sec 3.3 148 SPV_OPERAND_TYPE_ADDRESSING_MODEL, // SPIR-V Sec 3.4 149 SPV_OPERAND_TYPE_MEMORY_MODEL, // SPIR-V Sec 3.5 150 SPV_OPERAND_TYPE_EXECUTION_MODE, // SPIR-V Sec 3.6 151 SPV_OPERAND_TYPE_STORAGE_CLASS, // SPIR-V Sec 3.7 152 SPV_OPERAND_TYPE_DIMENSIONALITY, // SPIR-V Sec 3.8 153 SPV_OPERAND_TYPE_SAMPLER_ADDRESSING_MODE, // SPIR-V Sec 3.9 154 SPV_OPERAND_TYPE_SAMPLER_FILTER_MODE, // SPIR-V Sec 3.10 155 SPV_OPERAND_TYPE_SAMPLER_IMAGE_FORMAT, // SPIR-V Sec 3.11 156 SPV_OPERAND_TYPE_IMAGE_CHANNEL_ORDER, // SPIR-V Sec 3.12 157 SPV_OPERAND_TYPE_IMAGE_CHANNEL_DATA_TYPE, // SPIR-V Sec 3.13 158 SPV_OPERAND_TYPE_FP_ROUNDING_MODE, // SPIR-V Sec 3.16 159 SPV_OPERAND_TYPE_LINKAGE_TYPE, // SPIR-V Sec 3.17 160 SPV_OPERAND_TYPE_ACCESS_QUALIFIER, // SPIR-V Sec 3.18 161 SPV_OPERAND_TYPE_FUNCTION_PARAMETER_ATTRIBUTE, // SPIR-V Sec 3.19 162 SPV_OPERAND_TYPE_DECORATION, // SPIR-V Sec 3.20 163 SPV_OPERAND_TYPE_BUILT_IN, // SPIR-V Sec 3.21 164 SPV_OPERAND_TYPE_GROUP_OPERATION, // SPIR-V Sec 3.28 165 SPV_OPERAND_TYPE_KERNEL_ENQ_FLAGS, // SPIR-V Sec 3.29 166 SPV_OPERAND_TYPE_KERNEL_PROFILING_INFO, // SPIR-V Sec 3.30 167 SPV_OPERAND_TYPE_CAPABILITY, // SPIR-V Sec 3.31 168 169 // Set 5: Operands that are a single word bitmask. 170 // Sometimes a set bit indicates the instruction requires still more operands. 171 SPV_OPERAND_TYPE_IMAGE, // SPIR-V Sec 3.14 172 SPV_OPERAND_TYPE_FP_FAST_MATH_MODE, // SPIR-V Sec 3.15 173 SPV_OPERAND_TYPE_SELECTION_CONTROL, // SPIR-V Sec 3.22 174 SPV_OPERAND_TYPE_LOOP_CONTROL, // SPIR-V Sec 3.23 175 SPV_OPERAND_TYPE_FUNCTION_CONTROL, // SPIR-V Sec 3.24 176 SPV_OPERAND_TYPE_MEMORY_ACCESS, // SPIR-V Sec 3.26 177 178 // The remaining operand types are only used internally by the assembler. 179 // There are two categories: 180 // Optional : expands to 0 or 1 operand, like ? in regular expressions. 181 // Variable : expands to 0, 1 or many operands or pairs of operands. 182 // This is similar to * in regular expressions. 183 184 // Macros for defining bounds on optional and variable operand types. 185 // Any variable operand type is also optional. 186 #define FIRST_OPTIONAL(ENUM) ENUM, SPV_OPERAND_TYPE_FIRST_OPTIONAL_TYPE = ENUM 187 #define FIRST_VARIABLE(ENUM) ENUM, SPV_OPERAND_TYPE_FIRST_VARIABLE_TYPE = ENUM 188 #define LAST_VARIABLE(ENUM) \ 189 ENUM, SPV_OPERAND_TYPE_LAST_VARIABLE_TYPE = ENUM, \ 190 SPV_OPERAND_TYPE_LAST_OPTIONAL_TYPE = ENUM 191 192 // An optional operand represents zero or one logical operands. 193 // In an instruction definition, this may only appear at the end of the 194 // operand types. 195 FIRST_OPTIONAL(SPV_OPERAND_TYPE_OPTIONAL_ID), 196 // An optional image operand type. 197 SPV_OPERAND_TYPE_OPTIONAL_IMAGE, 198 // An optional memory access type. 199 SPV_OPERAND_TYPE_OPTIONAL_MEMORY_ACCESS, 200 // An optional literal integer. 201 SPV_OPERAND_TYPE_OPTIONAL_LITERAL_INTEGER, 202 // An optional literal number, which may be either integer or floating point. 203 SPV_OPERAND_TYPE_OPTIONAL_LITERAL_NUMBER, 204 // Like SPV_OPERAND_TYPE_TYPED_LITERAL_NUMBER, but optional, and integral. 205 SPV_OPERAND_TYPE_OPTIONAL_TYPED_LITERAL_INTEGER, 206 // An optional literal string. 207 SPV_OPERAND_TYPE_OPTIONAL_LITERAL_STRING, 208 // An optional access qualifier 209 SPV_OPERAND_TYPE_OPTIONAL_ACCESS_QUALIFIER, 210 // An optional context-independent value, or CIV. CIVs are tokens that we can 211 // assemble regardless of where they occur -- literals, IDs, immediate 212 // integers, etc. 213 SPV_OPERAND_TYPE_OPTIONAL_CIV, 214 215 // A variable operand represents zero or more logical operands. 216 // In an instruction definition, this may only appear at the end of the 217 // operand types. 218 FIRST_VARIABLE(SPV_OPERAND_TYPE_VARIABLE_ID), 219 SPV_OPERAND_TYPE_VARIABLE_LITERAL_INTEGER, 220 // A sequence of zero or more pairs of (typed literal integer, Id). 221 // Expands to zero or more: 222 // (SPV_OPERAND_TYPE_TYPED_LITERAL_INTEGER, SPV_OPERAND_TYPE_ID) 223 // where the literal number must always be an integer of some sort. 224 SPV_OPERAND_TYPE_VARIABLE_LITERAL_INTEGER_ID, 225 // A sequence of zero or more pairs of (Id, Literal integer) 226 LAST_VARIABLE(SPV_OPERAND_TYPE_VARIABLE_ID_LITERAL_INTEGER), 227 228 // The following are concrete enum types. 229 SPV_OPERAND_TYPE_DEBUG_INFO_FLAGS, // DebugInfo Sec 3.2. A mask. 230 SPV_OPERAND_TYPE_DEBUG_BASE_TYPE_ATTRIBUTE_ENCODING, // DebugInfo Sec 3.3 231 SPV_OPERAND_TYPE_DEBUG_COMPOSITE_TYPE, // DebugInfo Sec 3.4 232 SPV_OPERAND_TYPE_DEBUG_TYPE_QUALIFIER, // DebugInfo Sec 3.5 233 SPV_OPERAND_TYPE_DEBUG_OPERATION, // DebugInfo Sec 3.6 234 235 // This is a sentinel value, and does not represent an operand type. 236 // It should come last. 237 SPV_OPERAND_TYPE_NUM_OPERAND_TYPES, 238 239 SPV_FORCE_32_BIT_ENUM(spv_operand_type_t) 240 } spv_operand_type_t; 241 242 typedef enum spv_ext_inst_type_t { 243 SPV_EXT_INST_TYPE_NONE = 0, 244 SPV_EXT_INST_TYPE_GLSL_STD_450, 245 SPV_EXT_INST_TYPE_OPENCL_STD, 246 SPV_EXT_INST_TYPE_SPV_AMD_SHADER_EXPLICIT_VERTEX_PARAMETER, 247 SPV_EXT_INST_TYPE_SPV_AMD_SHADER_TRINARY_MINMAX, 248 SPV_EXT_INST_TYPE_SPV_AMD_GCN_SHADER, 249 SPV_EXT_INST_TYPE_SPV_AMD_SHADER_BALLOT, 250 SPV_EXT_INST_TYPE_DEBUGINFO, 251 252 SPV_FORCE_32_BIT_ENUM(spv_ext_inst_type_t) 253 } spv_ext_inst_type_t; 254 255 // This determines at a high level the kind of a binary-encoded literal 256 // number, but not the bit width. 257 // In principle, these could probably be folded into new entries in 258 // spv_operand_type_t. But then we'd have some special case differences 259 // between the assembler and disassembler. 260 typedef enum spv_number_kind_t { 261 SPV_NUMBER_NONE = 0, // The default for value initialization. 262 SPV_NUMBER_UNSIGNED_INT, 263 SPV_NUMBER_SIGNED_INT, 264 SPV_NUMBER_FLOATING, 265 } spv_number_kind_t; 266 267 typedef enum spv_text_to_binary_options_t { 268 SPV_TEXT_TO_BINARY_OPTION_NONE = SPV_BIT(0), 269 // Numeric IDs in the binary will have the same values as in the source. 270 // Non-numeric IDs are allocated by filling in the gaps, starting with 1 271 // and going up. 272 SPV_TEXT_TO_BINARY_OPTION_PRESERVE_NUMERIC_IDS = SPV_BIT(1), 273 SPV_FORCE_32_BIT_ENUM(spv_text_to_binary_options_t) 274 } spv_text_to_binary_options_t; 275 276 typedef enum spv_binary_to_text_options_t { 277 SPV_BINARY_TO_TEXT_OPTION_NONE = SPV_BIT(0), 278 SPV_BINARY_TO_TEXT_OPTION_PRINT = SPV_BIT(1), 279 SPV_BINARY_TO_TEXT_OPTION_COLOR = SPV_BIT(2), 280 SPV_BINARY_TO_TEXT_OPTION_INDENT = SPV_BIT(3), 281 SPV_BINARY_TO_TEXT_OPTION_SHOW_BYTE_OFFSET = SPV_BIT(4), 282 // Do not output the module header as leading comments in the assembly. 283 SPV_BINARY_TO_TEXT_OPTION_NO_HEADER = SPV_BIT(5), 284 // Use friendly names where possible. The heuristic may expand over 285 // time, but will use common names for scalar types, and debug names from 286 // OpName instructions. 287 SPV_BINARY_TO_TEXT_OPTION_FRIENDLY_NAMES = SPV_BIT(6), 288 SPV_FORCE_32_BIT_ENUM(spv_binary_to_text_options_t) 289 } spv_binary_to_text_options_t; 290 291 // Structures 292 293 // Information about an operand parsed from a binary SPIR-V module. 294 // Note that the values are not included. You still need access to the binary 295 // to extract the values. 296 typedef struct spv_parsed_operand_t { 297 // Location of the operand, in words from the start of the instruction. 298 uint16_t offset; 299 // Number of words occupied by this operand. 300 uint16_t num_words; 301 // The "concrete" operand type. See the definition of spv_operand_type_t 302 // for details. 303 spv_operand_type_t type; 304 // If type is a literal number type, then number_kind says whether it's 305 // a signed integer, an unsigned integer, or a floating point number. 306 spv_number_kind_t number_kind; 307 // The number of bits for a literal number type. 308 uint32_t number_bit_width; 309 } spv_parsed_operand_t; 310 311 // An instruction parsed from a binary SPIR-V module. 312 typedef struct spv_parsed_instruction_t { 313 // An array of words for this instruction, in native endianness. 314 const uint32_t* words; 315 // The number of words in this instruction. 316 uint16_t num_words; 317 uint16_t opcode; 318 // The extended instruction type, if opcode is OpExtInst. Otherwise 319 // this is the "none" value. 320 spv_ext_inst_type_t ext_inst_type; 321 // The type id, or 0 if this instruction doesn't have one. 322 uint32_t type_id; 323 // The result id, or 0 if this instruction doesn't have one. 324 uint32_t result_id; 325 // The array of parsed operands. 326 const spv_parsed_operand_t* operands; 327 uint16_t num_operands; 328 } spv_parsed_instruction_t; 329 330 typedef struct spv_const_binary_t { 331 const uint32_t* code; 332 const size_t wordCount; 333 } spv_const_binary_t; 334 335 typedef struct spv_binary_t { 336 uint32_t* code; 337 size_t wordCount; 338 } spv_binary_t; 339 340 typedef struct spv_text_t { 341 const char* str; 342 size_t length; 343 } spv_text_t; 344 345 typedef struct spv_position_t { 346 size_t line; 347 size_t column; 348 size_t index; 349 } spv_position_t; 350 351 typedef struct spv_diagnostic_t { 352 spv_position_t position; 353 char* error; 354 bool isTextSource; 355 } spv_diagnostic_t; 356 357 // Opaque struct containing the context used to operate on a SPIR-V module. 358 // Its object is used by various translation API functions. 359 typedef struct spv_context_t spv_context_t; 360 361 typedef struct spv_validator_options_t spv_validator_options_t; 362 363 // Type Definitions 364 365 typedef spv_const_binary_t* spv_const_binary; 366 typedef spv_binary_t* spv_binary; 367 typedef spv_text_t* spv_text; 368 typedef spv_position_t* spv_position; 369 typedef spv_diagnostic_t* spv_diagnostic; 370 typedef const spv_context_t* spv_const_context; 371 typedef spv_context_t* spv_context; 372 typedef spv_validator_options_t* spv_validator_options; 373 typedef const spv_validator_options_t* spv_const_validator_options; 374 375 // Platform API 376 377 // Returns the SPIRV-Tools software version as a null-terminated string. 378 // The contents of the underlying storage is valid for the remainder of 379 // the process. 380 SPIRV_TOOLS_EXPORT const char* spvSoftwareVersionString(void); 381 // Returns a null-terminated string containing the name of the project, 382 // the software version string, and commit details. 383 // The contents of the underlying storage is valid for the remainder of 384 // the process. 385 SPIRV_TOOLS_EXPORT const char* spvSoftwareVersionDetailsString(void); 386 387 // Certain target environments impose additional restrictions on SPIR-V, so it's 388 // often necessary to specify which one applies. SPV_ENV_UNIVERSAL means 389 // environment-agnostic SPIR-V. 390 typedef enum { 391 SPV_ENV_UNIVERSAL_1_0, // SPIR-V 1.0 latest revision, no other restrictions. 392 SPV_ENV_VULKAN_1_0, // Vulkan 1.0 latest revision. 393 SPV_ENV_UNIVERSAL_1_1, // SPIR-V 1.1 latest revision, no other restrictions. 394 SPV_ENV_OPENCL_2_1, // OpenCL Full Profile 2.1 latest revision. 395 SPV_ENV_OPENCL_2_2, // OpenCL Full Profile 2.2 latest revision. 396 SPV_ENV_OPENGL_4_0, // OpenGL 4.0 plus GL_ARB_gl_spirv, latest revisions. 397 SPV_ENV_OPENGL_4_1, // OpenGL 4.1 plus GL_ARB_gl_spirv, latest revisions. 398 SPV_ENV_OPENGL_4_2, // OpenGL 4.2 plus GL_ARB_gl_spirv, latest revisions. 399 SPV_ENV_OPENGL_4_3, // OpenGL 4.3 plus GL_ARB_gl_spirv, latest revisions. 400 // There is no variant for OpenGL 4.4. 401 SPV_ENV_OPENGL_4_5, // OpenGL 4.5 plus GL_ARB_gl_spirv, latest revisions. 402 SPV_ENV_UNIVERSAL_1_2, // SPIR-V 1.2, latest revision, no other restrictions. 403 SPV_ENV_OPENCL_1_2, // OpenCL Full Profile 1.2 plus cl_khr_il_program, 404 // latest revision. 405 SPV_ENV_OPENCL_EMBEDDED_1_2, // OpenCL Embedded Profile 1.2 plus 406 // cl_khr_il_program, latest revision. 407 SPV_ENV_OPENCL_2_0, // OpenCL Full Profile 2.0 plus cl_khr_il_program, 408 // latest revision. 409 SPV_ENV_OPENCL_EMBEDDED_2_0, // OpenCL Embedded Profile 2.0 plus 410 // cl_khr_il_program, latest revision. 411 SPV_ENV_OPENCL_EMBEDDED_2_1, // OpenCL Embedded Profile 2.1 latest revision. 412 SPV_ENV_OPENCL_EMBEDDED_2_2, // OpenCL Embedded Profile 2.2 latest revision. 413 SPV_ENV_UNIVERSAL_1_3, // SPIR-V 1.3 latest revision, no other restrictions. 414 SPV_ENV_VULKAN_1_1, // Vulkan 1.1 latest revision. 415 SPV_ENV_WEBGPU_0, // Work in progress WebGPU 1.0. 416 } spv_target_env; 417 418 // SPIR-V Validator can be parameterized with the following Universal Limits. 419 typedef enum { 420 spv_validator_limit_max_struct_members, 421 spv_validator_limit_max_struct_depth, 422 spv_validator_limit_max_local_variables, 423 spv_validator_limit_max_global_variables, 424 spv_validator_limit_max_switch_branches, 425 spv_validator_limit_max_function_args, 426 spv_validator_limit_max_control_flow_nesting_depth, 427 spv_validator_limit_max_access_chain_indexes, 428 } spv_validator_limit; 429 430 // Returns a string describing the given SPIR-V target environment. 431 SPIRV_TOOLS_EXPORT const char* spvTargetEnvDescription(spv_target_env env); 432 433 // Creates a context object. Returns null if env is invalid. 434 SPIRV_TOOLS_EXPORT spv_context spvContextCreate(spv_target_env env); 435 436 // Destroys the given context object. 437 SPIRV_TOOLS_EXPORT void spvContextDestroy(spv_context context); 438 439 // Creates a Validator options object with default options. Returns a valid 440 // options object. The object remains valid until it is passed into 441 // spvValidatorOptionsDestroy. 442 SPIRV_TOOLS_EXPORT spv_validator_options spvValidatorOptionsCreate(void); 443 444 // Destroys the given Validator options object. 445 SPIRV_TOOLS_EXPORT void spvValidatorOptionsDestroy( 446 spv_validator_options options); 447 448 // Records the maximum Universal Limit that is considered valid in the given 449 // Validator options object. <options> argument must be a valid options object. 450 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetUniversalLimit( 451 spv_validator_options options, spv_validator_limit limit_type, 452 uint32_t limit); 453 454 // Record whether or not the validator should relax the rules on types for 455 // stores to structs. When relaxed, it will allow a type mismatch as long as 456 // the types are structs with the same layout. Two structs have the same layout 457 // if 458 // 459 // 1) the members of the structs are either the same type or are structs with 460 // same layout, and 461 // 462 // 2) the decorations that affect the memory layout are identical for both 463 // types. Other decorations are not relevant. 464 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetRelaxStoreStruct( 465 spv_validator_options options, bool val); 466 467 // Records whether or not the validator should relax the rules on pointer usage 468 // in logical addressing mode. 469 // 470 // When relaxed, it will allow the following usage cases of pointers: 471 // 1) OpVariable allocating an object whose type is a pointer type 472 // 2) OpReturnValue returning a pointer value 473 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetRelaxLogicalPointer( 474 spv_validator_options options, bool val); 475 476 // Records whether or not the validator should relax the rules on block layout. 477 // 478 // When relaxed, it will skip checking standard uniform/storage buffer layout. 479 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetRelaxBlockLayout( 480 spv_validator_options options, bool val); 481 482 // Encodes the given SPIR-V assembly text to its binary representation. The 483 // length parameter specifies the number of bytes for text. Encoded binary will 484 // be stored into *binary. Any error will be written into *diagnostic if 485 // diagnostic is non-null. The generated binary is independent of the context 486 // and may outlive it. 487 SPIRV_TOOLS_EXPORT spv_result_t spvTextToBinary(const spv_const_context context, 488 const char* text, 489 const size_t length, 490 spv_binary* binary, 491 spv_diagnostic* diagnostic); 492 493 // Encodes the given SPIR-V assembly text to its binary representation. Same as 494 // spvTextToBinary but with options. The options parameter is a bit field of 495 // spv_text_to_binary_options_t. 496 SPIRV_TOOLS_EXPORT spv_result_t spvTextToBinaryWithOptions( 497 const spv_const_context context, const char* text, const size_t length, 498 const uint32_t options, spv_binary* binary, spv_diagnostic* diagnostic); 499 500 // Frees an allocated text stream. This is a no-op if the text parameter 501 // is a null pointer. 502 SPIRV_TOOLS_EXPORT void spvTextDestroy(spv_text text); 503 504 // Decodes the given SPIR-V binary representation to its assembly text. The 505 // word_count parameter specifies the number of words for binary. The options 506 // parameter is a bit field of spv_binary_to_text_options_t. Decoded text will 507 // be stored into *text. Any error will be written into *diagnostic if 508 // diagnostic is non-null. 509 SPIRV_TOOLS_EXPORT spv_result_t spvBinaryToText(const spv_const_context context, 510 const uint32_t* binary, 511 const size_t word_count, 512 const uint32_t options, 513 spv_text* text, 514 spv_diagnostic* diagnostic); 515 516 // Frees a binary stream from memory. This is a no-op if binary is a null 517 // pointer. 518 SPIRV_TOOLS_EXPORT void spvBinaryDestroy(spv_binary binary); 519 520 // Validates a SPIR-V binary for correctness. Any errors will be written into 521 // *diagnostic if diagnostic is non-null. 522 SPIRV_TOOLS_EXPORT spv_result_t spvValidate(const spv_const_context context, 523 const spv_const_binary binary, 524 spv_diagnostic* diagnostic); 525 526 // Validates a SPIR-V binary for correctness. Uses the provided Validator 527 // options. Any errors will be written into *diagnostic if diagnostic is 528 // non-null. 529 SPIRV_TOOLS_EXPORT spv_result_t spvValidateWithOptions( 530 const spv_const_context context, const spv_const_validator_options options, 531 const spv_const_binary binary, spv_diagnostic* diagnostic); 532 533 // Validates a raw SPIR-V binary for correctness. Any errors will be written 534 // into *diagnostic if diagnostic is non-null. 535 SPIRV_TOOLS_EXPORT spv_result_t 536 spvValidateBinary(const spv_const_context context, const uint32_t* words, 537 const size_t num_words, spv_diagnostic* diagnostic); 538 539 // Creates a diagnostic object. The position parameter specifies the location in 540 // the text/binary stream. The message parameter, copied into the diagnostic 541 // object, contains the error message to display. 542 SPIRV_TOOLS_EXPORT spv_diagnostic 543 spvDiagnosticCreate(const spv_position position, const char* message); 544 545 // Destroys a diagnostic object. This is a no-op if diagnostic is a null 546 // pointer. 547 SPIRV_TOOLS_EXPORT void spvDiagnosticDestroy(spv_diagnostic diagnostic); 548 549 // Prints the diagnostic to stderr. 550 SPIRV_TOOLS_EXPORT spv_result_t 551 spvDiagnosticPrint(const spv_diagnostic diagnostic); 552 553 // The binary parser interface. 554 555 // A pointer to a function that accepts a parsed SPIR-V header. 556 // The integer arguments are the 32-bit words from the header, as specified 557 // in SPIR-V 1.0 Section 2.3 Table 1. 558 // The function should return SPV_SUCCESS if parsing should continue. 559 typedef spv_result_t (*spv_parsed_header_fn_t)( 560 void* user_data, spv_endianness_t endian, uint32_t magic, uint32_t version, 561 uint32_t generator, uint32_t id_bound, uint32_t reserved); 562 563 // A pointer to a function that accepts a parsed SPIR-V instruction. 564 // The parsed_instruction value is transient: it may be overwritten 565 // or released immediately after the function has returned. That also 566 // applies to the words array member of the parsed instruction. The 567 // function should return SPV_SUCCESS if and only if parsing should 568 // continue. 569 typedef spv_result_t (*spv_parsed_instruction_fn_t)( 570 void* user_data, const spv_parsed_instruction_t* parsed_instruction); 571 572 // Parses a SPIR-V binary, specified as counted sequence of 32-bit words. 573 // Parsing feedback is provided via two callbacks provided as function 574 // pointers. Each callback function pointer can be a null pointer, in 575 // which case it is never called. Otherwise, in a valid parse the 576 // parsed-header callback is called once, and then the parsed-instruction 577 // callback once for each instruction in the stream. The user_data parameter 578 // is supplied as context to the callbacks. Returns SPV_SUCCESS on successful 579 // parse where the callbacks always return SPV_SUCCESS. For an invalid parse, 580 // returns a status code other than SPV_SUCCESS, and if diagnostic is non-null 581 // also emits a diagnostic. If a callback returns anything other than 582 // SPV_SUCCESS, then that status code is returned, no further callbacks are 583 // issued, and no additional diagnostics are emitted. 584 SPIRV_TOOLS_EXPORT spv_result_t spvBinaryParse( 585 const spv_const_context context, void* user_data, const uint32_t* words, 586 const size_t num_words, spv_parsed_header_fn_t parse_header, 587 spv_parsed_instruction_fn_t parse_instruction, spv_diagnostic* diagnostic); 588 589 #ifdef __cplusplus 590 } 591 #endif 592 593 #endif // SPIRV_TOOLS_LIBSPIRV_H_ 594