1 //===- PassDocGen.cpp - MLIR pass documentation generator -----------------===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 // 9 // PassDocGen uses the description of passes to generate documentation. 10 // 11 //===----------------------------------------------------------------------===// 12 13 #include "DocGenUtilities.h" 14 #include "mlir/TableGen/GenInfo.h" 15 #include "mlir/TableGen/Pass.h" 16 #include "llvm/Support/FormatVariadic.h" 17 #include "llvm/TableGen/Record.h" 18 19 using namespace mlir; 20 using namespace mlir::tblgen; 21 using llvm::RecordKeeper; 22 23 /// Emit the documentation for the given pass. 24 static void emitDoc(const Pass &pass, raw_ostream &os) { 25 os << llvm::formatv("### `-{0}`\n", pass.getArgument()); 26 emitSummary(pass.getSummary(), os); 27 emitDescription(pass.getDescription(), os); 28 29 // Handle the options of the pass. 30 ArrayRef<PassOption> options = pass.getOptions(); 31 if (!options.empty()) { 32 os << "\n#### Options\n```\n"; 33 size_t longestOption = 0; 34 for (const PassOption &option : options) 35 longestOption = std::max(option.getArgument().size(), longestOption); 36 for (const PassOption &option : options) { 37 os << "-" << option.getArgument(); 38 os.indent(longestOption - option.getArgument().size()) 39 << " : " << option.getDescription() << "\n"; 40 } 41 os << "```\n"; 42 } 43 44 // Handle the statistics of the pass. 45 ArrayRef<PassStatistic> stats = pass.getStatistics(); 46 if (!stats.empty()) { 47 os << "\n#### Statistics\n```\n"; 48 size_t longestStat = 0; 49 for (const PassStatistic &stat : stats) 50 longestStat = std::max(stat.getName().size(), longestStat); 51 for (const PassStatistic &stat : stats) { 52 os << stat.getName(); 53 os.indent(longestStat - stat.getName().size()) 54 << " : " << stat.getDescription() << "\n"; 55 } 56 os << "```\n"; 57 } 58 } 59 60 static void emitDocs(const RecordKeeper &records, raw_ostream &os) { 61 os << "<!-- Autogenerated by mlir-tblgen; don't manually edit -->\n"; 62 auto passDefs = records.getAllDerivedDefinitions("PassBase"); 63 64 // Collect the registered passes, sorted by argument name. 65 SmallVector<Pass, 16> passes(passDefs.begin(), passDefs.end()); 66 SmallVector<Pass *, 16> sortedPasses(llvm::make_pointer_range(passes)); 67 llvm::array_pod_sort(sortedPasses.begin(), sortedPasses.end(), 68 [](Pass *const *lhs, Pass *const *rhs) { 69 return (*lhs)->getArgument().compare( 70 (*rhs)->getArgument()); 71 }); 72 for (Pass *pass : sortedPasses) 73 emitDoc(*pass, os); 74 } 75 76 static mlir::GenRegistration 77 genRegister("gen-pass-doc", "Generate pass documentation", 78 [](const RecordKeeper &records, raw_ostream &os) { 79 emitDocs(records, os); 80 return false; 81 }); 82