[llvm] 93962ea - [docs][passes] Update documentation of Analysis and Transform Passes (#80835)

[via llvm-commits]

Author: Björn Pettersson
Date: 2024-02-07T08:57:14+01:00
New Revision: 93962ea1176b91239496378e7141a44dc95a5efd

URL: https://github.com/llvm/llvm-project/commit/93962ea1176b91239496378e7141a44dc95a5efd
DIFF: https://github.com/llvm/llvm-project/commit/93962ea1176b91239496378e7141a44dc95a5efd.diff

LOG: [docs][passes] Update documentation of Analysis and Transform Passes (#80835)

- Added a warning about the pass list being incomplete (and hint about
"opt -print-passes" listing known passes).
- Removed legacy PM example involving "opt -analyze".
- print-function and print-module does not exist with those names in the
new PM. Since the document has been updated to reflect the new PM names
earlier, those names were changed into referring to function(print) and
module(print) instead.
- Resolved some FIXME:s around strip* passes.

Added: 
    

Modified: 
    llvm/docs/Passes.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/Passes.rst b/llvm/docs/Passes.rst
index 0d0353ed6b611b..2edad5cd3c881a 100644
--- a/llvm/docs/Passes.rst
+++ b/llvm/docs/Passes.rst
@@ -7,6 +7,9 @@ LLVM's Analysis and Transform Passes
 
 Introduction
 ============
+.. warning:: This document is not updated frequently, and the list of passes
+  is most likely incomplete. It is possible to list passes known by the opt
+  tool using ``opt -print-passes``.
 
 This document serves as a high level summary of the optimization features that
 LLVM provides.  Optimizations are implemented as Passes that traverse some
@@ -193,15 +196,12 @@ memory operations it depends on.  It builds on alias analysis information, and
 tries to provide a lazy, caching interface to a common kind of alias
 information query.
 
-``module-debuginfo``: Decodes module-level debug info
------------------------------------------------------
+``print<module-debuginfo>``: Decodes module-level debug info
+------------------------------------------------------------
 
-This pass decodes the debug info metadata in a module and prints in a
+This pass decodes the debug info metadata in a module and prints it to standard output in a
 (sufficiently-prepared-) human-readable form.
 
-For example, run this pass from ``opt`` along with the ``-analyze`` option, and
-it'll print to standard output.
-
 ``postdomtree``: Post-Dominator Tree Construction
 -------------------------------------------------
 
@@ -228,18 +228,18 @@ standard error in a human-readable form.
 ``print-cfg-sccs``: Print SCCs of each function CFG
 ---------------------------------------------------
 
-This pass, only available in ``opt``, printsthe SCCs of each function CFG to
+This pass, only available in ``opt``, prints the SCCs of each function CFG to
 standard error in a human-readable fom.
 
-``print-function``: Print function to stderr
---------------------------------------------
+``function(print)``: Print function to stderr
+---------------------------------------------
 
 The ``PrintFunctionPass`` class is designed to be pipelined with other
 ``FunctionPasses``, and prints out the functions of the module as they are
 processed.
 
-``print-module``: Print module to stderr
-----------------------------------------
+``module(print)``: Print module to stderr
+-----------------------------------------
 
 This pass simply prints out the entire module when it is executed.
 
@@ -924,17 +924,8 @@ code size or making it harder to reverse engineer code.
 ``strip-dead-debug-info``: Strip debug info for unused symbols
 --------------------------------------------------------------
 
-.. FIXME: this description is the same as for -strip
-
-performs code stripping. this transformation can delete:
-
-* names for virtual registers
-* symbols for internal globals and functions
-* debug information
-
-note that this transformation makes code much less readable, so it should only
-be used in situations where the strip utility would be used, such as reducing
-code size or making it harder to reverse engineer code.
+Performs code stripping. Similar to strip, but only strips debug info for
+unused symbols.
 
 ``strip-dead-prototypes``: Strip Unused Function Prototypes
 -----------------------------------------------------------
@@ -947,32 +938,13 @@ functions).
 ``strip-debug-declare``: Strip all ``llvm.dbg.declare`` intrinsics
 ------------------------------------------------------------------
 
-.. FIXME: this description is the same as for -strip
-
-This pass implements code stripping.  Specifically, it can delete:
-
-#. names for virtual registers
-#. symbols for internal globals and functions
-#. debug information
-
-Note that this transformation makes code much less readable, so it should only
-be used in situations where the 'strip' utility would be used, such as reducing
-code size or making it harder to reverse engineer code.
+Performs code stripping. Similar to strip, but only strips
+``llvm.dbg.declare`` intrinsics.
 
 ``strip-nondebug``: Strip all symbols, except dbg symbols, from a module
 ------------------------------------------------------------------------
 
-.. FIXME: this description is the same as for -strip
-
-This pass implements code stripping.  Specifically, it can delete:
-
-#. names for virtual registers
-#. symbols for internal globals and functions
-#. debug information
-
-Note that this transformation makes code much less readable, so it should only
-be used in situations where the 'strip' utility would be used, such as reducing
-code size or making it harder to reverse engineer code.
+Performs code stripping. Similar to strip, but dbg info is preserved.
 
 ``tailcallelim``: Tail Call Elimination
 ---------------------------------------