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

Provided by KDAB

Privacy Policy
Learn more about Flutter for embedded and desktop on industrialflutter.com

source code of flutter_engine/third_party/vulkan-deps/spirv-tools/src/include/spirv-tools/libspirv.h