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 INCLUDE_SPIRV_TOOLS_LIBSPIRV_H_
16#define INCLUDE_SPIRV_TOOLS_LIBSPIRV_H_
17
18#ifdef __cplusplus
19extern "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
54typedef 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.
81typedef 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
95typedef 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.
114typedef 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
242typedef 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.
260typedef 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
267typedef 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
276typedef 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// Constants
292
293// The default id bound is to the minimum value for the id limit
294// in the spir-v specification under the section "Universal Limits".
295const uint32_t kDefaultMaxIdBound = 0x3FFFFF;
296
297// Structures
298
299// Information about an operand parsed from a binary SPIR-V module.
300// Note that the values are not included. You still need access to the binary
301// to extract the values.
302typedef struct spv_parsed_operand_t {
303 // Location of the operand, in words from the start of the instruction.
304 uint16_t offset;
305 // Number of words occupied by this operand.
306 uint16_t num_words;
307 // The "concrete" operand type. See the definition of spv_operand_type_t
308 // for details.
309 spv_operand_type_t type;
310 // If type is a literal number type, then number_kind says whether it's
311 // a signed integer, an unsigned integer, or a floating point number.
312 spv_number_kind_t number_kind;
313 // The number of bits for a literal number type.
314 uint32_t number_bit_width;
315} spv_parsed_operand_t;
316
317// An instruction parsed from a binary SPIR-V module.
318typedef struct spv_parsed_instruction_t {
319 // An array of words for this instruction, in native endianness.
320 const uint32_t* words;
321 // The number of words in this instruction.
322 uint16_t num_words;
323 uint16_t opcode;
324 // The extended instruction type, if opcode is OpExtInst. Otherwise
325 // this is the "none" value.
326 spv_ext_inst_type_t ext_inst_type;
327 // The type id, or 0 if this instruction doesn't have one.
328 uint32_t type_id;
329 // The result id, or 0 if this instruction doesn't have one.
330 uint32_t result_id;
331 // The array of parsed operands.
332 const spv_parsed_operand_t* operands;
333 uint16_t num_operands;
334} spv_parsed_instruction_t;
335
336typedef struct spv_const_binary_t {
337 const uint32_t* code;
338 const size_t wordCount;
339} spv_const_binary_t;
340
341typedef struct spv_binary_t {
342 uint32_t* code;
343 size_t wordCount;
344} spv_binary_t;
345
346typedef struct spv_text_t {
347 const char* str;
348 size_t length;
349} spv_text_t;
350
351typedef struct spv_position_t {
352 size_t line;
353 size_t column;
354 size_t index;
355} spv_position_t;
356
357typedef struct spv_diagnostic_t {
358 spv_position_t position;
359 char* error;
360 bool isTextSource;
361} spv_diagnostic_t;
362
363// Opaque struct containing the context used to operate on a SPIR-V module.
364// Its object is used by various translation API functions.
365typedef struct spv_context_t spv_context_t;
366
367typedef struct spv_validator_options_t spv_validator_options_t;
368
369typedef struct spv_optimizer_options_t spv_optimizer_options_t;
370
371typedef struct spv_reducer_options_t spv_reducer_options_t;
372
373typedef struct spv_fuzzer_options_t spv_fuzzer_options_t;
374
375// Type Definitions
376
377typedef spv_const_binary_t* spv_const_binary;
378typedef spv_binary_t* spv_binary;
379typedef spv_text_t* spv_text;
380typedef spv_position_t* spv_position;
381typedef spv_diagnostic_t* spv_diagnostic;
382typedef const spv_context_t* spv_const_context;
383typedef spv_context_t* spv_context;
384typedef spv_validator_options_t* spv_validator_options;
385typedef const spv_validator_options_t* spv_const_validator_options;
386typedef spv_optimizer_options_t* spv_optimizer_options;
387typedef const spv_optimizer_options_t* spv_const_optimizer_options;
388typedef spv_reducer_options_t* spv_reducer_options;
389typedef const spv_reducer_options_t* spv_const_reducer_options;
390typedef spv_fuzzer_options_t* spv_fuzzer_options;
391typedef const spv_fuzzer_options_t* spv_const_fuzzer_options;
392
393// Platform API
394
395// Returns the SPIRV-Tools software version as a null-terminated string.
396// The contents of the underlying storage is valid for the remainder of
397// the process.
398SPIRV_TOOLS_EXPORT const char* spvSoftwareVersionString(void);
399// Returns a null-terminated string containing the name of the project,
400// the software version string, and commit details.
401// The contents of the underlying storage is valid for the remainder of
402// the process.
403SPIRV_TOOLS_EXPORT const char* spvSoftwareVersionDetailsString(void);
404
405// Certain target environments impose additional restrictions on SPIR-V, so it's
406// often necessary to specify which one applies. SPV_ENV_UNIVERSAL means
407// environment-agnostic SPIR-V.
408typedef enum {
409 SPV_ENV_UNIVERSAL_1_0, // SPIR-V 1.0 latest revision, no other restrictions.
410 SPV_ENV_VULKAN_1_0, // Vulkan 1.0 latest revision.
411 SPV_ENV_UNIVERSAL_1_1, // SPIR-V 1.1 latest revision, no other restrictions.
412 SPV_ENV_OPENCL_2_1, // OpenCL Full Profile 2.1 latest revision.
413 SPV_ENV_OPENCL_2_2, // OpenCL Full Profile 2.2 latest revision.
414 SPV_ENV_OPENGL_4_0, // OpenGL 4.0 plus GL_ARB_gl_spirv, latest revisions.
415 SPV_ENV_OPENGL_4_1, // OpenGL 4.1 plus GL_ARB_gl_spirv, latest revisions.
416 SPV_ENV_OPENGL_4_2, // OpenGL 4.2 plus GL_ARB_gl_spirv, latest revisions.
417 SPV_ENV_OPENGL_4_3, // OpenGL 4.3 plus GL_ARB_gl_spirv, latest revisions.
418 // There is no variant for OpenGL 4.4.
419 SPV_ENV_OPENGL_4_5, // OpenGL 4.5 plus GL_ARB_gl_spirv, latest revisions.
420 SPV_ENV_UNIVERSAL_1_2, // SPIR-V 1.2, latest revision, no other restrictions.
421 SPV_ENV_OPENCL_1_2, // OpenCL Full Profile 1.2 plus cl_khr_il_program,
422 // latest revision.
423 SPV_ENV_OPENCL_EMBEDDED_1_2, // OpenCL Embedded Profile 1.2 plus
424 // cl_khr_il_program, latest revision.
425 SPV_ENV_OPENCL_2_0, // OpenCL Full Profile 2.0 plus cl_khr_il_program,
426 // latest revision.
427 SPV_ENV_OPENCL_EMBEDDED_2_0, // OpenCL Embedded Profile 2.0 plus
428 // cl_khr_il_program, latest revision.
429 SPV_ENV_OPENCL_EMBEDDED_2_1, // OpenCL Embedded Profile 2.1 latest revision.
430 SPV_ENV_OPENCL_EMBEDDED_2_2, // OpenCL Embedded Profile 2.2 latest revision.
431 SPV_ENV_UNIVERSAL_1_3, // SPIR-V 1.3 latest revision, no other restrictions.
432 SPV_ENV_VULKAN_1_1, // Vulkan 1.1 latest revision.
433 SPV_ENV_WEBGPU_0, // Work in progress WebGPU 1.0.
434 SPV_ENV_UNIVERSAL_1_4, // SPIR-V 1.4 latest revision, no other restrictions.
435 SPV_ENV_VULKAN_1_1_SPIRV_1_4, // Vulkan 1.1 with SPIR-V 1.4 binary.
436} spv_target_env;
437
438// SPIR-V Validator can be parameterized with the following Universal Limits.
439typedef enum {
440 spv_validator_limit_max_struct_members,
441 spv_validator_limit_max_struct_depth,
442 spv_validator_limit_max_local_variables,
443 spv_validator_limit_max_global_variables,
444 spv_validator_limit_max_switch_branches,
445 spv_validator_limit_max_function_args,
446 spv_validator_limit_max_control_flow_nesting_depth,
447 spv_validator_limit_max_access_chain_indexes,
448 spv_validator_limit_max_id_bound,
449} spv_validator_limit;
450
451// Returns a string describing the given SPIR-V target environment.
452SPIRV_TOOLS_EXPORT const char* spvTargetEnvDescription(spv_target_env env);
453
454// Parses s into *env and returns true if successful. If unparsable, returns
455// false and sets *env to SPV_ENV_UNIVERSAL_1_0.
456SPIRV_TOOLS_EXPORT bool spvParseTargetEnv(const char* s, spv_target_env* env);
457
458// Creates a context object. Returns null if env is invalid.
459SPIRV_TOOLS_EXPORT spv_context spvContextCreate(spv_target_env env);
460
461// Destroys the given context object.
462SPIRV_TOOLS_EXPORT void spvContextDestroy(spv_context context);
463
464// Creates a Validator options object with default options. Returns a valid
465// options object. The object remains valid until it is passed into
466// spvValidatorOptionsDestroy.
467SPIRV_TOOLS_EXPORT spv_validator_options spvValidatorOptionsCreate(void);
468
469// Destroys the given Validator options object.
470SPIRV_TOOLS_EXPORT void spvValidatorOptionsDestroy(
471 spv_validator_options options);
472
473// Records the maximum Universal Limit that is considered valid in the given
474// Validator options object. <options> argument must be a valid options object.
475SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetUniversalLimit(
476 spv_validator_options options, spv_validator_limit limit_type,
477 uint32_t limit);
478
479// Record whether or not the validator should relax the rules on types for
480// stores to structs. When relaxed, it will allow a type mismatch as long as
481// the types are structs with the same layout. Two structs have the same layout
482// if
483//
484// 1) the members of the structs are either the same type or are structs with
485// same layout, and
486//
487// 2) the decorations that affect the memory layout are identical for both
488// types. Other decorations are not relevant.
489SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetRelaxStoreStruct(
490 spv_validator_options options, bool val);
491
492// Records whether or not the validator should relax the rules on pointer usage
493// in logical addressing mode.
494//
495// When relaxed, it will allow the following usage cases of pointers:
496// 1) OpVariable allocating an object whose type is a pointer type
497// 2) OpReturnValue returning a pointer value
498SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetRelaxLogicalPointer(
499 spv_validator_options options, bool val);
500
501// Records whether or not the validator should relax the rules because it is
502// expected that the optimizations will make the code legal.
503//
504// When relaxed, it will allow the following:
505// 1) It will allow relaxed logical pointers. Setting this option will also
506// set that option.
507// 2) Pointers that are pass as parameters to function calls do not have to
508// match the storage class of the formal parameter.
509// 3) Pointers that are actaul parameters on function calls do not have to point
510// to the same type pointed as the formal parameter. The types just need to
511// logically match.
512SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetBeforeHlslLegalization(
513 spv_validator_options options, bool val);
514
515// Records whether the validator should use "relaxed" block layout rules.
516// Relaxed layout rules are described by Vulkan extension
517// VK_KHR_relaxed_block_layout, and they affect uniform blocks, storage blocks,
518// and push constants.
519//
520// This is enabled by default when targeting Vulkan 1.1 or later.
521// Relaxed layout is more permissive than the default rules in Vulkan 1.0.
522SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetRelaxBlockLayout(
523 spv_validator_options options, bool val);
524
525// Records whether the validator should use standard block layout rules for
526// uniform blocks.
527SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetUniformBufferStandardLayout(
528 spv_validator_options options, bool val);
529
530// Records whether the validator should use "scalar" block layout rules.
531// Scalar layout rules are more permissive than relaxed block layout.
532//
533// See Vulkan extnesion VK_EXT_scalar_block_layout. The scalar alignment is
534// defined as follows:
535// - scalar alignment of a scalar is the scalar size
536// - scalar alignment of a vector is the scalar alignment of its component
537// - scalar alignment of a matrix is the scalar alignment of its component
538// - scalar alignment of an array is the scalar alignment of its element
539// - scalar alignment of a struct is the max scalar alignment among its
540// members
541//
542// For a struct in Uniform, StorageClass, or PushConstant:
543// - a member Offset must be a multiple of the member's scalar alignment
544// - ArrayStride or MatrixStride must be a multiple of the array or matrix
545// scalar alignment
546SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetScalarBlockLayout(
547 spv_validator_options options, bool val);
548
549// Records whether or not the validator should skip validating standard
550// uniform/storage block layout.
551SPIRV_TOOLS_EXPORT void spvValidatorOptionsSetSkipBlockLayout(
552 spv_validator_options options, bool val);
553
554// Creates an optimizer options object with default options. Returns a valid
555// options object. The object remains valid until it is passed into
556// |spvOptimizerOptionsDestroy|.
557SPIRV_TOOLS_EXPORT spv_optimizer_options spvOptimizerOptionsCreate(void);
558
559// Destroys the given optimizer options object.
560SPIRV_TOOLS_EXPORT void spvOptimizerOptionsDestroy(
561 spv_optimizer_options options);
562
563// Records whether or not the optimizer should run the validator before
564// optimizing. If |val| is true, the validator will be run.
565SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetRunValidator(
566 spv_optimizer_options options, bool val);
567
568// Records the validator options that should be passed to the validator if it is
569// run.
570SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetValidatorOptions(
571 spv_optimizer_options options, spv_validator_options val);
572
573// Records the maximum possible value for the id bound.
574SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetMaxIdBound(
575 spv_optimizer_options options, uint32_t val);
576
577// Records whether all bindings within the module should be preserved.
578SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetPreserveBindings(
579 spv_optimizer_options options, bool val);
580
581// Records whether all specialization constants within the module
582// should be preserved.
583SPIRV_TOOLS_EXPORT void spvOptimizerOptionsSetPreserveSpecConstants(
584 spv_optimizer_options options, bool val);
585
586// Creates a reducer options object with default options. Returns a valid
587// options object. The object remains valid until it is passed into
588// |spvReducerOptionsDestroy|.
589SPIRV_TOOLS_EXPORT spv_reducer_options spvReducerOptionsCreate();
590
591// Destroys the given reducer options object.
592SPIRV_TOOLS_EXPORT void spvReducerOptionsDestroy(spv_reducer_options options);
593
594// Sets the maximum number of reduction steps that should run before the reducer
595// gives up.
596SPIRV_TOOLS_EXPORT void spvReducerOptionsSetStepLimit(
597 spv_reducer_options options, uint32_t step_limit);
598
599// Sets the fail-on-validation-error option; if true, the reducer will return
600// kStateInvalid if a reduction step yields a state that fails SPIR-V
601// validation. Otherwise, an invalid state is treated as uninteresting and the
602// reduction backtracks and continues.
603SPIRV_TOOLS_EXPORT void spvReducerOptionsSetFailOnValidationError(
604 spv_reducer_options options, bool fail_on_validation_error);
605
606// Creates a fuzzer options object with default options. Returns a valid
607// options object. The object remains valid until it is passed into
608// |spvFuzzerOptionsDestroy|.
609SPIRV_TOOLS_EXPORT spv_fuzzer_options spvFuzzerOptionsCreate();
610
611// Destroys the given fuzzer options object.
612SPIRV_TOOLS_EXPORT void spvFuzzerOptionsDestroy(spv_fuzzer_options options);
613
614// Sets the seed with which the random number generator used by the fuzzer
615// should be initialized.
616SPIRV_TOOLS_EXPORT void spvFuzzerOptionsSetRandomSeed(
617 spv_fuzzer_options options, uint32_t seed);
618
619// Sets the maximum number of steps that the shrinker should take before giving
620// up.
621SPIRV_TOOLS_EXPORT void spvFuzzerOptionsSetShrinkerStepLimit(
622 spv_fuzzer_options options, uint32_t shrinker_step_limit);
623
624// Encodes the given SPIR-V assembly text to its binary representation. The
625// length parameter specifies the number of bytes for text. Encoded binary will
626// be stored into *binary. Any error will be written into *diagnostic if
627// diagnostic is non-null, otherwise the context's message consumer will be
628// used. The generated binary is independent of the context and may outlive it.
629SPIRV_TOOLS_EXPORT spv_result_t spvTextToBinary(const spv_const_context context,
630 const char* text,
631 const size_t length,
632 spv_binary* binary,
633 spv_diagnostic* diagnostic);
634
635// Encodes the given SPIR-V assembly text to its binary representation. Same as
636// spvTextToBinary but with options. The options parameter is a bit field of
637// spv_text_to_binary_options_t.
638SPIRV_TOOLS_EXPORT spv_result_t spvTextToBinaryWithOptions(
639 const spv_const_context context, const char* text, const size_t length,
640 const uint32_t options, spv_binary* binary, spv_diagnostic* diagnostic);
641
642// Frees an allocated text stream. This is a no-op if the text parameter
643// is a null pointer.
644SPIRV_TOOLS_EXPORT void spvTextDestroy(spv_text text);
645
646// Decodes the given SPIR-V binary representation to its assembly text. The
647// word_count parameter specifies the number of words for binary. The options
648// parameter is a bit field of spv_binary_to_text_options_t. Decoded text will
649// be stored into *text. Any error will be written into *diagnostic if
650// diagnostic is non-null, otherwise the context's message consumer will be
651// used.
652SPIRV_TOOLS_EXPORT spv_result_t spvBinaryToText(const spv_const_context context,
653 const uint32_t* binary,
654 const size_t word_count,
655 const uint32_t options,
656 spv_text* text,
657 spv_diagnostic* diagnostic);
658
659// Frees a binary stream from memory. This is a no-op if binary is a null
660// pointer.
661SPIRV_TOOLS_EXPORT void spvBinaryDestroy(spv_binary binary);
662
663// Validates a SPIR-V binary for correctness. Any errors will be written into
664// *diagnostic if diagnostic is non-null, otherwise the context's message
665// consumer will be used.
666SPIRV_TOOLS_EXPORT spv_result_t spvValidate(const spv_const_context context,
667 const spv_const_binary binary,
668 spv_diagnostic* diagnostic);
669
670// Validates a SPIR-V binary for correctness. Uses the provided Validator
671// options. Any errors will be written into *diagnostic if diagnostic is
672// non-null, otherwise the context's message consumer will be used.
673SPIRV_TOOLS_EXPORT spv_result_t spvValidateWithOptions(
674 const spv_const_context context, const spv_const_validator_options options,
675 const spv_const_binary binary, spv_diagnostic* diagnostic);
676
677// Validates a raw SPIR-V binary for correctness. Any errors will be written
678// into *diagnostic if diagnostic is non-null, otherwise the context's message
679// consumer will be used.
680SPIRV_TOOLS_EXPORT spv_result_t
681spvValidateBinary(const spv_const_context context, const uint32_t* words,
682 const size_t num_words, spv_diagnostic* diagnostic);
683
684// Creates a diagnostic object. The position parameter specifies the location in
685// the text/binary stream. The message parameter, copied into the diagnostic
686// object, contains the error message to display.
687SPIRV_TOOLS_EXPORT spv_diagnostic
688spvDiagnosticCreate(const spv_position position, const char* message);
689
690// Destroys a diagnostic object. This is a no-op if diagnostic is a null
691// pointer.
692SPIRV_TOOLS_EXPORT void spvDiagnosticDestroy(spv_diagnostic diagnostic);
693
694// Prints the diagnostic to stderr.
695SPIRV_TOOLS_EXPORT spv_result_t
696spvDiagnosticPrint(const spv_diagnostic diagnostic);
697
698// The binary parser interface.
699
700// A pointer to a function that accepts a parsed SPIR-V header.
701// The integer arguments are the 32-bit words from the header, as specified
702// in SPIR-V 1.0 Section 2.3 Table 1.
703// The function should return SPV_SUCCESS if parsing should continue.
704typedef spv_result_t (*spv_parsed_header_fn_t)(
705 void* user_data, spv_endianness_t endian, uint32_t magic, uint32_t version,
706 uint32_t generator, uint32_t id_bound, uint32_t reserved);
707
708// A pointer to a function that accepts a parsed SPIR-V instruction.
709// The parsed_instruction value is transient: it may be overwritten
710// or released immediately after the function has returned. That also
711// applies to the words array member of the parsed instruction. The
712// function should return SPV_SUCCESS if and only if parsing should
713// continue.
714typedef spv_result_t (*spv_parsed_instruction_fn_t)(
715 void* user_data, const spv_parsed_instruction_t* parsed_instruction);
716
717// Parses a SPIR-V binary, specified as counted sequence of 32-bit words.
718// Parsing feedback is provided via two callbacks provided as function
719// pointers. Each callback function pointer can be a null pointer, in
720// which case it is never called. Otherwise, in a valid parse the
721// parsed-header callback is called once, and then the parsed-instruction
722// callback once for each instruction in the stream. The user_data parameter
723// is supplied as context to the callbacks. Returns SPV_SUCCESS on successful
724// parse where the callbacks always return SPV_SUCCESS. For an invalid parse,
725// returns a status code other than SPV_SUCCESS, and if diagnostic is non-null
726// also emits a diagnostic. If diagnostic is null the context's message consumer
727// will be used to emit any errors. If a callback returns anything other than
728// SPV_SUCCESS, then that status code is returned, no further callbacks are
729// issued, and no additional diagnostics are emitted.
730SPIRV_TOOLS_EXPORT spv_result_t spvBinaryParse(
731 const spv_const_context context, void* user_data, const uint32_t* words,
732 const size_t num_words, spv_parsed_header_fn_t parse_header,
733 spv_parsed_instruction_fn_t parse_instruction, spv_diagnostic* diagnostic);
734
735#ifdef __cplusplus
736}
737#endif
738
739#endif // INCLUDE_SPIRV_TOOLS_LIBSPIRV_H_
740