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