[docs][NewPM] Move pass plugin documentation into existing new PM docs

[awarzynski]

Thanks for all the effort @aeubanks ! Left some comments inline.

llvm/docs/WritingAnLLVMNewPMPass.rst

239–240

To me, "automatic pass registration" equals "static registration". However, IIUC, this is meant to cover both "static" and "dynamic" registration. And the first sentence here suggests that only static/automatic registration is covered.

256

257

262

Can you elaborate a bit? This isn't needed for Bye, is it? So when would it be needed?

[Meinersbur]

llvm/docs/WritingAnLLVMNewPMPass.rst

262

"Bye" is already included in llvm/Support/Extension.def (if enabled in CMake configuration).

This needed is when you want to write a tool (like opt, bugpoint, ...) that uses the NPM pipeline builder to automatically add pass-extension plugins (such as "Bye") when creating an O1/O2/... pipeline (in addition to a the pre-registered set of passes). I.e. that does not just happen automatically if the tool itself does not add code for it.

[aeubanks]

address comments

[aeubanks]

fix awkward wording

llvm/docs/WritingAnLLVMNewPMPass.rst

239–240

better?

262

clearer now?

[awarzynski]

Thanks for addressing my comments @aeubanks , LGTM!

[asbirlea]

Thank you for adding this!

llvm/docs/NewPassManager.rst

 backend to inject passes into the pipeline. This is equivalent to the legacy
 PM's ``TargetMachine::adjustPassManager()``.
 
 Clang's ``BackendUtil.cpp`` shows examples of a frontend adding (mostly
 sanitizer) passes to various parts of the pipeline.
 ``AMDGPUTargetMachine::registerPassBuilderCallbacks()`` is an example of a
 backend adding passes to various parts of the pipeline.
 
+Pass plugins can also add passes into default pipelines. Different tools have
+different ways of loading dynamic pass plugins. For example, ``opt
+-load-pass-plugin=path/to/plugin.so`` loads a pass plugin into ``opt``. For
+information on writing a pass plugin, see :doc:`WritingAnLLVMNewPMPass`.
+
 Using Analyses
 ==============
 
 LLVM provides many analyses that passes can use, such as a dominator tree.
 Calculating these can be expensive, so the new pass manager has
 infrastructure to cache analyses and reuse them when possible.
 
 When a pass runs on some IR, it also receives an analysis manager which it can

llvm/docs/WritingAnLLVMNewPMPass.rst

 other required passes.
 
 An example of how a pass can be skipped is the ``optnone`` function
 attribute, which specifies that optimizations should not be run on the
 function. Required passes will still be run on ``optnone`` functions.
 
 For more implementation details, see
 ``PassInstrumentation::runBeforePass()``.
+
+Registering passes as plugins
+-----------------------------
+
+LLVM provides a mechanism to register pass plugins within various tools like
+``clang`` or ``opt``. A pass plugin can add passes to default optimization
+pipelines or to be manually run via tools like ``opt``.  For more information,
+see :doc:`NewPassManager`.
+
+Create a CMake project at the root of the repo alongside
+other projects.  This project must contain the following minimal
+``CMakeLists.txt``:
+
+.. code-block:: cmake
+
+    add_llvm_pass_plugin(MyPassName source.cpp)
+
+See the definition of ``add_llvm_pass_plugin`` for more CMake details.
+
+The pass must provide at least one of two entry points for the new pass manager,
+one for static registration and one for dynamically loaded plugins:
+
+- ``llvm::PassPluginLibraryInfo get##Name##PluginInfo();``
+- ``extern "C" ::llvm::PassPluginLibraryInfo llvmGetPassPluginInfo() LLVM_ATTRIBUTE_WEAK;``
+
+Pass plugins are compiled and linked dynamically by default. Setting
+``LLVM_${NAME}_LINK_INTO_TOOLS`` to ``ON`` turns the project into a statically
+linked extension.
+
+For an in-tree example, see ``llvm/examples/Bye/``.
+
+To make ``PassBuilder`` aware of statically linked pass plugins:
+
+.. code-block:: c++
+
+    // Declare plugin extension function declarations.
+    #define HANDLE_EXTENSION(Ext) llvm::PassPluginLibraryInfo get##Ext##PluginInfo();
+    #include "llvm/Support/Extension.def"
+
+    ...
+
+    // Register plugin extensions in PassBuilder.
+    #define HANDLE_EXTENSION(Ext) get##Ext##PluginInfo().RegisterPassBuilderCallbacks(PB);
+    #include "llvm/Support/Extension.def"
+
+To make ``PassBuilder`` aware of dynamically linked pass plugins:
+
+.. code-block:: c++
+
+    // Load plugin dynamically.
+    auto Plugin = PassPlugin::Load(PathToPlugin);
+    if (!Plugin)
+      report_error();
+    // Register plugin extensions in PassBuilder.
+    Plugin.registerPassBuilderCallbacks(PB);

llvm/docs/WritingAnLLVMPass.rst

 
 If you are writing an analysis or any other pass that retains a significant
 amount of state (for use by another pass which "requires" your pass and uses
 the :ref:`getAnalysis <writing-an-llvm-pass-getAnalysis>` method) you should
 implement ``releaseMemory`` to, well, release the memory allocated to maintain
 this internal state.  This method is called after the ``run*`` method for the
 class, before the next call of ``run*`` in your pass.
 
-Building pass plugins
-=====================
-
-As an alternative to using ``PLUGIN_TOOL``, LLVM provides a mechanism to
-automatically register pass plugins within ``clang``, ``opt`` and ``bugpoint``.
-One first needs to create an independent project and add it to either ``tools/``
-or, using the MonoRepo layout, at the root of the repo alongside other projects.
-This project must contain the following minimal ``CMakeLists.txt``:
-
-.. code-block:: cmake
-
-    add_llvm_pass_plugin(Name source0.cpp)
-
-The pass must provide two entry points for the new pass manager, one for static
-registration and one for dynamically loaded plugins:
-
-- ``llvm::PassPluginLibraryInfo get##Name##PluginInfo();``
-- ``extern "C" ::llvm::PassPluginLibraryInfo llvmGetPassPluginInfo() LLVM_ATTRIBUTE_WEAK;``
-
-Pass plugins are compiled and link dynamically by default, but it's
-possible to set the following variables to change this behavior:
-
-- ``LLVM_${NAME}_LINK_INTO_TOOLS``, when set to ``ON``, turns the project into
-  a statically linked extension
-
-
-When building a tool that uses the new pass manager, one can use the following snippet to
-include statically linked pass plugins:
-
-.. code-block:: c++
-
-    // fetch the declaration
-    #define HANDLE_EXTENSION(Ext) llvm::PassPluginLibraryInfo get##Ext##PluginInfo();
-    #include "llvm/Support/Extension.def"
-
-    [...]
-
-    // use them, PB is an llvm::PassBuilder instance
-    #define HANDLE_EXTENSION(Ext) get##Ext##PluginInfo().RegisterPassBuilderCallbacks(PB);
-    #include "llvm/Support/Extension.def"
-
-
-
-
-
 Registering dynamically loaded passes
 =====================================
 
 *Size matters* when constructing production quality tools using LLVM, both for
 the purposes of distribution, and for regulating the resident code size when
 running on the target system.  Therefore, it becomes desirable to selectively
 use some passes, while omitting others and maintain the flexibility to change
 configurations later on.  You want to be able to do all this, and, provide