1 // Copyright (c) 2015-2020 The Khronos Group Inc. 2 // Modifications Copyright (C) 2020 Advanced Micro Devices, Inc. All rights 3 // reserved. 4 // 5 // Licensed under the Apache License, Version 2.0 (the "License"); 6 // you may not use this file except in compliance with the License. 7 // You may obtain a copy of the License at 8 // 9 // http://www.apache.org/licenses/LICENSE-2.0 10 // 11 // Unless required by applicable law or agreed to in writing, software 12 // distributed under the License is distributed on an "AS IS" BASIS, 13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 // See the License for the specific language governing permissions and 15 // limitations under the License. 16 17 #ifndef INCLUDE_SPIRV_TOOLS_LIBSPIRV_H_ 18 #define INCLUDE_SPIRV_TOOLS_LIBSPIRV_H_ 19 20 #ifdef __cplusplus 21 extern "C" { 22 #else 23 #include <stdbool.h> 24 #endif 25 26 #include <stddef.h> 27 #include <stdint.h> 28 29 #if defined(SPIRV_TOOLS_SHAREDLIB) 30 #if defined(_WIN32) 31 #if defined(SPIRV_TOOLS_IMPLEMENTATION) 32 #define SPIRV_TOOLS_EXPORT __declspec(dllexport) 33 #else 34 #define SPIRV_TOOLS_EXPORT __declspec(dllimport) 35 #endif 36 #else 37 #if defined(SPIRV_TOOLS_IMPLEMENTATION) 38 #define SPIRV_TOOLS_EXPORT __attribute__((visibility("default"))) 39 #else 40 #define SPIRV_TOOLS_EXPORT 41 #endif 42 #endif 43 #else 44 #define SPIRV_TOOLS_EXPORT 45 #endif 46 47 // Helpers 48 49 #define SPV_BIT(shift) (1 << (shift)) 50 51 #define SPV_FORCE_16_BIT_ENUM(name) SPV_FORCE_16BIT_##name = 0x7fff 52 #define SPV_FORCE_32_BIT_ENUM(name) SPV_FORCE_32BIT_##name = 0x7fffffff 53 54 // Enumerations 55 56 typedef enum spv_result_t { 57 SPV_SUCCESS = 0, 58 SPV_UNSUPPORTED = 1, 59 SPV_END_OF_STREAM = 2, 60 SPV_WARNING = 3, 61 SPV_FAILED_MATCH = 4, 62 SPV_REQUESTED_TERMINATION = 5, // Success, but signals early termination. 63 SPV_ERROR_INTERNAL = -1, 64 SPV_ERROR_OUT_OF_MEMORY = -2, 65 SPV_ERROR_INVALID_POINTER = -3, 66 SPV_ERROR_INVALID_BINARY = -4, 67 SPV_ERROR_INVALID_TEXT = -5, 68 SPV_ERROR_INVALID_TABLE = -6, 69 SPV_ERROR_INVALID_VALUE = -7, 70 SPV_ERROR_INVALID_DIAGNOSTIC = -8, 71 SPV_ERROR_INVALID_LOOKUP = -9, 72 SPV_ERROR_INVALID_ID = -10, 73 SPV_ERROR_INVALID_CFG = -11, 74 SPV_ERROR_INVALID_LAYOUT = -12, 75 SPV_ERROR_INVALID_CAPABILITY = -13, 76 SPV_ERROR_INVALID_DATA = -14, // Indicates data rules validation failure. 77 SPV_ERROR_MISSING_EXTENSION = -15, 78 SPV_ERROR_WRONG_VERSION = -16, // Indicates wrong SPIR-V version 79 SPV_FORCE_32_BIT_ENUM(spv_result_t) 80 } spv_result_t; 81 82 // Severity levels of messages communicated to the consumer. 83 typedef enum spv_message_level_t { 84 SPV_MSG_FATAL, // Unrecoverable error due to environment. 85 // Will exit the program immediately. E.g., 86 // out of memory. 87 SPV_MSG_INTERNAL_ERROR, // Unrecoverable error due to SPIRV-Tools 88 // internals. 89 // Will exit the program immediately. E.g., 90 // unimplemented feature. 91 SPV_MSG_ERROR, // Normal error due to user input. 92 SPV_MSG_WARNING, // Warning information. 93 SPV_MSG_INFO, // General information. 94 SPV_MSG_DEBUG, // Debug information. 95 } spv_message_level_t; 96 97 typedef enum spv_endianness_t { 98 SPV_ENDIANNESS_LITTLE, 99 SPV_ENDIANNESS_BIG, 100 SPV_FORCE_32_BIT_ENUM(spv_endianness_t) 101 } spv_endianness_t; 102 103 // The kinds of operands that an instruction may have. 104 // 105 // Some operand types are "concrete". The binary parser uses a concrete 106 // operand type to describe an operand of a parsed instruction. 107 // 108 // The assembler uses all operand types. In addition to determining what 109 // kind of value an operand may be, non-concrete operand types capture the 110 // fact that an operand might be optional (may be absent, or present exactly 111 // once), or might occur zero or more times. 112 // 113 // Sometimes we also need to be able to express the fact that an operand 114 // is a member of an optional tuple of values. In that case the first member 115 // would be optional, and the subsequent members would be required. 116 // 117 // NOTE: Although we don't promise binary compatibility, as a courtesy, please 118 // add new enum values at the end. 119 typedef enum spv_operand_type_t { 120 // A sentinel value. 121 SPV_OPERAND_TYPE_NONE = 0, 122 123 // Set 1: Operands that are IDs. 124 SPV_OPERAND_TYPE_ID, 125 SPV_OPERAND_TYPE_TYPE_ID, 126 SPV_OPERAND_TYPE_RESULT_ID, 127 SPV_OPERAND_TYPE_MEMORY_SEMANTICS_ID, // SPIR-V Sec 3.25 128 SPV_OPERAND_TYPE_SCOPE_ID, // SPIR-V Sec 3.27 129 130 // Set 2: Operands that are literal numbers. 131 SPV_OPERAND_TYPE_LITERAL_INTEGER, // Always unsigned 32-bits. 132 // The Instruction argument to OpExtInst. It's an unsigned 32-bit literal 133 // number indicating which instruction to use from an extended instruction 134 // set. 135 SPV_OPERAND_TYPE_EXTENSION_INSTRUCTION_NUMBER, 136 // The Opcode argument to OpSpecConstantOp. It determines the operation 137 // to be performed on constant operands to compute a specialization constant 138 // result. 139 SPV_OPERAND_TYPE_SPEC_CONSTANT_OP_NUMBER, 140 // A literal number whose format and size are determined by a previous operand 141 // in the same instruction. It's a signed integer, an unsigned integer, or a 142 // floating point number. It also has a specified bit width. The width 143 // may be larger than 32, which would require such a typed literal value to 144 // occupy multiple SPIR-V words. 145 SPV_OPERAND_TYPE_TYPED_LITERAL_NUMBER, 146 SPV_OPERAND_TYPE_LITERAL_FLOAT, // Always 32-bit float. 147 148 // Set 3: The literal string operand type. 149 SPV_OPERAND_TYPE_LITERAL_STRING, 150 151 // Set 4: Operands that are a single word enumerated value. 152 SPV_OPERAND_TYPE_SOURCE_LANGUAGE, // SPIR-V Sec 3.2 153 SPV_OPERAND_TYPE_EXECUTION_MODEL, // SPIR-V Sec 3.3 154 SPV_OPERAND_TYPE_ADDRESSING_MODEL, // SPIR-V Sec 3.4 155 SPV_OPERAND_TYPE_MEMORY_MODEL, // SPIR-V Sec 3.5 156 SPV_OPERAND_TYPE_EXECUTION_MODE, // SPIR-V Sec 3.6 157 SPV_OPERAND_TYPE_STORAGE_CLASS, // SPIR-V Sec 3.7 158 SPV_OPERAND_TYPE_DIMENSIONALITY, // SPIR-V Sec 3.8 159 SPV_OPERAND_TYPE_SAMPLER_ADDRESSING_MODE, // SPIR-V Sec 3.9 160 SPV_OPERAND_TYPE_SAMPLER_FILTER_MODE, // SPIR-V Sec 3.10 161 SPV_OPERAND_TYPE_SAMPLER_IMAGE_FORMAT, // SPIR-V Sec 3.11 162 SPV_OPERAND_TYPE_IMAGE_CHANNEL_ORDER, // SPIR-V Sec 3.12 163 SPV_OPERAND_TYPE_IMAGE_CHANNEL_DATA_TYPE, // SPIR-V Sec 3.13 164 SPV_OPERAND_TYPE_FP_ROUNDING_MODE, // SPIR-V Sec 3.16 165 SPV_OPERAND_TYPE_LINKAGE_TYPE, // SPIR-V Sec 3.17 166 SPV_OPERAND_TYPE_ACCESS_QUALIFIER, // SPIR-V Sec 3.18 167 SPV_OPERAND_TYPE_FUNCTION_PARAMETER_ATTRIBUTE, // SPIR-V Sec 3.19 168 SPV_OPERAND_TYPE_DECORATION, // SPIR-V Sec 3.20 169 SPV_OPERAND_TYPE_BUILT_IN, // SPIR-V Sec 3.21 170 SPV_OPERAND_TYPE_GROUP_OPERATION, // SPIR-V Sec 3.28 171 SPV_OPERAND_TYPE_KERNEL_ENQ_FLAGS, // SPIR-V Sec 3.29 172 SPV_OPERAND_TYPE_KERNEL_PROFILING_INFO, // SPIR-V Sec 3.30 173 SPV_OPERAND_TYPE_CAPABILITY, // SPIR-V Sec 3.31 174 175 // NOTE: New concrete enum values should be added at the end. 176 177 // Set 5: Operands that are a single word bitmask. 178 // Sometimes a set bit indicates the instruction requires still more operands. 179 SPV_OPERAND_TYPE_IMAGE, // SPIR-V Sec 3.14 180 SPV_OPERAND_TYPE_FP_FAST_MATH_MODE, // SPIR-V Sec 3.15 181 SPV_OPERAND_TYPE_SELECTION_CONTROL, // SPIR-V Sec 3.22 182 SPV_OPERAND_TYPE_LOOP_CONTROL, // SPIR-V Sec 3.23 183 SPV_OPERAND_TYPE_FUNCTION_CONTROL, // SPIR-V Sec 3.24 184 SPV_OPERAND_TYPE_MEMORY_ACCESS, // SPIR-V Sec 3.26 185 SPV_OPERAND_TYPE_FRAGMENT_SHADING_RATE, // SPIR-V Sec 3.FSR 186 187 // NOTE: New concrete enum values should be added at the end. 188 189 // The "optional" and "variable" operand types are only used internally by 190 // the assembler and the binary parser. 191 // There are two categories: 192 // Optional : expands to 0 or 1 operand, like ? in regular expressions. 193 // Variable : expands to 0, 1 or many operands or pairs of operands. 194 // This is similar to * in regular expressions. 195 196 // NOTE: These FIRST_* and LAST_* enum values are DEPRECATED. 197 // The concept of "optional" and "variable" operand types are only intended 198 // for use as an implementation detail of parsing SPIR-V, either in text or 199 // binary form. Instead of using enum ranges, use characteristic function 200 // spvOperandIsConcrete. 201 // The use of enum value ranges in a public API makes it difficult to insert 202 // new values into a range without also breaking binary compatibility. 203 // 204 // Macros for defining bounds on optional and variable operand types. 205 // Any variable operand type is also optional. 206 // TODO(dneto): Remove SPV_OPERAND_TYPE_FIRST_* and SPV_OPERAND_TYPE_LAST_* 207 #define FIRST_OPTIONAL(ENUM) ENUM, SPV_OPERAND_TYPE_FIRST_OPTIONAL_TYPE = ENUM 208 #define FIRST_VARIABLE(ENUM) ENUM, SPV_OPERAND_TYPE_FIRST_VARIABLE_TYPE = ENUM 209 #define LAST_VARIABLE(ENUM) \ 210 ENUM, SPV_OPERAND_TYPE_LAST_VARIABLE_TYPE = ENUM, \ 211 SPV_OPERAND_TYPE_LAST_OPTIONAL_TYPE = ENUM 212 213 // An optional operand represents zero or one logical operands. 214 // In an instruction definition, this may only appear at the end of the 215 // operand types. 216 FIRST_OPTIONAL(SPV_OPERAND_TYPE_OPTIONAL_ID), 217 // An optional image operand type. 218 SPV_OPERAND_TYPE_OPTIONAL_IMAGE, 219 // An optional memory access type. 220 SPV_OPERAND_TYPE_OPTIONAL_MEMORY_ACCESS, 221 // An optional literal integer. 222 SPV_OPERAND_TYPE_OPTIONAL_LITERAL_INTEGER, 223 // An optional literal number, which may be either integer or floating point. 224 SPV_OPERAND_TYPE_OPTIONAL_LITERAL_NUMBER, 225 // Like SPV_OPERAND_TYPE_TYPED_LITERAL_NUMBER, but optional, and integral. 226 SPV_OPERAND_TYPE_OPTIONAL_TYPED_LITERAL_INTEGER, 227 // An optional literal string. 228 SPV_OPERAND_TYPE_OPTIONAL_LITERAL_STRING, 229 // An optional access qualifier 230 SPV_OPERAND_TYPE_OPTIONAL_ACCESS_QUALIFIER, 231 // An optional context-independent value, or CIV. CIVs are tokens that we can 232 // assemble regardless of where they occur -- literals, IDs, immediate 233 // integers, etc. 234 SPV_OPERAND_TYPE_OPTIONAL_CIV, 235 236 // A variable operand represents zero or more logical operands. 237 // In an instruction definition, this may only appear at the end of the 238 // operand types. 239 FIRST_VARIABLE(SPV_OPERAND_TYPE_VARIABLE_ID), 240 SPV_OPERAND_TYPE_VARIABLE_LITERAL_INTEGER, 241 // A sequence of zero or more pairs of (typed literal integer, Id). 242 // Expands to zero or more: 243 // (SPV_OPERAND_TYPE_TYPED_LITERAL_INTEGER, SPV_OPERAND_TYPE_ID) 244 // where the literal number must always be an integer of some sort. 245 SPV_OPERAND_TYPE_VARIABLE_LITERAL_INTEGER_ID, 246 // A sequence of zero or more pairs of (Id, Literal integer) 247 LAST_VARIABLE(SPV_OPERAND_TYPE_VARIABLE_ID_LITERAL_INTEGER), 248 249 // The following are concrete enum types from the DebugInfo extended 250 // instruction set. 251 SPV_OPERAND_TYPE_DEBUG_INFO_FLAGS, // DebugInfo Sec 3.2. A mask. 252 SPV_OPERAND_TYPE_DEBUG_BASE_TYPE_ATTRIBUTE_ENCODING, // DebugInfo Sec 3.3 253 SPV_OPERAND_TYPE_DEBUG_COMPOSITE_TYPE, // DebugInfo Sec 3.4 254 SPV_OPERAND_TYPE_DEBUG_TYPE_QUALIFIER, // DebugInfo Sec 3.5 255 SPV_OPERAND_TYPE_DEBUG_OPERATION, // DebugInfo Sec 3.6 256 257 // The following are concrete enum types from the OpenCL.DebugInfo.100 258 // extended instruction set. 259 SPV_OPERAND_TYPE_CLDEBUG100_DEBUG_INFO_FLAGS, // Sec 3.2. A Mask 260 SPV_OPERAND_TYPE_CLDEBUG100_DEBUG_BASE_TYPE_ATTRIBUTE_ENCODING, // Sec 3.3 261 SPV_OPERAND_TYPE_CLDEBUG100_DEBUG_COMPOSITE_TYPE, // Sec 3.4 262 SPV_OPERAND_TYPE_CLDEBUG100_DEBUG_TYPE_QUALIFIER, // Sec 3.5 263 SPV_OPERAND_TYPE_CLDEBUG100_DEBUG_OPERATION, // Sec 3.6 264 SPV_OPERAND_TYPE_CLDEBUG100_DEBUG_IMPORTED_ENTITY, // Sec 3.7 265 266 // The following are concrete enum types from SPV_INTEL_float_controls2 267 // https://github.com/intel/llvm/blob/39fa9b0cbfbae88327118990a05c5b387b56d2ef/sycl/doc/extensions/SPIRV/SPV_INTEL_float_controls2.asciidoc 268 SPV_OPERAND_TYPE_FPDENORM_MODE, // Sec 3.17 FP Denorm Mode 269 SPV_OPERAND_TYPE_FPOPERATION_MODE, // Sec 3.18 FP Operation Mode 270 // A value enum from https://github.com/KhronosGroup/SPIRV-Headers/pull/177 271 SPV_OPERAND_TYPE_QUANTIZATION_MODES, 272 // A value enum from https://github.com/KhronosGroup/SPIRV-Headers/pull/177 273 SPV_OPERAND_TYPE_OVERFLOW_MODES, 274 275 // Concrete operand types for the provisional Vulkan ray tracing feature. 276 SPV_OPERAND_TYPE_RAY_FLAGS, // SPIR-V Sec 3.RF 277 SPV_OPERAND_TYPE_RAY_QUERY_INTERSECTION, // SPIR-V Sec 3.RQIntersection 278 SPV_OPERAND_TYPE_RAY_QUERY_COMMITTED_INTERSECTION_TYPE, // SPIR-V Sec 279 // 3.RQCommitted 280 SPV_OPERAND_TYPE_RAY_QUERY_CANDIDATE_INTERSECTION_TYPE, // SPIR-V Sec 281 // 3.RQCandidate 282 283 // Concrete operand types for integer dot product. 284 // Packed vector format 285 SPV_OPERAND_TYPE_PACKED_VECTOR_FORMAT, // SPIR-V Sec 3.x 286 // An optional packed vector format 287 SPV_OPERAND_TYPE_OPTIONAL_PACKED_VECTOR_FORMAT, 288 289 // Concrete operand types for cooperative matrix. 290 SPV_OPERAND_TYPE_COOPERATIVE_MATRIX_OPERANDS, 291 // An optional cooperative matrix operands 292 SPV_OPERAND_TYPE_OPTIONAL_COOPERATIVE_MATRIX_OPERANDS, 293 SPV_OPERAND_TYPE_COOPERATIVE_MATRIX_LAYOUT, 294 SPV_OPERAND_TYPE_COOPERATIVE_MATRIX_USE, 295 296 // Enum type from SPV_INTEL_global_variable_fpga_decorations 297 SPV_OPERAND_TYPE_INITIALIZATION_MODE_QUALIFIER, 298 // Enum type from SPV_INTEL_global_variable_host_access 299 SPV_OPERAND_TYPE_HOST_ACCESS_QUALIFIER, 300 // Enum type from SPV_INTEL_cache_controls 301 SPV_OPERAND_TYPE_LOAD_CACHE_CONTROL, 302 // Enum type from SPV_INTEL_cache_controls 303 SPV_OPERAND_TYPE_STORE_CACHE_CONTROL, 304 305 // This is a sentinel value, and does not represent an operand type. 306 // It should come last. 307 SPV_OPERAND_TYPE_NUM_OPERAND_TYPES, 308 309 SPV_FORCE_32_BIT_ENUM(spv_operand_type_t) 310 } spv_operand_type_t; 311 312 // Returns true if the given type is concrete. 313 bool spvOperandIsConcrete(spv_operand_type_t type); 314 315 // Returns true if the given type is concrete and also a mask. 316 bool spvOperandIsConcreteMask(spv_operand_type_t type); 317 318 typedef enum spv_ext_inst_type_t { 319 SPV_EXT_INST_TYPE_NONE = 0, 320 SPV_EXT_INST_TYPE_GLSL_STD_450, 321 SPV_EXT_INST_TYPE_OPENCL_STD, 322 SPV_EXT_INST_TYPE_SPV_AMD_SHADER_EXPLICIT_VERTEX_PARAMETER, 323 SPV_EXT_INST_TYPE_SPV_AMD_SHADER_TRINARY_MINMAX, 324 SPV_EXT_INST_TYPE_SPV_AMD_GCN_SHADER, 325 SPV_EXT_INST_TYPE_SPV_AMD_SHADER_BALLOT, 326 SPV_EXT_INST_TYPE_DEBUGINFO, 327 SPV_EXT_INST_TYPE_OPENCL_DEBUGINFO_100, 328 SPV_EXT_INST_TYPE_NONSEMANTIC_CLSPVREFLECTION, 329 SPV_EXT_INST_TYPE_NONSEMANTIC_SHADER_DEBUGINFO_100, 330 331 // Multiple distinct extended instruction set types could return this 332 // value, if they are prefixed with NonSemantic. and are otherwise 333 // unrecognised 334 SPV_EXT_INST_TYPE_NONSEMANTIC_UNKNOWN, 335 336 SPV_FORCE_32_BIT_ENUM(spv_ext_inst_type_t) 337 } spv_ext_inst_type_t; 338 339 // This determines at a high level the kind of a binary-encoded literal 340 // number, but not the bit width. 341 // In principle, these could probably be folded into new entries in 342 // spv_operand_type_t. But then we'd have some special case differences 343 // between the assembler and disassembler. 344 typedef enum spv_number_kind_t { 345 SPV_NUMBER_NONE = 0, // The default for value initialization. 346 SPV_NUMBER_UNSIGNED_INT, 347 SPV_NUMBER_SIGNED_INT, 348 SPV_NUMBER_FLOATING, 349 } spv_number_kind_t; 350 351 typedef enum spv_text_to_binary_options_t { 352 SPV_TEXT_TO_BINARY_OPTION_NONE = SPV_BIT(0), 353 // Numeric IDs in the binary will have the same values as in the source. 354 // Non-numeric IDs are allocated by filling in the gaps, starting with 1 355 // and going up. 356 SPV_TEXT_TO_BINARY_OPTION_PRESERVE_NUMERIC_IDS = SPV_BIT(1), 357 SPV_FORCE_32_BIT_ENUM(spv_text_to_binary_options_t) 358 } spv_text_to_binary_options_t; 359 360 typedef enum spv_binary_to_text_options_t { 361 SPV_BINARY_TO_TEXT_OPTION_NONE = SPV_BIT(0), 362 SPV_BINARY_TO_TEXT_OPTION_PRINT = SPV_BIT(1), 363 SPV_BINARY_TO_TEXT_OPTION_COLOR = SPV_BIT(2), 364 SPV_BINARY_TO_TEXT_OPTION_INDENT = SPV_BIT(3), 365 SPV_BINARY_TO_TEXT_OPTION_SHOW_BYTE_OFFSET = SPV_BIT(4), 366 // Do not output the module header as leading comments in the assembly. 367 SPV_BINARY_TO_TEXT_OPTION_NO_HEADER = SPV_BIT(5), 368 // Use friendly names where possible. The heuristic may expand over 369 // time, but will use common names for scalar types, and debug names from 370 // OpName instructions. 371 SPV_BINARY_TO_TEXT_OPTION_FRIENDLY_NAMES = SPV_BIT(6), 372 // Add some comments to the generated assembly 373 SPV_BINARY_TO_TEXT_OPTION_COMMENT = SPV_BIT(7), 374 SPV_FORCE_32_BIT_ENUM(spv_binary_to_text_options_t) 375 } spv_binary_to_text_options_t; 376 377 // Constants 378 379 // The default id bound is to the minimum value for the id limit 380 // in the spir-v specification under the section "Universal Limits". 381 const uint32_t kDefaultMaxIdBound = 0x3FFFFF; 382 383 // Structures 384 385 // Information about an operand parsed from a binary SPIR-V module. 386 // Note that the values are not included. You still need access to the binary 387 // to extract the values. 388 typedef struct spv_parsed_operand_t { 389 // Location of the operand, in words from the start of the instruction. 390 uint16_t offset; 391 // Number of words occupied by this operand. 392 uint16_t num_words; 393 // The "concrete" operand type. See the definition of spv_operand_type_t 394 // for details. 395 spv_operand_type_t type; 396 // If type is a literal number type, then number_kind says whether it's 397 // a signed integer, an unsigned integer, or a floating point number. 398 spv_number_kind_t number_kind; 399 // The number of bits for a literal number type. 400 uint32_t number_bit_width; 401 } spv_parsed_operand_t; 402 403 // An instruction parsed from a binary SPIR-V module. 404 typedef struct spv_parsed_instruction_t { 405 // An array of words for this instruction, in native endianness. 406 const uint32_t* words; 407 // The number of words in this instruction. 408 uint16_t num_words; 409 uint16_t opcode; 410 // The extended instruction type, if opcode is OpExtInst. Otherwise 411 // this is the "none" value. 412 spv_ext_inst_type_t ext_inst_type; 413 // The type id, or 0 if this instruction doesn't have one. 414 uint32_t type_id; 415 // The result id, or 0 if this instruction doesn't have one. 416 uint32_t result_id; 417 // The array of parsed operands. 418 const spv_parsed_operand_t* operands; 419 uint16_t num_operands; 420 } spv_parsed_instruction_t; 421 422 typedef struct spv_parsed_header_t { 423 // The magic number of the SPIR-V module. 424 uint32_t magic; 425 // Version number. 426 uint32_t version; 427 // Generator's magic number. 428 uint32_t generator; 429 // IDs bound for this module (0 < id < bound). 430 uint32_t bound; 431 // reserved. 432 uint32_t reserved; 433 } spv_parsed_header_t; 434 435 typedef struct spv_const_binary_t { 436 const uint32_t* code; 437 const size_t wordCount; 438 } spv_const_binary_t; 439 440 typedef struct spv_binary_t { 441 uint32_t* code; 442 size_t wordCount; 443 } spv_binary_t; 444 445 typedef struct spv_text_t { 446 const char* str; 447 size_t length; 448 } spv_text_t; 449 450 typedef struct spv_position_t { 451 size_t line; 452 size_t column; 453 size_t index; 454 } spv_position_t; 455 456 typedef struct spv_diagnostic_t { 457 spv_position_t position; 458 char* error; 459 bool isTextSource; 460 } spv_diagnostic_t; 461 462 // Opaque struct containing the context used to operate on a SPIR-V module. 463 // Its object is used by various translation API functions. 464 typedef struct spv_context_t spv_context_t; 465 466 typedef struct spv_validator_options_t spv_validator_options_t; 467 468 typedef struct spv_optimizer_options_t spv_optimizer_options_t; 469 470 typedef struct spv_reducer_options_t spv_reducer_options_t; 471 472 typedef struct spv_fuzzer_options_t spv_fuzzer_options_t; 473 474 typedef struct spv_optimizer_t spv_optimizer_t; 475 476 // Type Definitions 477 478 typedef spv_const_binary_t* spv_const_binary; 479 typedef spv_binary_t* spv_binary; 480 typedef spv_text_t* spv_text; 481 typedef spv_position_t* spv_position; 482 typedef spv_diagnostic_t* spv_diagnostic; 483 typedef const spv_context_t* spv_const_context; 484 typedef spv_context_t* spv_context; 485 typedef spv_validator_options_t* spv_validator_options; 486 typedef const spv_validator_options_t* spv_const_validator_options; 487 typedef spv_optimizer_options_t* spv_optimizer_options; 488 typedef const spv_optimizer_options_t* spv_const_optimizer_options; 489 typedef spv_reducer_options_t* spv_reducer_options; 490 typedef const spv_reducer_options_t* spv_const_reducer_options; 491 typedef spv_fuzzer_options_t* spv_fuzzer_options; 492 typedef const spv_fuzzer_options_t* spv_const_fuzzer_options; 493 494 // Platform API 495 496 // Returns the SPIRV-Tools software version as a null-terminated string. 497 // The contents of the underlying storage is valid for the remainder of 498 // the process. 499 SPIRV_TOOLS_EXPORT const char* spvSoftwareVersionString(void); 500 // Returns a null-terminated string containing the name of the project, 501 // the software version string, and commit details. 502 // The contents of the underlying storage is valid for the remainder of 503 // the process. 504 SPIRV_TOOLS_EXPORT const char* spvSoftwareVersionDetailsString(void); 505 506 // Certain target environments impose additional restrictions on SPIR-V, so it's 507 // often necessary to specify which one applies. SPV_ENV_UNIVERSAL_* implies an 508 // environment-agnostic SPIR-V. 509 // 510 // When an API method needs to derive a SPIR-V version from a target environment 511 // (from the spv_context object), the method will choose the highest version of 512 // SPIR-V supported by the target environment. Examples: 513 // SPV_ENV_VULKAN_1_0 -> SPIR-V 1.0 514 // SPV_ENV_VULKAN_1_1 -> SPIR-V 1.3 515 // SPV_ENV_VULKAN_1_1_SPIRV_1_4 -> SPIR-V 1.4 516 // SPV_ENV_VULKAN_1_2 -> SPIR-V 1.5 517 // SPV_ENV_VULKAN_1_3 -> SPIR-V 1.6 518 // Consult the description of API entry points for specific rules. 519 typedef enum { 520 SPV_ENV_UNIVERSAL_1_0, // SPIR-V 1.0 latest revision, no other restrictions. 521 SPV_ENV_VULKAN_1_0, // Vulkan 1.0 latest revision. 522 SPV_ENV_UNIVERSAL_1_1, // SPIR-V 1.1 latest revision, no other restrictions. 523 SPV_ENV_OPENCL_2_1, // OpenCL Full Profile 2.1 latest revision. 524 SPV_ENV_OPENCL_2_2, // OpenCL Full Profile 2.2 latest revision. 525 SPV_ENV_OPENGL_4_0, // OpenGL 4.0 plus GL_ARB_gl_spirv, latest revisions. 526 SPV_ENV_OPENGL_4_1, // OpenGL 4.1 plus GL_ARB_gl_spirv, latest revisions. 527 SPV_ENV_OPENGL_4_2, // OpenGL 4.2 plus GL_ARB_gl_spirv, latest revisions. 528 SPV_ENV_OPENGL_4_3, // OpenGL 4.3 plus GL_ARB_gl_spirv, latest revisions. 529 // There is no variant for OpenGL 4.4. 530 SPV_ENV_OPENGL_4_5, // OpenGL 4.5 plus GL_ARB_gl_spirv, latest revisions. 531 SPV_ENV_UNIVERSAL_1_2, // SPIR-V 1.2, latest revision, no other restrictions. 532 SPV_ENV_OPENCL_1_2, // OpenCL Full Profile 1.2 plus cl_khr_il_program, 533 // latest revision. 534 SPV_ENV_OPENCL_EMBEDDED_1_2, // OpenCL Embedded Profile 1.2 plus 535 // cl_khr_il_program, latest revision. 536 SPV_ENV_OPENCL_2_0, // OpenCL Full Profile 2.0 plus cl_khr_il_program, 537 // latest revision. 538 SPV_ENV_OPENCL_EMBEDDED_2_0, // OpenCL Embedded Profile 2.0 plus 539 // cl_khr_il_program, latest revision. 540 SPV_ENV_OPENCL_EMBEDDED_2_1, // OpenCL Embedded Profile 2.1 latest revision. 541 SPV_ENV_OPENCL_EMBEDDED_2_2, // OpenCL Embedded Profile 2.2 latest revision. 542 SPV_ENV_UNIVERSAL_1_3, // SPIR-V 1.3 latest revision, no other restrictions. 543 SPV_ENV_VULKAN_1_1, // Vulkan 1.1 latest revision. 544 SPV_ENV_WEBGPU_0, // DEPRECATED, may be removed in the future. 545 SPV_ENV_UNIVERSAL_1_4, // SPIR-V 1.4 latest revision, no other restrictions. 546 547 // Vulkan 1.1 with VK_KHR_spirv_1_4, i.e. SPIR-V 1.4 binary. 548 SPV_ENV_VULKAN_1_1_SPIRV_1_4, 549 550 SPV_ENV_UNIVERSAL_1_5, // SPIR-V 1.5 latest revision, no other restrictions. 551 SPV_ENV_VULKAN_1_2, // Vulkan 1.2 latest revision. 552 553 SPV_ENV_UNIVERSAL_1_6, // SPIR-V 1.6 latest revision, no other restrictions. 554 SPV_ENV_VULKAN_1_3, // Vulkan 1.3 latest revision. 555 556 SPV_ENV_MAX // Keep this as the last enum value. 557 } spv_target_env; 558 559 // SPIR-V Validator can be parameterized with the following Universal Limits. 560 typedef enum { 561 spv_validator_limit_max_struct_members, 562 spv_validator_limit_max_struct_depth, 563 spv_validator_limit_max_local_variables, 564 spv_validator_limit_max_global_variables, 565 spv_validator_limit_max_switch_branches, 566 spv_validator_limit_max_function_args, 567 spv_validator_limit_max_control_flow_nesting_depth, 568 spv_validator_limit_max_access_chain_indexes, 569 spv_validator_limit_max_id_bound, 570 } spv_validator_limit; 571 572 // Returns a string describing the given SPIR-V target environment. 573 SPIRV_TOOLS_EXPORT const char* spvTargetEnvDescription(spv_target_env env); 574 575 // Parses s into *env and returns true if successful. If unparsable, returns 576 // false and sets *env to SPV_ENV_UNIVERSAL_1_0. 577 SPIRV_TOOLS_EXPORT bool spvParseTargetEnv(const char* s, spv_target_env* env); 578 579 // Determines the target env value with the least features but which enables 580 // the given Vulkan and SPIR-V versions. If such a target is supported, returns 581 // true and writes the value to |env|, otherwise returns false. 582 // 583 // The Vulkan version is given as an unsigned 32-bit number as specified in 584 // Vulkan section "29.2.1 Version Numbers": the major version number appears 585 // in bits 22 to 21, and the minor version is in bits 12 to 21. The SPIR-V 586 // version is given in the SPIR-V version header word: major version in bits 587 // 16 to 23, and minor version in bits 8 to 15. 588 SPIRV_TOOLS_EXPORT bool spvParseVulkanEnv(uint32_t vulkan_ver, 589 uint32_t spirv_ver, 590 spv_target_env* env); 591 592 // Creates a context object for most of the SPIRV-Tools API. 593 // Returns null if env is invalid. 594 // 595 // See specific API calls for how the target environment is interpreted 596 // (particularly assembly and validation). 597 SPIRV_TOOLS_EXPORT spv_context spvContextCreate(spv_target_env env); 598 599 // Destroys the given context object. 600 SPIRV_TOOLS_EXPORT void spvContextDestroy(spv_context context); 601 602 // Creates a Validator options object with default options. Returns a valid 603 // options object. The object remains valid until it is passed into 604 // spvValidatorOptionsDestroy. 605 SPIRV_TOOLS_EXPORT spv_validator_options spvValidatorOptionsCreate(void); 606 607 // Destroys the given Validator options object. 608 SPIRV_TOOLS_EXPORT void spvValidatorOptionsDestroy( 609 spv_validator_options options); 610 611 // Records the maximum Universal Limit that is considered valid in the given 612 // Validator options object. <options> argument must be a valid options object. 613 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetUniversalLimit( 614 spv_validator_options options, spv_validator_limit limit_type, 615 uint32_t limit); 616 617 // Record whether or not the validator should relax the rules on types for 618 // stores to structs. When relaxed, it will allow a type mismatch as long as 619 // the types are structs with the same layout. Two structs have the same layout 620 // if 621 // 622 // 1) the members of the structs are either the same type or are structs with 623 // same layout, and 624 // 625 // 2) the decorations that affect the memory layout are identical for both 626 // types. Other decorations are not relevant. 627 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetRelaxStoreStruct( 628 spv_validator_options options, bool val); 629 630 // Records whether or not the validator should relax the rules on pointer usage 631 // in logical addressing mode. 632 // 633 // When relaxed, it will allow the following usage cases of pointers: 634 // 1) OpVariable allocating an object whose type is a pointer type 635 // 2) OpReturnValue returning a pointer value 636 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetRelaxLogicalPointer( 637 spv_validator_options options, bool val); 638 639 // Records whether or not the validator should relax the rules because it is 640 // expected that the optimizations will make the code legal. 641 // 642 // When relaxed, it will allow the following: 643 // 1) It will allow relaxed logical pointers. Setting this option will also 644 // set that option. 645 // 2) Pointers that are pass as parameters to function calls do not have to 646 // match the storage class of the formal parameter. 647 // 3) Pointers that are actual parameters on function calls do not have to point 648 // to the same type pointed as the formal parameter. The types just need to 649 // logically match. 650 // 4) GLSLstd450 Interpolate* instructions can have a load of an interpolant 651 // for a first argument. 652 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetBeforeHlslLegalization( 653 spv_validator_options options, bool val); 654 655 // Records whether the validator should use "relaxed" block layout rules. 656 // Relaxed layout rules are described by Vulkan extension 657 // VK_KHR_relaxed_block_layout, and they affect uniform blocks, storage blocks, 658 // and push constants. 659 // 660 // This is enabled by default when targeting Vulkan 1.1 or later. 661 // Relaxed layout is more permissive than the default rules in Vulkan 1.0. 662 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetRelaxBlockLayout( 663 spv_validator_options options, bool val); 664 665 // Records whether the validator should use standard block layout rules for 666 // uniform blocks. 667 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetUniformBufferStandardLayout( 668 spv_validator_options options, bool val); 669 670 // Records whether the validator should use "scalar" block layout rules. 671 // Scalar layout rules are more permissive than relaxed block layout. 672 // 673 // See Vulkan extension VK_EXT_scalar_block_layout. The scalar alignment is 674 // defined as follows: 675 // - scalar alignment of a scalar is the scalar size 676 // - scalar alignment of a vector is the scalar alignment of its component 677 // - scalar alignment of a matrix is the scalar alignment of its component 678 // - scalar alignment of an array is the scalar alignment of its element 679 // - scalar alignment of a struct is the max scalar alignment among its 680 // members 681 // 682 // For a struct in Uniform, StorageClass, or PushConstant: 683 // - a member Offset must be a multiple of the member's scalar alignment 684 // - ArrayStride or MatrixStride must be a multiple of the array or matrix 685 // scalar alignment 686 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetScalarBlockLayout( 687 spv_validator_options options, bool val); 688 689 // Records whether the validator should use "scalar" block layout 690 // rules (as defined above) for Workgroup blocks. See Vulkan 691 // extension VK_KHR_workgroup_memory_explicit_layout. 692 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetWorkgroupScalarBlockLayout( 693 spv_validator_options options, bool val); 694 695 // Records whether or not the validator should skip validating standard 696 // uniform/storage block layout. 697 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetSkipBlockLayout( 698 spv_validator_options options, bool val); 699 700 // Records whether or not the validator should allow the LocalSizeId 701 // decoration where the environment otherwise would not allow it. 702 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetAllowLocalSizeId( 703 spv_validator_options options, bool val); 704 705 // Whether friendly names should be used in validation error messages. 706 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetFriendlyNames( 707 spv_validator_options options, bool val); 708 709 // Creates an optimizer options object with default options. Returns a valid 710 // options object. The object remains valid until it is passed into 711 // |spvOptimizerOptionsDestroy|. 712 SPIRV_TOOLS_EXPORT spv_optimizer_options spvOptimizerOptionsCreate(void); 713 714 // Destroys the given optimizer options object. 715 SPIRV_TOOLS_EXPORT void spvOptimizerOptionsDestroy( 716 spv_optimizer_options options); 717 718 // Records whether or not the optimizer should run the validator before 719 // optimizing. If |val| is true, the validator will be run. 720 SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetRunValidator( 721 spv_optimizer_options options, bool val); 722 723 // Records the validator options that should be passed to the validator if it is 724 // run. 725 SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetValidatorOptions( 726 spv_optimizer_options options, spv_validator_options val); 727 728 // Records the maximum possible value for the id bound. 729 SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetMaxIdBound( 730 spv_optimizer_options options, uint32_t val); 731 732 // Records whether all bindings within the module should be preserved. 733 SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetPreserveBindings( 734 spv_optimizer_options options, bool val); 735 736 // Records whether all specialization constants within the module 737 // should be preserved. 738 SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetPreserveSpecConstants( 739 spv_optimizer_options options, bool val); 740 741 // Creates a reducer options object with default options. Returns a valid 742 // options object. The object remains valid until it is passed into 743 // |spvReducerOptionsDestroy|. 744 SPIRV_TOOLS_EXPORT spv_reducer_options spvReducerOptionsCreate(void); 745 746 // Destroys the given reducer options object. 747 SPIRV_TOOLS_EXPORT void spvReducerOptionsDestroy(spv_reducer_options options); 748 749 // Sets the maximum number of reduction steps that should run before the reducer 750 // gives up. 751 SPIRV_TOOLS_EXPORT void spvReducerOptionsSetStepLimit( 752 spv_reducer_options options, uint32_t step_limit); 753 754 // Sets the fail-on-validation-error option; if true, the reducer will return 755 // kStateInvalid if a reduction step yields a state that fails SPIR-V 756 // validation. Otherwise, an invalid state is treated as uninteresting and the 757 // reduction backtracks and continues. 758 SPIRV_TOOLS_EXPORT void spvReducerOptionsSetFailOnValidationError( 759 spv_reducer_options options, bool fail_on_validation_error); 760 761 // Sets the function that the reducer should target. If set to zero the reducer 762 // will target all functions as well as parts of the module that lie outside 763 // functions. Otherwise the reducer will restrict reduction to the function 764 // with result id |target_function|, which is required to exist. 765 SPIRV_TOOLS_EXPORT void spvReducerOptionsSetTargetFunction( 766 spv_reducer_options options, uint32_t target_function); 767 768 // Creates a fuzzer options object with default options. Returns a valid 769 // options object. The object remains valid until it is passed into 770 // |spvFuzzerOptionsDestroy|. 771 SPIRV_TOOLS_EXPORT spv_fuzzer_options spvFuzzerOptionsCreate(void); 772 773 // Destroys the given fuzzer options object. 774 SPIRV_TOOLS_EXPORT void spvFuzzerOptionsDestroy(spv_fuzzer_options options); 775 776 // Enables running the validator after every transformation is applied during 777 // a replay. 778 SPIRV_TOOLS_EXPORT void spvFuzzerOptionsEnableReplayValidation( 779 spv_fuzzer_options options); 780 781 // Sets the seed with which the random number generator used by the fuzzer 782 // should be initialized. 783 SPIRV_TOOLS_EXPORT void spvFuzzerOptionsSetRandomSeed( 784 spv_fuzzer_options options, uint32_t seed); 785 786 // Sets the range of transformations that should be applied during replay: 0 787 // means all transformations, +N means the first N transformations, -N means all 788 // except the final N transformations. 789 SPIRV_TOOLS_EXPORT void spvFuzzerOptionsSetReplayRange( 790 spv_fuzzer_options options, int32_t replay_range); 791 792 // Sets the maximum number of steps that the shrinker should take before giving 793 // up. 794 SPIRV_TOOLS_EXPORT void spvFuzzerOptionsSetShrinkerStepLimit( 795 spv_fuzzer_options options, uint32_t shrinker_step_limit); 796 797 // Enables running the validator after every pass is applied during a fuzzing 798 // run. 799 SPIRV_TOOLS_EXPORT void spvFuzzerOptionsEnableFuzzerPassValidation( 800 spv_fuzzer_options options); 801 802 // Enables all fuzzer passes during a fuzzing run (instead of a random subset 803 // of passes). 804 SPIRV_TOOLS_EXPORT void spvFuzzerOptionsEnableAllPasses( 805 spv_fuzzer_options options); 806 807 // Encodes the given SPIR-V assembly text to its binary representation. The 808 // length parameter specifies the number of bytes for text. Encoded binary will 809 // be stored into *binary. Any error will be written into *diagnostic if 810 // diagnostic is non-null, otherwise the context's message consumer will be 811 // used. The generated binary is independent of the context and may outlive it. 812 // The SPIR-V binary version is set to the highest version of SPIR-V supported 813 // by the context's target environment. 814 SPIRV_TOOLS_EXPORT spv_result_t spvTextToBinary(const spv_const_context context, 815 const char* text, 816 const size_t length, 817 spv_binary* binary, 818 spv_diagnostic* diagnostic); 819 820 // Encodes the given SPIR-V assembly text to its binary representation. Same as 821 // spvTextToBinary but with options. The options parameter is a bit field of 822 // spv_text_to_binary_options_t. 823 SPIRV_TOOLS_EXPORT spv_result_t spvTextToBinaryWithOptions( 824 const spv_const_context context, const char* text, const size_t length, 825 const uint32_t options, spv_binary* binary, spv_diagnostic* diagnostic); 826 827 // Frees an allocated text stream. This is a no-op if the text parameter 828 // is a null pointer. 829 SPIRV_TOOLS_EXPORT void spvTextDestroy(spv_text text); 830 831 // Decodes the given SPIR-V binary representation to its assembly text. The 832 // word_count parameter specifies the number of words for binary. The options 833 // parameter is a bit field of spv_binary_to_text_options_t. Decoded text will 834 // be stored into *text. Any error will be written into *diagnostic if 835 // diagnostic is non-null, otherwise the context's message consumer will be 836 // used. 837 SPIRV_TOOLS_EXPORT spv_result_t spvBinaryToText(const spv_const_context context, 838 const uint32_t* binary, 839 const size_t word_count, 840 const uint32_t options, 841 spv_text* text, 842 spv_diagnostic* diagnostic); 843 844 // Frees a binary stream from memory. This is a no-op if binary is a null 845 // pointer. 846 SPIRV_TOOLS_EXPORT void spvBinaryDestroy(spv_binary binary); 847 848 // Validates a SPIR-V binary for correctness. Any errors will be written into 849 // *diagnostic if diagnostic is non-null, otherwise the context's message 850 // consumer will be used. 851 // 852 // Validate for SPIR-V spec rules for the SPIR-V version named in the 853 // binary's header (at word offset 1). Additionally, if the context target 854 // environment is a client API (such as Vulkan 1.1), then validate for that 855 // client API version, to the extent that it is verifiable from data in the 856 // binary itself. 857 SPIRV_TOOLS_EXPORT spv_result_t spvValidate(const spv_const_context context, 858 const spv_const_binary binary, 859 spv_diagnostic* diagnostic); 860 861 // Validates a SPIR-V binary for correctness. Uses the provided Validator 862 // options. Any errors will be written into *diagnostic if diagnostic is 863 // non-null, otherwise the context's message consumer will be used. 864 // 865 // Validate for SPIR-V spec rules for the SPIR-V version named in the 866 // binary's header (at word offset 1). Additionally, if the context target 867 // environment is a client API (such as Vulkan 1.1), then validate for that 868 // client API version, to the extent that it is verifiable from data in the 869 // binary itself, or in the validator options. 870 SPIRV_TOOLS_EXPORT spv_result_t spvValidateWithOptions( 871 const spv_const_context context, const spv_const_validator_options options, 872 const spv_const_binary binary, spv_diagnostic* diagnostic); 873 874 // Validates a raw SPIR-V binary for correctness. Any errors will be written 875 // into *diagnostic if diagnostic is non-null, otherwise the context's message 876 // consumer will be used. 877 SPIRV_TOOLS_EXPORT spv_result_t 878 spvValidateBinary(const spv_const_context context, const uint32_t* words, 879 const size_t num_words, spv_diagnostic* diagnostic); 880 881 // Creates a diagnostic object. The position parameter specifies the location in 882 // the text/binary stream. The message parameter, copied into the diagnostic 883 // object, contains the error message to display. 884 SPIRV_TOOLS_EXPORT spv_diagnostic 885 spvDiagnosticCreate(const spv_position position, const char* message); 886 887 // Destroys a diagnostic object. This is a no-op if diagnostic is a null 888 // pointer. 889 SPIRV_TOOLS_EXPORT void spvDiagnosticDestroy(spv_diagnostic diagnostic); 890 891 // Prints the diagnostic to stderr. 892 SPIRV_TOOLS_EXPORT spv_result_t 893 spvDiagnosticPrint(const spv_diagnostic diagnostic); 894 895 // Gets the name of an instruction, without the "Op" prefix. 896 SPIRV_TOOLS_EXPORT const char* spvOpcodeString(const uint32_t opcode); 897 898 // The binary parser interface. 899 900 // A pointer to a function that accepts a parsed SPIR-V header. 901 // The integer arguments are the 32-bit words from the header, as specified 902 // in SPIR-V 1.0 Section 2.3 Table 1. 903 // The function should return SPV_SUCCESS if parsing should continue. 904 typedef spv_result_t (*spv_parsed_header_fn_t)( 905 void* user_data, spv_endianness_t endian, uint32_t magic, uint32_t version, 906 uint32_t generator, uint32_t id_bound, uint32_t reserved); 907 908 // A pointer to a function that accepts a parsed SPIR-V instruction. 909 // The parsed_instruction value is transient: it may be overwritten 910 // or released immediately after the function has returned. That also 911 // applies to the words array member of the parsed instruction. The 912 // function should return SPV_SUCCESS if and only if parsing should 913 // continue. 914 typedef spv_result_t (*spv_parsed_instruction_fn_t)( 915 void* user_data, const spv_parsed_instruction_t* parsed_instruction); 916 917 // Parses a SPIR-V binary, specified as counted sequence of 32-bit words. 918 // Parsing feedback is provided via two callbacks provided as function 919 // pointers. Each callback function pointer can be a null pointer, in 920 // which case it is never called. Otherwise, in a valid parse the 921 // parsed-header callback is called once, and then the parsed-instruction 922 // callback once for each instruction in the stream. The user_data parameter 923 // is supplied as context to the callbacks. Returns SPV_SUCCESS on successful 924 // parse where the callbacks always return SPV_SUCCESS. For an invalid parse, 925 // returns a status code other than SPV_SUCCESS, and if diagnostic is non-null 926 // also emits a diagnostic. If diagnostic is null the context's message consumer 927 // will be used to emit any errors. If a callback returns anything other than 928 // SPV_SUCCESS, then that status code is returned, no further callbacks are 929 // issued, and no additional diagnostics are emitted. 930 SPIRV_TOOLS_EXPORT spv_result_t spvBinaryParse( 931 const spv_const_context context, void* user_data, const uint32_t* words, 932 const size_t num_words, spv_parsed_header_fn_t parse_header, 933 spv_parsed_instruction_fn_t parse_instruction, spv_diagnostic* diagnostic); 934 935 // The optimizer interface. 936 937 // A pointer to a function that accepts a log message from an optimizer. 938 typedef void (*spv_message_consumer)( 939 spv_message_level_t, const char*, const spv_position_t*, const char*); 940 941 // Creates and returns an optimizer object. This object must be passed to 942 // optimizer APIs below and is valid until passed to spvOptimizerDestroy. 943 SPIRV_TOOLS_EXPORT spv_optimizer_t* spvOptimizerCreate(spv_target_env env); 944 945 // Destroys the given optimizer object. 946 SPIRV_TOOLS_EXPORT void spvOptimizerDestroy(spv_optimizer_t* optimizer); 947 948 // Sets an spv_message_consumer on an optimizer object. 949 SPIRV_TOOLS_EXPORT void spvOptimizerSetMessageConsumer( 950 spv_optimizer_t* optimizer, spv_message_consumer consumer); 951 952 // Registers passes that attempt to legalize the generated code. 953 SPIRV_TOOLS_EXPORT void spvOptimizerRegisterLegalizationPasses( 954 spv_optimizer_t* optimizer); 955 956 // Registers passes that attempt to improve performance of generated code. 957 SPIRV_TOOLS_EXPORT void spvOptimizerRegisterPerformancePasses( 958 spv_optimizer_t* optimizer); 959 960 // Registers passes that attempt to improve the size of generated code. 961 SPIRV_TOOLS_EXPORT void spvOptimizerRegisterSizePasses( 962 spv_optimizer_t* optimizer); 963 964 // Registers a pass specified by a flag in an optimizer object. 965 SPIRV_TOOLS_EXPORT bool spvOptimizerRegisterPassFromFlag( 966 spv_optimizer_t* optimizer, const char* flag); 967 968 // Registers passes specified by length number of flags in an optimizer object. 969 // Passes may remove interface variables that are unused. 970 SPIRV_TOOLS_EXPORT bool spvOptimizerRegisterPassesFromFlags( 971 spv_optimizer_t* optimizer, const char** flags, const size_t flag_count); 972 973 // Registers passes specified by length number of flags in an optimizer object. 974 // Passes will not remove interface variables. 975 SPIRV_TOOLS_EXPORT bool 976 spvOptimizerRegisterPassesFromFlagsWhilePreservingTheInterface( 977 spv_optimizer_t* optimizer, const char** flags, const size_t flag_count); 978 979 // Optimizes the SPIR-V code of size |word_count| pointed to by |binary| and 980 // returns an optimized spv_binary in |optimized_binary|. 981 // 982 // Returns SPV_SUCCESS on successful optimization, whether or not the module is 983 // modified. Returns an SPV_ERROR_* if the module fails to validate or if 984 // errors occur when processing using any of the registered passes. In that 985 // case, no further passes are executed and the |optimized_binary| contents may 986 // be invalid. 987 // 988 // By default, the binary is validated before any transforms are performed, 989 // and optionally after each transform. Validation uses SPIR-V spec rules 990 // for the SPIR-V version named in the binary's header (at word offset 1). 991 // Additionally, if the target environment is a client API (such as 992 // Vulkan 1.1), then validate for that client API version, to the extent 993 // that it is verifiable from data in the binary itself, or from the 994 // validator options set on the optimizer options. 995 SPIRV_TOOLS_EXPORT spv_result_t spvOptimizerRun( 996 spv_optimizer_t* optimizer, const uint32_t* binary, const size_t word_count, 997 spv_binary* optimized_binary, const spv_optimizer_options options); 998 999 #ifdef __cplusplus 1000 } 1001 #endif 1002 1003 #endif // INCLUDE_SPIRV_TOOLS_LIBSPIRV_H_ 1004