You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Description: Compiles an LLVM IL file to SPIR-V with (`-O1`) optimizations, targeting a 64-bit architecture. It enables the SPV_INTEL_arbitrary_precision_integers extension.
- Adds instructions to convert between single-precision 32-bit floating-point values and 16-bit bfloat16 values.
144
+
* - ``SPV_INTEL_function_pointers``
145
+
- Allows translation of function pointers.
146
+
* - ``SPV_INTEL_optnone``
147
+
- Adds OptNoneINTEL value for Function Control mask that indicates a request to not optimize the function.
148
+
* - ``SPV_INTEL_subgroups``
149
+
- Allows work items in a subgroup to share data without the use of local memory and work group barriers, and to utilize specialized hardware to load and store blocks of data from images or buffers.
150
+
* - ``SPV_INTEL_usm_storage_classes``
151
+
- Introduces two new storage classes that are subclasses of the CrossWorkgroup storage class that provides additional information that can enable optimization.
152
+
* - ``SPV_INTEL_variable_length_array``
153
+
- Allows to allocate local arrays whose number of elements is unknown at compile time.
154
+
* - ``SPV_KHR_bit_instructions``
155
+
- Enables bit instructions to be used by SPIR-V modules without requiring the Shader capability.
156
+
* - ``SPV_KHR_expect_assume``
157
+
- Provides additional information to a compiler, similar to the llvm.assume and llvm.expect intrinsics.
158
+
* - ``SPV_KHR_float_controls``
159
+
- Provides new execution modes to control floating-point computations by overriding an implementation’s default behavior for rounding modes, denormals, signed zero, and infinities.
160
+
* - ``SPV_KHR_linkonce_odr``
161
+
- Allows to use the LinkOnceODR linkage type that lets a function or global variable to be merged with other functions or global variables of the same name when linkage occurs.
162
+
* - ``SPV_KHR_no_integer_wrap_decoration``
163
+
- Adds decorations to indicate that a given instruction does not cause integer wrapping.
164
+
* - ``SPV_KHR_subgroup_rotate``
165
+
- Adds a new instruction that enables rotating values across invocations within a subgroup.
166
+
* - ``SPV_KHR_uniform_group_instructions``
167
+
- Allows support for additional group operations within uniform control flow.
80
168
81
-
Representing special types in SPIR-V
82
-
====================================
169
+
To enable multiple extensions, list them separated by spaces. For example, to enable support for atomic operations on floating-point numbers and arbitrary precision integers, use:
SPIR-V is intentionally designed for seamless integration with various Intermediate
183
+
Representations (IRs), including LLVM IR, facilitating straightforward mappings for
184
+
most of its entities. The development of the SPIR-V backend has been guided by a
185
+
principle of compatibility with the `Khronos Group SPIR-V LLVM Translator <https://github.com/KhronosGroup/SPIRV-LLVM-Translator>`_.
186
+
Consequently, the input representation accepted by the SPIR-V backend aligns closely
187
+
with that detailed in `the SPIR-V Representation in LLVM document <https://github.com/KhronosGroup/SPIRV-LLVM-Translator/blob/main/docs/SPIRVRepresentationInLLVM.rst>`_.
188
+
This document, along with the sections that follow, delineate the main points and focus
189
+
on any differences between the LLVM IR that this backend processes and the conventions
190
+
used by other tools.
191
+
192
+
.. _spirv-special-types:
193
+
194
+
Special types
195
+
-------------
83
196
84
197
SPIR-V specifies several kinds of opaque types. These types are represented
85
-
using target extension types. These types are represented as follows:
198
+
using target extension types and are represented as follows:
86
199
87
200
.. table:: SPIR-V Opaque Types
88
201
@@ -108,3 +221,210 @@ dimensionality parameter as ``1`` meaning 2D. Sampled image types include the
108
221
parameters of its underlying image type, so that a sampled image for the
The SPIR-V backend employs several LLVM IR intrinsics that facilitate various low-level
231
+
operations essential for generating correct and efficient SPIR-V code. These intrinsics
232
+
cover a range of functionalities from type assignment and memory management to control
233
+
flow and atomic operations. Below is a detailed table of selected intrinsics used in the
234
+
SPIR-V backend, along with their descriptions and argument details.
235
+
236
+
.. list-table:: LLVM IR Intrinsics for SPIR-V
237
+
:widths: 25 15 20 40
238
+
:header-rows: 1
239
+
240
+
* - Intrinsic ID
241
+
- Return Type
242
+
- Argument Types
243
+
- Description
244
+
* - `int_spv_assign_type`
245
+
- None
246
+
- `[Type, Metadata]`
247
+
- Associates a type with metadata, crucial for maintaining type information in SPIR-V structures. Not emitted directly but supports the type system internally.
248
+
* - `int_spv_assign_ptr_type`
249
+
- None
250
+
- `[Type, Metadata, Integer]`
251
+
- Similar to `int_spv_assign_type`, but for pointer types with an additional integer specifying the storage class. Supports SPIR-V's detailed pointer type system. Not emitted directly.
252
+
* - `int_spv_assign_name`
253
+
- None
254
+
- `[Type, Vararg]`
255
+
- Assigns names to types or values, enhancing readability and debuggability of SPIR-V code. Not emitted directly but used for metadata enrichment.
256
+
* - `int_spv_track_constant`
257
+
- Type
258
+
- `[Type, Metadata]`
259
+
- Tracks constants in the SPIR-V module. Essential for optimizing and reducing redundancy. Emitted for internal use only.
260
+
* - `int_spv_init_global`
261
+
- None
262
+
- `[Type, Type]`
263
+
- Initializes global variables, a necessary step for ensuring correct global state management in SPIR-V. Emitted for internal use only.
264
+
* - `int_spv_unref_global`
265
+
- None
266
+
- `[Type]`
267
+
- Manages the lifetime of global variables by marking them as unreferenced, thus enabling optimizations related to global variable usage. Emitted for internal use only.
268
+
* - `int_spv_gep`
269
+
- Pointer
270
+
- `[Boolean, Type, Vararg]`
271
+
- Computes the address of a sub-element of an aggregate type. Critical for accessing array elements and structure fields. Supports conditionally addressing elements in a generic way.
272
+
* - `int_spv_load`
273
+
- 32-bit Integer
274
+
- `[Pointer, 16-bit Integer, 8-bit Integer]`
275
+
- Loads a value from a memory location. The additional integers specify memory access and alignment details, vital for ensuring correct and efficient memory operations.
- Stores a value to a memory location. Like `int_spv_load`, it includes specifications for memory access and alignment, essential for memory operations.
280
+
* - `int_spv_extractv`
281
+
- Type
282
+
- `[32-bit Integer, Vararg]`
283
+
- Extracts a value from a vector, allowing for vector operations within SPIR-V. Enables manipulation of vector components.
284
+
* - `int_spv_insertv`
285
+
- 32-bit Integer
286
+
- `[32-bit Integer, Type, Vararg]`
287
+
- Inserts a value into a vector. Complementary to `int_spv_extractv`, it facilitates the construction and manipulation of vectors.
288
+
* - `int_spv_extractelt`
289
+
- Type
290
+
- `[Type, Any Integer]`
291
+
- Extracts an element from an aggregate type based on an index. Essential for operations on arrays and vectors.
292
+
* - `int_spv_insertelt`
293
+
- Type
294
+
- `[Type, Type, Any Integer]`
295
+
- Inserts an element into an aggregate type at a specified index. Allows for building and modifying arrays and vectors.
296
+
* - `int_spv_const_composite`
297
+
- 32-bit Integer
298
+
- `[Vararg]`
299
+
- Constructs a composite type from given elements. Key for creating arrays, structs, and vectors from individual components.
300
+
* - `int_spv_bitcast`
301
+
- Type
302
+
- `[Type]`
303
+
- Performs a bit-wise cast between types. Critical for type conversions that do not change the bit representation.
304
+
* - `int_spv_ptrcast`
305
+
- Type
306
+
- `[Type, Metadata, Integer]`
307
+
- Casts pointers between different types. Similar to `int_spv_bitcast` but specifically for pointers, taking into account SPIR-V's strict type system.
308
+
* - `int_spv_switch`
309
+
- None
310
+
- `[Type, Vararg]`
311
+
- Implements a multi-way branch based on a value. Enables complex control flow structures, similar to the switch statement in high-level languages.
312
+
* - `int_spv_cmpxchg`
313
+
- 32-bit Integer
314
+
- `[Type, Vararg]`
315
+
- Performs an atomic compare-and-exchange operation. Crucial for synchronization and concurrency control in compute shaders.
316
+
* - `int_spv_unreachable`
317
+
- None
318
+
- `[]`
319
+
- Marks a point in the code that should never be reached, enabling optimizations by indicating unreachable code paths.
320
+
* - `int_spv_alloca`
321
+
- Type
322
+
- `[]`
323
+
- Allocates memory on the stack. Fundamental for local variable storage in functions.
324
+
* - `int_spv_alloca_array`
325
+
- Type
326
+
- `[Any Integer]`
327
+
- Allocates an array on the stack. Extends `int_spv_alloca` to support array allocations, essential for temporary arrays.
328
+
* - `int_spv_undef`
329
+
- 32-bit Integer
330
+
- `[]`
331
+
- Generates an undefined value. Useful for optimizations and indicating uninitialized variables.
332
+
* - `int_spv_assume`
333
+
- None
334
+
- `[1-bit Integer]`
335
+
- Provides hints to the optimizer about assumptions that can be made about program state. Improves optimization potential.
336
+
* - `int_spv_expect`
337
+
- Any Integer Type
338
+
- `[Type, Type]`
339
+
- Guides branch prediction by indicating expected branch paths. Enhances performance by optimizing common code paths.
340
+
* - `int_spv_thread_id`
341
+
- 32-bit Integer
342
+
- `[32-bit Integer]`
343
+
- Retrieves the thread ID within a workgroup. Essential for identifying execution context in parallel compute operations.
344
+
* - `int_spv_create_handle`
345
+
- Pointer
346
+
- `[8-bit Integer]`
347
+
- Creates a resource handle for graphics or compute resources. Facilitates the management and use of resources in shaders.
348
+
349
+
.. _spirv-builtin-functions:
350
+
351
+
Builtin Functions
352
+
-----------------
353
+
354
+
The following section highlights the representation of SPIR-V builtins in LLVM IR,
355
+
emphasizing builtins that do not have direct counterparts in LLVM.
356
+
357
+
Instructions as Function Calls
358
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
359
+
360
+
SPIR-V builtins without direct LLVM counterparts are represented as LLVM function calls.
361
+
These functions, termed SPIR-V builtin functions, follow an IA64 mangling scheme with
362
+
SPIR-V-specific extensions. Parsing non-mangled calls to builtins is supported in some cases,
363
+
but not tested extensively. The general format is:
364
+
365
+
.. code-block:: c
366
+
367
+
__spirv_{OpCodeName}{_OptionalPostfixes}
368
+
369
+
Where `{OpCodeName}` is the SPIR-V opcode name sans the "Op" prefix, and
370
+
`{OptionalPostfixes}` are decoration-specific postfixes, if any. The mangling and
371
+
postfixes allow for the representation of SPIR-V's rich instruction set within LLVM's
372
+
framework.
373
+
374
+
Extended Instruction Sets
375
+
~~~~~~~~~~~~~~~~~~~~~~~~~
376
+
377
+
SPIR-V defines several extended instruction sets for additional functionalities, such as
378
+
OpenCL-specific operations. In LLVM IR, these are represented by function calls to
379
+
mangled builtins and selected based on the environment. For example:
380
+
381
+
.. code-block:: c
382
+
383
+
acos_f32
384
+
385
+
represents the `acos` function from the OpenCL extended instruction set for a float32
386
+
input.
387
+
388
+
Builtin Variables
389
+
~~~~~~~~~~~~~~~~~
390
+
391
+
SPIR-V builtin variables, which provide access to special hardware or execution model
392
+
properties, are mapped to either LLVM function calls or LLVM global variables. The
393
+
representation follows the naming convention:
394
+
395
+
.. code-block:: c
396
+
397
+
__spirv_BuiltIn{VariableName}
398
+
399
+
For instance, the SPIR-V builtin `GlobalInvocationId` is accessible in LLVM IR as
400
+
`__spirv_BuiltInGlobalInvocationId`.
401
+
402
+
Vector Load and Store Builtins
403
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
404
+
405
+
SPIR-V's capabilities for loading and storing vectors are represented in LLVM IR using
406
+
functions that mimic the SPIR-V instructions. These builtins handle cases that LLVM's
407
+
native instructions do not directly support, enabling fine-grained control over memory
408
+
operations.
409
+
410
+
Atomic Operations
411
+
~~~~~~~~~~~~~~~~~
412
+
413
+
SPIR-V's atomic operations, especially those operating on floating-point data, are
414
+
represented in LLVM IR with corresponding function calls. These builtins ensure
415
+
atomicity in operations where LLVM might not have direct support, essential for parallel
416
+
execution and synchronization.
417
+
418
+
Image Operations
419
+
~~~~~~~~~~~~~~~~
420
+
421
+
SPIR-V provides extensive support for image and sampler operations, which LLVM
422
+
represents through function calls to builtins. These include image reads, writes, and
423
+
queries, allowing detailed manipulation of image data and parameters.
424
+
425
+
Group and Subgroup Operations
426
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
427
+
428
+
For workgroup and subgroup operations, LLVM uses function calls to represent SPIR-V's
429
+
group-based instructions. These builtins facilitate group synchronization, data sharing,
430
+
and collective operations essential for efficient parallel computation.
0 commit comments