Lines Matching full:the
10 of the IR using a different portion of the IR. It refers to the IR being
11 transformed as payload IR, and to the IR guiding the transformation as
14 The main use case for this dialect is orchestrating fine-grain transformations
17 size) in the payload IR, applying loop tiling to those and only those
18 operations, and then applying loop unrolling to the inner loops produced by the
19 previous transformations. As such, it is not intended as a replacement for the
20 pass infrastructure, nor for the pattern rewriting infrastructure. In the most
21 common case, the transform IR will be processed and applied to the payload IR by
22 a pass. Transformations expressed by the Transform dialect may be implemented
23 using the pattern infrastructure or any other relevant MLIR component.
25 The following IR gives a rough idea of what the operations in this dialect
39 The values used in the Transform dialect may correspond to:
41 * sets of operations in the payload IR;
43 * sets of values in the payload IR;
45 * sets of parameters (attributes) known at the execution time of the
48 The former two kinds of values are also referred to as operation and value
49 *handles*, respectively. In the example above, `%0` corresponds to the set of
50 loops found in the payload IR that satisfy the condition, and `%2` correspond to
51 groups of outer and inner loops, respectively, produced by the tiling
52 transformation. `%3` corresponds to a set of values that are produced by the
54 each of the operations that `%0` corresponds to.
58 be made about the order of ops unless specified otherwise by the operation.
63 objects. They usually apply the respective transformation for every mapped
65 the documentation of Transform IR ops.
67 Parameters, such as `%1` in the above example, have two logical roles in
68 transform IR. In parameter based control, they carry the values needed to
69 execute the explicit control defined by the transforms, for example:
78 Alternatively, parameters can associate with the payload IR where the specific
79 value at execution time has no bearing on the execution of the transform IR. In
80 other words, parameters can either associate with the transform IR or the
85 The transform IR values have transform IR types, which should implement exactly one of:
93 The goal of these type interfaces, beyond providing a common base for accepted
94 types, is to verify the properties of the associated objects. For example, a
96 operations implement the "TileableOp" interface or have a specific "loop" kind.
97 Similarly, a value handle type interface implementation may check if the
99 parameter type interface may check whether the associated attributes contain
102 operation. The conditions are verified when payload objects operations are first
105 operand type constraints in the their definitions and verifiers. On the
108 restricted result type than the constraint in the operation (e.g., the "find"
109 operation only constrains the result type to be a transform IR type while its
111 the "tilable" interface). The verification will then happen at transform
113 properties in the transform IR without resorting to excessive use of type casts
115 verbosity/complexity and static hardening, which can be revised in the future.
118 op. Such top-level ops specify how to apply the transformations described
119 by the operations they contain, e.g., `transform.sequence` executes
121 expected to have the `PossibleTopLevelTransformOpTrait` and may be used
124 A program transformation expressed using the Transform dialect can be
135 that applies the transformations specified by the top-level `transform` to
136 payload IR contained in `payloadRoot`. The payload root operation will be
137 associated with the first argument of the entry block of the top-level transform
139 be associated with values provided as `extraMappings`. The call will report an
140 error and return if the wrong number of mappings is provided.
145 are allowed to inject additional operations into this dialect using the
146 `TransformDialectExtension` mechanism. This allows the dialect to avoid a
147 dependency on the implementation of the transformation as well as to avoid
148 introducing dialect-specific transform dialects. In the example above,
149 the operations may have been injected by a notional `loop` dialect rather
150 than defined in this dialect, hence the common prefix.
154 dialect-specific transformations, the prefix is naturally the name of the
156 transformations (typically implemented using interfaces), the prefix may
157 be derived from the interface name or from a common concept, e.g.,
159 `TileableOpInterface`. The C++ classes for the dialect extension should
160 include the prefix in their name, e.g., `AffineTransformDialectExtension` or
161 `LoopTransformDialectExtension` in the cases above. Unprefixed operation
162 names are reserved for ops defined directly in the Transform dialect.
164 Operations injected into the dialect must:
166 * Implement the `TransformOpInterface` to execute the corresponding
167 transformation on the payload IR.
169 * Implement the `MemoryEffectsOpInterface` to annotate the effects of
170 the transform IR operation on the payload IR as well as on the mapping
172 the description of available effects.
174 The presence of interface implementations is checked at runtime when the
178 Similarly to operations, additional types can be injected into the dialect using
179 the same extension mechanism. The types must:
186 The Transform dialect relies on MLIR side effect modelling to enable
187 optimization of the transform IR. More specifically, it provides several
191 * `TransformMappingResource` - side effect resource corresponding to the
197 - A `Read` effect from this resource means accessing the mapping.
199 - A `Free` effect on this resource indicates the removal of the mapping
200 entry, typically after a transformation that modifies the payload IR
201 operations associated with one of the transform IR operation's
204 * `PayloadIRResource` - side effect resource corresponding to the payload
207 - A `Read` effect from this resource means accessing the payload IR.
209 - A `Write` effect on this resource means mutating the payload IR. It is
212 The typical flow of values in the transform IR is as follows. Most
215 `Write` effects on the `TransformMappingResource`, and often requires at
216 least a `Read` effect on the `PayloadIRResource`. Transform operations that
217 only inspect the payload IR to produce new handles are usually limited to
218 these effects on their operands. Transform operations that mutate the
219 payload IR are thought to _consume_ the handles provided as operands, that
220 is have the `Read` and `Free` effects on them. As with the usual memory
221 effects, using a value after it was freed is incorrect. In case of the
223 that were modified or even removed by the transformation, so it is
224 meaningless to refer to them. When further transformations are desired, the
230 The transformation starts at the user-specified top-level transform IR
232 the payload IR op that contains the IR to transform. It is the
233 responsibility of the user to properly select the scope and/or to avoid the
234 transformations to modify the IR outside of the given scope. The top-level
236 them in the desired order.
245 perform the required recovery steps thus succeeding themselves. On
246 the other hand, they must propagate irrecoverable failures. For such
247 failures, the diagnostics are emitted immediately whereas their emission is
250 they can either propagate it to their parent or emit the diagnostic and turn
251 the failure into an irrecoverable one. A recoverable failure produced by
252 applying the top-level transform IR operation is considered irrecoverable.
255 operations if the application of some previous operation produced a failure.
258 effect. The transformation is skipped if the register already contains an
259 error description, and the control flow proceeds to the following operation.
263 if they haven't yet modified the payload IR, i.e. when reporting a
264 precondition failure, and an irrecoverable failure when they modified the IR
265 in a way that is contrary to the semantics of the transform operation or
267 payload IR targets for the following transformation may have a conceptual
268 "failure to match" that is considered a successful execution in the
274 The execution model of the Transform dialect allows a payload IR operation to be
278 operation consumes a handle, it usually indicates that the corresponding payload
280 that _may_ be pointing to an erased payload IR object are _invalidated_. The
281 mere presence of an invalidated handle in the transform IR is not a problem, but
283 as dangling pointers. Note that the _entire_ handle is invalidated, even if some
284 of the payload IR objects associated with it remain live.
286 The following handle invalidation rules apply.
290 - operation handles associated with one of the payload operations that the
293 - operation handles associated with one of the operations _nested_ in the
304 result any value associated with the consumed handle (when the associated
307 - operation handles associated with payload operations _nested_ in the
311 _contained_ in the block that defines as argument any value associated
312 with the consumed handle (when the associated value is a block argument);
313 note that the adjacent blocks are not affected;
316 including all results of the operation defining as result the value
317 associated with the consumed handle;
323 to an object defined or contained in the payload IR subtree rooted at the
326 The Transform dialect infrastructure has the capability of checking whether
327 the transform IR op operand is invalidated before applying the
329 must be enabled explicitly through `TransformOptions`. Additionally, the
331 after it has been consumed, but does so abstractly, without processing the
338 The transformation control infrastructure provided by this dialect is
343 transformations everywhere in the IR, a transform dialect-controlled
347 part of the transform op implementation.
349 One of the main scenarios for using this dialect is fine-grain chaining of
353 (e.g., the first loop is tiled and the second unrolled) with the necessary
354 enabling and cleanup patterns around the main transformation:
365 since the hypothetical "tiling" and "unrolling" pass would need to somehow
366 differentiate between the parts of the loop produced by the previous pass
367 (both are the same operation, and it is likely undesirable to pollute the
368 operation with pass-specific information). Implementing passes that run the
369 combined transformation would have run into the combinatorial explosion
370 issue due to multiple possible transform compositions or into the need for
371 deep pass parameterization, the ultimate form of which is an ad-hoc dialect
372 to specify which transformations the pass should run. The transform dialect
376 The Transform dialect is supposed to be consumed by an "interpreter" pass
377 that drives the application of transformations. To ensure extensibility and
378 composability, this pass is not expected to actually perform the
379 transformations specified by the ops. Instead, the transformations are
380 implemented by the transform ops themselves via `TransformOpInterface`. The
381 pass serves as the entry point, handles the flow of transform operations and
382 takes care of bookkeeping. As such, the Transform dialect does not provide
383 the interpreter pass. Instead, it provides a set of utilities that can be
385 complex pass. For example, the mapping between values in the transform IR
386 and operations in the payload IR, or the function that applies the
387 transformations specified by ops in the given block sequentially. Note that
389 the op itself guiding how to dispatch the transformation control flow to
390 those regions. This approach allows clients to decide on the relative
391 location of the transform IR in their input (e.g., nested modules, separate
395 ## Effects on the Infrastructure
398 to the MLIR infrastructure. It aims to be minimally intrusive and opt-in.
400 Some infrastructural components may grow extra functionality to support the
401 transform dialect. In particular, the pattern infrastructure may add extra
402 hooks to identify the "main results" of a transformation or to notify
404 expected to affect the existing uses of the infrastructure.
406 For the sake of reusability, transformations should be implemented as
407 utility functions that are called from the interface methods of transform
408 ops rather than having the methods directly act on the payload IR.