[opt][NewPM] Add a --print-passes flag to print all available passes

[aeubanks]

Summary

It seems nicer to list passes given a flag rather than displaying all
passes in opt --help.

This is awkwardly structured because a PassBuilder is required, but
reusing the PassBuilder in runPassPipeline() doesn't work because we
read the input IR before getting to runPassPipeline(). So printing the
list of passes needs to happen before reading the input IR. If we remove
the legacy PM code in main() and move everything from NewPMDriver.cpp
into opt.cpp, we can create the PassBuilder before reading IR and check
if we should print the list of passes and exit. But until then this hack
seems fine.

Compared to the legacy PM, the new PM passes are lacking descriptions.
We'll need to figure out a way to add descriptions if we think this is
important.

[bjope]

llvm/test/Other/print-passes.ll

6

Should analysis passes perhaps be printed as require<name>?

[aeubanks]

mention in the -passes help description about require<>

[aeubanks]

llvm/test/Other/print-passes.ll

6

Technically require<foo> is a pass that just runs foo, so that's separate. I added in the --help for -passes that you can specify require<foo>.

[bjope]

llvm/test/Other/print-passes.ll

6

But you can't for example do -passes="aa" so you need to write -passes="require<aa>". If comparing with the print passes they are listed as for example "print<loops>". So it is a bit inconsistent (or maybe I am missing something).

One idea was to use the output from -print-passes in scripts to randomly generate strings to use in -passes. It will be slightly more complicated if one need to parse the headings in the output to find which passes that need an enclosing require<>.

[aeubanks]

llvm/test/Other/print-passes.ll

6

print<loops> is a name that happens to have < inside it, it's not special in any way.

Is it helpful to run arbitrary analyses? It seems more fruitful to just run random passes and have them query analyses as needed. Although there are special cases required, like making sure GlobalsAA and ProfileSummaryAnalysis are available before running function passes (see the uses of RequireAnalysisPass in PassBuilder).

Alternatively, rather than randomly constructing the list of passes outside LLVM via text, it could be interesting to do that within PassBuilder.

[aeubanks]

llvm/test/Other/print-passes.ll

6

I just found out about llvm-opt-fuzzer. Looks like we could do something like this there.

llvm/include/llvm/Passes/PassBuilder.h

 
 #ifndef LLVM_PASSES_PASSBUILDER_H
 #define LLVM_PASSES_PASSBUILDER_H
 
 #include "llvm/ADT/Optional.h"
 #include "llvm/Analysis/CGSCCPassManager.h"
 #include "llvm/IR/PassManager.h"
 #include "llvm/Support/Error.h"
+#include "llvm/Support/raw_ostream.h"
 #include "llvm/Transforms/IPO/Inliner.h"
 #include "llvm/Transforms/Instrumentation.h"
 #include "llvm/Transforms/Scalar/LoopPassManager.h"
 #include <vector>
 
 namespace llvm {
 class StringRef;
 class AAManager;
public:
   Error parseAAPipeline(AAManager &AA, StringRef PipelineText);
 
   /// Returns true if the pass name is the name of an alias analysis pass.
   bool isAAPassName(StringRef PassName);
 
   /// Returns true if the pass name is the name of a (non-alias) analysis pass.
   bool isAnalysisPassName(StringRef PassName);
 
+  /// Print pass names.
+  void printPassNames(raw_ostream &OS);
+
   /// Register a callback for a default optimizer pipeline extension
   /// point
   ///
   /// This extension point allows adding passes that perform peephole
   /// optimizations similar to the instruction combiner. These passes will be
   /// inserted after each instance of the instruction combiner pass.
   void registerPeepholeEPCallback(
       const std::function<void(FunctionPassManager &, OptimizationLevel)> &C) {

llvm/lib/Passes/PassBuilder.cpp

if (PassName == NAME)                                                        \
     return true;
 #define FUNCTION_ALIAS_ANALYSIS(NAME, CREATE_PASS)                             \
   if (PassName == NAME)                                                        \
     return true;
 #include "PassRegistry.def"
   return false;
 }
 
+static void printPassName(StringRef PassName, raw_ostream &OS) {
+  OS << "  " << PassName << "\n";
+}
+
+void PassBuilder::printPassNames(raw_ostream &OS) {
+  // TODO: print pass descriptions when they are available
+
+  OS << "Module passes:\n";
+#define MODULE_PASS(NAME, CREATE_PASS) printPassName(NAME, OS);
+#include "PassRegistry.def"
+
+  OS << "Module analyses:\n";
+#define MODULE_ANALYSIS(NAME, CREATE_PASS) printPassName(NAME, OS);
+#include "PassRegistry.def"
+
+  OS << "Module alias analyses:\n";
+#define MODULE_ALIAS_ANALYSIS(NAME, CREATE_PASS) printPassName(NAME, OS);
+#include "PassRegistry.def"
+
+  OS << "CGSCC passes:\n";
+#define CGSCC_PASS(NAME, CREATE_PASS) printPassName(NAME, OS);
+#include "PassRegistry.def"
+
+  OS << "CGSCC analyses:\n";
+#define CGSCC_ANALYSIS(NAME, CREATE_PASS) printPassName(NAME, OS);
+#include "PassRegistry.def"
+
+  OS << "Function passes:\n";
+#define FUNCTION_PASS(NAME, CREATE_PASS) printPassName(NAME, OS);
+#include "PassRegistry.def"
+
+  OS << "Function analyses:\n";
+#define FUNCTION_ANALYSIS(NAME, CREATE_PASS) printPassName(NAME, OS);
+#include "PassRegistry.def"
+
+  OS << "Function alias analyses:\n";
+#define FUNCTION_ALIAS_ANALYSIS(NAME, CREATE_PASS) printPassName(NAME, OS);
+#include "PassRegistry.def"
+
+  OS << "Loop passes:\n";
+#define LOOP_PASS(NAME, CREATE_PASS) printPassName(NAME, OS);
+#include "PassRegistry.def"
+
+  OS << "Loop analyses:\n";
+#define LOOP_ANALYSIS(NAME, CREATE_PASS) printPassName(NAME, OS);
+#include "PassRegistry.def"
+}
+
 void PassBuilder::registerParseTopLevelPipelineCallback(
     const std::function<bool(ModulePassManager &, ArrayRef<PipelineElement>,
                              bool DebugLogging)> &C) {
   TopLevelPipelineParsingCallbacks.push_back(C);
 }

llvm/test/Other/print-passes.ll

+; RUN: opt --print-passes | FileCheck %s
+
+; CHECK: Module passes:
+; CHECK: no-op-module
+; CHECK: Module analyses:
+; CHECK: no-op-module
+; CHECK: Module alias analyses:
+; CHECK: globals-aa
+; CHECK: CGSCC passes:
+; CHECK: no-op-cgscc
+; CHECK: CGSCC analyses:
+; CHECK: no-op-cgscc
+; CHECK: Function passes:
+; CHECK: no-op-function
+; CHECK: Function analyses:
+; CHECK: no-op-function
+; CHECK: Function alias analyses:
+; CHECK: basic-aa
+; CHECK: Loop passes:
+; CHECK: no-op-loop
+; CHECK: Loop analyses:
+; CHECK: no-op-loop

llvm/tools/opt/NewPMDriver.h

enum PGOKind {
   NoPGO,
   InstrGen,
   InstrUse,
   SampleUse
 };
 enum CSPGOKind { NoCSPGO, CSInstrGen, CSInstrUse };
 }
 
+void printPasses();
+
 /// Driver function to run the new pass manager over a module.
 ///
 /// This function only exists factored away from opt.cpp in order to prevent
 /// inclusion of the new pass manager headers and the old headers into the same
 /// file. It's interface is consequentially somewhat ad-hoc, but will go away
 /// when the transition finishes.
 ///
 /// ThinLTOLinkOut is only used when OK is OK_OutputThinLTOBitcode, and can be

llvm/tools/opt/NewPMDriver.cpp

#include "llvm/Support/Extension.def"
   if (OptRemarkFile)
     OptRemarkFile->keep();
 
   if (DebugifyEach && !DebugifyExport.empty())
     exportDebugifyStats(DebugifyExport, Debugify.StatsMap);
 
   return true;
 }
+
+void llvm::printPasses() {
+  PassBuilder PB;
+  PB.printPassNames(outs());
+}

llvm/tools/opt/opt.cpp

 // to run over the module. This flag switches opt to use the new pass manager
 // infrastructure, completely disabling all of the flags specific to the old
 // pass management.
 static cl::opt<std::string> PassPipeline(
     "passes",
     cl::desc("A textual description of the pass pipeline for optimizing"),
     cl::Hidden);
 
-// Other command line options...
-//
+static cl::opt<bool> PrintPasses("print-passes",
+                                 cl::desc("Print available passes that can be "
+                                          "specified in -passes=foo and exit"));
+
 static cl::opt<std::string>
 InputFilename(cl::Positional, cl::desc("<input bitcode file>"),
     cl::init("-"), cl::value_desc("filename"));
 
 static cl::opt<std::string>
 OutputFilename("o", cl::desc("Override output filename"),
                cl::value_desc("filename"));
 
#endif
   cl::ParseCommandLineOptions(argc, argv,
     "llvm .bc -> .bc modular optimizer and analysis printer\n");
 
   if (AnalyzeOnly && NoOutput) {
     errs() << argv[0] << ": analyze mode conflicts with no-output mode.\n";
     return 1;
   }
 
+  // FIXME: once the legacy PM code is deleted, move runPassPipeline() here and
+  // construct the PassBuilder before parsing IR so we can reuse the same
+  // PassBuilder for print passes.
+  if (PrintPasses) {
+    printPasses();
+    return 0;
+  }
+
   TimeTracerRAII TimeTracer(argv[0]);
 
   SMDiagnostic Err;
 
   Context.setDiscardValueNames(DiscardValueNames);
   if (!DisableDITypeMap)
     Context.enableDebugTypeODRUniquing();