[docs][NewPM] Add some instructions on how to invoke opt

[aeubanks]

Summary

Also add link to blog post.

[nickdesaulniers]

Thank you for this patch! It is very much welcome!

llvm/docs/NewPassManager.rst

390

Can you please document the relation/order between function,loop, and cgscc "adapters?" I think it would be good to provide more information about "adapters" here.

394–395

How does a developer know whether a pass is a module pass vs a function pass? Is there a way to find out? Can that be added to the documentation?

I assume some error message is produced when the proper "adapter" is left out? Perhaps having such an error message, with an explicit recommendation on what's going wrong, why, and how to resolve will make search engines able to index. That way, when a developer hits such an error, then searches for the error, they find this solution in the docs?

429

How does this differ from say:
-passes='function(my-function-analysis,my-module-pass'
?

[aeubanks]

address comments

llvm/docs/NewPassManager.rst

394–395

it's part of the section below that prints all available passes, clarified there

429

-passes=my-function-analysis just isn't a thing
I've made it clearer what this actually does

[nickdesaulniers]

This is incredibly helpful, thank you so much.

General feedback about NPM, completely orthogonal to this review.

I find the nesting a little confusing. Not the order, but the adapters. It seems they describe what they're wrapping, not what they're producing (unlike casting in C). For example, function(foo) wraps foo (which is a function pass) in a module pass adapter. It seems more intuitive IMO for the syntax to be module(foo), not function(foo). Does this have to do with the optional cgscc wrapper?

The help text from opt for incorrect nesting could be improved. Rather than feedback like unknown function pass 'no-op-module' for a valid pass name, but invalid nesting, it would be nice if opt could provide more helpful feedback in such a case like: 'no-op-module' is a function pass, not a module pass. Reinvoke with 'function(no-op-module)' in pass list. or something.

For a more concrete example,

$ opt -passes='adce,always-inline' foo.ll -S
opt: unknown function pass 'always-inline'

So this seems to be using the implicit module adapter you spoke of, but the error message is confusing. I assume that always-inline, a module level pass, is being wrapped in the function adapter since adce was first, and needed one.

$ opt -passes='function(adce),always-inline' foo.ll -S

would be the correct invocation. But I need to invoke opt --print-passes to find out what IR unit such a pass operates on. opt *knows* what IR unit each pass runs on (assuming it is a valid pass for some unit of IR); it should just tell me politely via a helpful diagnostic, or figure out what I meant, rather than error out and require me to look up and think about nesting adapters.

llvm/docs/NewPassManager.rst

423

maybe after "the IR unit" add "(module, cgscc, function, or loop)" to reiterate?

429

Sorry, I meant:

What is the difference between:
opt -passes='function(require<my-function-analysis>),my-module-pass' /tmp/a.ll -S
vs
opt -passes='function(my-function-analysis),my-module-pass' /tmp/a.ll -S

Wouldn't my-function-analysis run either way? If so, what's the point of require<>? If not, what difference does require<> imply?

[aeubanks]

clarify IR Unit

[aeubanks]

I see what you mean by module(func-pass) vs function(func-pass), but function(func-pass) is much more unambiguous. If there was a cgscc pass and a function pass with the same name it would be ambiguous.

As for a better error message, a similar issue is there, but of course most pass names are unique, so we could do something like what you propose. Or maybe just tack on a "perhaps the type of pass you're running is wrong".

llvm/docs/NewPassManager.rst

429

you don't directly run analyses, you can only run passes. require<foo> is basically just a pass that just queries for that analysis, putting it in the cache

llvm/docs/NewPassManager.rst

 ==========================
 Using the New Pass Manager
 ==========================
 
 .. contents::
     :local:
 
+Overview
+========
+
+For an overview of the new pass manager, see the `blog post
+<https://blog.llvm.org/posts/2021-03-26-the-new-pass-manager/>`_.
+
 Adding Passes to a Pass Manager
 ===============================
 
 For how to write a new PM pass, see :doc:`this page <WritingAnLLVMNewPMPass>`.
 
 To add a pass to a new PM pass manager, the important thing is to match the
 pass type and the pass manager type. For example, a ``FunctionPassManager``
 can only contain function passes:

 analyses are also invalidated. This actually happens with alias analysis
 results. Alias analysis is a function-level analysis, but there are
 module-level implementations of specific types of alias analysis. Currently
 ``GlobalsAA`` is the only module-level alias analysis and it generally is not
 invalidated so this is not so much of a concern. See
 ``OuterAnalysisManagerProxy::Result::registerOuterAnalysisInvalidation()``
 for more details.
 
+Invoking ``opt``
+================
+
+To use the legacy pass manager:
+
+.. code-block:: shell
+
+  $ opt -enable-new-pm=0 -pass1 -pass2 /tmp/a.ll -S
+
+This will be removed once the legacy pass manager is deprecated and removed for
+the optimization pipeline.
+
+To use the new PM:
+
+.. code-block:: shell
+
+  $ opt -passes='pass1,pass2' /tmp/a.ll -S
+
+The new PM typically requires explicit pass nesting. For example, to run a
+function pass, then a module pass, we need to wrap the function pass in a module
+adaptor:
+
+.. code-block:: shell
+
+  $ opt -passes='function(no-op-function),no-op-module' /tmp/a.ll -S
+
+A more complete example, and ``-debug-pass-manager`` to show the execution
+order:
+
+.. code-block:: shell
+
+  $ opt -passes='no-op-module,cgscc(no-op-cgscc,function(no-op-function,loop(no-op-loop))),function(no-op-function,loop(no-op-loop))' /tmp/a.ll -S -debug-pass-manager
+
+Improper nesting can lead to error messages such as
+
+.. code-block:: shell
+
+  $ opt -passes='no-op-function,no-op-module' /tmp/a.ll -S
+  opt: unknown function pass 'no-op-module'
+
+The nesting is: module (-> cgscc) -> function -> loop, where the CGSCC nesting is optional.
+
+There are a couple of special cases for easier typing:
+
+* If the first pass is not a module pass, a pass manager of the first pass is
+  implicitly created
+
+  * For example, the following are equivalent
+
+.. code-block:: shell
+
+  $ opt -passes='no-op-function,no-op-function' /tmp/a.ll -S
+  $ opt -passes='function(no-op-function,no-op-function)' /tmp/a.ll -S
+
+* If there is an adaptor for a pass that lets it fit in the previous pass
+  manager, that is implicitly created
+
+  * For example, the following are equivalent
+
+.. code-block:: shell
+
+  $ opt -passes='no-op-function,no-op-loop' /tmp/a.ll -S
+  $ opt -passes='no-op-function,loop(no-op-loop)' /tmp/a.ll -S
+
+For a list of available passes and analyses, including the IR unit (module,
+CGSCC, function, loop) they operate on, run
+
+.. code-block:: shell
+
+  $ opt --print-passes
+
+or take a look at ``PassRegistry.def``.
+
+To make sure an analysis named ``foo`` is available before a pass, add
+``require<foo>`` to the pass pipeline. This adds a pass that simply requests
+that the analysis is run. This pass is also subject to proper nesting.  For
+example, to make sure some function analysis is already computed for all
+functions before a module pass:
+
+.. code-block:: shell
+
+  $ opt -passes='function(require<my-function-analysis>),my-module-pass' /tmp/a.ll -S
+
 Status of the New and Legacy Pass Managers
 ==========================================
 
 LLVM currently contains two pass managers, the legacy PM and the new PM. The
 optimization pipeline (aka the middle-end) works with both the legacy PM and
 the new PM, whereas the backend target-dependent code generation only works
 with the legacy PM.