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) _##name = 0x7fff 52 #define SPV_FORCE_32_BIT_ENUM(name) _##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 typedef enum spv_operand_type_t { 117 // A sentinel value. 118 SPV_OPERAND_TYPE_NONE = 0, 119 120 // Set 1: Operands that are IDs. 121 SPV_OPERAND_TYPE_ID, 122 SPV_OPERAND_TYPE_TYPE_ID, 123 SPV_OPERAND_TYPE_RESULT_ID, 124 SPV_OPERAND_TYPE_MEMORY_SEMANTICS_ID, // SPIR-V Sec 3.25 125 SPV_OPERAND_TYPE_SCOPE_ID, // SPIR-V Sec 3.27 126 127 // Set 2: Operands that are literal numbers. 128 SPV_OPERAND_TYPE_LITERAL_INTEGER, // Always unsigned 32-bits. 129 // The Instruction argument to OpExtInst. It's an unsigned 32-bit literal 130 // number indicating which instruction to use from an extended instruction 131 // set. 132 SPV_OPERAND_TYPE_EXTENSION_INSTRUCTION_NUMBER, 133 // The Opcode argument to OpSpecConstantOp. It determines the operation 134 // to be performed on constant operands to compute a specialization constant 135 // result. 136 SPV_OPERAND_TYPE_SPEC_CONSTANT_OP_NUMBER, 137 // A literal number whose format and size are determined by a previous operand 138 // in the same instruction. It's a signed integer, an unsigned integer, or a 139 // floating point number. It also has a specified bit width. The width 140 // may be larger than 32, which would require such a typed literal value to 141 // occupy multiple SPIR-V words. 142 SPV_OPERAND_TYPE_TYPED_LITERAL_NUMBER, 143 144 // Set 3: The literal string operand type. 145 SPV_OPERAND_TYPE_LITERAL_STRING, 146 147 // Set 4: Operands that are a single word enumerated value. 148 SPV_OPERAND_TYPE_SOURCE_LANGUAGE, // SPIR-V Sec 3.2 149 SPV_OPERAND_TYPE_EXECUTION_MODEL, // SPIR-V Sec 3.3 150 SPV_OPERAND_TYPE_ADDRESSING_MODEL, // SPIR-V Sec 3.4 151 SPV_OPERAND_TYPE_MEMORY_MODEL, // SPIR-V Sec 3.5 152 SPV_OPERAND_TYPE_EXECUTION_MODE, // SPIR-V Sec 3.6 153 SPV_OPERAND_TYPE_STORAGE_CLASS, // SPIR-V Sec 3.7 154 SPV_OPERAND_TYPE_DIMENSIONALITY, // SPIR-V Sec 3.8 155 SPV_OPERAND_TYPE_SAMPLER_ADDRESSING_MODE, // SPIR-V Sec 3.9 156 SPV_OPERAND_TYPE_SAMPLER_FILTER_MODE, // SPIR-V Sec 3.10 157 SPV_OPERAND_TYPE_SAMPLER_IMAGE_FORMAT, // SPIR-V Sec 3.11 158 SPV_OPERAND_TYPE_IMAGE_CHANNEL_ORDER, // SPIR-V Sec 3.12 159 SPV_OPERAND_TYPE_IMAGE_CHANNEL_DATA_TYPE, // SPIR-V Sec 3.13 160 SPV_OPERAND_TYPE_FP_ROUNDING_MODE, // SPIR-V Sec 3.16 161 SPV_OPERAND_TYPE_LINKAGE_TYPE, // SPIR-V Sec 3.17 162 SPV_OPERAND_TYPE_ACCESS_QUALIFIER, // SPIR-V Sec 3.18 163 SPV_OPERAND_TYPE_FUNCTION_PARAMETER_ATTRIBUTE, // SPIR-V Sec 3.19 164 SPV_OPERAND_TYPE_DECORATION, // SPIR-V Sec 3.20 165 SPV_OPERAND_TYPE_BUILT_IN, // SPIR-V Sec 3.21 166 SPV_OPERAND_TYPE_GROUP_OPERATION, // SPIR-V Sec 3.28 167 SPV_OPERAND_TYPE_KERNEL_ENQ_FLAGS, // SPIR-V Sec 3.29 168 SPV_OPERAND_TYPE_KERNEL_PROFILING_INFO, // SPIR-V Sec 3.30 169 SPV_OPERAND_TYPE_CAPABILITY, // SPIR-V Sec 3.31 170 SPV_OPERAND_TYPE_RAY_FLAGS, // SPIR-V Sec 3.RF 171 SPV_OPERAND_TYPE_RAY_QUERY_INTERSECTION, // SPIR-V Sec 3.RQIntersection 172 SPV_OPERAND_TYPE_RAY_QUERY_COMMITTED_INTERSECTION_TYPE, // SPIR-V Sec 173 // 3.RQCommitted 174 SPV_OPERAND_TYPE_RAY_QUERY_CANDIDATE_INTERSECTION_TYPE, // SPIR-V Sec 175 // 3.RQCandidate 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 186 // The remaining operand types are only used internally by the assembler. 187 // There are two categories: 188 // Optional : expands to 0 or 1 operand, like ? in regular expressions. 189 // Variable : expands to 0, 1 or many operands or pairs of operands. 190 // This is similar to * in regular expressions. 191 192 // Macros for defining bounds on optional and variable operand types. 193 // Any variable operand type is also optional. 194 #define FIRST_OPTIONAL(ENUM) ENUM, SPV_OPERAND_TYPE_FIRST_OPTIONAL_TYPE = ENUM 195 #define FIRST_VARIABLE(ENUM) ENUM, SPV_OPERAND_TYPE_FIRST_VARIABLE_TYPE = ENUM 196 #define LAST_VARIABLE(ENUM) \ 197 ENUM, SPV_OPERAND_TYPE_LAST_VARIABLE_TYPE = ENUM, \ 198 SPV_OPERAND_TYPE_LAST_OPTIONAL_TYPE = ENUM 199 200 // An optional operand represents zero or one logical operands. 201 // In an instruction definition, this may only appear at the end of the 202 // operand types. 203 FIRST_OPTIONAL(SPV_OPERAND_TYPE_OPTIONAL_ID), 204 // An optional image operand type. 205 SPV_OPERAND_TYPE_OPTIONAL_IMAGE, 206 // An optional memory access type. 207 SPV_OPERAND_TYPE_OPTIONAL_MEMORY_ACCESS, 208 // An optional literal integer. 209 SPV_OPERAND_TYPE_OPTIONAL_LITERAL_INTEGER, 210 // An optional literal number, which may be either integer or floating point. 211 SPV_OPERAND_TYPE_OPTIONAL_LITERAL_NUMBER, 212 // Like SPV_OPERAND_TYPE_TYPED_LITERAL_NUMBER, but optional, and integral. 213 SPV_OPERAND_TYPE_OPTIONAL_TYPED_LITERAL_INTEGER, 214 // An optional literal string. 215 SPV_OPERAND_TYPE_OPTIONAL_LITERAL_STRING, 216 // An optional access qualifier 217 SPV_OPERAND_TYPE_OPTIONAL_ACCESS_QUALIFIER, 218 // An optional context-independent value, or CIV. CIVs are tokens that we can 219 // assemble regardless of where they occur -- literals, IDs, immediate 220 // integers, etc. 221 SPV_OPERAND_TYPE_OPTIONAL_CIV, 222 223 // A variable operand represents zero or more logical operands. 224 // In an instruction definition, this may only appear at the end of the 225 // operand types. 226 FIRST_VARIABLE(SPV_OPERAND_TYPE_VARIABLE_ID), 227 SPV_OPERAND_TYPE_VARIABLE_LITERAL_INTEGER, 228 // A sequence of zero or more pairs of (typed literal integer, Id). 229 // Expands to zero or more: 230 // (SPV_OPERAND_TYPE_TYPED_LITERAL_INTEGER, SPV_OPERAND_TYPE_ID) 231 // where the literal number must always be an integer of some sort. 232 SPV_OPERAND_TYPE_VARIABLE_LITERAL_INTEGER_ID, 233 // A sequence of zero or more pairs of (Id, Literal integer) 234 LAST_VARIABLE(SPV_OPERAND_TYPE_VARIABLE_ID_LITERAL_INTEGER), 235 236 // The following are concrete enum types from the DebugInfo extended 237 // instruction set. 238 SPV_OPERAND_TYPE_DEBUG_INFO_FLAGS, // DebugInfo Sec 3.2. A mask. 239 SPV_OPERAND_TYPE_DEBUG_BASE_TYPE_ATTRIBUTE_ENCODING, // DebugInfo Sec 3.3 240 SPV_OPERAND_TYPE_DEBUG_COMPOSITE_TYPE, // DebugInfo Sec 3.4 241 SPV_OPERAND_TYPE_DEBUG_TYPE_QUALIFIER, // DebugInfo Sec 3.5 242 SPV_OPERAND_TYPE_DEBUG_OPERATION, // DebugInfo Sec 3.6 243 244 // The following are concrete enum types from the OpenCL.DebugInfo.100 245 // extended instruction set. 246 SPV_OPERAND_TYPE_CLDEBUG100_DEBUG_INFO_FLAGS, // Sec 3.2. A Mask 247 SPV_OPERAND_TYPE_CLDEBUG100_DEBUG_BASE_TYPE_ATTRIBUTE_ENCODING, // Sec 3.3 248 SPV_OPERAND_TYPE_CLDEBUG100_DEBUG_COMPOSITE_TYPE, // Sec 3.4 249 SPV_OPERAND_TYPE_CLDEBUG100_DEBUG_TYPE_QUALIFIER, // Sec 3.5 250 SPV_OPERAND_TYPE_CLDEBUG100_DEBUG_OPERATION, // Sec 3.6 251 SPV_OPERAND_TYPE_CLDEBUG100_DEBUG_IMPORTED_ENTITY, // Sec 3.7 252 253 // This is a sentinel value, and does not represent an operand type. 254 // It should come last. 255 SPV_OPERAND_TYPE_NUM_OPERAND_TYPES, 256 257 SPV_FORCE_32_BIT_ENUM(spv_operand_type_t) 258 } spv_operand_type_t; 259 260 typedef enum spv_ext_inst_type_t { 261 SPV_EXT_INST_TYPE_NONE = 0, 262 SPV_EXT_INST_TYPE_GLSL_STD_450, 263 SPV_EXT_INST_TYPE_OPENCL_STD, 264 SPV_EXT_INST_TYPE_SPV_AMD_SHADER_EXPLICIT_VERTEX_PARAMETER, 265 SPV_EXT_INST_TYPE_SPV_AMD_SHADER_TRINARY_MINMAX, 266 SPV_EXT_INST_TYPE_SPV_AMD_GCN_SHADER, 267 SPV_EXT_INST_TYPE_SPV_AMD_SHADER_BALLOT, 268 SPV_EXT_INST_TYPE_DEBUGINFO, 269 SPV_EXT_INST_TYPE_OPENCL_DEBUGINFO_100, 270 271 // Multiple distinct extended instruction set types could return this 272 // value, if they are prefixed with NonSemantic. and are otherwise 273 // unrecognised 274 SPV_EXT_INST_TYPE_NONSEMANTIC_UNKNOWN, 275 276 SPV_FORCE_32_BIT_ENUM(spv_ext_inst_type_t) 277 } spv_ext_inst_type_t; 278 279 // This determines at a high level the kind of a binary-encoded literal 280 // number, but not the bit width. 281 // In principle, these could probably be folded into new entries in 282 // spv_operand_type_t. But then we'd have some special case differences 283 // between the assembler and disassembler. 284 typedef enum spv_number_kind_t { 285 SPV_NUMBER_NONE = 0, // The default for value initialization. 286 SPV_NUMBER_UNSIGNED_INT, 287 SPV_NUMBER_SIGNED_INT, 288 SPV_NUMBER_FLOATING, 289 } spv_number_kind_t; 290 291 typedef enum spv_text_to_binary_options_t { 292 SPV_TEXT_TO_BINARY_OPTION_NONE = SPV_BIT(0), 293 // Numeric IDs in the binary will have the same values as in the source. 294 // Non-numeric IDs are allocated by filling in the gaps, starting with 1 295 // and going up. 296 SPV_TEXT_TO_BINARY_OPTION_PRESERVE_NUMERIC_IDS = SPV_BIT(1), 297 SPV_FORCE_32_BIT_ENUM(spv_text_to_binary_options_t) 298 } spv_text_to_binary_options_t; 299 300 typedef enum spv_binary_to_text_options_t { 301 SPV_BINARY_TO_TEXT_OPTION_NONE = SPV_BIT(0), 302 SPV_BINARY_TO_TEXT_OPTION_PRINT = SPV_BIT(1), 303 SPV_BINARY_TO_TEXT_OPTION_COLOR = SPV_BIT(2), 304 SPV_BINARY_TO_TEXT_OPTION_INDENT = SPV_BIT(3), 305 SPV_BINARY_TO_TEXT_OPTION_SHOW_BYTE_OFFSET = SPV_BIT(4), 306 // Do not output the module header as leading comments in the assembly. 307 SPV_BINARY_TO_TEXT_OPTION_NO_HEADER = SPV_BIT(5), 308 // Use friendly names where possible. The heuristic may expand over 309 // time, but will use common names for scalar types, and debug names from 310 // OpName instructions. 311 SPV_BINARY_TO_TEXT_OPTION_FRIENDLY_NAMES = SPV_BIT(6), 312 SPV_FORCE_32_BIT_ENUM(spv_binary_to_text_options_t) 313 } spv_binary_to_text_options_t; 314 315 // Constants 316 317 // The default id bound is to the minimum value for the id limit 318 // in the spir-v specification under the section "Universal Limits". 319 const uint32_t kDefaultMaxIdBound = 0x3FFFFF; 320 321 // Structures 322 323 // Information about an operand parsed from a binary SPIR-V module. 324 // Note that the values are not included. You still need access to the binary 325 // to extract the values. 326 typedef struct spv_parsed_operand_t { 327 // Location of the operand, in words from the start of the instruction. 328 uint16_t offset; 329 // Number of words occupied by this operand. 330 uint16_t num_words; 331 // The "concrete" operand type. See the definition of spv_operand_type_t 332 // for details. 333 spv_operand_type_t type; 334 // If type is a literal number type, then number_kind says whether it's 335 // a signed integer, an unsigned integer, or a floating point number. 336 spv_number_kind_t number_kind; 337 // The number of bits for a literal number type. 338 uint32_t number_bit_width; 339 } spv_parsed_operand_t; 340 341 // An instruction parsed from a binary SPIR-V module. 342 typedef struct spv_parsed_instruction_t { 343 // An array of words for this instruction, in native endianness. 344 const uint32_t* words; 345 // The number of words in this instruction. 346 uint16_t num_words; 347 uint16_t opcode; 348 // The extended instruction type, if opcode is OpExtInst. Otherwise 349 // this is the "none" value. 350 spv_ext_inst_type_t ext_inst_type; 351 // The type id, or 0 if this instruction doesn't have one. 352 uint32_t type_id; 353 // The result id, or 0 if this instruction doesn't have one. 354 uint32_t result_id; 355 // The array of parsed operands. 356 const spv_parsed_operand_t* operands; 357 uint16_t num_operands; 358 } spv_parsed_instruction_t; 359 360 typedef struct spv_const_binary_t { 361 const uint32_t* code; 362 const size_t wordCount; 363 } spv_const_binary_t; 364 365 typedef struct spv_binary_t { 366 uint32_t* code; 367 size_t wordCount; 368 } spv_binary_t; 369 370 typedef struct spv_text_t { 371 const char* str; 372 size_t length; 373 } spv_text_t; 374 375 typedef struct spv_position_t { 376 size_t line; 377 size_t column; 378 size_t index; 379 } spv_position_t; 380 381 typedef struct spv_diagnostic_t { 382 spv_position_t position; 383 char* error; 384 bool isTextSource; 385 } spv_diagnostic_t; 386 387 // Opaque struct containing the context used to operate on a SPIR-V module. 388 // Its object is used by various translation API functions. 389 typedef struct spv_context_t spv_context_t; 390 391 typedef struct spv_validator_options_t spv_validator_options_t; 392 393 typedef struct spv_optimizer_options_t spv_optimizer_options_t; 394 395 typedef struct spv_reducer_options_t spv_reducer_options_t; 396 397 typedef struct spv_fuzzer_options_t spv_fuzzer_options_t; 398 399 // Type Definitions 400 401 typedef spv_const_binary_t* spv_const_binary; 402 typedef spv_binary_t* spv_binary; 403 typedef spv_text_t* spv_text; 404 typedef spv_position_t* spv_position; 405 typedef spv_diagnostic_t* spv_diagnostic; 406 typedef const spv_context_t* spv_const_context; 407 typedef spv_context_t* spv_context; 408 typedef spv_validator_options_t* spv_validator_options; 409 typedef const spv_validator_options_t* spv_const_validator_options; 410 typedef spv_optimizer_options_t* spv_optimizer_options; 411 typedef const spv_optimizer_options_t* spv_const_optimizer_options; 412 typedef spv_reducer_options_t* spv_reducer_options; 413 typedef const spv_reducer_options_t* spv_const_reducer_options; 414 typedef spv_fuzzer_options_t* spv_fuzzer_options; 415 typedef const spv_fuzzer_options_t* spv_const_fuzzer_options; 416 417 // Platform API 418 419 // Returns the SPIRV-Tools software version as a null-terminated string. 420 // The contents of the underlying storage is valid for the remainder of 421 // the process. 422 SPIRV_TOOLS_EXPORT const char* spvSoftwareVersionString(void); 423 // Returns a null-terminated string containing the name of the project, 424 // the software version string, and commit details. 425 // The contents of the underlying storage is valid for the remainder of 426 // the process. 427 SPIRV_TOOLS_EXPORT const char* spvSoftwareVersionDetailsString(void); 428 429 // Certain target environments impose additional restrictions on SPIR-V, so it's 430 // often necessary to specify which one applies. SPV_ENV_UNIVERSAL_* implies an 431 // environment-agnostic SPIR-V. 432 // 433 // When an API method needs to derive a SPIR-V version from a target environment 434 // (from the spv_context object), the method will choose the highest version of 435 // SPIR-V supported by the target environment. Examples: 436 // SPV_ENV_VULKAN_1_0 -> SPIR-V 1.0 437 // SPV_ENV_VULKAN_1_1 -> SPIR-V 1.3 438 // SPV_ENV_VULKAN_1_1_SPIRV_1_4 -> SPIR-V 1.4 439 // SPV_ENV_VULKAN_1_2 -> SPIR-V 1.5 440 // Consult the description of API entry points for specific rules. 441 typedef enum { 442 SPV_ENV_UNIVERSAL_1_0, // SPIR-V 1.0 latest revision, no other restrictions. 443 SPV_ENV_VULKAN_1_0, // Vulkan 1.0 latest revision. 444 SPV_ENV_UNIVERSAL_1_1, // SPIR-V 1.1 latest revision, no other restrictions. 445 SPV_ENV_OPENCL_2_1, // OpenCL Full Profile 2.1 latest revision. 446 SPV_ENV_OPENCL_2_2, // OpenCL Full Profile 2.2 latest revision. 447 SPV_ENV_OPENGL_4_0, // OpenGL 4.0 plus GL_ARB_gl_spirv, latest revisions. 448 SPV_ENV_OPENGL_4_1, // OpenGL 4.1 plus GL_ARB_gl_spirv, latest revisions. 449 SPV_ENV_OPENGL_4_2, // OpenGL 4.2 plus GL_ARB_gl_spirv, latest revisions. 450 SPV_ENV_OPENGL_4_3, // OpenGL 4.3 plus GL_ARB_gl_spirv, latest revisions. 451 // There is no variant for OpenGL 4.4. 452 SPV_ENV_OPENGL_4_5, // OpenGL 4.5 plus GL_ARB_gl_spirv, latest revisions. 453 SPV_ENV_UNIVERSAL_1_2, // SPIR-V 1.2, latest revision, no other restrictions. 454 SPV_ENV_OPENCL_1_2, // OpenCL Full Profile 1.2 plus cl_khr_il_program, 455 // latest revision. 456 SPV_ENV_OPENCL_EMBEDDED_1_2, // OpenCL Embedded Profile 1.2 plus 457 // cl_khr_il_program, latest revision. 458 SPV_ENV_OPENCL_2_0, // OpenCL Full Profile 2.0 plus cl_khr_il_program, 459 // latest revision. 460 SPV_ENV_OPENCL_EMBEDDED_2_0, // OpenCL Embedded Profile 2.0 plus 461 // cl_khr_il_program, latest revision. 462 SPV_ENV_OPENCL_EMBEDDED_2_1, // OpenCL Embedded Profile 2.1 latest revision. 463 SPV_ENV_OPENCL_EMBEDDED_2_2, // OpenCL Embedded Profile 2.2 latest revision. 464 SPV_ENV_UNIVERSAL_1_3, // SPIR-V 1.3 latest revision, no other restrictions. 465 SPV_ENV_VULKAN_1_1, // Vulkan 1.1 latest revision. 466 SPV_ENV_WEBGPU_0, // Work in progress WebGPU 1.0. 467 SPV_ENV_UNIVERSAL_1_4, // SPIR-V 1.4 latest revision, no other restrictions. 468 469 // Vulkan 1.1 with VK_KHR_spirv_1_4, i.e. SPIR-V 1.4 binary. 470 SPV_ENV_VULKAN_1_1_SPIRV_1_4, 471 472 SPV_ENV_UNIVERSAL_1_5, // SPIR-V 1.5 latest revision, no other restrictions. 473 SPV_ENV_VULKAN_1_2, // Vulkan 1.2 latest revision. 474 } spv_target_env; 475 476 // SPIR-V Validator can be parameterized with the following Universal Limits. 477 typedef enum { 478 spv_validator_limit_max_struct_members, 479 spv_validator_limit_max_struct_depth, 480 spv_validator_limit_max_local_variables, 481 spv_validator_limit_max_global_variables, 482 spv_validator_limit_max_switch_branches, 483 spv_validator_limit_max_function_args, 484 spv_validator_limit_max_control_flow_nesting_depth, 485 spv_validator_limit_max_access_chain_indexes, 486 spv_validator_limit_max_id_bound, 487 } spv_validator_limit; 488 489 // Returns a string describing the given SPIR-V target environment. 490 SPIRV_TOOLS_EXPORT const char* spvTargetEnvDescription(spv_target_env env); 491 492 // Parses s into *env and returns true if successful. If unparsable, returns 493 // false and sets *env to SPV_ENV_UNIVERSAL_1_0. 494 SPIRV_TOOLS_EXPORT bool spvParseTargetEnv(const char* s, spv_target_env* env); 495 496 // Determines the target env value with the least features but which enables 497 // the given Vulkan and SPIR-V versions. If such a target is supported, returns 498 // true and writes the value to |env|, otherwise returns false. 499 // 500 // The Vulkan version is given as an unsigned 32-bit number as specified in 501 // Vulkan section "29.2.1 Version Numbers": the major version number appears 502 // in bits 22 to 21, and the minor version is in bits 12 to 21. The SPIR-V 503 // version is given in the SPIR-V version header word: major version in bits 504 // 16 to 23, and minor version in bits 8 to 15. 505 SPIRV_TOOLS_EXPORT bool spvParseVulkanEnv(uint32_t vulkan_ver, 506 uint32_t spirv_ver, 507 spv_target_env* env); 508 509 // Creates a context object for most of the SPIRV-Tools API. 510 // Returns null if env is invalid. 511 // 512 // See specific API calls for how the target environment is interpeted 513 // (particularly assembly and validation). 514 SPIRV_TOOLS_EXPORT spv_context spvContextCreate(spv_target_env env); 515 516 // Destroys the given context object. 517 SPIRV_TOOLS_EXPORT void spvContextDestroy(spv_context context); 518 519 // Creates a Validator options object with default options. Returns a valid 520 // options object. The object remains valid until it is passed into 521 // spvValidatorOptionsDestroy. 522 SPIRV_TOOLS_EXPORT spv_validator_options spvValidatorOptionsCreate(void); 523 524 // Destroys the given Validator options object. 525 SPIRV_TOOLS_EXPORT void spvValidatorOptionsDestroy( 526 spv_validator_options options); 527 528 // Records the maximum Universal Limit that is considered valid in the given 529 // Validator options object. <options> argument must be a valid options object. 530 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetUniversalLimit( 531 spv_validator_options options, spv_validator_limit limit_type, 532 uint32_t limit); 533 534 // Record whether or not the validator should relax the rules on types for 535 // stores to structs. When relaxed, it will allow a type mismatch as long as 536 // the types are structs with the same layout. Two structs have the same layout 537 // if 538 // 539 // 1) the members of the structs are either the same type or are structs with 540 // same layout, and 541 // 542 // 2) the decorations that affect the memory layout are identical for both 543 // types. Other decorations are not relevant. 544 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetRelaxStoreStruct( 545 spv_validator_options options, bool val); 546 547 // Records whether or not the validator should relax the rules on pointer usage 548 // in logical addressing mode. 549 // 550 // When relaxed, it will allow the following usage cases of pointers: 551 // 1) OpVariable allocating an object whose type is a pointer type 552 // 2) OpReturnValue returning a pointer value 553 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetRelaxLogicalPointer( 554 spv_validator_options options, bool val); 555 556 // Records whether or not the validator should relax the rules because it is 557 // expected that the optimizations will make the code legal. 558 // 559 // When relaxed, it will allow the following: 560 // 1) It will allow relaxed logical pointers. Setting this option will also 561 // set that option. 562 // 2) Pointers that are pass as parameters to function calls do not have to 563 // match the storage class of the formal parameter. 564 // 3) Pointers that are actaul parameters on function calls do not have to point 565 // to the same type pointed as the formal parameter. The types just need to 566 // logically match. 567 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetBeforeHlslLegalization( 568 spv_validator_options options, bool val); 569 570 // Records whether the validator should use "relaxed" block layout rules. 571 // Relaxed layout rules are described by Vulkan extension 572 // VK_KHR_relaxed_block_layout, and they affect uniform blocks, storage blocks, 573 // and push constants. 574 // 575 // This is enabled by default when targeting Vulkan 1.1 or later. 576 // Relaxed layout is more permissive than the default rules in Vulkan 1.0. 577 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetRelaxBlockLayout( 578 spv_validator_options options, bool val); 579 580 // Records whether the validator should use standard block layout rules for 581 // uniform blocks. 582 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetUniformBufferStandardLayout( 583 spv_validator_options options, bool val); 584 585 // Records whether the validator should use "scalar" block layout rules. 586 // Scalar layout rules are more permissive than relaxed block layout. 587 // 588 // See Vulkan extnesion VK_EXT_scalar_block_layout. The scalar alignment is 589 // defined as follows: 590 // - scalar alignment of a scalar is the scalar size 591 // - scalar alignment of a vector is the scalar alignment of its component 592 // - scalar alignment of a matrix is the scalar alignment of its component 593 // - scalar alignment of an array is the scalar alignment of its element 594 // - scalar alignment of a struct is the max scalar alignment among its 595 // members 596 // 597 // For a struct in Uniform, StorageClass, or PushConstant: 598 // - a member Offset must be a multiple of the member's scalar alignment 599 // - ArrayStride or MatrixStride must be a multiple of the array or matrix 600 // scalar alignment 601 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetScalarBlockLayout( 602 spv_validator_options options, bool val); 603 604 // Records whether or not the validator should skip validating standard 605 // uniform/storage block layout. 606 SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetSkipBlockLayout( 607 spv_validator_options options, bool val); 608 609 // Creates an optimizer options object with default options. Returns a valid 610 // options object. The object remains valid until it is passed into 611 // |spvOptimizerOptionsDestroy|. 612 SPIRV_TOOLS_EXPORT spv_optimizer_options spvOptimizerOptionsCreate(void); 613 614 // Destroys the given optimizer options object. 615 SPIRV_TOOLS_EXPORT void spvOptimizerOptionsDestroy( 616 spv_optimizer_options options); 617 618 // Records whether or not the optimizer should run the validator before 619 // optimizing. If |val| is true, the validator will be run. 620 SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetRunValidator( 621 spv_optimizer_options options, bool val); 622 623 // Records the validator options that should be passed to the validator if it is 624 // run. 625 SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetValidatorOptions( 626 spv_optimizer_options options, spv_validator_options val); 627 628 // Records the maximum possible value for the id bound. 629 SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetMaxIdBound( 630 spv_optimizer_options options, uint32_t val); 631 632 // Records whether all bindings within the module should be preserved. 633 SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetPreserveBindings( 634 spv_optimizer_options options, bool val); 635 636 // Records whether all specialization constants within the module 637 // should be preserved. 638 SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetPreserveSpecConstants( 639 spv_optimizer_options options, bool val); 640 641 // Creates a reducer options object with default options. Returns a valid 642 // options object. The object remains valid until it is passed into 643 // |spvReducerOptionsDestroy|. 644 SPIRV_TOOLS_EXPORT spv_reducer_options spvReducerOptionsCreate(); 645 646 // Destroys the given reducer options object. 647 SPIRV_TOOLS_EXPORT void spvReducerOptionsDestroy(spv_reducer_options options); 648 649 // Sets the maximum number of reduction steps that should run before the reducer 650 // gives up. 651 SPIRV_TOOLS_EXPORT void spvReducerOptionsSetStepLimit( 652 spv_reducer_options options, uint32_t step_limit); 653 654 // Sets the fail-on-validation-error option; if true, the reducer will return 655 // kStateInvalid if a reduction step yields a state that fails SPIR-V 656 // validation. Otherwise, an invalid state is treated as uninteresting and the 657 // reduction backtracks and continues. 658 SPIRV_TOOLS_EXPORT void spvReducerOptionsSetFailOnValidationError( 659 spv_reducer_options options, bool fail_on_validation_error); 660 661 // Creates a fuzzer options object with default options. Returns a valid 662 // options object. The object remains valid until it is passed into 663 // |spvFuzzerOptionsDestroy|. 664 SPIRV_TOOLS_EXPORT spv_fuzzer_options spvFuzzerOptionsCreate(); 665 666 // Destroys the given fuzzer options object. 667 SPIRV_TOOLS_EXPORT void spvFuzzerOptionsDestroy(spv_fuzzer_options options); 668 669 // Enables running the validator after every transformation is applied during 670 // a replay. 671 SPIRV_TOOLS_EXPORT void spvFuzzerOptionsEnableReplayValidation( 672 spv_fuzzer_options options); 673 674 // Sets the seed with which the random number generator used by the fuzzer 675 // should be initialized. 676 SPIRV_TOOLS_EXPORT void spvFuzzerOptionsSetRandomSeed( 677 spv_fuzzer_options options, uint32_t seed); 678 679 // Sets the maximum number of steps that the shrinker should take before giving 680 // up. 681 SPIRV_TOOLS_EXPORT void spvFuzzerOptionsSetShrinkerStepLimit( 682 spv_fuzzer_options options, uint32_t shrinker_step_limit); 683 684 // Enables running the validator after every pass is applied during a fuzzing 685 // run. 686 SPIRV_TOOLS_EXPORT void spvFuzzerOptionsEnableFuzzerPassValidation( 687 spv_fuzzer_options options); 688 689 // Encodes the given SPIR-V assembly text to its binary representation. The 690 // length parameter specifies the number of bytes for text. Encoded binary will 691 // be stored into *binary. Any error will be written into *diagnostic if 692 // diagnostic is non-null, otherwise the context's message consumer will be 693 // used. The generated binary is independent of the context and may outlive it. 694 // The SPIR-V binary version is set to the highest version of SPIR-V supported 695 // by the context's target environment. 696 SPIRV_TOOLS_EXPORT spv_result_t spvTextToBinary(const spv_const_context context, 697 const char* text, 698 const size_t length, 699 spv_binary* binary, 700 spv_diagnostic* diagnostic); 701 702 // Encodes the given SPIR-V assembly text to its binary representation. Same as 703 // spvTextToBinary but with options. The options parameter is a bit field of 704 // spv_text_to_binary_options_t. 705 SPIRV_TOOLS_EXPORT spv_result_t spvTextToBinaryWithOptions( 706 const spv_const_context context, const char* text, const size_t length, 707 const uint32_t options, spv_binary* binary, spv_diagnostic* diagnostic); 708 709 // Frees an allocated text stream. This is a no-op if the text parameter 710 // is a null pointer. 711 SPIRV_TOOLS_EXPORT void spvTextDestroy(spv_text text); 712 713 // Decodes the given SPIR-V binary representation to its assembly text. The 714 // word_count parameter specifies the number of words for binary. The options 715 // parameter is a bit field of spv_binary_to_text_options_t. Decoded text will 716 // be stored into *text. Any error will be written into *diagnostic if 717 // diagnostic is non-null, otherwise the context's message consumer will be 718 // used. 719 SPIRV_TOOLS_EXPORT spv_result_t spvBinaryToText(const spv_const_context context, 720 const uint32_t* binary, 721 const size_t word_count, 722 const uint32_t options, 723 spv_text* text, 724 spv_diagnostic* diagnostic); 725 726 // Frees a binary stream from memory. This is a no-op if binary is a null 727 // pointer. 728 SPIRV_TOOLS_EXPORT void spvBinaryDestroy(spv_binary binary); 729 730 // Validates a SPIR-V binary for correctness. Any errors will be written into 731 // *diagnostic if diagnostic is non-null, otherwise the context's message 732 // consumer will be used. 733 // 734 // Validate for SPIR-V spec rules for the SPIR-V version named in the 735 // binary's header (at word offset 1). Additionally, if the context target 736 // environment is a client API (such as Vulkan 1.1), then validate for that 737 // client API version, to the extent that it is verifiable from data in the 738 // binary itself. 739 SPIRV_TOOLS_EXPORT spv_result_t spvValidate(const spv_const_context context, 740 const spv_const_binary binary, 741 spv_diagnostic* diagnostic); 742 743 // Validates a SPIR-V binary for correctness. Uses the provided Validator 744 // options. Any errors will be written into *diagnostic if diagnostic is 745 // non-null, otherwise the context's message consumer will be used. 746 // 747 // Validate for SPIR-V spec rules for the SPIR-V version named in the 748 // binary's header (at word offset 1). Additionally, if the context target 749 // environment is a client API (such as Vulkan 1.1), then validate for that 750 // client API version, to the extent that it is verifiable from data in the 751 // binary itself, or in the validator options. 752 SPIRV_TOOLS_EXPORT spv_result_t spvValidateWithOptions( 753 const spv_const_context context, const spv_const_validator_options options, 754 const spv_const_binary binary, spv_diagnostic* diagnostic); 755 756 // Validates a raw SPIR-V binary for correctness. Any errors will be written 757 // into *diagnostic if diagnostic is non-null, otherwise the context's message 758 // consumer will be used. 759 SPIRV_TOOLS_EXPORT spv_result_t 760 spvValidateBinary(const spv_const_context context, const uint32_t* words, 761 const size_t num_words, spv_diagnostic* diagnostic); 762 763 // Creates a diagnostic object. The position parameter specifies the location in 764 // the text/binary stream. The message parameter, copied into the diagnostic 765 // object, contains the error message to display. 766 SPIRV_TOOLS_EXPORT spv_diagnostic 767 spvDiagnosticCreate(const spv_position position, const char* message); 768 769 // Destroys a diagnostic object. This is a no-op if diagnostic is a null 770 // pointer. 771 SPIRV_TOOLS_EXPORT void spvDiagnosticDestroy(spv_diagnostic diagnostic); 772 773 // Prints the diagnostic to stderr. 774 SPIRV_TOOLS_EXPORT spv_result_t 775 spvDiagnosticPrint(const spv_diagnostic diagnostic); 776 777 // Gets the name of an instruction, without the "Op" prefix. 778 SPIRV_TOOLS_EXPORT const char* spvOpcodeString(const uint32_t opcode); 779 780 // The binary parser interface. 781 782 // A pointer to a function that accepts a parsed SPIR-V header. 783 // The integer arguments are the 32-bit words from the header, as specified 784 // in SPIR-V 1.0 Section 2.3 Table 1. 785 // The function should return SPV_SUCCESS if parsing should continue. 786 typedef spv_result_t (*spv_parsed_header_fn_t)( 787 void* user_data, spv_endianness_t endian, uint32_t magic, uint32_t version, 788 uint32_t generator, uint32_t id_bound, uint32_t reserved); 789 790 // A pointer to a function that accepts a parsed SPIR-V instruction. 791 // The parsed_instruction value is transient: it may be overwritten 792 // or released immediately after the function has returned. That also 793 // applies to the words array member of the parsed instruction. The 794 // function should return SPV_SUCCESS if and only if parsing should 795 // continue. 796 typedef spv_result_t (*spv_parsed_instruction_fn_t)( 797 void* user_data, const spv_parsed_instruction_t* parsed_instruction); 798 799 // Parses a SPIR-V binary, specified as counted sequence of 32-bit words. 800 // Parsing feedback is provided via two callbacks provided as function 801 // pointers. Each callback function pointer can be a null pointer, in 802 // which case it is never called. Otherwise, in a valid parse the 803 // parsed-header callback is called once, and then the parsed-instruction 804 // callback once for each instruction in the stream. The user_data parameter 805 // is supplied as context to the callbacks. Returns SPV_SUCCESS on successful 806 // parse where the callbacks always return SPV_SUCCESS. For an invalid parse, 807 // returns a status code other than SPV_SUCCESS, and if diagnostic is non-null 808 // also emits a diagnostic. If diagnostic is null the context's message consumer 809 // will be used to emit any errors. If a callback returns anything other than 810 // SPV_SUCCESS, then that status code is returned, no further callbacks are 811 // issued, and no additional diagnostics are emitted. 812 SPIRV_TOOLS_EXPORT spv_result_t spvBinaryParse( 813 const spv_const_context context, void* user_data, const uint32_t* words, 814 const size_t num_words, spv_parsed_header_fn_t parse_header, 815 spv_parsed_instruction_fn_t parse_instruction, spv_diagnostic* diagnostic); 816 817 #ifdef __cplusplus 818 } 819 #endif 820 821 #endif // INCLUDE_SPIRV_TOOLS_LIBSPIRV_H_ 822