[Mlir-commits] [mlir] baa39b7 - [mlir] fix wording in transform dialect docs
Alex Zinenko
llvmlistbot at llvm.org
Wed Jan 17 01:20:09 PST 2024
Author: Alex Zinenko
Date: 2024-01-17T09:20:02Z
New Revision: baa39b789bbcf3c597945e6794a02c8e32ccbbd5
URL: https://github.com/llvm/llvm-project/commit/baa39b789bbcf3c597945e6794a02c8e32ccbbd5
DIFF: https://github.com/llvm/llvm-project/commit/baa39b789bbcf3c597945e6794a02c8e32ccbbd5.diff
LOG: [mlir] fix wording in transform dialect docs
The wording "fails silently" has been sometimes used to indicate that a
silenceable failure was emitted by the operation. The meaning is exactly
the opposite: silenceable failure is _not_ silent unless silenced.
Added:
Modified:
mlir/include/mlir/Dialect/Linalg/TransformOps/LinalgTransformOps.td
mlir/include/mlir/Dialect/SCF/TransformOps/SCFTransformOps.td
mlir/include/mlir/Dialect/Transform/IR/TransformOps.td
Removed:
################################################################################
diff --git a/mlir/include/mlir/Dialect/Linalg/TransformOps/LinalgTransformOps.td b/mlir/include/mlir/Dialect/Linalg/TransformOps/LinalgTransformOps.td
index 7d10ba0ae829e5..b139f1ef58b3a9 100644
--- a/mlir/include/mlir/Dialect/Linalg/TransformOps/LinalgTransformOps.td
+++ b/mlir/include/mlir/Dialect/Linalg/TransformOps/LinalgTransformOps.td
@@ -186,9 +186,9 @@ def DecomposeOp : Op<Transform_Dialect, "structured.decompose",
This operation ignores non-Linalg ops and drops them in the return.
If all the operations referred to by the `target` handle decompose
- properly, the transform succeeds. Otherwise the transform silently fails.
- The return handle points to only the subset of successfully produced
- computational operations, which can be empty.
+ properly, the transform succeeds. Otherwise the transform produces a
+ silenceable failure. The return handle points to only the subset of
+ successfully produced computational operations, which can be empty.
}];
let arguments = (ins TransformHandleTypeInterface:$target);
@@ -336,11 +336,11 @@ def FuseIntoContainingOp :
#### Return modes
- If at least one producer could not be fused, this operation fails silently.
- This is the case when tiling fails or when no producer op could be found
- among the remaining producers that has at least one use within the
- containing op. I.e., "producers" that are not consumed within the containing
- op are rejected by this operation.
+ If at least one producer could not be fused, this operation produces a
+ silenceable failure. This is the case when tiling fails or when no
+ producer op could be found among the remaining producers that has at least
+ one use within the containing op. I.e., "producers" that are not consumed
+ within the containing op are rejected by this operation.
This operation consumes the producer handle.
This operation only reads the containing op handle.
@@ -374,10 +374,10 @@ def GeneralizeOp : Op<Transform_Dialect, "structured.generalize",
This operation ignores non-Linalg ops and drops them in the return.
If all the operations referred to by the `target` handle generalize
- properly, the transform succeeds. Otherwise the transform silently fails.
- The return handle points to only the subset of successfully produced
- equivalent generic operations, which can be empty or contain the original
- ops if they were already in generic form.
+ properly, the transform succeeds. Otherwise the transform produces a
+ silenceable failure. The return handle points to only the subset of
+ successfully produced equivalent generic operations, which can be empty or
+ contain the original ops if they were already in generic form.
}];
let arguments = (ins TransformHandleTypeInterface:$target);
@@ -450,7 +450,7 @@ def InterchangeOp : Op<Transform_Dialect, "structured.interchange",
This operation fails if the interchange attribute is invalid.
If all the operations referred to by the `target` handle interchange
properly, the transform succeeds.
- If any interchange fails, the transform definitely fails.
+ If any interchange fails, the transform produces a definite failure.
The return handle points to only the subset of successfully produced
interchanged operations, which can be empty.
}];
@@ -492,7 +492,7 @@ def LowerPackOp : Op<Transform_Dialect, "structured.lower_pack", [
#### Return modes
This operation ignores non-pack ops and drops them in the return.
- This operation produces a silenceableFailure if the rewrite fails for any
+ This operation produces a silenceable failure if the rewrite fails for any
reason.
If all the operations referred to by the `target` are rewritten, the
transform succeeds.
@@ -532,7 +532,7 @@ def LowerUnPackOp : Op<Transform_Dialect, "structured.lower_unpack", [
#### Return modes
This operation ignores non-unpack ops and drops them in the return.
- This operation produces a silenceableFailure if the rewrite fails for any
+ This operation produces a silenceable failure if the rewrite fails for any
reason.
If all the operations referred to by the `target` are rewritten, the
transform succeeds.
@@ -770,7 +770,7 @@ def PackOp : Op<Transform_Dialect, "structured.pack", [
#### Return modes
This operation applies to a single Linalg op, otherwise it fails.
- This operation may produce a definiteFailure if the packing fails for any
+ This operation may produce a definite failure if the packing fails for any
reason.
The returned handle point to the packed LinalgOp.
@@ -997,11 +997,12 @@ def PadOp : Op<Transform_Dialect, "structured.pad",
#### Return modes
This operation ignores non-Linalg ops and drops them in the return.
- This operation may produce a definiteFailure if the padding fails for any
+ This operation may produce a definite failure if the padding fails for any
reason.
If all the operations referred to by the `target` handle pad
- properly, the transform succeeds. Otherwise the transform silently fails.
+ properly, the transform succeeds. Otherwise the transform produces a
+ silenceable failure.
The return handle points to only the subset of successfully produced
padded operations, which can be empty.
}];
@@ -1114,7 +1115,7 @@ def HoistPadOp : Op<Transform_Dialect, "structured.hoist_pad",
If any non-tensor.pad is passed, the transform emits a silenceable failure.
If all the operations referred to by the `target` handle padproperly, the
- transform succeeds. Otherwise the transform silently fails.
+ transform succeeds. Otherwise the transform produces a silenceable failure.
The return handle points to only the subset of successfully hoisted
tensor.pad operations, which can be empty.
@@ -1240,10 +1241,11 @@ def ScalarizeOp : Op<Transform_Dialect, "structured.scalarize",
#### Return modes:
This operation ignores non-Linalg ops and drops them in the return.
- This operation produces `definiteFailure` if the scalarization fails for any
+ This operation produces definite failure if the scalarization fails for any
reason.
If all the operations referred to by the `target` handle scalarize
- properly, the transform succeeds. Otherwise the transform silently fails.
+ properly, the transform succeeds. Otherwise the transform produces a
+ silenceable failure.
The return handle points to only the subset of successfully produced
tiled-by-1 operations, which can be empty.
@@ -1351,7 +1353,8 @@ def RewriteInDestinationPassingStyleOp : Op<
This operation ignores non-unsupported ops and drops them from the return.
If all the operations referred to by the `target` handle generalize
- properly, the transform succeeds. Otherwise the transform silently fails.
+ properly, the transform succeeds. Otherwise the transform produces a
+ silenceable failure.
The return handle points to a subset of successfully produced operations:
- `tensor.pad` case, the returned handle points to the tensor.insert_slice.
- `tensor.generate` case, the returned handle points to the linalg.generic.
@@ -1444,13 +1447,13 @@ def SplitReductionOp : Op<Transform_Dialect, "structured.split_reduction",
#### Return modes
This operation ignores non-Linalg ops and drops them in the return.
- This operation produces `definiteFailure` if the splitting fails for any
+ This operation produces a definite failure if the splitting fails for any
reason.
If all the operations referred to by the `target` handle split
- properly, the transform succeeds. Otherwise the transform silently fails.
- The 4 returned handles points to only the subset of successfully produced
- computational operations, which can all be empty.
+ properly, the transform succeeds. Otherwise the transform produces a
+ silenceable failure. The 4 returned handles points to only the subset of
+ successfully produced computational operations, which can all be empty.
This 4 returned handles point to:
- the init op (or tensor_alloc op if use_alloc = true),
- the fill op used to initialize the neutral element,
@@ -1910,7 +1913,7 @@ def TileUsingForallOp :
Tiling is applied by either specifying `num_threads` or `tile_size`. If
`num_threads` is specified, then the tile size for each dimension `i` is
calculated dynamically via `ceilDiv(dimSize[i], num_threads[i])`.
- `num_threads` and `tile_size` can be either static index attributes or
+ `num_threads` and `tile_size` can be either static index attributes or
operation handles (or a mix thereof). Operation handles must be mapped to
exactly one op that has exactly one result of index type.
@@ -1935,7 +1938,7 @@ def TileUsingForallOp :
If all the operations referred to by the `target` handle tile
successfully, the transform succeeds.
- Otherwise the transform silently fails.
+ Otherwise the transform produces a silenceable failure.
The two returned handles point to only the subset of successfully produced
tiled operations, which can all be empty.
@@ -2066,7 +2069,7 @@ def VectorizeChildrenAndApplyPatternsOp :
#### Return modes:
- This operation produces `definiteFailure` if vectorization fails for any
+ This operation produces a definite failure if vectorization fails for any
reason.
The operation always returns the handle to the target op that is expected
to be isolated from above.
@@ -2103,7 +2106,7 @@ def VectorizeOp : Op<Transform_Dialect, "structured.vectorize",
[DeclareOpInterfaceMethods<MemoryEffectsOpInterface>,
TransformOpInterface, ReportTrackingListenerFailuresOpTrait]> {
let description = [{
- Vectorize the target ops, which must be Linalg ops.
+ Vectorize the target ops, which must be Linalg ops.
Use the optional vector sizes to specify exactly what configuration the
vectorizer should use. It will then use masked vectors of the specified
@@ -2133,7 +2136,7 @@ def VectorizeOp : Op<Transform_Dialect, "structured.vectorize",
This operation produces a silenceable failure if at least one target op is
not a Linalg op or fails to vectorize. It produces a definite failure if
the dynamic vector sizes (SSA values) do not satisfy the constraints
- mentioned above.
+ mentioned above.
}];
let arguments = (ins TransformHandleTypeInterface:$target,
diff --git a/mlir/include/mlir/Dialect/SCF/TransformOps/SCFTransformOps.td b/mlir/include/mlir/Dialect/SCF/TransformOps/SCFTransformOps.td
index b5ac22a2a758dd..cef73689c072b8 100644
--- a/mlir/include/mlir/Dialect/SCF/TransformOps/SCFTransformOps.td
+++ b/mlir/include/mlir/Dialect/SCF/TransformOps/SCFTransformOps.td
@@ -177,9 +177,9 @@ def LoopPipelineOp : Op<Transform_Dialect, "loop.pipeline",
This operation ignores non-scf::For ops and drops them in the return.
If all the operations referred to by the `target` PDLOperation pipeline
- properly, the transform succeeds. Otherwise the transform silently fails.
- The return handle points to only the subset of successfully produced
- pipelined loops, which can be empty.
+ properly, the transform succeeds. Otherwise the transform produces a
+ silenceable failure. The return handle points to only the subset of
+ successfully produced pipelined loops, which can be empty.
}];
let arguments = (ins Transform_ScfForOp:$target,
@@ -240,10 +240,10 @@ def LoopUnrollOp : Op<Transform_Dialect, "loop.unroll",
#### Return modes
- This operation ignores non-scf::For, non-affine::For ops and drops them in
- the return. If all the operations referred to by the `target` PDLOperation
- unroll properly, the transform succeeds. Otherwise the transform silently
- fails.
+ This operation ignores non-`scf.for`, non-`affine.for` ops and drops them
+ in the return. If all the operations referred to by the `target` operand
+ unroll properly, the transform succeeds. Otherwise the transform produces a
+ silencebale failure.
Does not return handles as the operation may result in the loop being
removed after a full unrolling.
diff --git a/mlir/include/mlir/Dialect/Transform/IR/TransformOps.td b/mlir/include/mlir/Dialect/Transform/IR/TransformOps.td
index fe2c28f45aea04..2627553cff6953 100644
--- a/mlir/include/mlir/Dialect/Transform/IR/TransformOps.td
+++ b/mlir/include/mlir/Dialect/Transform/IR/TransformOps.td
@@ -113,8 +113,9 @@ def AnnotateOp : TransformDialectOp<"annotate",
all target operations, otherwise the attributes will be mapped 1:1 based on
the order within the handles.
- Fails silently if the length of the parameter payload does not match the length of
- the target payload. Does not consume the provided handles.
+ Produces a silenceable failure if the length of the parameter payload does
+ not match the length of the target payload. Does not consume the provided
+ handles.
}];
let arguments = (ins TransformHandleTypeInterface:$target,
@@ -192,7 +193,8 @@ def ApplyConversionPatternsOp : TransformDialectOp<"apply_conversion_patterns",
This transform consumes the `target` handle and modifies the payload. It
does not produce any handles.
- This transform fails silently if the dialect conversion was unsuccessful.
+ This transform produces a silenceable failure if the dialect conversion was
+ unsuccessful.
}];
let arguments = (ins TransformHandleTypeInterface:$target,
@@ -308,13 +310,13 @@ def ApplyPatternsOp : TransformDialectOp<"apply_patterns",
Only replacements via `RewriterBase::replaceOp` or `replaceOpWithNewOp` are
considered "payload op replacements". Furthermore, only if the replacement
values are defined by the same op and that op has the same type as the
- original op, the mapping is updated. Otherwise, this transform fails
- silently. More details can be found at the documentation site of
+ original op, the mapping is updated. Otherwise, this transform produces a
+ silenceable failure. More details can be found at the documentation site of
`TrackingListener`.
- This transform also fails silently if the pattern application did not
- converge within the default number of iterations/rewrites of the greedy
- pattern rewrite driver.
+ This transform also produces a silenceable failure if the pattern
+ application did not converge within the default number of
+ iterations/rewrites of the greedy pattern rewrite driver.
}];
let arguments = (ins
@@ -414,7 +416,7 @@ def ApplyRegisteredPassOp : TransformDialectOp<"apply_registered_pass",
let extraClassDeclaration = [{
::mlir::DiagnosedSilenceableFailure applyToOne(
- ::mlir::transform::TransformRewriter &rewriter,
+ ::mlir::transform::TransformRewriter &rewriter,
::mlir::Operation *target,
::mlir::transform::ApplyToEachResultList &results,
::mlir::transform::TransformState &state);
@@ -536,8 +538,8 @@ def ForeachMatchOp : TransformDialectOp<"foreach_match", [
This operation consumes the operand and produces a new handle associated
with the same payload. This is necessary to trigger invalidation of handles
to any of the payload operations nested in the payload operations associated
- with the operand, as those are likely to be modified by actions.
-
+ with the operand, as those are likely to be modified by actions.
+
By default, the root payload operation associated with the operand is not
matched. This is to support the conservative case where applied actions may
invalidate the root payload operation. If the optional `restrict_root`
@@ -631,8 +633,8 @@ def GetConsumersOfResult : TransformDialectOp<"get_consumers_of_result",
The handle defined by this Transform op corresponds to all operations that
consume the SSA value defined by the `target` and `result_number`
arguments.
- This operation applies to a single payload operation, otherwise it
- definitely fails.
+ This operation applies to a single payload operation, otherwise it produces
+ a definite failure.
The return handle points to the consuming operations operations, which can
be empty.
}];
@@ -653,7 +655,8 @@ def GetDefiningOp : TransformDialectOp<"get_defining_op",
The handle defined by this Transform op corresponds to the defining op of
the targeted value.
- This transform fails silently if the targeted value is a block argument.
+ This transform produces a silenceable failure if the targeted value is a
+ block argument.
}];
let arguments = (ins TransformValueHandleTypeInterface:$target);
@@ -676,7 +679,7 @@ def GetParentOp : TransformDialectOp<"get_parent_op",
requirements, is returned.
- `isolated_from_above`: the parent op must be isolated from above
- `allow_empty_results`: get_parent_op is allowed to return an empty list
- and still succeeds. In such a case, if get_parent_op fails for any
+ and still succeeds. In such a case, if `get_parent_op` fails for any
operation in the list, the entire transform returns an empty handle.
- `op_name`: the parent op must have the specified name
- `nth_parent`: get the n-th parent of that satisfies the above requirements
@@ -713,7 +716,7 @@ def GetProducerOfOperand : TransformDialectOp<"get_producer_of_operand",
The handle defined by this Transform op corresponds to operation that
produces the SSA value defined by the `target` and `operand_number`
arguments. If the origin of the SSA value is not an operations (i.e. it is
- a block argument), the transform silently fails.
+ a block argument), the transform produces a silenceable failure.
The return handle points to only the subset of successfully produced
computational operations, which can be empty.
}];
@@ -732,9 +735,10 @@ def GetResultOp : TransformDialectOp<"get_result",
let description = [{
The handle defined by this Transform op corresponds to the OpResult with
`result_number` that is defined by the given `target` operation.
-
- This transform fails silently if the targeted operation does not have enough
- results. It reads the target handle and produces the result handle.
+
+ This transform produces a silenceable failure if the targeted operation
+ does not have enough results. It reads the target handle and produces the
+ result handle.
}];
let arguments = (ins TransformHandleTypeInterface:$target,
@@ -793,7 +797,7 @@ def IncludeOp : TransformDialectOp<"include",
FailurePropagationMode:$failure_propagation_mode,
Variadic<Transform_AnyHandleOrParamType>:$operands);
let results = (outs Variadic<Transform_AnyHandleOrParamType>:$results);
-
+
let assemblyFormat =
"$target `failures` `(` $failure_propagation_mode `)`"
"`(` $operands `)` attr-dict `:` functional-type($operands, $results)";
@@ -926,7 +930,7 @@ def NamedSequenceOp : TransformDialectOp<"named_sequence",
Named sequences may include other named sequences via `transform.include`,
but recursion is *not* allowed.
}];
-
+
let arguments = (ins
SymbolNameAttr:$sym_name,
TypeAttrBase<"::mlir::FunctionType",
@@ -971,10 +975,10 @@ def SplitHandleOp : TransformDialectOp<"split_handle",
let description = [{
Splits `handle` into one or multiple handles, as specified by the number
of results of this operation. `handle` should be mapped to as many payload
- ops as there are results. Otherwise, this transform will fail silently by
- default. Each result handle is mapped to exactly one payload op. The order
- of the payload ops is preserved, i.e., the i-th payload op is mapped to the
- i-th result handle.
+ ops as there are results. Otherwise, this transform will fail produces a
+ silenceable failure by default. Each result handle is mapped to exactly one
+ payload op. The order of the payload ops is preserved, i.e., the i-th
+ payload op is mapped to the i-th result handle.
This operation is useful for ensuring a statically known number of
operations are tracked by the source `handle` and to extract them into
@@ -982,13 +986,14 @@ def SplitHandleOp : TransformDialectOp<"split_handle",
If there are more payload ops than results, the remaining ops are mapped to
the result with index `overflow_result`. If no `overflow_result` is
- specified, the transform fails silently.
-
- If there are fewer payload ops than results, the transform fails silently
- if `fail_on_payload_too_small` is set to "true". Otherwise, it succeeds and
- the remaining result handles are not mapped to any op. It also succeeds if
- `handle` is empty and `pass_through_empty_handle` is set to "true",
- regardless of `fail_on_payload_too_small`.
+ specified, the transform produces a silenceable failure.
+
+ If there are fewer payload ops than results, the transform produces a
+ silenceable failure if `fail_on_payload_too_small` is set to "true".
+ Otherwise, it succeeds and the remaining result handles are not mapped to
+ any op. It also succeeds if `handle` is empty and
+ `pass_through_empty_handle` is set to "true", regardless of
+ `fail_on_payload_too_small`.
}];
let arguments = (ins TransformHandleTypeInterface:$handle,
@@ -1225,7 +1230,7 @@ def VerifyOp : TransformDialectOp<"verify",
let summary = "Verifies the targeted ops";
let description = [{
This transform verifies the targeted ops. If at least one op fails to
- verify, the transform fails definitely.
+ verify, the transform produces a definite failure.
Note: This op was designed for debugging purposes and should be used like an
assertion. It is intentional that this op produces a definite failure and
More information about the Mlir-commits
mailing list