[Mlir-commits] [mlir] [mlir][Transforms][NFC] Dialect conversion: Reland docs improvement (PR #97886)
Matthias Springer
llvmlistbot at llvm.org
Sat Jul 6 03:04:50 PDT 2024
https://github.com/matthias-springer created https://github.com/llvm/llvm-project/pull/97886
#96207 was reverted but the improvements to the documentation of the dialect conversion are still useful.
>From d22ab66e8d35d68216981fb71e56d0eed60d220b Mon Sep 17 00:00:00 2001
From: Matthias Springer <mspringer at nvidia.com>
Date: Sat, 6 Jul 2024 12:02:41 +0200
Subject: [PATCH] [mlir][Transforms][NFC] Dialect conversion: Reland docs
improvement
96207 was reverted but the improvements to the documentation of the dialect conversion are still useful.
---
mlir/docs/DialectConversion.md | 45 ++++++++++++-------
.../mlir/Transforms/DialectConversion.h | 18 +++++---
2 files changed, 41 insertions(+), 22 deletions(-)
diff --git a/mlir/docs/DialectConversion.md b/mlir/docs/DialectConversion.md
index 69781bb868bbf..db26e6477d5fc 100644
--- a/mlir/docs/DialectConversion.md
+++ b/mlir/docs/DialectConversion.md
@@ -246,6 +246,13 @@ depending on the situation.
- An argument materialization is used when converting the type of a block
argument during a [signature conversion](#region-signature-conversion).
+ The new block argument types are specified in a `SignatureConversion`
+ object. An original block argument can be converted into multiple
+ block arguments, which is not supported everywhere in the dialect
+ conversion. (E.g., adaptors support only a single replacement value for
+ each original value.) Therefore, an argument materialization is used to
+ convert potentially multiple new block arguments back into a single SSA
+ value.
* Source Materialization
@@ -259,6 +266,9 @@ depending on the situation.
* When a block argument has been converted to a different type, but
the original argument still has users that will remain live after
the conversion process has finished.
+ * When a block argument has been dropped, but the argument still has
+ users that will remain live after the conversion process has
+ finished.
* When the result type of an operation has been converted to a
different type, but the original result still has users that will
remain live after the conversion process is finished.
@@ -328,36 +338,41 @@ class TypeConverter {
registerConversion(wrapCallback<T>(std::forward<FnT>(callback)));
}
- /// Register a materialization function, which must be convertible to the
- /// following form:
- /// `Optional<Value> (OpBuilder &, T, ValueRange, Location)`,
- /// where `T` is any subclass of `Type`.
- /// This function is responsible for creating an operation, using the
- /// OpBuilder and Location provided, that "converts" a range of values into a
- /// single value of the given type `T`. It must return a Value of the
- /// converted type on success, an `std::nullopt` if it failed but other
- /// materialization can be attempted, and `nullptr` on unrecoverable failure.
- /// It will only be called for (sub)types of `T`.
- ///
+ /// All of the following materializations require function objects that are
+ /// convertible to the following form:
+ /// `std::optional<Value>(OpBuilder &, T, ValueRange, Location)`,
+ /// where `T` is any subclass of `Type`. This function is responsible for
+ /// creating an operation, using the OpBuilder and Location provided, that
+ /// "casts" a range of values into a single value of the given type `T`. It
+ /// must return a Value of the converted type on success, an `std::nullopt` if
+ /// it failed but other materialization can be attempted, and `nullptr` on
+ /// unrecoverable failure. It will only be called for (sub)types of `T`.
+ /// Materialization functions must be provided when a type conversion may
+ /// persist after the conversion has finished.
+
/// This method registers a materialization that will be called when
- /// converting an illegal block argument type, to a legal type.
+ /// converting (potentially multiple) block arguments that were the result of
+ /// a signature conversion of a single block argument, to a single SSA value.
template <typename FnT,
typename T = typename llvm::function_traits<FnT>::template arg_t<1>>
void addArgumentMaterialization(FnT &&callback) {
argumentMaterializations.emplace_back(
wrapMaterialization<T>(std::forward<FnT>(callback)));
}
+
/// This method registers a materialization that will be called when
- /// converting a legal type to an illegal source type. This is used when
- /// conversions to an illegal type must persist beyond the main conversion.
+ /// converting a legal replacement value back to an illegal source type.
+ /// This is used when some uses of the original, illegal value must persist
+ /// beyond the main conversion.
template <typename FnT,
typename T = typename llvm::function_traits<FnT>::template arg_t<1>>
void addSourceMaterialization(FnT &&callback) {
sourceMaterializations.emplace_back(
wrapMaterialization<T>(std::forward<FnT>(callback)));
}
+
/// This method registers a materialization that will be called when
- /// converting type from an illegal, or source, type to a legal type.
+ /// converting an illegal (source) value to a legal (target) type.
template <typename FnT,
typename T = typename llvm::function_traits<FnT>::template arg_t<1>>
void addTargetMaterialization(FnT &&callback) {
diff --git a/mlir/include/mlir/Transforms/DialectConversion.h b/mlir/include/mlir/Transforms/DialectConversion.h
index f83f3a3fdf992..a22f198bdf252 100644
--- a/mlir/include/mlir/Transforms/DialectConversion.h
+++ b/mlir/include/mlir/Transforms/DialectConversion.h
@@ -168,8 +168,8 @@ class TypeConverter {
registerConversion(wrapCallback<T>(std::forward<FnT>(callback)));
}
- /// Register a materialization function, which must be convertible to the
- /// following form:
+ /// All of the following materializations require function objects that are
+ /// convertible to the following form:
/// `std::optional<Value>(OpBuilder &, T, ValueRange, Location)`,
/// where `T` is any subclass of `Type`. This function is responsible for
/// creating an operation, using the OpBuilder and Location provided, that
@@ -179,26 +179,30 @@ class TypeConverter {
/// unrecoverable failure. It will only be called for (sub)types of `T`.
/// Materialization functions must be provided when a type conversion may
/// persist after the conversion has finished.
- ///
+
/// This method registers a materialization that will be called when
- /// converting an illegal block argument type, to a legal type.
+ /// converting (potentially multiple) block arguments that were the result of
+ /// a signature conversion of a single block argument, to a single SSA value.
template <typename FnT, typename T = typename llvm::function_traits<
std::decay_t<FnT>>::template arg_t<1>>
void addArgumentMaterialization(FnT &&callback) {
argumentMaterializations.emplace_back(
wrapMaterialization<T>(std::forward<FnT>(callback)));
}
+
/// This method registers a materialization that will be called when
- /// converting a legal type to an illegal source type. This is used when
- /// conversions to an illegal type must persist beyond the main conversion.
+ /// converting a legal replacement value back to an illegal source type.
+ /// This is used when some uses of the original, illegal value must persist
+ /// beyond the main conversion.
template <typename FnT, typename T = typename llvm::function_traits<
std::decay_t<FnT>>::template arg_t<1>>
void addSourceMaterialization(FnT &&callback) {
sourceMaterializations.emplace_back(
wrapMaterialization<T>(std::forward<FnT>(callback)));
}
+
/// This method registers a materialization that will be called when
- /// converting type from an illegal, or source, type to a legal type.
+ /// converting an illegal (source) value to a legal (target) type.
template <typename FnT, typename T = typename llvm::function_traits<
std::decay_t<FnT>>::template arg_t<1>>
void addTargetMaterialization(FnT &&callback) {
More information about the Mlir-commits
mailing list