llvm/docs/SPIRVUsage.rst

   1 =============================
   2 User Guide for SPIR-V Target
   3 =============================
   4
   5 .. contents::
   6    :local:
   7
   8 .. toctree::
   9    :hidden:
  10
  11 Introduction
  12 ============
  13
  14 The SPIR-V target provides code generation for the SPIR-V binary format described
  15 in  `the official SPIR-V specification <https://www.khronos.org/registry/SPIR-V/>`_.
  16
  17 Usage
  18 =====
  19
  20 The SPIR-V backend can be invoked either from LLVM's Static Compiler (llc) or Clang,
  21 allowing developers to compile LLVM intermediate language (IL) files or OpenCL kernel
  22 sources directly to SPIR-V. This section outlines the usage of various commands to
  23 leverage the SPIR-V backend for different purposes.
  24
  25 Static Compiler Commands
  26 ------------------------
  27
  28 1. **Basic SPIR-V Compilation**
  29    Command: `llc -mtriple=spirv32-unknown-unknown input.ll -o output.spvt`
  30    Description: This command compiles an LLVM IL file (`input.ll`) to a SPIR-V binary (`output.spvt`) for a 32-bit architecture.
  31
  32 2. **Compilation with Extensions and Optimization**
  33    Command: `llc -O1 -mtriple=spirv64-unknown-unknown --spirv-ext=+SPV_INTEL_arbitrary_precision_integers input.ll -o output.spvt`
  34    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.
  35
  36 3. **SPIR-V Binary Generation**
  37    Command: `llc -O0 -mtriple=spirv64-unknown-unknown -filetype=obj input.ll -o output.spvt`
  38    Description: Generates a SPIR-V object file (`output.spvt`) from an LLVM module, targeting a 64-bit SPIR-V architecture with no optimizations.
  39
  40 Clang Commands
  41 --------------
  42
  43 1. **SPIR-V Generation**
  44    Command: `clang –target=spirv64 input.cl`
  45    Description: Generates a SPIR-V file directly from an OpenCL kernel source file (`input.cl`).
  46
  47 Compiler Options
  48 ================
  49
  50 .. _spirv-target-triples:
  51
  52 Target Triples
  53 --------------
  54
  55 For cross-compilation into SPIR-V use option
  56
  57 ``-target <Architecture><Subarchitecture>-<Vendor>-<OS>-<Environment>``
  58
  59 to specify the target triple:
  60
  61   .. table:: SPIR-V Architectures
  62
  63      ============ ==============================================================
  64      Architecture Description
  65      ============ ==============================================================
  66      ``spirv32``   SPIR-V with 32-bit pointer width.
  67      ``spirv64``   SPIR-V with 64-bit pointer width.
  68      ``spirv``     SPIR-V with logical memory layout.
  69      ============ ==============================================================
  70
  71   .. table:: SPIR-V Subarchitectures
  72
  73      =============== ==============================================================
  74      Subarchitecture Description
  75      =============== ==============================================================
  76      *<empty>*        SPIR-V version deduced by backend based on the input.
  77      ``v1.0``         SPIR-V version 1.0.
  78      ``v1.1``         SPIR-V version 1.1.
  79      ``v1.2``         SPIR-V version 1.2.
  80      ``v1.3``         SPIR-V version 1.3.
  81      ``v1.4``         SPIR-V version 1.4.
  82      ``v1.5``         SPIR-V version 1.5.
  83      ``v1.6``         SPIR-V version 1.6.
  84      =============== ==============================================================
  85
  86   .. table:: SPIR-V Vendors
  87
  88      ===================== ==============================================================
  89      Vendor                Description
  90      ===================== ==============================================================
  91      *<empty>*/``unknown``  Generic SPIR-V target without any vendor-specific settings.
  92      ``amd``                AMDGCN SPIR-V target, with support for target specific
  93                             builtins and ASM, meant to be consumed by AMDGCN toolchains.
  94      ===================== ==============================================================
  95
  96   .. table:: Operating Systems
  97
  98      ===================== ==============================================================
  99      OS                    Description
 100      ===================== ==============================================================
 101      *<empty>*/``unknown``  Defaults to the OpenCL runtime.
 102      ``vulkan``             Vulkan shader runtime.
 103      ``vulkan1.2``          Vulkan 1.2 runtime, corresponding to SPIR-V 1.5.
 104      ``vulkan1.3``          Vulkan 1.3 runtime, corresponding to SPIR-V 1.6.
 105      ``amdhsa``             AMDHSA runtime, meant to be used on HSA compatible runtimes,
 106                             corresponding to SPIR-V 1.6.
 107      ===================== ==============================================================
 108
 109   .. table:: SPIR-V Environments
 110
 111      ===================== ==============================================================
 112      Environment           Description
 113      ===================== ==============================================================
 114      *<empty>*/``unknown``  OpenCL environment or deduced by backend based on the input.
 115      ===================== ==============================================================
 116
 117 Example:
 118
 119 ``-target spirv64v1.0`` can be used to compile for SPIR-V version 1.0 with 64-bit pointer width.
 120
 121 ``-target spirv64-amd-amdhsa`` can be used to compile for AMDGCN flavoured SPIR-V with 64-bit pointer width.
 122
 123 .. _spirv-extensions:
 124
 125 Extensions
 126 ----------
 127
 128 The SPIR-V backend supports a variety of `extensions <https://github.com/KhronosGroup/SPIRV-Registry/tree/main/extensions>`_
 129 that enable or enhance features beyond the core SPIR-V specification.
 130 These extensions can be enabled using the ``-spirv-extensions`` option
 131 followed by the name of the extension(s) you wish to enable. Below is a
 132 list of supported SPIR-V extensions, sorted alphabetically by their extension names:
 133
 134 .. list-table:: Supported SPIR-V Extensions
 135    :widths: 50 150
 136    :header-rows: 1
 137
 138    * - Extension Name
 139      - Description
 140    * - ``SPV_EXT_shader_atomic_float16_add``
 141      - Extends the SPV_EXT_shader_atomic_float_add extension to support atomically adding to 16-bit floating-point numbers in memory.
 142    * - ``SPV_EXT_shader_atomic_float_add``
 143      - Adds atomic add instruction on floating-point numbers.
 144    * - ``SPV_EXT_shader_atomic_float_min_max``
 145      - Adds atomic min and max instruction on floating-point numbers.
 146    * - ``SPV_INTEL_arbitrary_precision_integers``
 147      - Allows generating arbitrary width integer types.
 148    * - ``SPV_INTEL_bfloat16_conversion``
 149      - Adds instructions to convert between single-precision 32-bit floating-point values and 16-bit bfloat16 values.
 150    * - ``SPV_INTEL_cache_controls``
 151      - Allows cache control information to be applied to memory access instructions.
 152    * - ``SPV_INTEL_function_pointers``
 153      - Allows translation of function pointers.
 154    * - ``SPV_INTEL_inline_assembly``
 155      - Allows to use inline assembly.
 156    * - ``SPV_INTEL_global_variable_host_access``
 157      - Adds decorations that can be applied to global (module scope) variables.
 158    * - ``SPV_INTEL_global_variable_fpga_decorations``
 159      - Adds decorations that can be applied to global (module scope) variables to help code generation for FPGA devices.
 160    * - ``SPV_INTEL_optnone``
 161      - Adds OptNoneINTEL value for Function Control mask that indicates a request to not optimize the function.
 162    * - ``SPV_INTEL_subgroups``
 163      - 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.
 164    * - ``SPV_INTEL_usm_storage_classes``
 165      - Introduces two new storage classes that are subclasses of the CrossWorkgroup storage class that provides additional information that can enable optimization.
 166    * - ``SPV_INTEL_variable_length_array``
 167      - Allows to allocate local arrays whose number of elements is unknown at compile time.
 168    * - ``SPV_KHR_bit_instructions``
 169      - Enables bit instructions to be used by SPIR-V modules without requiring the Shader capability.
 170    * - ``SPV_KHR_expect_assume``
 171      - Provides additional information to a compiler, similar to the llvm.assume and llvm.expect intrinsics.
 172    * - ``SPV_KHR_float_controls``
 173      - Provides new execution modes to control floating-point computations by overriding an implementation’s default behavior for rounding modes, denormals, signed zero, and infinities.
 174    * - ``SPV_KHR_linkonce_odr``
 175      - 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.
 176    * - ``SPV_KHR_no_integer_wrap_decoration``
 177      - Adds decorations to indicate that a given instruction does not cause integer wrapping.
 178    * - ``SPV_KHR_shader_clock``
 179      - Adds the extension cl_khr_kernel_clock that adds the ability for a kernel to sample the value from clocks provided by compute units.
 180    * - ``SPV_KHR_subgroup_rotate``
 181      - Adds a new instruction that enables rotating values across invocations within a subgroup.
 182    * - ``SPV_KHR_uniform_group_instructions``
 183      - Allows support for additional group operations within uniform control flow.
 184
 185 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:
 186
 187 ``-spirv-ext=+SPV_EXT_shader_atomic_float_add,+SPV_INTEL_arbitrary_precision_integers``
 188
 189 To enable all extensions, use the following option:
 190 ``-spirv-ext=all``
 191
 192 To enable all extensions except specified, specify ``all`` followed by a list of disallowed extensions. For example:
 193 ``-spirv-ext=all,-SPV_INTEL_arbitrary_precision_integers``
 194
 195 SPIR-V representation in LLVM IR
 196 ================================
 197
 198 SPIR-V is intentionally designed for seamless integration with various Intermediate
 199 Representations (IRs), including LLVM IR, facilitating straightforward mappings for
 200 most of its entities. The development of the SPIR-V backend has been guided by a
 201 principle of compatibility with the `Khronos Group SPIR-V LLVM Translator <https://github.com/KhronosGroup/SPIRV-LLVM-Translator>`_.
 202 Consequently, the input representation accepted by the SPIR-V backend aligns closely
 203 with that detailed in `the SPIR-V Representation in LLVM document <https://github.com/KhronosGroup/SPIRV-LLVM-Translator/blob/main/docs/SPIRVRepresentationInLLVM.rst>`_.
 204 This document, along with the sections that follow, delineate the main points and focus
 205 on any differences between the LLVM IR that this backend processes and the conventions
 206 used by other tools.
 207
 208 .. _spirv-special-types:
 209
 210 Special types
 211 -------------
 212
 213 SPIR-V specifies several kinds of opaque types. These types are represented
 214 using target extension types and are represented as follows:
 215
 216   .. table:: SPIR-V Opaque Types
 217
 218      ================== ====================== =========================================================================================
 219      SPIR-V Type        LLVM type name         LLVM type arguments
 220      ================== ====================== =========================================================================================
 221      OpTypeImage        ``spirv.Image``        sampled type, dimensionality, depth, arrayed, MS, sampled, image format, access qualifier
 222      OpTypeSampler      ``spirv.Sampler``      (none)
 223      OpTypeSampledImage ``spirv.SampledImage`` sampled type, dimensionality, depth, arrayed, MS, sampled, image format, access qualifier
 224      OpTypeEvent        ``spirv.Event``        (none)
 225      OpTypeDeviceEvent  ``spirv.DeviceEvent``  (none)
 226      OpTypeReserveId    ``spirv.ReserveId``    (none)
 227      OpTypeQueue        ``spirv.Queue``        (none)
 228      OpTypePipe         ``spirv.Pipe``         access qualifier
 229      OpTypePipeStorage  ``spirv.PipeStorage``  (none)
 230      ================== ====================== =========================================================================================
 231
 232 All integer arguments take the same value as they do in their `corresponding
 233 SPIR-V instruction <https://registry.khronos.org/SPIR-V/specs/unified1/SPIRV.html#_type_declaration_instructions>`_.
 234 For example, the OpenCL type ``image2d_depth_ro_t`` would be represented in
 235 SPIR-V IR as ``target("spirv.Image", void, 1, 1, 0, 0, 0, 0, 0)``, with its
 236 dimensionality parameter as ``1`` meaning 2D. Sampled image types include the
 237 parameters of its underlying image type, so that a sampled image for the
 238 previous type has the representation
 239 ``target("spirv.SampledImage, void, 1, 1, 0, 0, 0, 0, 0)``.
 240
 241 .. _spirv-intrinsics:
 242
 243 Target Intrinsics
 244 -----------------
 245
 246 The SPIR-V backend employs several LLVM IR intrinsics that facilitate various low-level
 247 operations essential for generating correct and efficient SPIR-V code. These intrinsics
 248 cover a range of functionalities from type assignment and memory management to control
 249 flow and atomic operations. Below is a detailed table of selected intrinsics used in the
 250 SPIR-V backend, along with their descriptions and argument details.
 251
 252 .. list-table:: LLVM IR Intrinsics for SPIR-V
 253    :widths: 25 15 20 40
 254    :header-rows: 1
 255
 256    * - Intrinsic ID
 257      - Return Type
 258      - Argument Types
 259      - Description
 260    * - `int_spv_assign_type`
 261      - None
 262      - `[Type, Metadata]`
 263      - Associates a type with metadata, crucial for maintaining type information in SPIR-V structures. Not emitted directly but supports the type system internally.
 264    * - `int_spv_assign_ptr_type`
 265      - None
 266      - `[Type, Metadata, Integer]`
 267      - 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.
 268    * - `int_spv_assign_name`
 269      - None
 270      - `[Type, Vararg]`
 271      - Assigns names to types or values, enhancing readability and debuggability of SPIR-V code. Not emitted directly but used for metadata enrichment.
 272    * - `int_spv_assign_decoration`
 273      - None
 274      - `[Type, Metadata]`
 275      - Assigns decoration to values by associating them with metadatas. Not emitted directly but used to support SPIR-V representation in LLVM IR.
 276    * - `int_spv_track_constant`
 277      - Type
 278      - `[Type, Metadata]`
 279      - Tracks constants in the SPIR-V module. Essential for optimizing and reducing redundancy. Emitted for internal use only.
 280    * - `int_spv_init_global`
 281      - None
 282      - `[Type, Type]`
 283      - Initializes global variables, a necessary step for ensuring correct global state management in SPIR-V. Emitted for internal use only.
 284    * - `int_spv_unref_global`
 285      - None
 286      - `[Type]`
 287      - Manages the lifetime of global variables by marking them as unreferenced, thus enabling optimizations related to global variable usage. Emitted for internal use only.
 288    * - `int_spv_gep`
 289      - Pointer
 290      - `[Boolean, Type, Vararg]`
 291      - 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.
 292    * - `int_spv_load`
 293      - 32-bit Integer
 294      - `[Pointer, 16-bit Integer, 8-bit Integer]`
 295      - Loads a value from a memory location. The additional integers specify memory access and alignment details, vital for ensuring correct and efficient memory operations.
 296    * - `int_spv_store`
 297      - None
 298      - `[Type, Pointer, 16-bit Integer, 8-bit Integer]`
 299      - Stores a value to a memory location. Like `int_spv_load`, it includes specifications for memory access and alignment, essential for memory operations.
 300    * - `int_spv_extractv`
 301      - Type
 302      - `[32-bit Integer, Vararg]`
 303      - Extracts a value from a vector, allowing for vector operations within SPIR-V. Enables manipulation of vector components.
 304    * - `int_spv_insertv`
 305      - 32-bit Integer
 306      - `[32-bit Integer, Type, Vararg]`
 307      - Inserts a value into a vector. Complementary to `int_spv_extractv`, it facilitates the construction and manipulation of vectors.
 308    * - `int_spv_extractelt`
 309      - Type
 310      - `[Type, Any Integer]`
 311      - Extracts an element from an aggregate type based on an index. Essential for operations on arrays and vectors.
 312    * - `int_spv_insertelt`
 313      - Type
 314      - `[Type, Type, Any Integer]`
 315      - Inserts an element into an aggregate type at a specified index. Allows for building and modifying arrays and vectors.
 316    * - `int_spv_const_composite`
 317      - Type
 318      - `[Vararg]`
 319      - Constructs a composite type from given elements. Key for creating arrays, structs, and vectors from individual components.
 320    * - `int_spv_bitcast`
 321      - Type
 322      - `[Type]`
 323      - Performs a bit-wise cast between types. Critical for type conversions that do not change the bit representation.
 324    * - `int_spv_ptrcast`
 325      - Type
 326      - `[Type, Metadata, Integer]`
 327      - Casts pointers between different types. Similar to `int_spv_bitcast` but specifically for pointers, taking into account SPIR-V's strict type system.
 328    * - `int_spv_switch`
 329      - None
 330      - `[Type, Vararg]`
 331      - Implements a multi-way branch based on a value. Enables complex control flow structures, similar to the switch statement in high-level languages.
 332    * - `int_spv_cmpxchg`
 333      - 32-bit Integer
 334      - `[Type, Vararg]`
 335      - Performs an atomic compare-and-exchange operation. Crucial for synchronization and concurrency control in compute shaders.
 336    * - `int_spv_unreachable`
 337      - None
 338      - `[]`
 339      - Marks a point in the code that should never be reached, enabling optimizations by indicating unreachable code paths.
 340    * - `int_spv_alloca`
 341      - Type
 342      - `[]`
 343      - Allocates memory on the stack. Fundamental for local variable storage in functions.
 344    * - `int_spv_alloca_array`
 345      - Type
 346      - `[Any Integer]`
 347      - Allocates an array on the stack. Extends `int_spv_alloca` to support array allocations, essential for temporary arrays.
 348    * - `int_spv_undef`
 349      - 32-bit Integer
 350      - `[]`
 351      - Generates an undefined value. Useful for optimizations and indicating uninitialized variables.
 352    * - `int_spv_inline_asm`
 353      - None
 354      - `[Metadata, Metadata, Vararg]`
 355      - Associates inline assembly features to inline assembly call instances by creating metadatas and preserving original arguments. Not emitted directly but used to support SPIR-V representation in LLVM IR.
 356    * - `int_spv_assume`
 357      - None
 358      - `[1-bit Integer]`
 359      - Provides hints to the optimizer about assumptions that can be made about program state. Improves optimization potential.
 360    * - `int_spv_expect`
 361      - Any Integer Type
 362      - `[Type, Type]`
 363      - Guides branch prediction by indicating expected branch paths. Enhances performance by optimizing common code paths.
 364    * - `int_spv_thread_id`
 365      - 32-bit Integer
 366      - `[32-bit Integer]`
 367      - Retrieves the thread ID within a workgroup. Essential for identifying execution context in parallel compute operations.
 368    * - `int_spv_create_handle`
 369      - Pointer
 370      - `[8-bit Integer]`
 371      - Creates a resource handle for graphics or compute resources. Facilitates the management and use of resources in shaders.
 372
 373 .. _spirv-builtin-functions:
 374
 375 Builtin Functions
 376 -----------------
 377
 378 The following section highlights the representation of SPIR-V builtins in LLVM IR,
 379 emphasizing builtins that do not have direct counterparts in LLVM.
 380
 381 Instructions as Function Calls
 382 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 383
 384 SPIR-V builtins without direct LLVM counterparts are represented as LLVM function calls.
 385 These functions, termed SPIR-V builtin functions, follow an IA64 mangling scheme with
 386 SPIR-V-specific extensions. Parsing non-mangled calls to builtins is supported in some cases,
 387 but not tested extensively. The general format is:
 388
 389 .. code-block:: c
 390
 391   __spirv_{OpCodeName}{_OptionalPostfixes}
 392
 393 Where `{OpCodeName}` is the SPIR-V opcode name sans the "Op" prefix, and
 394 `{OptionalPostfixes}` are decoration-specific postfixes, if any. The mangling and
 395 postfixes allow for the representation of SPIR-V's rich instruction set within LLVM's
 396 framework.
 397
 398 Extended Instruction Sets
 399 ~~~~~~~~~~~~~~~~~~~~~~~~~
 400
 401 SPIR-V defines several extended instruction sets for additional functionalities, such as
 402 OpenCL-specific operations. In LLVM IR, these are represented by function calls to
 403 mangled builtins and selected based on the environment. For example:
 404
 405 .. code-block:: c
 406
 407   acos_f32
 408
 409 represents the `acos` function from the OpenCL extended instruction set for a float32
 410 input.
 411
 412 Builtin Variables
 413 ~~~~~~~~~~~~~~~~~
 414
 415 SPIR-V builtin variables, which provide access to special hardware or execution model
 416 properties, are mapped to either LLVM function calls or LLVM global variables. The
 417 representation follows the naming convention:
 418
 419 .. code-block:: c
 420
 421   __spirv_BuiltIn{VariableName}
 422
 423 For instance, the SPIR-V builtin `GlobalInvocationId` is accessible in LLVM IR as
 424 `__spirv_BuiltInGlobalInvocationId`.
 425
 426 Vector Load and Store Builtins
 427 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 428
 429 SPIR-V's capabilities for loading and storing vectors are represented in LLVM IR using
 430 functions that mimic the SPIR-V instructions. These builtins handle cases that LLVM's
 431 native instructions do not directly support, enabling fine-grained control over memory
 432 operations.
 433
 434 Atomic Operations
 435 ~~~~~~~~~~~~~~~~~
 436
 437 SPIR-V's atomic operations, especially those operating on floating-point data, are
 438 represented in LLVM IR with corresponding function calls. These builtins ensure
 439 atomicity in operations where LLVM might not have direct support, essential for parallel
 440 execution and synchronization.
 441
 442 Image Operations
 443 ~~~~~~~~~~~~~~~~
 444
 445 SPIR-V provides extensive support for image and sampler operations, which LLVM
 446 represents through function calls to builtins. These include image reads, writes, and
 447 queries, allowing detailed manipulation of image data and parameters.
 448
 449 Group and Subgroup Operations
 450 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 451
 452 For workgroup and subgroup operations, LLVM uses function calls to represent SPIR-V's
 453 group-based instructions. These builtins facilitate group synchronization, data sharing,
 454 and collective operations essential for efficient parallel computation.