================================ SPIR-V representation in LLVM IR ================================ .. contents:: :local: Overview ======== As one of the goals of SPIR-V is to `"map easily to other IRs, including LLVM IR" `_, most of SPIR-V entities (global variables, constants, types, functions, basic blocks, instructions) have straightforward counterparts in LLVM. Therefore the focus of this document is those entities in SPIR-V which do not map to LLVM in an obvious way. These include: * SPIR-V types mapped to LLVM types * SPIR-V instructions mapped to LLVM function calls * SPIR-V extended instructions mapped to LLVM function calls * SPIR-V builtin variables mapped to LLVM function calls or LLVM global variables * SPIR-V instructions mapped to LLVM metadata * SPIR-V types mapped to LLVM opaque types * SPIR-V decorations mapped to LLVM metadata or named attributes * Additional requirements for LLVM module SPIR-V Types Mapped to LLVM Types ================================= Limited to this section, we define the following common postfix. * {Access} - Postifix indicating the access qualifier. {Access} take integer literal values which are defined by the SPIR-V spec. OpTypeImage ----------- OpTypeImage is mapped to LLVM opaque type spirv.Image._{SampledType}_{Dim}_{Depth}_{Arrayed}_{MS}_{Sampled}_{Format}_{Access} and mangled as __spirv_Image__{SampledType}_{Dim}_{Depth}_{Arrayed}_{MS}_{Sampled}_{Format}_{Access}, where * {SampledType}={float|half|int|uint|void} - Postfix indicating the sampled data type - void for unknown sampled data type * {Dim} - Postfix indicating the dimension of the image * {Depth} - Postfix indicating whether the image is a depth image * {Arrayed} - Postfix indicating whether the image is arrayed image * {MS} - Postfix indicating whether the image is multi-sampled * {Sampled} - Postfix indicating whether the image is associated with sampler * {Format} - Postfix indicating the image format Postfixes {Dim}, {Depth}, {Arrayed}, {MS}, {Sampled} and {Format} take integer literal values which are defined by the SPIR-V spec. OpTypeSampledImage ------------------ OpTypeSampledImage is mapped to LLVM opaque type spirv.SampledImage._{Postfixes} and mangled as __spirv_SampledImage__{Postfixes}, where {Postfixes} are the same as the postfixes of the original image type, as defined above in this section. OpTypePipe ---------- OpTypePipe is mapped to LLVM opaque type spirv.Pipe._{Access} and mangled as __spirv_Pipe__{Access}. Other SPIR-V Types ------------------ * OpTypeEvent * OpTypeDeviceEvent * OpTypeReserveId * OpTypeQueue * OpTypeSampler * OpTypePipeStorage (SPIR-V 1.1) The above SPIR-V types are mapped to LLVM opaque type spirv.{TypeName} and mangled as __spirv_{TypeName}, where {TypeName} is the name of the SPIR-V type with "OpType" removed, e.g., OpTypeEvent is mapped to spirv.Event and mangled as __spirv_Event. Address spaces -------------- The following `SPIR-V storage classes `_ are naturally represented as LLVM IR address spaces with the following mapping: ==================== ==================================== SPIR-V storage class LLVM IR address space ==================== ==================================== ``Function`` No address space or ``addrspace(0)`` ``CrossWorkgroup`` ``addrspace(1)`` ``UniformConstant`` ``addrspace(2)`` ``Workgroup`` ``addrspace(3)`` ``Generic`` ``addrspace(4)`` ==================== ==================================== SPIR-V extensions are allowed to add new storage classes. For example, SPV_INTEL_usm_storage_classes extension adds ``DeviceOnlyINTEL`` and ``HostOnlyINTEL`` storage classes which are mapped to ``addrspace(5)`` and ``addrspace(6)`` respectively. SPIR-V Instructions Mapped to LLVM Function Calls ================================================= Some SPIR-V instructions which can be included in basic blocks do not have corresponding LLVM instructions or intrinsics. These SPIR-V instructions are represented by function calls in LLVM. The function corresponding to a SPIR-V instruction is termed SPIR-V builtin function and its name is `IA64 mangled `_ with extensions for SPIR-V specific types. The unmangled name of a SPIR-V builtin function follows the convention .. code-block:: c __spirv_{OpCodeName}{_OptionalPostfixes} where {OpCodeName} is the op code name of the SPIR-V instructions without the "Op" prefix, e.g. EnqueueKernel. {OptionalPostfixes} are optional postfixes to specify decorations for the SPIR-V instruction. The SPIR-V op code name and each postfix does not contain "_". SPIR-V builtin functions accepts all argument types accepted by the corresponding SPIR-V instructions. The literal operands of extended instruction are mapped to function call arguments with type i32. Optional Postfixes for SPIR-V Builtin Function Names ---------------------------------------------------- SPIR-V builtin functions corresponding to the following SPIR-V instructions are postfixed following the order specified as below: * Instructions having identical argument types but different return types are postfixed with "_R{ReturnType}" where - {ReturnType} = {ScalarType}|{VectorType} - {ScalarType} = char|uchar|short|ushort|int|uint|long|ulong|half|float|double|bool - {VectorType} = {ScalarType}{2|3|4|8|16} * Instructions with saturation decoration are postfixed with "_sat" * Instructions with floating point rounding mode decoration are postfixed with "_rtp|_rtn|_rtz|_rte" SPIR-V Builtin Conversion Function Names ---------------------------------------- The unmangled names of SPIR-V builtin conversion functions follow the convention: .. code-block:: c __spirv_{ConversionOpCodeName}_R{ReturnType}{_sat}{_rtp|_rtn|_rtz|_rte} where * {ConversionOpCodeName} = ConvertFToU|ConvertFToS|ConvertUToF|ConvertUToS|UConvert|SConvert|FConvert|SatConvertSToU|SatConvertUToS SPIR-V Builtin Reinterpret / Bitcast Function Names --------------------------------------------------- The unmangled names of SPIR-V builtin reinterpret / bitcast functions follow the convention: .. code-block:: c __spirv_{BitcastOpCodeName}_R{ReturnType} SPIR-V Builtin ImageSample Function Names ---------------------------------------- The unmangled names of SPIR-V builtin ImageSample functions follow the convention: .. code-block:: c __spirv_{ImageSampleOpCodeName}_R{ReturnType} SPIR-V Builtin GenericCastToPtr Function Name ---------------------------------------- The unmangled names of SPIR-V builtin GenericCastToPtrExplicit function follow the convention: .. code-block:: c __spirv_GenericCastToPtrExplicit_To{Global|Local|Private} SPIR-V Builtin BuildNDRange Function Name ---------------------------------------- The unmangled names of SPIR-V builtin BuildNDRange functions follow the convention: .. code-block:: c __spirv_{BuildNDRange}_{1|2|3}D SPIR-V 1.1 Builtin CreatePipeFromPipeStorage Function Name ---------------------------------------- The unmangled names of SPIR-V builtin CreatePipeFromPipeStorage function follow the convention: .. code-block:: c __spirv_CreatePipeFromPipeStorage_{read|write} SPIR-V Extended Instructions Mapped to LLVM Function Calls ========================================================== SPIR-V extended instructions are mapped to LLVM function calls. The function name is IA64 mangled and the unmangled name has the format .. code-block:: c __spirv_{ExtendedInstructionSetName}_{ExtendedInstrutionName}{__OptionalPostfixes} where {ExtendedInstructionSetName} for OpenCL is "ocl". The translated functions accepts all argument types accepted by the corresponding SPIR-V instructions. The literal operands of extended instruction are mapped to function call arguments with type i32. The optional postfixes take the same format as SPIR-V builtin functions. The first postfix starts with two underscores to facilitate identification since extended instruction name may contain underscore. The remaining postfixes start with one underscore. OpenCL Extended Builtin Vector Load Function Names ---------------------------------------- The unmangled names of OpenCL extended vector load functions follow the convention: .. code-block:: c __spirv_ocl_{VectorLoadOpCodeName}__R{ReturnType} where * {VectorLoadOpCodeName} = vloadn|vload_half|vload_halfn|vloada_halfn SPIR-V Builtin Variables Mapped to LLVM Function Calls or LLVM Global Variables =============================================================================== By default each access of SPIR-V builtin variable's value is mapped to LLVM function call. The unmangled names of these functions follow the convention: .. code-block:: c __spirv_BuiltIn{VariableName} In case if SPIR-V builtin variable has vector type, the corresponding LLVM function will have an integer argument, so each access of the variable's scalar component is mapped to a function call with index argument, i.e.: .. code-block:: llvm ; For scalar variables ; SPIR-V OpDecorate %__spirv_BuiltInGlobalInvocationId BuiltIn GlobalInvocationId %13 = OpLoad %uint %__spirv_BuiltInGlobalLinearId Aligned 4 ; Will be transformed into the following LLVM IR: %0 = call spir_func i32 @_Z29__spirv_BuiltInGlobalLinearIdv() ; For vector variables ; SPIRV OpDecorate %__spirv_BuiltInGlobalInvocationId BuiltIn GlobalInvocationId %14 = OpLoad %v3ulong %__spirv_BuiltInGlobalInvocationId Aligned 32 %15 = OpCompositeExtract %ulong %14 1 ; Can be transformed into the following LLVM IR: %0 = call spir_func i64 @_Z33__spirv_BuiltInGlobalInvocationIdi(i32 1) ; However SPIRV-LLVM translator will transform it to the following pattern: %1 = call spir_func i64 @_Z33__spirv_BuiltInGlobalInvocationIdi(i32 0) %2 = insertelement <3 x i64> undef, i64 %1, i32 0 %3 = call spir_func i64 @_Z33__spirv_BuiltInGlobalInvocationIdi(i32 1) %4 = insertelement <3 x i64> %2, i64 %3, i32 1 %5 = call spir_func i64 @_Z33__spirv_BuiltInGlobalInvocationIdi(i32 2) %6 = insertelement <3 x i64> %4, i64 %5, i32 2 %7 = extractelement <3 x i64> %6, i32 1 ; In case some actions are performed with the variable's value in vector form. SPIR-V builtin variables can also be mapped to LLVM global variables with unmangled name __spirv_BuiltIn{Name}. The representation with variables is closer to SPIR-V, so it is easier to translate from SPIR-V to LLVM and back using it. Hovewer in languages like OpenCL the functionality covered by SPIR-V builtin variables is usually represented by builtin functions, so it is easier to translate from/to SPIR-V friendly IR to/from LLVM IR produced from OpenCL-like source languages. That is why both forms of mapping are supported. SPIR-V instructions mapped to LLVM metadata =========================================== SPIR-V specification allows multiple module scope instructions, whereas LLVM named metadata must be unique, so encoding of such instructions has the following format: .. code-block:: llvm !spirv. = !{!, !, ..} ! = !{, , ..} ! = !{, , ..} +--------------------+---------------------------------------------------------+ | SPIR-V instruction | LLVM IR | +====================+=========================================================+ | OpSource | .. code-block:: llvm | | | | | | !spirv.Source = !{!0} | | | !0 = !{i32 3, i32 66048, !1} | | | ; 3 - OpenCL_C | | | ; 66048 = 0x10200 - OpenCL version 1.2 | | | ; !1 - optional file id. | | | !1 = !{!"/tmp/opencl/program.cl"} | +--------------------+---------------------------------------------------------+ | OpSourceExtension | .. code-block:: llvm | | | | | | !spirv.SourceExtension = !{!0, !1} | | | !0 = !{!"cl_khr_fp16"} | | | !1 = !{!"cl_khr_gl_sharing"} | +--------------------+---------------------------------------------------------+ | OpExtension | .. code-block:: llvm | | | | | | !spirv.Extension = !{!0} | | | !0 = !{!"SPV_KHR_expect_assume"} | +--------------------+---------------------------------------------------------+ | OpCapability | .. code-block:: llvm | | | | | | !spirv.Capability = !{!0} | | | !0 = !{i32 10} ; Float64 - program uses doubles | +--------------------+---------------------------------------------------------+ | OpExecutionMode | .. code-block:: llvm | | | | | | !spirv.ExecutionMode = !{!0} | | | !0 = !{void ()* @worker, i32 30, i32 262149} | | | ; Set execution mode with id 30 (VecTypeHint) and | | | ; literal `262149` operand. | +--------------------+---------------------------------------------------------+ | Generator's magic | .. code-block:: llvm | | number - word # 2 | | | in SPIR-V module | !spirv.Generator = !{!0} | | | !0 = !{i16 6, i16 123} | | | ; 6 - Generator Id, 123 - Generator Version | +--------------------+---------------------------------------------------------+ For example: .. code-block:: llvm !spirv.Source = !{!0} !spirv.SourceExtension = !{!2, !3} !spirv.Extension = !{!2} !spirv.Capability = !{!4} !spirv.MemoryModel = !{!5} !spirv.EntryPoint = !{!6 ,!7} !spirv.ExecutionMode = !{!8, !9} !spirv.Generator = !{!10 } ; 3 - OpenCL_C, 102000 - OpenCL version 1.2, !1 - optional file id. !0 = !{i32 3, i32 102000, !1} !1 = !{!"/tmp/opencl/program.cl"} !2 = !{!"cl_khr_fp16"} !3 = !{!"cl_khr_gl_sharing"} !4 = !{i32 10} ; Float64 - program uses doubles !5 = !{i32 1, i32 2} ; 1 - 32-bit addressing model, 2 - OpenCL memory model !6 = !{i32 6, TBD, !"kernel1", TBD} !7 = !{i32 6, TBD, !"kernel2", TBD} !8 = !{!6, i32 18, i32 16, i32 1, i32 1} ; local size hint <16, 1, 1> for 'kernel1' !9 = !{!7, i32 32} ; independent forward progress is required for 'kernel2' !10 = !{i16 6, i16 123} ; 6 - Generator Id, 123 - Generator Version Additional requirements for LLVM module ======================================= Target triple and datalayout string ----------------------------------- Target triple architecture must be ``spir`` (32-bit architecture) or ``spir64`` (64-bit architecture) and ``datalayout`` string must be aligned with OpenCL environment specification requirements for data type sizes and alignments (e.g. 3-element vector must have 4-element vector alignment). For example: .. code-block:: llvm target datalayout = "e-p:32:32-i64:64-v16:16-v24:32-v32:32-v48:64-v96:128-v192:256-v256:256-v512:512-v1024:1024" target triple = "spir-unknown-unknown" Target triple architecture is translated to `addressing model operand `_ of `OpMemoryModel `_ SPIR-V instruction. - ``spir`` -> Physical32 - ``spir64`` -> Physical64 Calling convention ------------------ ``OpEntryPoint`` information is represented in LLVM IR in calling convention. A function with ``spir_kernel`` calling convention will be translated as an entry point of the SPIR-V module. Function metadata ----------------- Some kernel parameter information is stored in LLVM IR as a function metadata. For example: .. code-block:: llvm !kernel_arg_addr_space !1 !kernel_arg_access_qual !2 !kernel_arg_type !3 !kernel_arg_base_type !4 !kernel_arg_type_qual !5 **NOTE**: All metadata from the example above are optional. Access qualifiers are translated for image types, but they should be encoded in LLVM IR type name rather than function metadata. Function parameter, instruction and global variable decoration through metadata ------------------------------------------------------------------ Function parameters, instructions and global variables can be decorated using LLVM metadata through the metadata names ``spirv.ParameterDecorations`` and ``spirv.Decorations`` respectively. ``spirv.ParameterDecorations`` must be tied to the kernel function while ``spirv.Decorations`` is tied directly to the instruction or global variable. A "decoration-node" is a metadata node consisting of one or more operands. The first operand is an integer literal representing the SPIR-V decoration identifier. The other operands are either an integer or string literal representing the remaining extra operands of the corresponding SPIR-V decoration. A "decoration-list" is a metadata node consisting of references to zero or more decoration-nodes. ``spirv.Decorations`` must refer to a decoration-list while ``spirv.ParameterDecorations`` must refer to a metadata node that contains N references to decoration-lists, where N is the number of arguments of the function the metadata is tied to. ``spirv.Decorations`` applied on a global variable example: .. code-block:: llvm @v = global i32 0, !spirv.Decorations !1 ... !1 = !{!2, !3} ; decoration-list with two decoration nodes !2 = !{i32 22} ; decoration-node with no extra operands !3 = !{i32 41, !"v", i32 0} ; decoration-node with 2 extra operands decorates a global variable ``v`` with ``Constant`` and ``LinkageAttributes`` with extra operands ``"v"`` and ``Export`` in SPIR-V. ``spirv.Decorations`` applied on an instruction example: .. code-block:: llvm %idx = getelementptr inbounds i32, ptr addrspace(1) %b, i64 1, !spirv.Decorations !1 ... !1 = !{!2} !2 = !{i32 6442, i32 1, i32 2} ; {CacheControlLoadINTEL, CacheLevel=1, Cached} decorates getelementptr instruction with CacheControlLoadINTEL decoration with extra operands ``i32 1`` and ``i32 2``. ``spirv.ParameterDecorations`` example: .. code-block:: llvm define spir_kernel void @k(float %a, float %b) #0 !spirv.ParameterDecorations !1 ... !1 = !{!2, !3} ; metadata node with 2 decoration-lists !2 = !{} ; empty decoration-list !3 = !{!4} ; decoration-list with one decoration node !4 = !{i32 19} ; decoration-node with no extra operands decorates the argument ``b`` of ``k`` with ``Restrict`` in SPIR-V while not adding any decoration to argument ``a``. Member decoration through pointer annotations --------------------------------------------- Class members can be decorated using the ``llvm.ptr.annotation`` LLVM IR intrinsic. Member decorations specified in ``llvm.ptr.annotation`` must be in the second argument and must have the format ``{X}`` or ``{X:Y}`` where ``X`` is either one of the reserved names or an integer literal representing the SPIR-V decoration identifier and ``Y`` is 1 or more arguments separated by ",", where each argument must be either a word (including numbers) or a string enclosed by quotation marks. The ``llvm.ptr.annotation`` can contain any number decorations following this format. For example, both ``{5835:1,2,3}`` and ``{bank_bits:1,2,3}`` will result in the ``BankwidthINTEL`` decoration with literals 1, 2, and 3 attached to the annotated member. The translator accepts a number of reserved names that correspond to SPIR-V member decorations. +-----------------------+------------------+-----------------------------------+ | Decoration | Reserved Name | Note | +=======================+==================+===================================+ | RegisterINTEL | register | Additional arguments are ignored, | | | | but reverse translation will add | | | | a 1 argument, i.e. | | | | ``{register:1}``. | +-----------------------+------------------+-----------------------------------+ | MemoryINTEL | memory | | +-----------------------+------------------+-----------------------------------+ | NumbanksINTEL | numbanks | | +-----------------------+------------------+-----------------------------------+ | BankwidthINTEL | bankwidth | | +-----------------------+------------------+-----------------------------------+ | MaxPrivateCopiesINTEL | private_copies | | +-----------------------+------------------+-----------------------------------+ | SinglepumpINTEL | pump | Reserved name is shared with | | | | DoublepumpINTEL. SinglepumpINTEL | | | | will be selected if the argument | | | | is 2, i.e ``{pump:1}``. | +-----------------------+------------------+-----------------------------------+ | DoublepumpINTEL | pump | Reserved name is shared with | | | | SinglepumpINTEL. DoublepumpINTEL | | | | will be selected if the argument | | | | is 2, i.e ``{pump:2}``. | +-----------------------+------------------+-----------------------------------+ | MaxReplicatesINTEL | max_replicates | | +-----------------------+------------------+-----------------------------------+ | SimpleDualPortINTEL | simple_dual_port | Additional arguments are ignored, | | | | but reverse translation will add | | | | a 1 argument, i.e. | | | | ``{simple_dual_port:1}``. | +-----------------------+------------------+-----------------------------------+ | MergeINTEL | merge | Arguments of this are separated by| | | | ":" rather than ",", i.e. | | | | ``{merge:X:Y}``. | +-----------------------+------------------+-----------------------------------+ | BankBitsINTEL | bank_bits | | +-----------------------+------------------+-----------------------------------+ | ForcePow2DepthINTEL | force_pow2_depth | | +-----------------------+------------------+-----------------------------------+ None of the special requirements imposed from using the reserved names apply to using decoration identifiers directly. During reverse translation, the translator prioritizes reserved names over decoration identifiers, even if the member decoration was generated using the corresponding decoration identifier. For example, this means that translating ``{5825}`` to SPIR-V and back to LLVM IR will result in ``{register:1}`` being in the annotation string argument instead of the initial value. Debug information extension =========================== **TBD**