[mlir] NFC: fix trivial typos
[lldb.git] / mlir / docs / Dialects / LLVM.md
1 # 'llvm' Dialect
2
3 This dialect maps [LLVM IR](https://llvm.org/docs/LangRef.html) into MLIR by
4 defining the corresponding operations and types. LLVM IR metadata is usually
5 represented as MLIR attributes, which offer additional structure verification.
6
7 We use "LLVM IR" to designate the
8 [intermediate representation of LLVM](https://llvm.org/docs/LangRef.html) and
9 "LLVM _dialect_" or "LLVM IR _dialect_" to refer to this MLIR dialect.
10
11 Unless explicitly stated otherwise, the semantics of the LLVM dialect operations
12 must correspond to the semantics of LLVM IR instructions and any divergence is
13 considered a bug. The dialect also contains auxiliary operations that smoothen
14 the differences in the IR structure, e.g., MLIR does not have `phi` operations
15 and LLVM IR does not have a `constant` operation. These auxiliary operations are
16 systematically prefixed with `mlir`, e.g. `llvm.mlir.constant` where `llvm.` is
17 the dialect namespace prefix.
18
19 [TOC]
20
21 ## Dependency on LLVM IR
22
23 LLVM dialect is not expected to depend on any object that requires an
24 `LLVMContext`, such as an LLVM IR instruction or type. Instead, MLIR provides
25 thread-safe alternatives compatible with the rest of the infrastructure. The
26 dialect is allowed to depend on the LLVM IR objects that don't require a
27 context, such as data layout and triple description.
28
29 ## Module Structure
30
31 IR modules use the built-in MLIR `ModuleOp` and support all its features. In
32 particular, modules can be named, nested and are subject to symbol visibility.
33 Modules can contain any operations, including LLVM functions and globals.
34
35 ### Data Layout and Triple
36
37 An IR module may have an optional data layout and triple information attached
38 using MLIR attributes `llvm.data_layout` and `llvm.triple`, respectively. Both
39 are string attributes with the
40 [same syntax](https://llvm.org/docs/LangRef.html#data-layout) as in LLVM IR and
41 are verified to be correct. They can be defined as follows.
42
43 ```mlir
44 module attributes {llvm.data_layout = "e",
45                    llvm.target_triple = "aarch64-linux-android"} {
46   // module contents
47 }
48 ```
49
50 ### Functions
51
52 LLVM functions are represented by a special operation, `llvm.func`, that has
53 syntax similar to that of the built-in function operation but supports
54 LLVM-related features such as linkage and variadic argument lists. See detailed
55 description in the operation list [below](#llvmfunc-mlirllvmllvmfuncop).
56
57 ### PHI Nodes and Block Arguments
58
59 MLIR uses block arguments instead of PHI nodes to communicate values between
60 blocks. Therefore, the LLVM dialect has no operation directly equivalent to
61 `phi` in LLVM IR. Instead, all terminators can pass values as successor operands
62 as these values will be forwarded as block arguments when the control flow is
63 transferred.
64
65 For example:
66
67 ```mlir
68 ^bb1:
69   %0 = llvm.addi %arg0, %cst : !llvm.i32
70   llvm.br ^bb2[%0: !llvm.i32]
71
72 // If the control flow comes from ^bb1, %arg1 == %0.
73 ^bb2(%arg1: !llvm.i32)
74   // ...
75 ```
76
77 is equivalent to LLVM IR
78
79 ```llvm
80 %0:
81   %1 = add i32 %arg0, %cst
82   br %3
83
84 %3:
85   %arg1 = phi [%1, %0], //...
86 ```
87
88 Since there is no need to use the block identifier to differentiate the source
89 of different values, the LLVM dialect supports terminators that transfer the
90 control flow to the same block with different arguments. For example:
91
92 ```mlir
93 ^bb1:
94   llvm.cond_br %cond, ^bb2[%0: !llvm.i32], ^bb2[%1: !llvm.i32]
95
96 ^bb2(%arg0: !llvm.i32):
97   // ...
98 ```
99
100 ### Context-Level Values
101
102 Some value kinds in LLVM IR, such as constants and undefs, are uniqued in
103 context and used directly in relevant operations. MLIR does not support such
104 values for thread-safety and concept parsimony reasons. Instead, regular values
105 are produced by dedicated operations that have the corresponding semantics:
106 [`llvm.mlir.constant`](#llvmmlirconstant-mlirllvmconstantop),
107 [`llvm.mlir.undef`](#llvmmlirundef-mlirllvmundefop),
108 [`llvm.mlir.null`](#llvmmlirnull-mlirnullop). Note how these operations are
109 prefixed with `mlir.` to indicate that they don't belong to LLVM IR but are only
110 necessary to model it in MLIR. The values produced by these operations are
111 usable just like any other value.
112
113 Examples:
114
115 ```mlir
116 // Create an undefined value of structure type with a 32-bit integer followed
117 // by a float.
118 %0 = llvm.mlir.undef : !llvm.struct<(i32, float)>
119
120 // Null pointer to i8.
121 %1 = llvm.mlir.null : !llvm.ptr<i8>
122
123 // Null pointer to a function with signature void().
124 %2 = llvm.mlir.null : !llvm.ptr<func<void ()>>
125
126 // Constant 42 as i32.
127 %3 = llvm.mlir.constant(42 : i32) : !llvm.i32
128
129 // Splat dense vector constant.
130 %3 = llvm.mlir.constant(dense<1.0> : vector<4xf32>) : !llvm.vec<4 x float>
131 ```
132
133 Note that constants use built-in types within the initializer definition: MLIR
134 attributes are typed and the attributes used for constants require a built-in
135 type.
136
137 ### Globals
138
139 Global variables are also defined using a special operation,
140 [`llvm.mlir.global`](#llvmmlirglobal-mlirllvmglobalop), located at the module
141 level. Globals are MLIR symbols and are identified by their name.
142
143 Since functions need to be isolated-from-above, i.e. values defined outside the
144 function cannot be directly used inside the function, an additional operation,
145 [`llvm.mlir.addressof`](#llvmmliraddressof-mlirllvmaddressofop), is provided to
146 locally define a value containing the _address_ of a global. The actual value
147 can then be loaded from that pointer, or a new value can be stored into it if
148 the global is not declared constant. This is similar to LLVM IR where globals
149 are accessed through name and have a pointer type.
150
151 ### Linkage
152
153 Module-level named objects in the LLVM dialect, namely functions and globals,
154 have an optional _linkage_ attribute derived from LLVM IR
155 [linkage types](https://llvm.org/docs/LangRef.html#linkage-types). Linkage is
156 specified by the same keyword as in LLVM IR and is located between the operation
157 name (`llvm.func` or `llvm.global`) and the symbol name. If no linkage keyword
158 is present, `external` linkage is assumed by default. Linakge is _distinct_ from
159 MLIR symbol visibility.
160
161 ### Attribute Pass-Through
162
163 The LLVM dialect provides a mechanism to forward function-level attributes to
164 LLVM IR using the `passthrough` attribute. This is an array attribute containing
165 either string attributes or array attributes. In the former case, the value of
166 the string is interpreted as the name of LLVM IR function attribute. In the
167 latter case, the array is expected to contain exactly two string attributes, the
168 first corresponding to the name of LLVM IR function attribute, and the second
169 corresponding to its value. Note that even integer LLVM IR function attributes
170 have their value represented in the string form.
171
172 Example:
173
174 ```mlir
175 llvm.func @func() attributes {
176   passthrough = ["noinline",           // value-less attribute
177                  ["alignstack", "4"],  // integer attribute with value
178                  ["other", "attr"]]    // attribute unknown to LLVM
179 } {
180   llvm.return
181 }
182 ```
183
184 If the attribute is not known to LLVM IR, it will be attached as a string
185 attribute.
186
187 ## Types
188
189 LLVM dialect defines a set of types that correspond to LLVM IR types. The
190 dialect type system is _closed_: types from other dialects are not allowed
191 within LLVM dialect aggregate types. This property allows for more concise
192 custom syntax and ensures easy translation to LLVM IR.
193
194 Similarly to other MLIR context-owned objects, the creation and manipulation of
195 LLVM dialect types is thread-safe.
196
197 MLIR does not support module-scoped named type declarations, e.g. `%s = type
198 {i32, i32}` in LLVM IR. Instead, types must be fully specified at each use,
199 except for recursive types where only the first reference to a named type needs
200 to be fully specified. MLIR type aliases are supported for top-level types, i.e.
201 they cannot be used inside the type due to type system closedness.
202
203 The general syntax of LLVM dialect types is `!llvm.`, followed by a type kind
204 identifier (e.g., `ptr` for pointer or `struct` for structure) and by an
205 optional list of type parameters in angle brackets. The dialect follows MLIR
206 style for types with nested angle brackets and keyword specifiers rather than
207 using different bracket styles to differentiate types. Inside angle brackets,
208 the `!llvm` prefix is omitted for brevity; thanks to closedness of the type
209 system, all types are assumed to be defined in the LLVM dialect. For example,
210 `!llvm.ptr<struct<packed, (i8, i32)>>` is a pointer to a packed structure type
211 containing an 8-bit and a 32-bit integer.
212
213 ### Simple Types
214
215 The following non-parametric types are supported.
216
217 -   `!llvm.bfloat` (`LLVMBFloatType`) - 16-bit “brain” floating-point value
218     (7-bit significand).
219 -   `!llvm.half` (`LLVMHalfType`) - 16-bit floating-point value as per
220     IEEE-754-2008.
221 -   `!llvm.float` (`LLVMFloatType`) - 32-bit floating-point value as per
222     IEEE-754-2008.
223 -   `!llvm.double` (`LLVMDoubleType`) - 64-bit floating-point value as per
224     IEEE-754-2008.
225 -   `!llvm.fp128` (`LLVMFP128Type`) - 128-bit floating-point value as per
226     IEEE-754-2008.
227 -   `!llvm.x86_fp80` (`LLVMX86FP80Type`) - 80-bit floating-point value (x87).
228 -   `!llvm.x86_mmx` (`LLVMX86MMXType`) - value held in an MMX register on x86
229     machine.
230 -   `!llvm.ppc_fp128` (`LLVMPPCFP128Type`) - 128-bit floating-point value (two
231     64 bits).
232 -   `!llvm.token` (`LLVMTokenType`) - a non-inspectable value associated with an
233     operation.
234 -   `!llvm.metadata` (`LLVMMetadataType`) - LLVM IR metadata, to be used only if
235     the metadata cannot be represented as structured MLIR attributes.
236 -   `!llvm.void` (`LLVMVoidType`) - does not represent any value; can only
237     appear in function results.
238
239 These types represent a single value (or an absence thereof in case of `void`)
240 and correspond to their LLVM IR counterparts.
241
242 ### Parametric Types
243
244 #### Integer Types
245
246 Integer types are parametric in MLIR terminology, with their bitwidth being a
247 type parameter. They are expressed as follows:
248
249 ```
250   llvm-int-type ::= `!llvm.i` integer-literal
251 ```
252
253 and represented internally as `LLVMIntegerType`. For example, `i1` is a 1-bit
254 integer type (bool) and `i32` as a 32-bit integer type.
255
256 #### Pointer Types
257
258 Pointer types specify an address in memory.
259
260 Pointer types are parametric types parameterized by the element type and the
261 address space. The address space is an integer, but this choice may be
262 reconsidered if MLIR implements named address spaces. Their syntax is as
263 follows:
264
265 ```
266   llvm-ptr-type ::= `!llvm.ptr<` llvm-type (`,` integer-literal)? `>`
267 ```
268
269 where the optional integer literal corresponds to the memory space. Both cases
270 are represented by `LLVMPointerType` internally.
271
272 #### Vector Types
273
274 Vector types represent sequences of elements, typically when multiple data
275 elements are processed by a single instruction (SIMD). Vectors are thought of as
276 stored in registers and therefore vector elements can only be addressed through
277 constant indices.
278
279 Vector types are parameterized by the size, which may be either _fixed_ or a
280 multiple of some fixed size in case of _scalable_ vectors, and the element type.
281 Vectors cannot be nested and only 1D vectors are supported. Scalable vectors are
282 still considered 1D. Their syntax is as follows:
283
284 ```
285   llvm-vec-type ::= `!llvm.vec<` (`?` `x`)? integer-literal `x` llvm-type `>`
286 ```
287
288 Internally, fixed vector types are represented as `LLVMFixedVectorType` and
289 scalable vector types are represented as `LLVMScalableVectorType`. Both classes
290 derive`LLVMVectorType`.
291
292 #### Array Types
293
294 Array types represent sequences of elements in memory. Unlike vectors, array
295 elements can be addressed with a value unknown at compile time, and can be
296 nested. Only 1D arrays are allowed though.
297
298 Array types are parameterized by the fixed size and the element type.
299 Syntactically, their representation is close to vectors:
300
301 ```
302   llvm-array-type ::= `!llvm.array<` integer-literal `x` llvm-type `>`
303 ```
304
305 and are internally represented as `LLVMArrayType`.
306
307 #### Function Types
308
309 Function types represent the type of a function, i.e. its signature.
310
311 Function types are parameterized by the result type, the list of argument types
312 and by an optional "variadic" flag. Unlike built-in `FunctionType`, LLVM dialect
313 functions (`LLVMFunctionType`) always have single result, which may be
314 `!llvm.void` if the function does not return anything. The syntax is as follows:
315
316 ```
317   llvm-func-type ::= `!llvm.func<` llvm-type `(` llvm-type-list (`,` `...`)?
318                      `)` `>`
319 ```
320
321 For example,
322
323 ```mlir
324 !llvm.func<void ()>            // a function with no arguments;
325 !llvm.func<i32 (float, i32)>  // a function with two arguments and a result;
326 !llvm.func<void (i32, ...)>   // a variadic function with at least one argument.
327 ```
328
329 In the LLVM dialect, functions are not first-class objects and one cannot have a
330 value of function type. Instead, one can take the address of a function and
331 operate on pointers to functions.
332
333 ### Structure Types
334
335 The structure type is used to represent a collection of data members together in
336 memory. The elements of a structure may be any type that has a size.
337
338 Structure types are represented in a single dedicated class
339 mlir::LLVM::LLVMStructType. Internally, the struct type stores a (potentially
340 empty) name, a (potentially empty) list of contained types and a bitmask
341 indicating whether the struct is named, opaque, packed or uninitialized.
342 Structure types that don't have a name are referred to as _literal_ structs.
343 Such structures are uniquely identified by their contents. _Identified_ structs
344 on the other hand are uniquely identified by the name.
345
346 #### Identified Structure Types
347
348 Identified structure types are uniqued using their name in a given context.
349 Attempting to construct an identified structure with the same name a structure
350 that already exists in the context *will result in the existing structure being
351 returned*. **MLIR does not auto-rename identified structs in case of name
352 conflicts** because there is no naming scope equivalent to a module in LLVM IR
353 since MLIR modules can be arbitrarily nested.
354
355 Programmatically, identified structures can be constructed in an _uninitialized_
356 state. In this case, they are given a name but the body must be set up by a
357 later call, using MLIR's type mutation mechanism. Such uninitialized types can
358 be used in type construction, but must be eventually initialized for IR to be
359 valid. This mechanism allows for constructing _recursive_ or mutually referring
360 structure types: an uninitialized type can be used in its own initialization.
361
362 Once the type is initialized, its body cannot be changed anymore. Any further
363 attempts to modify the body will fail and return failure to the caller _unless
364 the type is initialized with the exact same body_. Type initialization is
365 thread-safe; however, if a concurrent thread initializes the type before the
366 current thread, the initialization may return failure.
367
368 The syntax for identified structure types is as follows.
369
370 ```
371 llvm-ident-struct-type ::= `!llvm.struct<` string-literal, `opaque` `>`
372                          | `!llvm.struct<` string-literal, `packed`?
373                             `(` llvm-type-or-ref-list  `)` `>`
374 llvm-type-or-ref-list ::= <maybe empty comma-separated list of llvm-type-or-ref>
375 llvm-type-or-ref ::= <any llvm type>
376                    | `!llvm.struct<` string-literal >
377 ```
378
379 The body of the identified struct is printed in full unless the it is
380 transitively contained in the same struct. In the latter case, only the
381 identifier is printed. For example, the structure containing the pointer to
382 itself is represented as `!llvm.struct<"A", (ptr<"A">)>`, and the structure `A`
383 containing two pointers to the structure `B` containing a pointer to the
384 structure `A` is represented as `!llvm.struct<"A", (ptr<"B", (ptr<"A">)>,
385 ptr<"B", (ptr<"A">))>`. Note that the structure `B` is "unrolled" for both
386 elements. _A structure with the same name but different body is a syntax error._
387 **The user must ensure structure name uniqueness across all modules processed in
388 a given MLIR context.** Structure names are arbitrary string literals and may
389 include, e.g., spaces and keywords.
390
391 Identified structs may be _opaque_. In this case, the body is unknown but the
392 structure type is considered _initialized_ and is valid in the IR.
393
394 #### Literal Structure Types
395
396 Literal structures are uniqued according to the list of elements they contain,
397 and can optionally be packed. The syntax for such structs is as follows.
398
399 ```
400 llvm-literal-struct-type ::= `!llvm.struct<` `packed`? `(` llvm-type-list `)`
401                              `>`
402 llvm-type-list ::= <maybe empty comma-separated list of llvm types w/o `!llvm`>
403 ```
404
405 Literal structs cannot be recursive, but can contain other structs. Therefore,
406 they must be constructed in a single step with the entire list of contained
407 elements provided.
408
409 #### Examples of Structure Types
410
411 ```mlir
412 !llvm.struct<>                  // NOT allowed
413 !llvm.struct<()>                // empty, literal
414 !llvm.struct<(i32)>             // literal
415 !llvm.struct<(struct<(i32)>)>   // struct containing a struct
416 !llvm.struct<packed (i8, i32)>  // packed struct
417 !llvm.struct<"a">               // recursive reference, only allowed within
418                                 // another struct, NOT allowed at top level
419 !llvm.struct<"a", ptr<struct<"a">>>  // supported example of recursive reference
420 !llvm.struct<"a", ()>           // empty, named (necessary to differentiate from
421                                 // recursive reference)
422 !llvm.struct<"a", opaque>       // opaque, named
423 !llvm.struct<"a", (i32)>        // named
424 !llvm.struct<"a", packed (i8, i32)>  // named, packed
425 ```
426
427 ### Unsupported Types
428
429 LLVM IR `label` type does not have a counterpart in the LLVM dialect since, in
430 MLIR, blocks are not values and don't need a type.
431
432 ## Operations
433
434 All operations in the LLVM IR dialect have a custom form in MLIR. The mnemonic
435 of an operation is that used in LLVM IR prefixed with "`llvm.`".
436
437 [include "Dialects/LLVMOps.md"]