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

Tue Feb 6 13:25:30 PST 2024

https://github.com/bjope updated https://github.com/llvm/llvm-project/pull/80835

>From 000c5d9a83acd31537661e4a201c9694724fbe4f Mon Sep 17 00:00:00 2001
From: Bjorn Pettersson <bjorn.a.pettersson at ericsson.com>
Date: Wed, 31 Jan 2024 17:44:40 +0100
Subject: [PATCH 1/2] [docs][passes] Update documentation of Analysis and
 Transform Passes

- Added a warning about the pass list being incomplete (and hint about
  "opt -print-passes" listing known passes).
- Replaced legacy PM example involving "opt -analyze" with a proper
  example using -passes option.
- 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.
---
 llvm/docs/Passes.rst | 60 +++++++++++++-------------------------------
 1 file changed, 18 insertions(+), 42 deletions(-)

diff --git a/llvm/docs/Passes.rst b/llvm/docs/Passes.rst
index 0d0353ed6b611b..9bd31b60f5cb17 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,14 +196,15 @@ 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
 (sufficiently-prepared-) human-readable form.
 
-For example, run this pass from ``opt`` along with the ``-analyze`` option, and
-it'll print to standard output.
+For example, run this pass from ``opt`` along with the
+``-passes='print<module-debuginfo>'`` option, and it'll print to standard
+output.
 
 ``postdomtree``: Post-Dominator Tree Construction
 -------------------------------------------------
@@ -228,18 +232,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 +928,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 +942,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
 ---------------------------------------

>From a7deb3f8251b04306e3dc081edd10d86f453c26c Mon Sep 17 00:00:00 2001
From: Bjorn Pettersson <bjorn.a.pettersson at ericsson.com>
Date: Tue, 6 Feb 2024 22:24:59 +0100
Subject: [PATCH 2/2] fixup print<module-debuginfo> description after review
 feedback

---
 llvm/docs/Passes.rst | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/llvm/docs/Passes.rst b/llvm/docs/Passes.rst
index 9bd31b60f5cb17..2edad5cd3c881a 100644
--- a/llvm/docs/Passes.rst
+++ b/llvm/docs/Passes.rst
@@ -199,13 +199,9 @@ information query.
 ``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
-``-passes='print<module-debuginfo>'`` option, and it'll print to standard
-output.
-
 ``postdomtree``: Post-Dominator Tree Construction
 -------------------------------------------------
 

