[Mlir-commits] [mlir] 8a49ed2 - [mlir][Transforms][docs] Add a description blurb for various passes

[River Riddle]

Author: River Riddle
Date: 2020-04-13T11:28:03-07:00
New Revision: 8a49ed21333fd37b74e67ffc9f82ba40398af560

URL: https://github.com/llvm/llvm-project/commit/8a49ed21333fd37b74e67ffc9f82ba40398af560
DIFF: https://github.com/llvm/llvm-project/commit/8a49ed21333fd37b74e67ffc9f82ba40398af560.diff

LOG: [mlir][Transforms][docs] Add a description blurb for various passes

Summary: This revision adds blurbs of documentation to various different passes, namely: Canonicalizer, CSE, LocationSnapshot, StripDebugInfo, and SymbolDCE.

Differential Revision: https://reviews.llvm.org/D78007

Added: 
    

Modified: 
    mlir/include/mlir/Transforms/Passes.td

Removed: 
    


################################################################################
diff  --git a/mlir/include/mlir/Transforms/Passes.td b/mlir/include/mlir/Transforms/Passes.td
index 70b8f8113703..e9cace9688aa 100644
--- a/mlir/include/mlir/Transforms/Passes.td
+++ b/mlir/include/mlir/Transforms/Passes.td
@@ -104,11 +104,23 @@ def AffinePipelineDataTransfer
 
 def Canonicalizer : Pass<"canonicalize"> {
   let summary = "Canonicalize operations";
+  let description = [{
+    This pass performs various types of canonicalizations over a set of
+    operations. See [Operation Canonicalization](Canonicalization.md) for more
+    details.
+  }];
   let constructor = "mlir::createCanonicalizerPass()";
 }
 
 def CSE : Pass<"cse"> {
   let summary = "Eliminate common sub-expressions";
+  let description = [{
+    This pass implements a generalized algorithm for common sub-expression
+    elimination. This pass relies on information provided by the
+    `Memory SideEffect` interface to identify when it is safe to eliminate
+    operations. See [Common subexpression elimination](https://en.wikipedia.org/wiki/Common_subexpression_elimination)
+    for more general details on this optimization.
+  }];
   let constructor = "mlir::createCSEPass()";
   let statistics = [
     Statistic<"numCSE", "num-cse'd", "Number of operations CSE'd">,
@@ -131,6 +143,39 @@ def Inliner : Pass<"inline"> {
 
 def LocationSnapshot : Pass<"snapshot-op-locations"> {
   let summary = "Generate new locations from the current IR";
+  let description = [{
+    This pass allows for generating new locations from the IR during any stage
+    of compilation, by snapshotting the IR to a file and using that file to
+    generate new locations for the operations.
+
+    Depending on the value of the `tag` option, 
diff erent resulting locations
+    may be generated:
+
+    * If unset, the original location of the operation is replaced.
+
+    Example:
+
+    ```mlir
+    // old:
+    ... loc("original_source.cpp":1:1)
+
+    // new:
+    ... loc("snapshot_source.mlir":10:10)
+    ```
+
+    * If set, the new location is fused with the original location in the form
+    of a [`Name Location`](Diagnostics.md#name-location) with the specified tag.
+
+    Example:
+
+    ```mlir
+    // old:
+    ... loc("original_source.cpp":1:1)
+
+    // new:
+    ... loc(fused["original_source.cpp":1:1, "snapshot"("snapshot_source.mlir":10:10)])
+    ```
+  }];
   let constructor = "mlir::createLocationSnapshotPass()";
   let options = [
     Option<"fileName", "filename", "std::string", /*default=*/"",
@@ -230,11 +275,53 @@ def PrintOp : Pass<"print-op-graph", "ModuleOp"> {
 
 def StripDebugInfo : Pass<"strip-debuginfo"> {
   let summary = "Strip debug info from all operations";
+  let description = [{
+    This pass strips the IR of any location information, by replacing all
+    operation locations with [`unknown`](Diagnostics.md#unknown-location).
+  }];
   let constructor = "mlir::createStripDebugInfoPass()";
 }
 
 def SymbolDCE : Pass<"symbol-dce"> {
   let summary = "Eliminate dead symbols";
+  let description = [{
+    This pass deletes all symbols that are found to be unreachable. This is done
+    by computing the set of operations that are known to be live, propagating
+    that liveness to other symbols, and then deleting all symbols that are not
+    within this live set. Live symbols are those that have a
+    [visibility](SymbolsAndSymbolTables.md#symbol-visibility) that extends
+    beyond the IR, e.g. `public`, or those that are referenced by live symbols
+    or other non-Symbol operations.
+
+    For example, consider the following input:
+
+    ```mlir
+    func @dead_private_function() attributes { sym_visibility = "private" }
+    func @live_private_function() attributes { sym_visibility = "private" }
+
+    // Note: The `public` isn't necessary here, as this is the default.
+    func @public_function() attributes { sym_visibility = "public" } {
+      "foo.return"() {uses = [@live_private_function]} : () -> ()
+    }
+    ```
+
+    A known live function, `public_function`, contains a reference to an
+    otherwise non-live function `live_private_function`. After running
+    `symbol-dce`, only these two symbols should remain, as the final symbol
+    `dead_private_function` is not visible outside of the current IR and there
+    are no links to known-live operations. After running, we get the expected:
+
+    ```mlir
+    func @live_private_function() attributes { sym_visibility = "private" }
+
+    func @public_function() attributes { sym_visibility = "public" } {
+      "foo.return"() {uses = [@live_private_function]} : () -> ()
+    }
+    ```
+
+    See [Symbols and SymbolTables](SymbolsAndSymbolTables.md) for more
+    information on `Symbols`.
+  }];
   let constructor = "mlir::createSymbolDCEPass()";
 }