diff --git a/mlir/include/mlir/Transforms/Passes.td b/mlir/include/mlir/Transforms/Passes.td --- a/mlir/include/mlir/Transforms/Passes.td +++ b/mlir/include/mlir/Transforms/Passes.td @@ -104,11 +104,23 @@ 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 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, different 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 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()"; }