[docs] Try to make it easier to find info about new PM vs legacy PM (#80834)

Seen several beginner questions popping up in discourse about how to
implement and run custom passes. And then it turns out that they are
following the old "Writing an LLVM Pass" guide that describe legacy
passes, and then things are mixed up when they try to run that pass
using opt that nowadays default to the new pass manager.

This is an attempt to make it slightly clearer in the User Guides that
there are two different "Writing an LLVM Pass" pages depending on which
pass manager that should be used. This is done by renaming the legacy
version of "Writing an LLVM Pass" as "Writing an LLVM Pass (legacy PM
version)".
Also reordered the links to put the link to the new pass manager
documentation first.

This patch also moves the warning text that cross references the
description on how to write a pass for legacy/new PM to make sure it
ends up already in the beginning of the descriptions.

Also adding a new warning in the "Running a pass with opt" section of
the legacy PM version of the guide, to inform that those examples are
outdated.

llvm/docs/UserGuides.rst

@@ -123,13 +123,14 @@ LLVM Builds and Distributions
 Optimizations
 -------------
 
-:doc:`WritingAnLLVMPass`
-   Information on how to write LLVM transformations and analyses.
-
 :doc:`WritingAnLLVMNewPMPass`
    Information on how to write LLVM transformations under the new pass
    manager.
 
+:doc:`WritingAnLLVMPass`
+   Information on how to write LLVM transformations and analyses under the
+   legacy pass manager.
+
 :doc:`Passes`
    A list of optimizations and analyses implemented in LLVM.
 

llvm/docs/WritingAnLLVMNewPMPass.rst

@@ -10,6 +10,11 @@ Writing an LLVM Pass
 Introduction --- What is a pass?
 ================================
 
+.. warning::
+  This document deals with the new pass manager. LLVM uses the legacy pass
+  manager for the codegen pipeline. For more details, see
+  :doc:`WritingAnLLVMPass` and :doc:`NewPassManager`.
+
 The LLVM pass framework is an important part of the LLVM system, because LLVM
 passes are where most of the interesting parts of the compiler exist. Passes
 perform the transformations and optimizations that make up the compiler, they
@@ -29,11 +34,6 @@ We start by showing you how to construct a pass, from setting up the build,
 creating the pass, to executing and testing it. Looking at existing passes is
 always a great way to learn details.
 
-.. warning::
-  This document deals with the new pass manager. LLVM uses the legacy pass
-  manager for the codegen pipeline. For more details, see
-  :doc:`WritingAnLLVMPass` and :doc:`NewPassManager`.
-
 Quick Start --- Writing hello world
 ===================================
 

llvm/docs/WritingAnLLVMPass.rst

@@ -1,6 +1,6 @@
-====================
-Writing an LLVM Pass
-====================
+========================================
+Writing an LLVM Pass (legacy PM version)
+========================================
 
 .. program:: opt
 
@@ -10,6 +10,13 @@ Writing an LLVM Pass
 Introduction --- What is a pass?
 ================================
 
+.. warning::
+  This document deals with the legacy pass manager. LLVM uses the new pass
+  manager for the optimization pipeline (the codegen pipeline
+  still uses the legacy pass manager), which has its own way of defining
+  passes. For more details, see :doc:`WritingAnLLVMNewPMPass` and
+  :doc:`NewPassManager`.
+
 The LLVM Pass Framework is an important part of the LLVM system, because LLVM
 passes are where most of the interesting parts of the compiler exist.  Passes
 perform the transformations and optimizations that make up the compiler, they
@@ -34,13 +41,6 @@ We start by showing you how to construct a pass, everything from setting up the
 code, to compiling, loading, and executing it.  After the basics are down, more
 advanced features are discussed.
 
-.. warning::
-  This document deals with the legacy pass manager. LLVM uses the new pass
-  manager for the optimization pipeline (the codegen pipeline
-  still uses the legacy pass manager), which has its own way of defining
-  passes. For more details, see :doc:`WritingAnLLVMNewPMPass` and
-  :doc:`NewPassManager`.
-
 Quick Start --- Writing hello world
 ===================================
 
@@ -224,6 +224,13 @@ can have them) to be useful.
 Running a pass with ``opt``
 ---------------------------
 
+.. warning::
+  This document deals with the legacy pass manager. The :program:`opt` tool no
+  longer supports running legacy passes (except for certain hardcoded backend
+  passes and when using bugpoint). So the examples below for loading and
+  running legacy passes using :program:`opt` are deprecated and no longer
+  guaranteed to work.
+
 Now that you have a brand new shiny shared object file, we can use the
 :program:`opt` command to run an LLVM program through your pass.  Because you
 registered your pass with ``RegisterPass``, you will be able to use the