1# MLIR Language Reference 2 3MLIR (Multi-Level IR) is a compiler intermediate representation with 4similarities to traditional three-address SSA representations (like 5[LLVM IR](http://llvm.org/docs/LangRef.html) or 6[SIL](https://github.com/apple/swift/blob/master/docs/SIL.rst)), but which 7introduces notions from polyhedral loop optimization as first-class concepts. 8This hybrid design is optimized to represent, analyze, and transform high level 9dataflow graphs as well as target-specific code generated for high performance 10data parallel systems. Beyond its representational capabilities, its single 11continuous design provides a framework to lower from dataflow graphs to 12high-performance target-specific code. 13 14This document defines and describes the key concepts in MLIR, and is intended 15to be a dry reference document - the [rationale 16documentation](Rationale/Rationale.md), 17[glossary](../getting_started/Glossary.md), and other content are hosted 18elsewhere. 19 20MLIR is designed to be used in three different forms: a human-readable textual 21form suitable for debugging, an in-memory form suitable for programmatic 22transformations and analysis, and a compact serialized form suitable for 23storage and transport. The different forms all describe the same semantic 24content. This document describes the human-readable textual form. 25 26[TOC] 27 28## High-Level Structure 29 30MLIR is fundamentally based on a graph-like data structure of nodes, called 31*Operations*, and edges, called *Values*. Each Value is the result of exactly 32one Operation or Block Argument, and has a *Value Type* defined by the [type 33system](#type-system). [Operations](#operations) are contained in 34[Blocks](#blocks) and Blocks are contained in [Regions](#regions). Operations 35are also ordered within their containing block and Blocks are ordered in their 36containing region, although this order may or may not be semantically 37meaningful in a given [kind of region](Interfaces.md/#regionkindinterfaces)). 38Operations may also contain regions, enabling hierarchical structures to be 39represented. 40 41Operations can represent many different concepts, from higher-level concepts 42like function definitions, function calls, buffer allocations, view or slices 43of buffers, and process creation, to lower-level concepts like 44target-independent arithmetic, target-specific instructions, configuration 45registers, and logic gates. These different concepts are represented by 46different operations in MLIR and the set of operations usable in MLIR can be 47arbitrarily extended. 48 49MLIR also provides an extensible framework for transformations on operations, 50using familiar concepts of compiler [Passes](Passes.md). Enabling an arbitrary 51set of passes on an arbitrary set of operations results in a significant 52scaling challenge, since each transformation must potentially take into 53account the semantics of any operation. MLIR addresses this complexity by 54allowing operation semantics to be described abstractly using 55[Traits](Traits.md) and [Interfaces](Interfaces.md), enabling transformations 56to operate on operations more generically. Traits often describe verification 57constraints on valid IR, enabling complex invariants to be captured and 58checked. (see [Op vs 59Operation](Tutorials/Toy/Ch-2.md/#op-vs-operation-using-mlir-operations)) 60 61One obvious application of MLIR is to represent an 62[SSA-based](https://en.wikipedia.org/wiki/Static_single_assignment_form) IR, 63like the LLVM core IR, with appropriate choice of operation types to define 64Modules, Functions, Branches, Memory Allocation, and verification constraints to 65ensure the SSA Dominance property. MLIR includes a collection of dialects which 66defines just such structures. However, MLIR is intended to be general enough to 67represent other compiler-like data structures, such as Abstract Syntax Trees in 68a language frontend, generated instructions in a target-specific backend, or 69circuits in a High-Level Synthesis tool. 70 71Here's an example of an MLIR module: 72 73```mlir 74// Compute A*B using an implementation of multiply kernel and print the 75// result using a TensorFlow op. The dimensions of A and B are partially 76// known. The shapes are assumed to match. 77func @mul(%A: tensor<100x?xf32>, %B: tensor<?x50xf32>) -> (tensor<100x50xf32>) { 78 // Compute the inner dimension of %A using the dim operation. 79 %n = dim %A, 1 : tensor<100x?xf32> 80 81 // Allocate addressable "buffers" and copy tensors %A and %B into them. 82 %A_m = alloc(%n) : memref<100x?xf32> 83 tensor_store %A to %A_m : memref<100x?xf32> 84 85 %B_m = alloc(%n) : memref<?x50xf32> 86 tensor_store %B to %B_m : memref<?x50xf32> 87 88 // Call function @multiply passing memrefs as arguments, 89 // and getting returned the result of the multiplication. 90 %C_m = call @multiply(%A_m, %B_m) 91 : (memref<100x?xf32>, memref<?x50xf32>) -> (memref<100x50xf32>) 92 93 dealloc %A_m : memref<100x?xf32> 94 dealloc %B_m : memref<?x50xf32> 95 96 // Load the buffer data into a higher level "tensor" value. 97 %C = tensor_load %C_m : memref<100x50xf32> 98 dealloc %C_m : memref<100x50xf32> 99 100 // Call TensorFlow built-in function to print the result tensor. 101 "tf.Print"(%C){message: "mul result"} 102 : (tensor<100x50xf32) -> (tensor<100x50xf32>) 103 104 return %C : tensor<100x50xf32> 105} 106 107// A function that multiplies two memrefs and returns the result. 108func @multiply(%A: memref<100x?xf32>, %B: memref<?x50xf32>) 109 -> (memref<100x50xf32>) { 110 // Compute the inner dimension of %A. 111 %n = dim %A, 1 : memref<100x?xf32> 112 113 // Allocate memory for the multiplication result. 114 %C = alloc() : memref<100x50xf32> 115 116 // Multiplication loop nest. 117 affine.for %i = 0 to 100 { 118 affine.for %j = 0 to 50 { 119 store 0 to %C[%i, %j] : memref<100x50xf32> 120 affine.for %k = 0 to %n { 121 %a_v = load %A[%i, %k] : memref<100x?xf32> 122 %b_v = load %B[%k, %j] : memref<?x50xf32> 123 %prod = mulf %a_v, %b_v : f32 124 %c_v = load %C[%i, %j] : memref<100x50xf32> 125 %sum = addf %c_v, %prod : f32 126 store %sum, %C[%i, %j] : memref<100x50xf32> 127 } 128 } 129 } 130 return %C : memref<100x50xf32> 131} 132``` 133 134## Notation 135 136MLIR has a simple and unambiguous grammar, allowing it to reliably round-trip 137through a textual form. This is important for development of the compiler - 138e.g. for understanding the state of code as it is being transformed and 139writing test cases. 140 141This document describes the grammar using 142[Extended Backus-Naur Form (EBNF)](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form). 143 144This is the EBNF grammar used in this document, presented in yellow boxes. 145 146``` 147alternation ::= expr0 | expr1 | expr2 // Either expr0 or expr1 or expr2. 148sequence ::= expr0 expr1 expr2 // Sequence of expr0 expr1 expr2. 149repetition0 ::= expr* // 0 or more occurrences. 150repetition1 ::= expr+ // 1 or more occurrences. 151optionality ::= expr? // 0 or 1 occurrence. 152grouping ::= (expr) // Everything inside parens is grouped together. 153literal ::= `abcd` // Matches the literal `abcd`. 154``` 155 156Code examples are presented in blue boxes. 157 158```mlir 159// This is an example use of the grammar above: 160// This matches things like: ba, bana, boma, banana, banoma, bomana... 161example ::= `b` (`an` | `om`)* `a` 162``` 163 164### Common syntax 165 166The following core grammar productions are used in this document: 167 168``` 169// TODO: Clarify the split between lexing (tokens) and parsing (grammar). 170digit ::= [0-9] 171hex_digit ::= [0-9a-fA-F] 172letter ::= [a-zA-Z] 173id-punct ::= [$._-] 174 175integer-literal ::= decimal-literal | hexadecimal-literal 176decimal-literal ::= digit+ 177hexadecimal-literal ::= `0x` hex_digit+ 178float-literal ::= [-+]?[0-9]+[.][0-9]*([eE][-+]?[0-9]+)? 179string-literal ::= `"` [^"\n\f\v\r]* `"` TODO: define escaping rules 180``` 181 182Not listed here, but MLIR does support comments. They use standard BCPL syntax, 183starting with a `//` and going until the end of the line. 184 185### Identifiers and keywords 186 187Syntax: 188 189``` 190// Identifiers 191bare-id ::= (letter|[_]) (letter|digit|[_$.])* 192bare-id-list ::= bare-id (`,` bare-id)* 193value-id ::= `%` suffix-id 194suffix-id ::= (digit+ | ((letter|id-punct) (letter|id-punct|digit)*)) 195 196symbol-ref-id ::= `@` (suffix-id | string-literal) 197value-id-list ::= value-id (`,` value-id)* 198 199// Uses of value, e.g. in an operand list to an operation. 200value-use ::= value-id 201value-use-list ::= value-use (`,` value-use)* 202``` 203 204Identifiers name entities such as values, types and functions, and are 205chosen by the writer of MLIR code. Identifiers may be descriptive (e.g. 206`%batch_size`, `@matmul`), or may be non-descriptive when they are 207auto-generated (e.g. `%23`, `@func42`). Identifier names for values may be 208used in an MLIR text file but are not persisted as part of the IR - the printer 209will give them anonymous names like `%42`. 210 211MLIR guarantees identifiers never collide with keywords by prefixing identifiers 212with a sigil (e.g. `%`, `#`, `@`, `^`, `!`). In certain unambiguous contexts 213(e.g. affine expressions), identifiers are not prefixed, for brevity. New 214keywords may be added to future versions of MLIR without danger of collision 215with existing identifiers. 216 217Value identifiers are only [in scope](#value-scoping) for the (nested) 218region in which they are defined and cannot be accessed or referenced 219outside of that region. Argument identifiers in mapping functions are 220in scope for the mapping body. Particular operations may further limit 221which identifiers are in scope in their regions. For instance, the 222scope of values in a region with [SSA control flow 223semantics](#control-flow-and-ssacfg-regions) is constrained according 224to the standard definition of [SSA 225dominance](https://en.wikipedia.org/wiki/Dominator_\(graph_theory\)). Another 226example is the [IsolatedFromAbove trait](Traits.md/#isolatedfromabove), 227which restricts directly accessing values defined in containing 228regions. 229 230Function identifiers and mapping identifiers are associated with 231[Symbols](SymbolsAndSymbolTables.md) and have scoping rules dependent on 232symbol attributes. 233 234## Dialects 235 236Dialects are the mechanism by which to engage with and extend the MLIR 237ecosystem. They allow for defining new [operations](#operations), as well as 238[attributes](#attributes) and [types](#type-system). Each dialect is given a 239unique `namespace` that is prefixed to each defined attribute/operation/type. 240For example, the [Affine dialect](Dialects/Affine.md) defines the namespace: 241`affine`. 242 243MLIR allows for multiple dialects, even those outside of the main tree, to 244co-exist together within one module. Dialects are produced and consumed by 245certain passes. MLIR provides a [framework](DialectConversion.md) to convert 246between, and within, different dialects. 247 248A few of the dialects supported by MLIR: 249 250* [Affine dialect](Dialects/Affine.md) 251* [GPU dialect](Dialects/GPU.md) 252* [LLVM dialect](Dialects/LLVM.md) 253* [SPIR-V dialect](Dialects/SPIR-V.md) 254* [Standard dialect](Dialects/Standard.md) 255* [Vector dialect](Dialects/Vector.md) 256 257### Target specific operations 258 259Dialects provide a modular way in which targets can expose target-specific 260operations directly through to MLIR. As an example, some targets go through 261LLVM. LLVM has a rich set of intrinsics for certain target-independent 262operations (e.g. addition with overflow check) as well as providing access to 263target-specific operations for the targets it supports (e.g. vector 264permutation operations). LLVM intrinsics in MLIR are represented via 265operations that start with an "llvm." name. 266 267Example: 268 269```mlir 270// LLVM: %x = call {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b) 271%x:2 = "llvm.sadd.with.overflow.i16"(%a, %b) : (i16, i16) -> (i16, i1) 272``` 273 274These operations only work when targeting LLVM as a backend (e.g. for CPUs and 275GPUs), and are required to align with the LLVM definition of these intrinsics. 276 277## Operations 278 279Syntax: 280 281``` 282operation ::= op-result-list? (generic-operation | custom-operation) 283 trailing-location? 284generic-operation ::= string-literal `(` value-use-list? `)` successor-list? 285 region-list? dictionary-attribute? `:` function-type 286custom-operation ::= bare-id custom-operation-format 287op-result-list ::= op-result (`,` op-result)* `=` 288op-result ::= value-id (`:` integer-literal) 289successor-list ::= `[` successor (`,` successor)* `]` 290successor ::= caret-id (`:` bb-arg-list)? 291region-list ::= `(` region (`,` region)* `)` 292dictionary-attribute ::= `{` (attribute-entry (`,` attribute-entry)*)? `}` 293trailing-location ::= (`loc` `(` location `)`)? 294``` 295 296MLIR introduces a uniform concept called _operations_ to enable describing 297many different levels of abstractions and computations. Operations in MLIR are 298fully extensible (there is no fixed list of operations) and have 299application-specific semantics. For example, MLIR supports [target-independent 300operations](Dialects/Standard.md#memory-operations), [affine 301operations](Dialects/Affine.md), and [target-specific machine 302operations](#target-specific-operations). 303 304The internal representation of an operation is simple: an operation is 305identified by a unique string (e.g. `dim`, `tf.Conv2d`, `x86.repmovsb`, 306`ppc.eieio`, etc), can return zero or more results, take zero or more 307operands, has a dictionary of [attributes](#attributes), has zero or more 308successors, and zero or more enclosed [regions](#regions). The generic printing 309form includes all these elements literally, with a function type to indicate the 310types of the results and operands. 311 312Example: 313 314```mlir 315// An operation that produces two results. 316// The results of %result can be accessed via the <name> `#` <opNo> syntax. 317%result:2 = "foo_div"() : () -> (f32, i32) 318 319// Pretty form that defines a unique name for each result. 320%foo, %bar = "foo_div"() : () -> (f32, i32) 321 322// Invoke a TensorFlow function called tf.scramble with two inputs 323// and an attribute "fruit". 324%2 = "tf.scramble"(%result#0, %bar) {fruit = "banana"} : (f32, i32) -> f32 325``` 326 327In addition to the basic syntax above, dialects may register known operations. 328This allows those dialects to support _custom assembly form_ for parsing and 329printing operations. In the operation sets listed below, we show both forms. 330 331### Builtin Operations 332 333The [builtin dialect](Dialects/Builtin.md) defines a select few operations that 334are widely applicable by MLIR dialects, such as a universal conversion cast 335operation that simplifies inter/intra dialect conversion. This dialect also 336defines a top-level `module` operation, that represents a useful IR container. 337 338## Blocks 339 340Syntax: 341 342``` 343block ::= block-label operation+ 344block-label ::= block-id block-arg-list? `:` 345block-id ::= caret-id 346caret-id ::= `^` suffix-id 347value-id-and-type ::= value-id `:` type 348 349// Non-empty list of names and types. 350value-id-and-type-list ::= value-id-and-type (`,` value-id-and-type)* 351 352block-arg-list ::= `(` value-id-and-type-list? `)` 353``` 354 355A *Block* is a list of operations. In [SSACFG 356regions](#control-flow-and-ssacfg-regions), each block represents a compiler 357[basic block](https://en.wikipedia.org/wiki/Basic_block) where instructions 358inside the block are executed in order and terminator operations implement 359control flow branches between basic blocks. 360 361A region with a single block may not include a [terminator 362operation](#terminator-operations). The enclosing op can opt-out of this 363requirement with the `NoTerminator` trait. The top-level `ModuleOp` is an 364example of such operation which defined this trait and whose block body does 365not have a terminator. 366 367Blocks in MLIR take a list of block arguments, notated in a function-like 368way. Block arguments are bound to values specified by the semantics of 369individual operations. Block arguments of the entry block of a region are also 370arguments to the region and the values bound to these arguments are determined 371by the semantics of the containing operation. Block arguments of other blocks 372are determined by the semantics of terminator operations, e.g. Branches, which 373have the block as a successor. In regions with [control 374flow](#control-flow-and-ssacfg-regions), MLIR leverages this structure to 375implicitly represent the passage of control-flow dependent values without the 376complex nuances of PHI nodes in traditional SSA representations. Note that 377values which are not control-flow dependent can be referenced directly and do 378not need to be passed through block arguments. 379 380Here is a simple example function showing branches, returns, and block 381arguments: 382 383```mlir 384func @simple(i64, i1) -> i64 { 385^bb0(%a: i64, %cond: i1): // Code dominated by ^bb0 may refer to %a 386 cond_br %cond, ^bb1, ^bb2 387 388^bb1: 389 br ^bb3(%a: i64) // Branch passes %a as the argument 390 391^bb2: 392 %b = addi %a, %a : i64 393 br ^bb3(%b: i64) // Branch passes %b as the argument 394 395// ^bb3 receives an argument, named %c, from predecessors 396// and passes it on to bb4 along with %a. %a is referenced 397// directly from its defining operation and is not passed through 398// an argument of ^bb3. 399^bb3(%c: i64): 400 br ^bb4(%c, %a : i64, i64) 401 402^bb4(%d : i64, %e : i64): 403 %0 = addi %d, %e : i64 404 return %0 : i64 // Return is also a terminator. 405} 406``` 407 408**Context:** The "block argument" representation eliminates a number 409of special cases from the IR compared to traditional "PHI nodes are 410operations" SSA IRs (like LLVM). For example, the [parallel copy 411semantics](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.524.5461&rep=rep1&type=pdf) 412of SSA is immediately apparent, and function arguments are no longer a 413special case: they become arguments to the entry block [[more 414rationale](Rationale/Rationale.md/#block-arguments-vs-phi-nodes)]. Blocks 415are also a fundamental concept that cannot be represented by 416operations because values defined in an operation cannot be accessed 417outside the operation. 418 419## Regions 420 421### Definition 422 423A region is an ordered list of MLIR [Blocks](#blocks). The semantics within a 424region is not imposed by the IR. Instead, the containing operation defines the 425semantics of the regions it contains. MLIR currently defines two kinds of 426regions: [SSACFG regions](#control-flow-and-ssacfg-regions), which describe 427control flow between blocks, and [Graph regions](#graph-regions), which do not 428require control flow between block. The kinds of regions within an operation 429are described using the 430[RegionKindInterface](Interfaces.md/#regionkindinterfaces). 431 432Regions do not have a name or an address, only the blocks contained in a 433region do. Regions must be contained within operations and have no type or 434attributes. The first block in the region is a special block called the 'entry 435block'. The arguments to the entry block are also the arguments of the region 436itself. The entry block cannot be listed as a successor of any other 437block. The syntax for a region is as follows: 438 439``` 440region ::= `{` block* `}` 441``` 442 443A function body is an example of a region: it consists of a CFG of blocks and 444has additional semantic restrictions that other types of regions may not have. 445For example, in a function body, block terminators must either branch to a 446different block, or return from a function where the types of the `return` 447arguments must match the result types of the function signature. Similarly, 448the function arguments must match the types and count of the region arguments. 449In general, operations with regions can define these correspondances 450arbitrarily. 451 452### Value Scoping 453 454Regions provide hierarchical encapsulation of programs: it is impossible to 455reference, i.e. branch to, a block which is not in the same region as the 456source of the reference, i.e. a terminator operation. Similarly, regions 457provides a natural scoping for value visibility: values defined in a region 458don't escape to the enclosing region, if any. By default, operations inside a 459region can reference values defined outside of the region whenever it would 460have been legal for operands of the enclosing operation to reference those 461values, but this can be restricted using traits, such as 462[OpTrait::IsolatedFromAbove](Traits.md/#isolatedfromabove), or a custom 463verifier. 464 465Example: 466 467```mlir 468 "any_op"(%a) ({ // if %a is in-scope in the containing region... 469 // then %a is in-scope here too. 470 %new_value = "another_op"(%a) : (i64) -> (i64) 471 }) : (i64) -> (i64) 472``` 473 474MLIR defines a generalized 'hierarchical dominance' concept that operates 475across hierarchy and defines whether a value is 'in scope' and can be used by 476a particular operation. Whether a value can be used by another operation in 477the same region is defined by the kind of region. A value defined in a region 478can be used by an operation which has a parent in the same region, if and only 479if the parent could use the value. A value defined by an argument to a region 480can always be used by any operation deeply contained in the region. A value 481defined in a region can never be used outside of the region. 482 483### Control Flow and SSACFG Regions 484 485In MLIR, control flow semantics of a region is indicated by 486[RegionKind::SSACFG](Interfaces.md/#regionkindinterfaces). Informally, these 487regions support semantics where operations in a region 'execute 488sequentially'. Before an operation executes, its operands have well-defined 489values. After an operation executes, the operands have the same values and 490results also have well-defined values. After an operation executes, the next 491operation in the block executes until the operation is the terminator operation 492at the end of a block, in which case some other operation will execute. The 493determination of the next instruction to execute is the 'passing of control 494flow'. 495 496In general, when control flow is passed to an operation, MLIR does not 497restrict when control flow enters or exits the regions contained in that 498operation. However, when control flow enters a region, it always begins in the 499first block of the region, called the *entry* block. Terminator operations 500ending each block represent control flow by explicitly specifying the 501successor blocks of the block. Control flow can only pass to one of the 502specified successor blocks as in a `branch` operation, or back to the 503containing operation as in a `return` operation. Terminator operations without 504successors can only pass control back to the containing operation. Within 505these restrictions, the particular semantics of terminator operations is 506determined by the specific dialect operations involved. Blocks (other than the 507entry block) that are not listed as a successor of a terminator operation are 508defined to be unreachable and can be removed without affecting the semantics 509of the containing operation. 510 511Although control flow always enters a region through the entry block, control 512flow may exit a region through any block with an appropriate terminator. The 513standard dialect leverages this capability to define operations with 514Single-Entry-Multiple-Exit (SEME) regions, possibly flowing through different 515blocks in the region and exiting through any block with a `return` 516operation. This behavior is similar to that of a function body in most 517programming languages. In addition, control flow may also not reach the end of 518a block or region, for example if a function call does not return. 519 520Example: 521 522```mlir 523func @accelerator_compute(i64, i1) -> i64 { // An SSACFG region 524^bb0(%a: i64, %cond: i1): // Code dominated by ^bb0 may refer to %a 525 cond_br %cond, ^bb1, ^bb2 526 527^bb1: 528 // This def for %value does not dominate ^bb2 529 %value = "op.convert"(%a) : (i64) -> i64 530 br ^bb3(%a: i64) // Branch passes %a as the argument 531 532^bb2: 533 accelerator.launch() { // An SSACFG region 534 ^bb0: 535 // Region of code nested under "accelerator.launch", it can reference %a but 536 // not %value. 537 %new_value = "accelerator.do_something"(%a) : (i64) -> () 538 } 539 // %new_value cannot be referenced outside of the region 540 541^bb3: 542 ... 543} 544``` 545 546#### Operations with Multiple Regions 547 548An operation containing multiple regions also completely determines the 549semantics of those regions. In particular, when control flow is passed to an 550operation, it may transfer control flow to any contained region. When control 551flow exits a region and is returned to the containing operation, the 552containing operation may pass control flow to any region in the same 553operation. An operation may also pass control flow to multiple contained 554regions concurrently. An operation may also pass control flow into regions 555that were specified in other operations, in particular those that defined the 556values or symbols the given operation uses as in a call operation. This 557passage of control is generally independent of passage of control flow through 558the basic blocks of the containing region. 559 560#### Closure 561 562Regions allow defining an operation that creates a closure, for example by 563“boxing” the body of the region into a value they produce. It remains up to the 564operation to define its semantics. Note that if an operation triggers 565asynchronous execution of the region, it is under the responsibility of the 566operation caller to wait for the region to be executed guaranteeing that any 567directly used values remain live. 568 569### Graph Regions 570 571In MLIR, graph-like semantics in a region is indicated by 572[RegionKind::Graph](Interfaces.md/#regionkindinterfaces). Graph regions are 573appropriate for concurrent semantics without control flow, or for modeling 574generic directed graph data structures. Graph regions are appropriate for 575representing cyclic relationships between coupled values where there is no 576fundamental order to the relationships. For instance, operations in a graph 577region may represent independent threads of control with values representing 578streams of data. As usual in MLIR, the particular semantics of a region is 579completely determined by its containing operation. Graph regions may only 580contain a single basic block (the entry block). 581 582**Rationale:** Currently graph regions are arbitrarily limited to a single 583basic block, although there is no particular semantic reason for this 584limitation. This limitation has been added to make it easier to stabilize the 585pass infrastructure and commonly used passes for processing graph regions to 586properly handle feedback loops. Multi-block regions may be allowed in the 587future if use cases that require it arise. 588 589In graph regions, MLIR operations naturally represent nodes, while each MLIR 590value represents a multi-edge connecting a single source node and multiple 591destination nodes. All values defined in the region as results of operations 592are in scope within the region and can be accessed by any other operation in 593the region. In graph regions, the order of operations within a block and the 594order of blocks in a region is not semantically meaningful and non-terminator 595operations may be freely reordered, for instance, by canonicalization. Other 596kinds of graphs, such as graphs with multiple source nodes and multiple 597destination nodes, can also be represented by representing graph edges as MLIR 598operations. 599 600Note that cycles can occur within a single block in a graph region, or between 601basic blocks. 602 603```mlir 604"test.graph_region"() ({ // A Graph region 605 %1 = "op1"(%1, %3) : (i32, i32) -> (i32) // OK: %1, %3 allowed here 606 %2 = "test.ssacfg_region"() ({ 607 %5 = "op2"(%1, %2, %3, %4) : (i32, i32, i32, i32) -> (i32) // OK: %1, %2, %3, %4 all defined in the containing region 608 }) : () -> (i32) 609 %3 = "op2"(%1, %4) : (i32, i32) -> (i32) // OK: %4 allowed here 610 %4 = "op3"(%1) : (i32) -> (i32) 611}) : () -> () 612``` 613 614### Arguments and Results 615 616The arguments of the first block of a region are treated as arguments of the 617region. The source of these arguments is defined by the semantics of the parent 618operation. They may correspond to some of the values the operation itself uses. 619 620Regions produce a (possibly empty) list of values. The operation semantics 621defines the relation between the region results and the operation results. 622 623## Type System 624 625Each value in MLIR has a type defined by the type system. MLIR has an open type 626system (i.e. there is no fixed list of types), and types may have 627application-specific semantics. MLIR dialects may define any number of types 628with no restrictions on the abstractions they represent. 629 630``` 631type ::= type-alias | dialect-type | builtin-type 632 633type-list-no-parens ::= type (`,` type)* 634type-list-parens ::= `(` `)` 635 | `(` type-list-no-parens `)` 636 637// This is a common way to refer to a value with a specified type. 638ssa-use-and-type ::= ssa-use `:` type 639 640// Non-empty list of names and types. 641ssa-use-and-type-list ::= ssa-use-and-type (`,` ssa-use-and-type)* 642``` 643 644### Type Aliases 645 646``` 647type-alias-def ::= '!' alias-name '=' 'type' type 648type-alias ::= '!' alias-name 649``` 650 651MLIR supports defining named aliases for types. A type alias is an identifier 652that can be used in the place of the type that it defines. These aliases *must* 653be defined before their uses. Alias names may not contain a '.', since those 654names are reserved for [dialect types](#dialect-types). 655 656Example: 657 658```mlir 659!avx_m128 = type vector<4 x f32> 660 661// Using the original type. 662"foo"(%x) : vector<4 x f32> -> () 663 664// Using the type alias. 665"foo"(%x) : !avx_m128 -> () 666``` 667 668### Dialect Types 669 670Similarly to operations, dialects may define custom extensions to the type 671system. 672 673``` 674dialect-namespace ::= bare-id 675 676opaque-dialect-item ::= dialect-namespace '<' string-literal '>' 677 678pretty-dialect-item ::= dialect-namespace '.' pretty-dialect-item-lead-ident 679 pretty-dialect-item-body? 680 681pretty-dialect-item-lead-ident ::= '[A-Za-z][A-Za-z0-9._]*' 682pretty-dialect-item-body ::= '<' pretty-dialect-item-contents+ '>' 683pretty-dialect-item-contents ::= pretty-dialect-item-body 684 | '(' pretty-dialect-item-contents+ ')' 685 | '[' pretty-dialect-item-contents+ ']' 686 | '{' pretty-dialect-item-contents+ '}' 687 | '[^[<({>\])}\0]+' 688 689dialect-type ::= '!' opaque-dialect-item 690dialect-type ::= '!' pretty-dialect-item 691``` 692 693Dialect types can be specified in a verbose form, e.g. like this: 694 695```mlir 696// LLVM type that wraps around llvm IR types. 697!llvm<"i32*"> 698 699// Tensor flow string type. 700!tf.string 701 702// Complex type 703!foo<"something<abcd>"> 704 705// Even more complex type 706!foo<"something<a%%123^^^>>>"> 707``` 708 709Dialect types that are simple enough can use the pretty format, which is a 710lighter weight syntax that is equivalent to the above forms: 711 712```mlir 713// Tensor flow string type. 714!tf.string 715 716// Complex type 717!foo.something<abcd> 718``` 719 720Sufficiently complex dialect types are required to use the verbose form for 721generality. For example, the more complex type shown above wouldn't be valid in 722the lighter syntax: `!foo.something<a%%123^^^>>>` because it contains characters 723that are not allowed in the lighter syntax, as well as unbalanced `<>` 724characters. 725 726See [here](Tutorials/DefiningAttributesAndTypes.md) to learn how to define 727dialect types. 728 729### Builtin Types 730 731The [builtin dialect](Dialects/Builtin.md) defines a set of types that are 732directly usable by any other dialect in MLIR. These types cover a range from 733primitive integer and floating-point types, function types, and more. 734 735## Attributes 736 737Syntax: 738 739``` 740attribute-entry ::= (bare-id | string-literal) `=` attribute-value 741attribute-value ::= attribute-alias | dialect-attribute | builtin-attribute 742``` 743 744Attributes are the mechanism for specifying constant data on operations in 745places where a variable is never allowed - e.g. the comparison predicate of a 746[`cmpi` operation](Dialects/Standard.md#stdcmpi-cmpiop). Each operation has an 747attribute dictionary, which associates a set of attribute names to attribute 748values. MLIR's builtin dialect provides a rich set of 749[builtin attribute values](#builtin-attribute-values) out of the box (such as 750arrays, dictionaries, strings, etc.). Additionally, dialects can define their 751own [dialect attribute values](#dialect-attribute-values). 752 753The top-level attribute dictionary attached to an operation has special 754semantics. The attribute entries are considered to be of two different kinds 755based on whether their dictionary key has a dialect prefix: 756 757- *inherent attributes* are inherent to the definition of an operation's 758 semantics. The operation itself is expected to verify the consistency of these 759 attributes. An example is the `predicate` attribute of the `std.cmpi` op. 760 These attributes must have names that do not start with a dialect prefix. 761 762- *discardable attributes* have semantics defined externally to the operation 763 itself, but must be compatible with the operations's semantics. These 764 attributes must have names that start with a dialect prefix. The dialect 765 indicated by the dialect prefix is expected to verify these attributes. An 766 example is the `gpu.container_module` attribute. 767 768Note that attribute values are allowed to themselves be dictionary attributes, 769but only the top-level dictionary attribute attached to the operation is subject 770to the classification above. 771 772### Attribute Value Aliases 773 774``` 775attribute-alias-def ::= '#' alias-name '=' attribute-value 776attribute-alias ::= '#' alias-name 777``` 778 779MLIR supports defining named aliases for attribute values. An attribute alias is 780an identifier that can be used in the place of the attribute that it defines. 781These aliases *must* be defined before their uses. Alias names may not contain a 782'.', since those names are reserved for 783[dialect attributes](#dialect-attribute-values). 784 785Example: 786 787```mlir 788#map = affine_map<(d0) -> (d0 + 10)> 789 790// Using the original attribute. 791%b = affine.apply affine_map<(d0) -> (d0 + 10)> (%a) 792 793// Using the attribute alias. 794%b = affine.apply #map(%a) 795``` 796 797### Dialect Attribute Values 798 799Similarly to operations, dialects may define custom attribute values. The 800syntactic structure of these values is identical to custom dialect type values, 801except that dialect attribute values are distinguished with a leading '#', while 802dialect types are distinguished with a leading '!'. 803 804``` 805dialect-attribute-value ::= '#' opaque-dialect-item 806dialect-attribute-value ::= '#' pretty-dialect-item 807``` 808 809Dialect attribute values can be specified in a verbose form, e.g. like this: 810 811```mlir 812// Complex attribute value. 813#foo<"something<abcd>"> 814 815// Even more complex attribute value. 816#foo<"something<a%%123^^^>>>"> 817``` 818 819Dialect attribute values that are simple enough can use the pretty format, which 820is a lighter weight syntax that is equivalent to the above forms: 821 822```mlir 823// Complex attribute 824#foo.something<abcd> 825``` 826 827Sufficiently complex dialect attribute values are required to use the verbose 828form for generality. For example, the more complex type shown above would not be 829valid in the lighter syntax: `#foo.something<a%%123^^^>>>` because it contains 830characters that are not allowed in the lighter syntax, as well as unbalanced 831`<>` characters. 832 833See [here](Tutorials/DefiningAttributesAndTypes.md) on how to define dialect 834attribute values. 835 836### Builtin Attribute Values 837 838The [builtin dialect](Dialects/Builtin.md) defines a set of attribute values 839that are directly usable by any other dialect in MLIR. These types cover a range 840from primitive integer and floating-point values, attribute dictionaries, dense 841multi-dimensional arrays, and more. 842