improve docs

Author: fabianmcg

mlir/include/mlir/Dialect/MemRef/IR/MemRefOps.td

@@ -1288,7 +1288,7 @@ def LoadOp : MemRef_Op<"load",
 def MemRef_MemorySpaceCastOp : MemRef_Op<"memory_space_cast", [
       DeclareOpInterfaceMethods<CastOpInterface>,
       DeclareOpInterfaceMethods<OpAsmOpInterface, ["getAsmResultNames"]>,
-      DeclareOpInterfaceMethods<MemorySpaceCastOpInterface>,
+      MemorySpaceCastOpInterface,
       MemRefsNormalizable,
       Pure,
       SameOperandsAndResultElementType,
@@ -1326,6 +1326,27 @@ def MemRef_MemorySpaceCastOp : MemRef_Op<"memory_space_cast", [
 
   let extraClassDeclaration = [{
     Value getViewSource() { return getSource(); }
+
+    //===------------------------------------------------------------------===//
+    // MemorySpaceCastConsumerOpInterface
+    //===------------------------------------------------------------------===//
+    /// Returns the `source` memref.
+    TypedValue<PtrLikeTypeInterface> getSourcePtr();
+    /// Returns the `dest` memref.
+    TypedValue<PtrLikeTypeInterface> getTargetPtr();
+    /// Returns whether the memory-space cast is valid. Only casts between
+    /// memrefs are considered valid. Further, the `tgt` and `src` should only
+    /// differ on the memory-space parameter of the memref type.
+    bool isValidMemorySpaceCast(PtrLikeTypeInterface tgt,
+                                PtrLikeTypeInterface src);
+    /// Clones the operation using a new target type and source value.
+    MemorySpaceCastOpInterface cloneMemorySpaceCastOp(
+        OpBuilder &b, PtrLikeTypeInterface tgt,
+        TypedValue<PtrLikeTypeInterface> src);
+    /// Returns whether the `source` value can be promoted by the
+    /// `MemorySpaceCastConsumerOpInterface::bubbleDownCasts` method. The only
+    /// casts the op recognizes as promotable are to the generic memory-space.
+    bool isSourcePromotable();
   }];
 
   let hasFolder = 1;

mlir/include/mlir/Interfaces/MemOpInterfaces.td

@@ -14,13 +14,15 @@
 #define MLIR_INTERFACES_MEMOPINTERFACES_TD
 
 include "mlir/IR/OpBase.td"
-include "mlir/Interfaces/SideEffectInterfaces.td"
 
 def MemorySpaceCastConsumerOpInterface :
     OpInterface<"MemorySpaceCastConsumerOpInterface"> {
   let description = [{
     An interface for operations that can consume memory-space cast-like
     operations.
+
+    This interface can be used to bubble-down memory-space cast operations,
+    see the `bubble-down-memory-space-casts` pass for an example.
   }];
   let cppNamespace = "::mlir";
   let methods = [
@@ -59,6 +61,10 @@ def MemorySpaceCastOpInterface : OpInterface<"MemorySpaceCastOpInterface"> {
 
     These operations expect to have a well-defined ptr-like operand, and
     a well-defined target ptr-like result.
+
+    This interface also allows to determine whether a cast can be bubbled-down
+    by the `MemorySpaceCastConsumerOpInterface`, allowing control over which
+    casts can be bubbled-down or not.
   }];
   let cppNamespace = "::mlir";
   let methods = [
@@ -91,14 +97,16 @@ def MemorySpaceCastOpInterface : OpInterface<"MemorySpaceCastOpInterface"> {
         Returns whether the source pointer of the memory-space cast can be used
         by the `MemorySpaceCastConsumerOpInterface::bubbleDownCasts` method to
         promote the source pointer and bubble down the cast.
+
+        For example, a cast operation might decide that all casts to the generic
+        memory-space can be promoted. 
       }],
       "bool", "isSourcePromotable"
     >
   ];
   let verify = [{
     return ::mlir::detail::verifyMemorySpaceCastOpInterface($_op);
   }];
-  let dependentTraits = [Pure];
   let extraClassDeclaration = [{
     /// Returns the underlying `MemorySpaceCastOpInterface` op if `value`
     /// is produced by a `MemorySpaceCastOpInterface` op, and

mlir/include/mlir/Transforms/Passes.td

@@ -590,8 +590,12 @@ def BubbleDownMemorySpaceCasts :
   let summary = "Bubbles down memory-space cast operations.";
   let description = [{
     This pass tries to iteratively bubble down all possible memory-space cast
-    operations. It does this by looking for `MemorySpaceCastConsumerOpInterface`
-    operations, and invoking the interface methods to perform the bubbling down.
+    operations. It is important to note that the determination of which casts
+    are bubbled down is based on the interfaces
+    `MemorySpaceCastConsumerOpInterface`, and `MemorySpaceCastOpInterface`, and
+    not the pass. The pass only looks for operations implementing the
+    `MemorySpaceCastConsumerOpInterface` interface, and invoking the interface
+    methods to perform the bubbling down.
 
     Example: