1# SPIR-V Dialect to LLVM Dialect conversion manual
2
3This manual describes the conversion from [SPIR-V Dialect](Dialects/SPIR-V.md)
4to [LLVM Dialect](Dialects/LLVM.md). It assumes familiarity with both, and
5describes the design choices behind the modelling of SPIR-V concepts in LLVM
6Dialect. The conversion is an ongoing work, and is expected to grow as more
7features are implemented.
8
9Conversion can be performed by invoking an appropriate conversion pass:
10
11```shell
12mlir-opt -convert-spirv-to-llvm <filename.mlir>
13```
14
15This pass performs type and operation conversions for SPIR-V operations as
16described in this document.
17
18[TOC]
19
20## Type Conversion
21
22This section describes how SPIR-V Dialect types are mapped to LLVM Dialect.
23
24### Scalar types
25
26SPIR-V Dialect                       | LLVM Dialect
27:----------------------------------: | :----------------------------------:
28`i<bitwidth>`                        | `!llvm.i<bitwidth>`
29`si<bitwidth>`                       | `!llvm.i<bitwidth>`
30`ui<bitwidth>`                       | `!llvm.i<bitwidth>`
31`f16`                                | `!llvm.half`
32`f32`                                | `!llvm.float`
33`f64`                                | `!llvm.double`
34
35### Vector types
36
37SPIR-V Dialect                       | LLVM Dialect
38:----------------------------------: | :----------------------------------:
39`vector<<count> x <scalar-type>>`    | `!llvm.vec<<count> x <scalar-type>>`
40
41### Pointer types
42
43A SPIR-V pointer also takes a Storage Class. At the moment, conversion does
44**not** take it into account.
45
46SPIR-V Dialect                                | LLVM Dialect
47:-------------------------------------------: | :-------------------------:
48`!spv.ptr< <element-type>, <storage-class> >` | `!llvm.ptr<<element-type>>`
49
50### Array types
51
52SPIR-V distinguishes between array type and run-time array type, the length of
53which is not known at compile time. In LLVM, it is possible to index beyond the
54end of the array. Therfore, runtime array can be implemented as a zero length
55array type.
56
57Moreover, SPIR-V supports the notion of array stride. Note that this is **not**
58supported by type conversion at the moment.
59
60SPIR-V Dialect                        | LLVM Dialect
61:-----------------------------------: | :-----------------------------------:
62`!spv.array<<count> x <element-type>>`| `!llvm.array<<count> x <element-type>>`
63`!spv.rtarray< <element-type> >`      | `!llvm.array<0 x <element-type>>`
64
65### Struct types
66
67Members of SPIR-V struct types may have decorations and offset information.
68Currently, there is **no** support of member decorations conversion for structs.
69For more information see section on [Decorations](#Decorations-conversion).
70
71Usually we expect that each struct member has a natural size and alignment.
72However, there are cases (*e.g.* in graphics) where one would place struct
73members explicitly at particular offsets. This case is **not** supported
74at the moment. Hence, we adhere to the following mapping:
75
76*   Structs with no offset are modelled as LLVM packed structures.
77
78*   Structs with natural offset (*i.e.* offset that equals to cumulative size of
79    the previous struct elements or is a natural alignment) are mapped to
80    naturally padded structs. Nested structs with offset and structs with offset
81    containing arrays are **not** supported.
82
83*   Structs with unnatural offset (*i.e.* offset that is not equal to cumulative
84    size of the previous struct elements) are **not** supported. In this case,
85    offsets can be emulated with padding fields (*e.g.* integers). However, such
86    a design would require index recalculation in the conversion of ops that
87    involve memmory addressing.
88
89Examples of SPIR-V struct conversion are:
90```mlir
91!spv.struct<i8, i32>          =>  !llvm.struct<packed (i8, i32)>
92!spv.struct<i8 [0], i32 [4]>  =>  !llvm.struct<(i8, i32)>
93
94// error
95!spv.struct<i8 [0], i32 [8]>
96```
97
98### Not implemented types
99
100The rest of the types not mentioned explicitly above are not supported by the
101conversion. This includes `ImageType` and `MatrixType`.
102
103## Operation Conversion
104
105This section describes how SPIR-V Dialect operations are converted to LLVM
106Dialect. It lists already working conversion patterns, as well as those that are
107an ongoing work.
108
109There are also multiple ops for which there is no clear mapping in LLVM.
110Conversion for those have to be discussed within the community on the
111case-by-case basis.
112
113### Arithmetic ops
114
115SPIR-V arithmetic ops mostly have a direct equivalent in LLVM Dialect. Such
116exceptions as `spv.SMod` and `spv.FMod` are rare.
117
118SPIR-V Dialect op                     | LLVM Dialect op
119:-----------------------------------: | :-----------------------------------:
120`spv.FAdd`                            | `llvm.fadd`
121`spv.FDiv`                            | `llvm.fdiv`
122`spv.FNegate`                         | `llvm.fneg`
123`spv.FMul`                            | `llvm.fmul`
124`spv.FRem`                            | `llvm.frem`
125`spv.FSub`                            | `llvm.fsub`
126`spv.IAdd`                            | `llvm.add`
127`spv.IMul`                            | `llvm.mul`
128`spv.ISub`                            | `llvm.sub`
129`spv.SDiv`                            | `llvm.sdiv`
130`spv.SRem`                            | `llvm.srem`
131`spv.UDiv`                            | `llvm.udiv`
132`spv.UMod`                            | `llvm.urem`
133
134### Bitwise ops
135
136SPIR-V has a range of bit ops that are mapped to LLVM dialect ops, intrinsics or
137may have a specific conversion pattern.
138
139#### Direct conversion
140
141As with arithmetic ops, most of bitwise ops have a semantically equivalent op in
142LLVM:
143
144SPIR-V Dialect op                     | LLVM Dialect op
145:-----------------------------------: | :-----------------------------------:
146`spv.BitwiseAnd`                      | `llvm.and`
147`spv.BitwiseOr`                       | `llvm.or`
148`spv.BitwiseXor`                      | `llvm.xor`
149
150Also, some of bitwise ops can be modelled with LLVM intrinsics:
151
152SPIR-V Dialect op                     | LLVM Dialect intrinsic
153:-----------------------------------: | :-----------------------------------:
154`spv.BitCount`                        | `llvm.intr.ctpop`
155`spv.BitReverse`                      | `llvm.intr.bitreverse`
156
157#### `spv.Not`
158
159`spv.Not` is modelled with a `xor` operation with a mask with all bits set.
160
161```mlir
162                            %mask = llvm.mlir.constant(-1 : i32) : !llvm.i32
163%0 = spv.Not %op : i32  =>  %0  = llvm.xor %op, %mask : !llvm.i32
164```
165
166#### Bitfield ops
167
168SPIR-V dialect has three bitfield ops: `spv.BitFieldInsert`,
169`spv.BitFieldSExtract` and `spv.BitFieldUExtract`. This section will first
170outline the general design of conversion patterns for this ops, and then
171describe each of them.
172
173All of these ops take `base`, `offset` and `count` (`insert` for
174`spv.BitFieldInsert`) as arguments. There are two important things
175to note:
176
177*   `offset` and `count` are always scalar. This means that we can have the
178    following case:
179
180    ```mlir
181    %0 = spv.BitFieldSExtract %base, %offset, %count : vector<2xi32>, i8, i8
182    ```
183
184    To be able to proceed with conversion algorithms described below, all
185    operands have to be of the same type and bitwidth. This requires
186    broadcasting of `offset` and `count` to vectors, for example for the case
187    above it gives:
188
189    ```mlir
190    // Broadcasting offset
191    %offset0 = llvm.mlir.undef : !llvm.vec<2 x i8>
192    %zero = llvm.mlir.constant(0 : i32) : !llvm.i32
193    %offset1 = llvm.insertelement %offset, %offset0[%zero : !llvm.i32] : !llvm.vec<2 x i8>
194    %one = llvm.mlir.constant(1 : i32) : !llvm.i32
195    %vec_offset = llvm.insertelement  %offset, %offset1[%one : !llvm.i32] : !llvm.vec<2 x i8>
196
197    // Broadcasting count
198    // ...
199    ```
200
201*   `offset` and `count` may have different bitwidths from `base`. In this case,
202    both of these operands have to be zero extended (since they are treated as
203    unsigned by the specification) or truncated. For the above example it would
204    be:
205
206    ```mlir
207    // Zero extending offest after broadcasting
208    %res_offset = llvm.zext %vec_offset: !llvm.vec<2 x i8> to !llvm.vec<2 x i32>
209    ```
210
211    Also, note that if the bitwidth of `offset` or `count` is greater than the
212    bitwidth of `base`, truncation is still permitted. This is because the ops have a
213    defined behaviour with `offset` and `count` being less than the size of
214    `base`. It creates a natural upper bound on what values `offset` and `count`
215    can take, which is 64. This can be expressed in less than 8 bits.
216
217Now, having these two cases in mind, we can proceed with conversion for the ops
218and their operands.
219
220##### `spv.BitFieldInsert`
221
222This operation is implemented as a series of LLVM Dialect operations. First step
223would be to create a mask with bits set outside
224[`offset`, `offset` + `count` - 1]. Then, unchanged bits are extracted from
225`base` that are outside of [`offset`, `offset` + `count` - 1]. The result is
226`or`ed with shifted `insert`.
227
228```mlir
229// Create mask
230// %minus_one = llvm.mlir.constant(-1 : i32) : !llvm.i32
231// %t0        = llvm.shl %minus_one, %count : !llvm.i32
232// %t1        = llvm.xor %t0, %minus_one : !llvm.i32
233// %t2        = llvm.shl %t1, %offset : !llvm.i32
234// %mask      = llvm.xor %t2, %minus_one : !llvm.i32
235
236// Extract unchanged bits from the Base
237// %new_base  = llvm.and %base, %mask : !llvm.i32
238
239// Insert new bits
240// %sh_insert = llvm.shl %insert, %offset : !llvm.i32
241// %res       = llvm.or %new_base, %sh_insert : !llvm.i32
242%res = spv.BitFieldInsert %base, %insert, %offset, %count : i32, i32, i32
243```
244
245##### `spv.BitFieldSExtract`
246
247To implement `spv.BitFieldSExtract`, `base` is shifted left by [sizeof(`base`) -
248(`count` + `offset`)], so that the bit at `offset` + `count` - 1 is the most
249significant bit. After, the result is shifted right, filling the bits with the
250sign bit.
251
252```mlir
253// Calculate the amount to shift left.
254// %size    = llvm.mlir.constant(32 : i32) : !llvm.i32
255// %t0      = llvm.add %count, %offset : !llvm.i32
256// %t1      = llvm.sub %size, %t0 : !llvm.i32
257
258// Shift left and then right to extract the bits
259// %sh_left = llvm.shl %base, %t1 : !llvm.i32
260// %t2      = llvm.add %offset, %t1 : !llvm.i32
261// %res     = llvm.ashr %sh_left, %t2 : !llvm.i32
262%res = spv.BitFieldSExtract %base, %offset, %count : i32, i32, i32
263```
264
265##### `spv.BitFieldUExtract`
266
267For this op a similar pattern as for `spv.BitFieldInsert` is used. First, a mask
268with bits set at [0, `count` - 1] is created. Then `base` is shifted by `offset`
269and the mask is applied.
270
271```mlir
272// Create a mask
273// %minus_one = llvm.mlir.constant(-1 : i32) : !llvm.i32
274// %t0        = llvm.shl %minus_one, %count : !llvm.i32
275// mask       = llvm.xor  %t0, %minus_one : !llvm.i32
276
277// Shift Base and apply mask
278// %sh_base   = llvm.lshr %base, %offset : !llvm.i32
279// %res       = llvm.and %sh_base, %mask : !llvm.i32
280%res = spv.BitFieldUExtract %base, %offset, %count : i32, i32, i32
281```
282
283### Cast ops
284
285#### Direct conversions
286
287SPIR-V Dialect op                     | LLVM Dialect op
288:-----------------------------------: | :-----------------------------------:
289`spv.ConvertFToS`                     | `llvm.fptosi`
290`spv.ConvertFToU`                     | `llvm.fptoui`
291`spv.ConvertSToF`                     | `llvm.sitofp`
292`spv.ConvertUToF`                     | `llvm.uitofp`
293
294#### spv.Bitcast
295This operation has a direct counterpart in LLVM: `llvm.bitcast`. It is treated
296separately since it also supports pointer to pointer bit pattern-preserving type
297conversion, apart from regular scalar or vector of numerical type.
298
299#### Special cases
300Special cases include `spv.FConvert`, `spv.SConvert` and `spv.UConvert`. These
301operations are either a truncate or extend. Let's denote the operand component
302width as A, and result component width as R. Then, the following mappings are
303used:
304
305##### `spv.FConvert`
306Case            | LLVM Dialect op
307:-------------: | :-----------------------------------:
308A < R           | `llvm.fpext`
309A > R           | `llvm.fptrunc`
310
311##### `spv.SConvert`
312Case            | LLVM Dialect op
313:-------------: | :-----------------------------------:
314A < R           | `llvm.sext`
315A > R           | `llvm.trunc`
316
317##### `spv.UConvert`
318Case            | LLVM Dialect op
319:-------------: | :-----------------------------------:
320A < R           | `llvm.zext`
321A > R           | `llvm.trunc`
322
323The case when A = R is not possible, based on SPIR-V Dialect specification:
324> The component width cannot equal the component width in Result Type.
325
326### Comparison ops
327
328SPIR-V comparison ops are mapped to LLVM `icmp` and `fcmp` operations.
329
330SPIR-V Dialect op                     | LLVM Dialect op
331:-----------------------------------: | :-----------------------------------:
332`spv.IEqual`                          | `llvm.icmp "eq"`
333`spv.INotEqual`                       | `llvm.icmp "ne"`
334`spv.FOrdEqual`                       | `llvm.fcmp "oeq"`
335`spv.FOrdGreaterThan`                 | `llvm.fcmp "ogt"`
336`spv.FOrdGreaterThanEqual`            | `llvm.fcmp "oge"`
337`spv.FOrdLessThan`                    | `llvm.fcmp "olt"`
338`spv.FOrdLessThanEqual`               | `llvm.fcmp "ole"`
339`spv.FOrdNotEqual`                    | `llvm.fcmp "one"`
340`spv.FUnordEqual`                     | `llvm.fcmp "ueq"`
341`spv.FUnordGreaterThan`               | `llvm.fcmp "ugt"`
342`spv.FUnordGreaterThanEqual`          | `llvm.fcmp "uge"`
343`spv.FUnordLessThan`                  | `llvm.fcmp "ult"`
344`spv.FUnordLessThanEqual`             | `llvm.fcmp "ule"`
345`spv.FUnordNotEqual`                  | `llvm.fcmp "une"`
346`spv.SGreaterThan`                    | `llvm.icmp "sgt"`
347`spv.SGreaterThanEqual`               | `llvm.icmp "sge"`
348`spv.SLessThan`                       | `llvm.icmp "slt"`
349`spv.SLessThanEqual`                  | `llvm.icmp "sle"`
350`spv.UGreaterThan`                    | `llvm.icmp "ugt"`
351`spv.UGreaterThanEqual`               | `llvm.icmp "uge"`
352`spv.ULessThan`                       | `llvm.icmp "ult"`
353`spv.ULessThanEqual`                  | `llvm.icmp "ule"`
354
355### `spv.EntryPoint` and `spv.ExecutionMode`
356
357**Note: these conversions are likely to be changed in the future**
358
359First of all, it is important to note that there is no direct representation of
360entry points in LLVM. At the moment, we choose to **remove these ops**, assuming
361that the module generated from SPIR-V has no other internal functions (This
362assumption is actually made in [`mlir-spirv-cpu-runner`](#`mlir-spirv-cpu-runner`)).
363
364However, these ops can be used to see which functions in the module are entry
365point functions. `spv.ExecutionMode` also carries the metadata associated with
366the entry point such as `LocalSize`, which indicates the workgroup size in the
367x, y, and z dimensions. It will be useful to represent this on the LLVM side
368(TODO).
369
370### Logical ops
371
372Logical ops follow a similar pattern as bitwise ops, with the difference that
373they operate on `i1` or vector of `i1` values. The following mapping is used to
374emulate SPIR-V ops behaviour:
375
376SPIR-V Dialect op                     | LLVM Dialect op
377:-----------------------------------: | :-----------------------------------:
378`spv.LogicalAnd`                      | `llvm.and`
379`spv.LogicalOr`                       | `llvm.or`
380`spv.LogicalEqual`                    | `llvm.icmp "eq"`
381`spv.LogicalNotEqual`                 | `llvm.icmp "ne"`
382
383`spv.LogicalNot` has the same conversion pattern as bitwise `spv.Not`. It is
384modelled with `xor` operation with a mask with all bits set.
385
386```mlir
387                                  %mask = llvm.mlir.constant(-1 : i1) : !llvm.i1
388%0 = spv.LogicalNot %op : i1  =>  %0    = llvm.xor %op, %mask : !llvm.i1
389```
390
391### Memory ops
392
393This section describes the conversion patterns for SPIR-V dialect operations
394that concern memory.
395
396#### `spv.AccessChain`
397
398`spv.AccessChain` is mapped to `llvm.getelementptr` op. In order to create a
399valid LLVM op, we also add a 0 index to the `spv.AccessChain`'s indices list in
400order to go through the pointer.
401
402```mlir
403// Access the 1st element of the array
404%i   = spv.constant 1: i32
405%var = spv.Variable : !spv.ptr<!spv.struct<f32, !spv.array<4xf32>>, Function>
406%el  = spv.AccessChain %var[%i, %i] : !spv.ptr<!spv.struct<f32, !spv.array<4xf32>>, Function>, i32, i32
407
408// Corresponding LLVM dialect code
409%i   = ...
410%var = ...
411%0   = llvm.mlir.constant(0 : i32) : !llvm.i32
412%el  = llvm.getelementptr %var[%0, %i, %i] : (!llvm.ptr<struct<packed (float, array<4 x float>)>>, !llvm.i32, !llvm.i32, !llvm.i32)
413```
414
415#### `spv.Load` and `spv.Store`
416
417These ops are converted to their LLVM counterparts: `llvm.load` and
418`llvm.store`. If the op has a memory access attribute, then there are the
419following cases, based on the value of the attribute:
420
421* **Aligned**: alignment is passed on to LLVM op builder, for example:
422  ```mlir
423  // llvm.store %ptr, %val {alignment = 4 : i64} : !llvm.ptr<float>
424  spv.Store "Function" %ptr, %val ["Aligned", 4] : f32
425  ```
426* **None**: same case as if there is no memory access attribute.
427
428* **Nontemporal**: set `nontemporal` flag, for example:
429  ```mlir
430  // %res = llvm.load %ptr {nontemporal} : !llvm.ptr<float>
431  %res = spv.Load "Function" %ptr ["Nontemporal"] : f32
432  ```
433* **Volatile**: mark the op as `volatile`, for example:
434  ```mlir
435  // %res = llvm.load volatile %ptr : !llvm.ptr<float>
436  %res = spv.Load "Function" %ptr ["Volatile"] : f32
437  ```
438Otherwise the conversion fails as other cases (`MakePointerAvailable`,
439`MakePointerVisible`, `NonPrivatePointer`) are not supported yet.
440
441#### `spv.globalVariable` and `spv._address_of`
442
443`spv.globalVariable` is modelled with `llvm.mlir.global` op. However, there
444is a difference that has to be pointed out.
445
446In SPIR-V dialect, the global variable returns a pointer, whereas in LLVM
447dialect the global holds an actual value. This difference is handled by
448`spv._address_of` and `llvm.mlir.addressof` ops that both return a pointer and
449are used to reference the global.
450
451```mlir
452// Original SPIR-V module
453spv.module Logical GLSL450 {
454  spv.globalVariable @struct : !spv.ptr<!spv.struct<f32, !spv.array<10xf32>>, Private>
455  spv.func @func() -> () "None" {
456    %0 = spv._address_of @struct : !spv.ptr<!spv.struct<f32, !spv.array<10xf32>>, Private>
457    spv.Return
458  }
459}
460
461// Converted result
462module {
463  llvm.mlir.global private @struct() : !llvm.struct<packed (float, [10 x float])>
464  llvm.func @func() {
465    %0 = llvm.mlir.addressof @struct : !llvm.ptr<struct<packed (float, [10 x float])>>
466    llvm.return
467  }
468}
469```
470
471The SPIR-V to LLVM conversion does not involve modelling of workgroups.
472Hence, we say that only current invocation is in conversion's scope. This means
473that global variables with pointers of `Input`, `Output`, and `Private` storage
474classes are supported. Also, `StorageBuffer` storage class is allowed for
475executing [`mlir-spirv-cpu-runner`](#`mlir-spirv-cpu-runner`).
476
477Moreover, `bind` that specifies the descriptor set and the binding number and
478`built_in` that specifies SPIR-V `BuiltIn` decoration have no conversion into
479LLVM dialect.
480
481Currently `llvm.mlir.global`s are created with `private` linkage for `Private`
482storage class and `External` for other storage classes, based on SPIR-V spec:
483
484> By default, functions and global variables are private to a module and cannot
485be accessed by other modules. However, a module may be written to export or
486import functions and global (module scope) variables.
487
488If the global variable's pointer has `Input` storage class, then a `constant`
489flag is added to LLVM op:
490
491```mlir
492spv.globalVariable @var : !spv.ptr<f32, Input>    =>    llvm.mlir.global external constant @var() : !llvm.float
493```
494
495#### `spv.Variable`
496
497Per SPIR-V dialect spec, `spv.Variable` allocates an object in memory, resulting
498in a pointer to it, which can be used with `spv.Load` and `spv.Store`. It is
499also a function-level variable.
500
501`spv.Variable` is modelled as `llvm.alloca` op. If initialized, an additional
502store instruction is used. Note that there is no initialization for arrays and
503structs since constants of these types are not supported in LLVM dialect (TODO).
504Also, at the moment initialization is only possible via `spv.constant`.
505
506```mlir
507// Conversion of VariableOp without initialization
508                                                               %size = llvm.mlir.constant(1 : i32) : !llvm.i32
509%res = spv.Variable : !spv.ptr<vector<3xf32>, Function>   =>   %res  = llvm.alloca  %size x !llvm.vec<3 x float> : (!llvm.i32) -> !llvm.ptr<vec<3 x float>>
510
511// Conversion of VariableOp with initialization
512                                                               %c    = llvm.mlir.constant(0 : i64) : !llvm.i64
513%c   = spv.constant 0 : i64                                    %size = llvm.mlir.constant(1 : i32) : !llvm.i32
514%res = spv.Variable init(%c) : !spv.ptr<i64, Function>    =>   %res	 = llvm.alloca %[[SIZE]] x !llvm.i64 : (!llvm.i32) -> !llvm.ptr<i64>
515                                                               llvm.store %c, %res : !llvm.ptr<i64>
516```
517
518Note that simple conversion to `alloca` may not be sufficent if the code has
519some scoping. For example, if converting ops executed in a loop into `alloca`s,
520a stack overflow may occur. For this case, `stacksave`/`stackrestore` pair can
521be used (TODO).
522
523### Miscellaneous ops with direct conversions
524
525There are multiple SPIR-V ops that do not fit in a particular group but can be
526converted directly to LLVM dialect. Their conversion is addressed in this
527section.
528
529SPIR-V Dialect op                     | LLVM Dialect op
530:-----------------------------------: | :-----------------------------------:
531`spv.Select`                          | `llvm.select`
532`spv.Undef`                           | `llvm.mlir.undef`
533
534### Shift ops
535
536Shift operates on two operands: `shift` and `base`.
537
538In SPIR-V dialect, `shift` and `base` may have different bit width. On the
539contrary, in LLVM Dialect both `base` and `shift` have to be of the same
540bitwidth. This leads to the following conversions:
541
542*   if `base` has the same bitwidth as `shift`, the conversion is
543    straightforward.
544
545*   if `base` has a greater bit width than `shift`, shift is sign or zero
546    extended first. Then the extended value is passed to the shift.
547
548*   otherwise, the conversion is considered to be illegal.
549
550```mlir
551// Shift without extension
552%res0 = spv.ShiftRightArithmetic %0, %2 : i32, i32  =>  %res0 = llvm.ashr %0, %2 : !llvm.i32
553
554// Shift with extension
555                                                        %ext  = llvm.sext %1 : !llvm.i16 to !llvm.i32
556%res1 = spv.ShiftRightArithmetic %0, %1 : i32, i16  =>  %res1 = llvm.ashr %0, %ext: !llvm.i32
557```
558
559### `spv.constant`
560
561At the moment `spv.constant` conversion supports scalar and vector constants
562**only**.
563
564#### Mapping
565
566`spv.constant` is mapped to `llvm.mlir.constant`. This is a straightforward
567conversion pattern with a special case when the argument is signed or unsigned.
568
569#### Special case
570
571SPIR-V constant can be a signed or unsigned integer. Since LLVM Dialect does not
572have signedness semantics, this case should be handled separately.
573
574The conversion casts constant value attribute to a signless integer or a vector
575of signless integers. This is correct because in SPIR-V, like in LLVM, how to
576interpret an integer number is also dictated by the opcode. However, in reality
577hardware implementation might show unexpected behavior. Therefore, it is better
578to handle it case-by-case, given that the purpose of the conversion is not to
579cover all possible corner cases.
580
581```mlir
582// %0 = llvm.mlir.constant(0 : i8) : !llvm.i8
583%0 = spv.constant  0 : i8
584
585// %1 = llvm.mlir.constant(dense<[2, 3, 4]> : vector<3xi32>) : !llvm.vec<3 x i32>
586%1 = spv.constant dense<[2, 3, 4]> : vector<3xui32>
587```
588
589### Not implemented ops
590
591There is no support of the following ops:
592
593*   All Atomic ops
594*   All matrix ops
595*   All GroupNonUniform ops
596
597As well as:
598
599*   spv.CompositeConstruct
600*   spv.CompositeExtract
601*   spv.CompositeInsert
602*   spv.ControlBarrier
603*   spv.CopyMemory
604*   spv.FMod
605*   spv.GLSL.SAbs
606*   spv.GLSL.SSign
607*   spv.GLSL.FSign
608*   spv.MemoryBarrier
609*   spv._reference_of
610*   spv.SMod
611*   spv.specConstant
612*   spv.SubgroupBallotKHR
613*   spv.Unreachable
614
615## Control flow conversion
616
617### Branch ops
618
619`spv.Branch` and `spv.BranchConditional` are mapped to `llvm.br` and
620`llvm.cond_br`. Branch weigths for `spv.BranchConditional` are mapped to
621coresponding `branch_weights` attribute of `llvm.cond_br`. When translated to
622proper LLVM, `branch_weights` are converted into LLVM metadata associated with
623the conditional branch.
624
625### `spv.FunctionCall`
626
627`spv.FunctionCall` maps to `llvm.call`. For example:
628
629```mlir
630%0 = spv.FunctionCall @foo() : () -> i32    =>    %0 = llvm.call @foo() : () -> !llvm.float
631spv.FunctionCall @bar(%0) : (i32) -> ()     =>    llvm.call @bar(%0) : (!llvm.float) -> ()
632```
633
634### `spv.selection` and `spv.loop`
635
636Control flow within `spv.selection` and `spv.loop` is lowered directly to LLVM
637via branch ops. The conversion can only be applied to selection or loop with all
638blocks being reachable. Moreover, selection and loop control attributes (such as
639`Flatten` or `Unroll`) are not supported at the moment.
640
641```mlir
642// Conversion of selection
643%cond = spv.constant true                               %cond = llvm.mlir.constant(true) : !llvm.i1
644spv.selection {
645  spv.BranchConditional %cond, ^true, ^false            llvm.cond_br %cond, ^true, ^false
646
647^true:																								^true:
648  // True block code                                    // True block code
649  spv.Branch ^merge                             =>      llvm.br ^merge
650
651^false:                                               ^false:
652  // False block code                                   // False block code
653  spv.Branch ^merge                                     llvm.br ^merge
654
655^merge:                                               ^merge:
656  spv._merge                                            llvm.br ^continue
657}
658// Remaining code																			^continue:
659                                                        // Remaining code
660```
661
662```mlir
663// Conversion of loop
664%cond = spv.constant true                               %cond = llvm.mlir.constant(true) : !llvm.i1
665spv.loop {
666  spv.Branch ^header                                    llvm.br ^header
667
668^header:                                              ^header:
669  // Header code                                        // Header code
670  spv.BranchConditional %cond, ^body, ^merge    =>      llvm.cond_br %cond, ^body, ^merge
671
672^body:                                                ^body:
673  // Body code                                          // Body code
674  spv.Branch ^continue                                  llvm.br ^continue
675
676^continue:                                            ^continue:
677  // Continue code                                      // Continue code
678  spv.Branch ^header                                    llvm.br ^header
679
680^merge:                                               ^merge:
681  spv._merge                                            llvm.br ^remaining
682}
683// Remaining code                                     ^remaining:
684                                                        // Remaining code
685```
686
687## Decorations conversion
688
689**Note: these conversions have not been implemented yet**
690
691## GLSL extended instruction set
692
693This section describes how SPIR-V ops from GLSL extended instructions set are
694mapped to LLVM Dialect.
695
696### Direct conversions
697
698SPIR-V Dialect op                     | LLVM Dialect op
699:-----------------------------------: | :-----------------------------------:
700`spv.GLSL.Ceil`                       | `llvm.intr.ceil`
701`spv.GLSL.Cos`                        | `llvm.intr.cos`
702`spv.GLSL.Exp`                        | `llvm.intr.exp`
703`spv.GLSL.FAbs`                       | `llvm.intr.fabs`
704`spv.GLSL.Floor`                      | `llvm.intr.floor`
705`spv.GLSL.FMax`                       | `llvm.intr.maxnum`
706`spv.GLSL.FMin`                       | `llvm.intr.minnum`
707`spv.GLSL.Log`                        | `llvm.intr.log`
708`spv.GLSL.Sin`                        | `llvm.intr.sin`
709`spv.GLSL.Sqrt`                       | `llvm.intr.sqrt`
710`spv.GLSL.SMax`                       | `llvm.intr.smax`
711`spv.GLSL.SMin`                       | `llvm.intr.smin`
712
713### Special cases
714
715`spv.InverseSqrt` is mapped to:
716```mlir
717                                           %one  = llvm.mlir.constant(1.0 : f32) : !llvm.float
718%res = spv.InverseSqrt %arg : f32    =>    %sqrt = "llvm.intr.sqrt"(%arg) : (!llvm.float) -> !llvm.float
719                                           %res  = fdiv %one, %sqrt : !llvm.float
720```
721
722`spv.Tan` is mapped to:
723```mlir
724                                   %sin = "llvm.intr.sin"(%arg) : (!llvm.float) -> !llvm.float
725%res = spv.Tan %arg : f32    =>    %cos = "llvm.intr.cos"(%arg) : (!llvm.float) -> !llvm.float
726                                   %res = fdiv %sin, %cos : !llvm.float
727```
728
729`spv.Tanh` is modelled using the equality `tanh(x) = {exp(2x) - 1}/{exp(2x) + 1}`:
730```mlir
731                                     %two   = llvm.mlir.constant(2.0: f32) : !llvm.float
732                                     %2xArg = llvm.fmul %two, %arg : !llvm.float
733                                     %exp   = "llvm.intr.exp"(%2xArg) : (!llvm.float) -> !llvm.float
734%res = spv.Tanh %arg : f32     =>    %one   = llvm.mlir.constant(1.0 : f32) : !llvm.float
735                                     %num   = llvm.fsub %exp, %one : !llvm.float
736                                     %den   = llvm.fadd %exp, %one : !llvm.float
737                                     %res   = llvm.fdiv %num, %den : !llvm.float
738```
739
740## Function conversion and related ops
741
742This section describes the conversion of function-related operations from SPIR-V
743to LLVM dialect.
744
745### `spv.func`
746This op declares or defines a SPIR-V function and it is converted to `llvm.func`.
747This conversion handles signarture conversion, and function control attributes
748remapping to LLVM dialect function [`passthrough` attribute](Dialects/LLVM.md#Attribute-pass-through).
749
750The following mapping is used to map [SPIR-V function control](SPIRVFunctionAttributes) to
751[LLVM function attributes](LLVMFunctionAttributes):
752
753SPIR-V Function Control Attributes    | LLVM Function Attributes
754:-----------------------------------: | :-----------------------------------:
755None                                  | No function attributes passed
756Inline                                | `alwaysinline`
757DontInline                            | `noinline`
758Pure                                  | `readonly`
759Const                                 | `readnone`
760
761### `spv.Return` and `spv.ReturnValue`
762
763In LLVM IR, functions may return either 1 or 0 value. Hence, we map both ops to
764`llvm.return` with or without a return value.
765
766## Module ops
767
768Module in SPIR-V has one region that contains one block. It is defined via
769`spv.module` op that also takes a range of attributes:
770
771*   Addressing model
772*   Memory model
773*   Version-Capability-Extension attribute
774
775`spv.module` is converted into `ModuleOp`. This plays a role of enclosing scope
776to LLVM ops. At the moment, SPIR-V module attributes are ignored.
777
778`spv._module_end` is mapped to an equivalent terminator `ModuleTerminatorOp`.
779
780## `mlir-spirv-cpu-runner`
781
782**Note: this is a section in progress, more information will appear soon**
783
784[LLVMFunctionAttributes]: https://llvm.org/docs/LangRef.html#function-attributes
785[SPIRVFunctionAttributes]: https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#_a_id_function_control_a_function_control
786