Skip to content

Commit 1a90ca3

Browse files
baderAlexeySachkovAlexeySotkinsvenvh
authored
Specify additional requirements for LLVM module (#1115)
* Add a reference guide for input program format * Add a note about additional storage classes added by SPIR-V extensions. Co-authored-by: Alexey Sachkov <[email protected]> Co-authored-by: Alexey Sotkin <[email protected]> Co-authored-by: Sven van Haastregt <[email protected]>
1 parent 0161b32 commit 1a90ca3

File tree

1 file changed

+120
-0
lines changed

1 file changed

+120
-0
lines changed

‎docs/SPIRVRepresentationInLLVM.rst

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ an obvious way. These include:
2121
* SPIR-V instructions mapped to LLVM metadata
2222
* SPIR-V types mapped to LLVM opaque types
2323
* SPIR-V decorations mapped to LLVM metadata or named attributes
24+
* Additional requirements for LLVM module
2425

2526
SPIR-V Types Mapped to LLVM Types
2627
=================================
@@ -74,6 +75,28 @@ mangled as __spirv_{TypeName}, where {TypeName} is the name of the SPIR-V
7475
type with "OpType" removed, e.g., OpTypeEvent is mapped to spirv.Event and
7576
mangled as __spirv_Event.
7677

78+
Address spaces
79+
--------------
80+
81+
The following
82+
`SPIR-V storage classes <https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#Storage_Class>`_
83+
are naturally represented as LLVM IR address spaces with the following mapping:
84+
85+
==================== ====================================
86+
SPIR-V storage class LLVM IR address space
87+
==================== ====================================
88+
``Function`` No address space or ``addrspace(0)``
89+
``CrossWorkgroup`` ``addrspace(1)``
90+
``UniformConstant`` ``addrspace(2)``
91+
``Workgroup`` ``addrspace(3)``
92+
``Generic`` ``addrspace(4)``
93+
==================== ====================================
94+
95+
SPIR-V extensions are allowed to add new storage classes. For example,
96+
SPV_INTEL_usm_storage_classes extension adds ``DeviceOnlyINTEL`` and
97+
``HostOnlyINTEL`` storage classes which are mapped to ``addrspace(5)`` and
98+
``addrspace(6)`` respectively.
99+
77100
SPIR-V Instructions Mapped to LLVM Function Calls
78101
=================================================
79102

@@ -269,6 +292,48 @@ following format:
269292
!<InstructionMetadata1> = !{<Operand1>, <Operand2>, ..}
270293
!<InstructionMetadata2> = !{<Operand1>, <Operand2>, ..}
271294
295+
+--------------------+---------------------------------------------------------+
296+
| SPIR-V instruction | LLVM IR |
297+
+====================+=========================================================+
298+
| OpSource | .. code-block:: llvm |
299+
| | |
300+
| | !spirv.Source = !{!0} |
301+
| | !0 = !{i32 3, i32 66048, !1} |
302+
| | ; 3 - OpenCL_C |
303+
| | ; 66048 = 0x10200 - OpenCL version 1.2 |
304+
| | ; !1 - optional file id. |
305+
| | !1 = !{!"/tmp/opencl/program.cl"} |
306+
+--------------------+---------------------------------------------------------+
307+
| OpSourceExtension | .. code-block:: llvm |
308+
| | |
309+
| | !spirv.SourceExtension = !{!0, !1} |
310+
| | !0 = !{!"cl_khr_fp16"} |
311+
| | !1 = !{!"cl_khr_gl_sharing"} |
312+
+--------------------+---------------------------------------------------------+
313+
| OpExtension | .. code-block:: llvm |
314+
| | |
315+
| | !spirv.Extension = !{!0} |
316+
| | !0 = !{!"SPV_KHR_expect_assume"} |
317+
+--------------------+---------------------------------------------------------+
318+
| OpCapability | .. code-block:: llvm |
319+
| | |
320+
| | !spirv.Capability = !{!0} |
321+
| | !0 = !{i32 10} ; Float64 - program uses doubles |
322+
+--------------------+---------------------------------------------------------+
323+
| OpExecutionMode | .. code-block:: llvm |
324+
| | |
325+
| | !spirv.ExecutionMode = !{!0} |
326+
| | !0 = !{void ()* @worker, i32 30, i32 262149} |
327+
| | ; Set execution mode with id 30 (VecTypeHint) and |
328+
| | ; literal `262149` operand. |
329+
+--------------------+---------------------------------------------------------+
330+
| Generator's magic | .. code-block:: llvm |
331+
| number - word # 2 | |
332+
| in SPIR-V module | !spirv.Generator = !{!0} |
333+
| | !0 = !{i16 6, i16 123} |
334+
| | ; 6 - Generator Id, 123 - Generator Version |
335+
+--------------------+---------------------------------------------------------+
336+
272337
For example:
273338

274339
.. code-block:: llvm
@@ -295,3 +360,58 @@ For example:
295360
!9 = !{!7, i32 32} ; independent forward progress is required for 'kernel2'
296361
!10 = !{i16 6, i16 123} ; 6 - Generator Id, 123 - Generator Version
297362
363+
Additional requirements for LLVM module
364+
=======================================
365+
366+
Target triple and datalayout string
367+
-----------------------------------
368+
369+
Target triple architecture must be ``spir`` (32-bit architecture) or ``spir64``
370+
(64-bit architecture) and ``datalayout`` string must be aligned with OpenCL
371+
environment specification requirements for data type sizes and alignments (e.g.
372+
3-element vector must have 4-element vector alignment). For example:
373+
374+
.. code-block:: llvm
375+
376+
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"
377+
target triple = "spir-unknown-unknown"
378+
379+
Target triple architecture is translated to
380+
`addressing model operand <https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#_a_id_addressing_model_a_addressing_model>`_
381+
of
382+
`OpMemoryModel <https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#_a_id_mode_setting_a_mode_setting_instructions>`_
383+
SPIR-V instruction.
384+
385+
- ``spir`` -> Physical32
386+
- ``spir64`` -> Physical64
387+
388+
Calling convention
389+
------------------
390+
391+
``OpEntryPoint`` information is represented in LLVM IR in calling convention.
392+
A function with ``spir_kernel`` calling convention will be translated as an entry
393+
point of the SPIR-V module.
394+
395+
Function metadata
396+
-----------------
397+
398+
Some kernel parameter information is stored in LLVM IR as a function metadata.
399+
400+
For example:
401+
402+
.. code-block:: llvm
403+
404+
!kernel_arg_addr_space !1
405+
!kernel_arg_access_qual !2
406+
!kernel_arg_type !3
407+
!kernel_arg_base_type !4
408+
!kernel_arg_type_qual !5
409+
410+
**NOTE**: All metadata from the example above are optional. Access qualifiers
411+
are translated for image types, but they should be encoded in LLVM IR type name
412+
rather than function metadata.
413+
414+
Debug information extension
415+
===========================
416+
417+
**TBD**

0 commit comments

Comments
 (0)