From 55b95a7a75ec4568d6ee7a3199090e830619c68e Mon Sep 17 00:00:00 2001 From: Matthias Springer Date: Sat, 6 Jul 2024 12:05:00 +0200 Subject: [mlir][Transforms][NFC] Dialect conversion: Reland docs improvement (#97886) #96207 was reverted but the improvements to the documentation of the dialect conversion are still useful. --- mlir/docs/DialectConversion.md | 45 ++++++++++++++++-------- mlir/include/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 69781bb..db26e64 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(std::forward(callback))); } - /// Register a materialization function, which must be convertible to the - /// following form: - /// `Optional (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(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 ::template arg_t<1>> void addArgumentMaterialization(FnT &&callback) { argumentMaterializations.emplace_back( wrapMaterialization(std::forward(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 ::template arg_t<1>> void addSourceMaterialization(FnT &&callback) { sourceMaterializations.emplace_back( wrapMaterialization(std::forward(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 ::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 f83f3a3..a22f198 100644 --- a/mlir/include/mlir/Transforms/DialectConversion.h +++ b/mlir/include/mlir/Transforms/DialectConversion.h @@ -168,8 +168,8 @@ public: registerConversion(wrapCallback(std::forward(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(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 @@ public: /// 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 >::template arg_t<1>> void addArgumentMaterialization(FnT &&callback) { argumentMaterializations.emplace_back( wrapMaterialization(std::forward(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 >::template arg_t<1>> void addSourceMaterialization(FnT &&callback) { sourceMaterializations.emplace_back( wrapMaterialization(std::forward(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 >::template arg_t<1>> void addTargetMaterialization(FnT &&callback) { -- cgit v1.1