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 .. _spirv-target-triples:
  18
  19 Target Triples
  20 ==============
  21
  22 For cross-compilation into SPIR-V use option
  23
  24 ``-target <Architecture><Subarchitecture>-<Vendor>-<OS>-<Environment>``
  25
  26 to specify the target triple:
  27
  28   .. table:: SPIR-V Architectures
  29
  30      ============ ==============================================================
  31      Architecture Description
  32      ============ ==============================================================
  33      ``spirv32``   SPIR-V with 32-bit pointer width.
  34      ``spirv64``   SPIR-V with 64-bit pointer width.
  35      ============ ==============================================================
  36
  37   .. table:: SPIR-V Subarchitectures
  38
  39      =============== ==============================================================
  40      Subarchitecture Description
  41      =============== ==============================================================
  42      *<empty>*        SPIR-V version deduced by tools based on the compiled input.
  43      ``v1.0``         SPIR-V version 1.0.
  44      ``v1.1``         SPIR-V version 1.1.
  45      ``v1.2``         SPIR-V version 1.2.
  46      ``v1.3``         SPIR-V version 1.3.
  47      ``v1.4``         SPIR-V version 1.4.
  48      ``v1.5``         SPIR-V version 1.5.
  49      =============== ==============================================================
  50
  51   .. table:: SPIR-V Vendors
  52
  53      ===================== ==============================================================
  54      Vendor                Description
  55      ===================== ==============================================================
  56      *<empty>*/``unknown``  Generic SPIR-V target without any vendor-specific settings.
  57      ===================== ==============================================================
  58
  59   .. table:: Operating Systems
  60
  61      ===================== ============================================================
  62      OS                    Description
  63      ===================== ============================================================
  64      *<empty>*/``unknown``  Defaults to the OpenCL runtime.
  65      ===================== ============================================================
  66
  67   .. table:: SPIR-V Environments
  68
  69      ===================== ==============================================================
  70      Environment           Description
  71      ===================== ==============================================================
  72      *<empty>*/``unknown``  Defaults to the OpenCL environment.
  73      ===================== ==============================================================
  74
  75 Example:
  76
  77 ``-target spirv64v1.0`` can be used to compile for SPIR-V version 1.0 with 64-bit pointer width.
  78
  79 .. _spirv-types:
  80
  81 Representing special types in SPIR-V
  82 ====================================
  83
  84 SPIR-V specifies several kinds of opaque types. These types are represented
  85 using target extension types. These types are represented as follows:
  86
  87   .. table:: SPIR-V Opaque Types
  88
  89      ================== ====================== =========================================================================================
  90      SPIR-V Type        LLVM type name         LLVM type arguments
  91      ================== ====================== =========================================================================================
  92      OpTypeImage        ``spirv.Image``        sampled type, dimensionality, depth, arrayed, MS, sampled, image format, access qualifier
  93      OpTypeSampler      ``spirv.Sampler``      (none)
  94      OpTypeSampledImage ``spirv.SampledImage`` sampled type, dimensionality, depth, arrayed, MS, sampled, image format, access qualifier
  95      OpTypeEvent        ``spirv.Event``        (none)
  96      OpTypeDeviceEvent  ``spirv.DeviceEvent``  (none)
  97      OpTypeReserveId    ``spirv.ReserveId``    (none)
  98      OpTypeQueue        ``spirv.Queue``        (none)
  99      OpTypePipe         ``spirv.Pipe``         access qualifier
 100      OpTypePipeStorage  ``spirv.PipeStorage``  (none)
 101      ================== ====================== =========================================================================================
 102
 103 All integer arguments take the same value as they do in their `corresponding
 104 SPIR-V instruction <https://registry.khronos.org/SPIR-V/specs/unified1/SPIRV.html#_type_declaration_instructions>`_.
 105 For example, the OpenCL type ``image2d_depth_ro_t`` would be represented in
 106 SPIR-V IR as ``target("spirv.Image", void, 1, 1, 0, 0, 0, 0, 0)``, with its
 107 dimensionality parameter as ``1`` meaning 2D. Sampled image types include the
 108 parameters of its underlying image type, so that a sampled image for the
 109 previous type has the representation
 110 ``target("spirv.SampledImage, void, 1, 1, 0, 0, 0, 0, 0)``.