1//===-- llvm-mca.cpp - Machine Code Analyzer -------------------*- C++ -* -===//
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// This utility is a simple driver that allows static performance analysis on
10// machine code similarly to how IACA (Intel Architecture Code Analyzer) works.
11//
12//   llvm-mca [options] <file-name>
13//      -march <type>
14//      -mcpu <cpu>
15//      -o <file>
16//
17// The target defaults to the host target.
18// The cpu defaults to the 'native' host cpu.
19// The output defaults to standard output.
20//
21//===----------------------------------------------------------------------===//
22
23#include "CodeRegion.h"
24#include "CodeRegionGenerator.h"
25#include "PipelinePrinter.h"
26#include "Views/BottleneckAnalysis.h"
27#include "Views/DispatchStatistics.h"
28#include "Views/InstructionInfoView.h"
29#include "Views/RegisterFileStatistics.h"
30#include "Views/ResourcePressureView.h"
31#include "Views/RetireControlUnitStatistics.h"
32#include "Views/SchedulerStatistics.h"
33#include "Views/SummaryView.h"
34#include "Views/TimelineView.h"
35#include "llvm/MC/MCAsmBackend.h"
36#include "llvm/MC/MCAsmInfo.h"
37#include "llvm/MC/MCCodeEmitter.h"
38#include "llvm/MC/MCContext.h"
39#include "llvm/MC/MCObjectFileInfo.h"
40#include "llvm/MC/MCRegisterInfo.h"
41#include "llvm/MC/MCSubtargetInfo.h"
42#include "llvm/MC/MCTargetOptionsCommandFlags.inc"
43#include "llvm/MCA/CodeEmitter.h"
44#include "llvm/MCA/Context.h"
45#include "llvm/MCA/InstrBuilder.h"
46#include "llvm/MCA/Pipeline.h"
47#include "llvm/MCA/Stages/EntryStage.h"
48#include "llvm/MCA/Stages/InstructionTables.h"
49#include "llvm/MCA/Support.h"
50#include "llvm/Support/CommandLine.h"
51#include "llvm/Support/ErrorHandling.h"
52#include "llvm/Support/ErrorOr.h"
53#include "llvm/Support/FileSystem.h"
54#include "llvm/Support/Host.h"
55#include "llvm/Support/InitLLVM.h"
56#include "llvm/Support/MemoryBuffer.h"
57#include "llvm/Support/SourceMgr.h"
58#include "llvm/Support/TargetRegistry.h"
59#include "llvm/Support/TargetSelect.h"
60#include "llvm/Support/ToolOutputFile.h"
61#include "llvm/Support/WithColor.h"
62
63using namespace llvm;
64
65static cl::OptionCategory ToolOptions("Tool Options");
66static cl::OptionCategory ViewOptions("View Options");
67
68static cl::opt<std::string> InputFilename(cl::Positional,
69                                          cl::desc("<input file>"),
70                                          cl::cat(ToolOptions), cl::init("-"));
71
72static cl::opt<std::string> OutputFilename("o", cl::desc("Output filename"),
73                                           cl::init("-"), cl::cat(ToolOptions),
74                                           cl::value_desc("filename"));
75
76static cl::opt<std::string>
77    ArchName("march",
78             cl::desc("Target architecture. "
79                      "See -version for available targets"),
80             cl::cat(ToolOptions));
81
82static cl::opt<std::string>
83    TripleName("mtriple",
84               cl::desc("Target triple. See -version for available targets"),
85               cl::cat(ToolOptions));
86
87static cl::opt<std::string>
88    MCPU("mcpu",
89         cl::desc("Target a specific cpu type (-mcpu=help for details)"),
90         cl::value_desc("cpu-name"), cl::cat(ToolOptions), cl::init("native"));
91
92static cl::opt<std::string>
93    MATTR("mattr",
94          cl::desc("Additional target features."),
95          cl::cat(ToolOptions));
96
97static cl::opt<int>
98    OutputAsmVariant("output-asm-variant",
99                     cl::desc("Syntax variant to use for output printing"),
100                     cl::cat(ToolOptions), cl::init(-1));
101
102static cl::opt<bool>
103    PrintImmHex("print-imm-hex", cl::cat(ToolOptions), cl::init(false),
104                cl::desc("Prefer hex format when printing immediate values"));
105
106static cl::opt<unsigned> Iterations("iterations",
107                                    cl::desc("Number of iterations to run"),
108                                    cl::cat(ToolOptions), cl::init(0));
109
110static cl::opt<unsigned>
111    DispatchWidth("dispatch", cl::desc("Override the processor dispatch width"),
112                  cl::cat(ToolOptions), cl::init(0));
113
114static cl::opt<unsigned>
115    RegisterFileSize("register-file-size",
116                     cl::desc("Maximum number of physical registers which can "
117                              "be used for register mappings"),
118                     cl::cat(ToolOptions), cl::init(0));
119
120static cl::opt<unsigned>
121    MicroOpQueue("micro-op-queue-size", cl::Hidden,
122                 cl::desc("Number of entries in the micro-op queue"),
123                 cl::cat(ToolOptions), cl::init(0));
124
125static cl::opt<unsigned>
126    DecoderThroughput("decoder-throughput", cl::Hidden,
127                      cl::desc("Maximum throughput from the decoders "
128                               "(instructions per cycle)"),
129                      cl::cat(ToolOptions), cl::init(0));
130
131static cl::opt<bool>
132    PrintRegisterFileStats("register-file-stats",
133                           cl::desc("Print register file statistics"),
134                           cl::cat(ViewOptions), cl::init(false));
135
136static cl::opt<bool> PrintDispatchStats("dispatch-stats",
137                                        cl::desc("Print dispatch statistics"),
138                                        cl::cat(ViewOptions), cl::init(false));
139
140static cl::opt<bool>
141    PrintSummaryView("summary-view", cl::Hidden,
142                     cl::desc("Print summary view (enabled by default)"),
143                     cl::cat(ViewOptions), cl::init(true));
144
145static cl::opt<bool> PrintSchedulerStats("scheduler-stats",
146                                         cl::desc("Print scheduler statistics"),
147                                         cl::cat(ViewOptions), cl::init(false));
148
149static cl::opt<bool>
150    PrintRetireStats("retire-stats",
151                     cl::desc("Print retire control unit statistics"),
152                     cl::cat(ViewOptions), cl::init(false));
153
154static cl::opt<bool> PrintResourcePressureView(
155    "resource-pressure",
156    cl::desc("Print the resource pressure view (enabled by default)"),
157    cl::cat(ViewOptions), cl::init(true));
158
159static cl::opt<bool> PrintTimelineView("timeline",
160                                       cl::desc("Print the timeline view"),
161                                       cl::cat(ViewOptions), cl::init(false));
162
163static cl::opt<unsigned> TimelineMaxIterations(
164    "timeline-max-iterations",
165    cl::desc("Maximum number of iterations to print in timeline view"),
166    cl::cat(ViewOptions), cl::init(0));
167
168static cl::opt<unsigned> TimelineMaxCycles(
169    "timeline-max-cycles",
170    cl::desc(
171        "Maximum number of cycles in the timeline view. Defaults to 80 cycles"),
172    cl::cat(ViewOptions), cl::init(80));
173
174static cl::opt<bool>
175    AssumeNoAlias("noalias",
176                  cl::desc("If set, assume that loads and stores do not alias"),
177                  cl::cat(ToolOptions), cl::init(true));
178
179static cl::opt<unsigned> LoadQueueSize("lqueue",
180                                       cl::desc("Size of the load queue"),
181                                       cl::cat(ToolOptions), cl::init(0));
182
183static cl::opt<unsigned> StoreQueueSize("squeue",
184                                        cl::desc("Size of the store queue"),
185                                        cl::cat(ToolOptions), cl::init(0));
186
187static cl::opt<bool>
188    PrintInstructionTables("instruction-tables",
189                           cl::desc("Print instruction tables"),
190                           cl::cat(ToolOptions), cl::init(false));
191
192static cl::opt<bool> PrintInstructionInfoView(
193    "instruction-info",
194    cl::desc("Print the instruction info view (enabled by default)"),
195    cl::cat(ViewOptions), cl::init(true));
196
197static cl::opt<bool> EnableAllStats("all-stats",
198                                    cl::desc("Print all hardware statistics"),
199                                    cl::cat(ViewOptions), cl::init(false));
200
201static cl::opt<bool>
202    EnableAllViews("all-views",
203                   cl::desc("Print all views including hardware statistics"),
204                   cl::cat(ViewOptions), cl::init(false));
205
206static cl::opt<bool> EnableBottleneckAnalysis(
207    "bottleneck-analysis",
208    cl::desc("Enable bottleneck analysis (disabled by default)"),
209    cl::cat(ViewOptions), cl::init(false));
210
211static cl::opt<bool> ShowEncoding(
212    "show-encoding",
213    cl::desc("Print encoding information in the instruction info view"),
214    cl::cat(ViewOptions), cl::init(false));
215
216namespace {
217
218const Target *getTarget(const char *ProgName) {
219  if (TripleName.empty())
220    TripleName = Triple::normalize(sys::getDefaultTargetTriple());
221  Triple TheTriple(TripleName);
222
223  // Get the target specific parser.
224  std::string Error;
225  const Target *TheTarget =
226      TargetRegistry::lookupTarget(ArchName, TheTriple, Error);
227  if (!TheTarget) {
228    errs() << ProgName << ": " << Error;
229    return nullptr;
230  }
231
232  // Return the found target.
233  return TheTarget;
234}
235
236ErrorOr<std::unique_ptr<ToolOutputFile>> getOutputStream() {
237  if (OutputFilename == "")
238    OutputFilename = "-";
239  std::error_code EC;
240  auto Out =
241      std::make_unique<ToolOutputFile>(OutputFilename, EC, sys::fs::OF_Text);
242  if (!EC)
243    return std::move(Out);
244  return EC;
245}
246} // end of anonymous namespace
247
248static void processOptionImpl(cl::opt<bool> &O, const cl::opt<bool> &Default) {
249  if (!O.getNumOccurrences() || O.getPosition() < Default.getPosition())
250    O = Default.getValue();
251}
252
253static void processViewOptions() {
254  if (!EnableAllViews.getNumOccurrences() &&
255      !EnableAllStats.getNumOccurrences())
256    return;
257
258  if (EnableAllViews.getNumOccurrences()) {
259    processOptionImpl(PrintSummaryView, EnableAllViews);
260    processOptionImpl(EnableBottleneckAnalysis, EnableAllViews);
261    processOptionImpl(PrintResourcePressureView, EnableAllViews);
262    processOptionImpl(PrintTimelineView, EnableAllViews);
263    processOptionImpl(PrintInstructionInfoView, EnableAllViews);
264  }
265
266  const cl::opt<bool> &Default =
267      EnableAllViews.getPosition() < EnableAllStats.getPosition()
268          ? EnableAllStats
269          : EnableAllViews;
270  processOptionImpl(PrintRegisterFileStats, Default);
271  processOptionImpl(PrintDispatchStats, Default);
272  processOptionImpl(PrintSchedulerStats, Default);
273  processOptionImpl(PrintRetireStats, Default);
274}
275
276// Returns true on success.
277static bool runPipeline(mca::Pipeline &P) {
278  // Handle pipeline errors here.
279  Expected<unsigned> Cycles = P.run();
280  if (!Cycles) {
281    WithColor::error() << toString(Cycles.takeError());
282    return false;
283  }
284  return true;
285}
286
287int main(int argc, char **argv) {
288  InitLLVM X(argc, argv);
289
290  // Initialize targets and assembly parsers.
291  InitializeAllTargetInfos();
292  InitializeAllTargetMCs();
293  InitializeAllAsmParsers();
294
295  // Enable printing of available targets when flag --version is specified.
296  cl::AddExtraVersionPrinter(TargetRegistry::printRegisteredTargetsForVersion);
297
298  cl::HideUnrelatedOptions({&ToolOptions, &ViewOptions});
299
300  // Parse flags and initialize target options.
301  cl::ParseCommandLineOptions(argc, argv,
302                              "llvm machine code performance analyzer.\n");
303
304  // Get the target from the triple. If a triple is not specified, then select
305  // the default triple for the host. If the triple doesn't correspond to any
306  // registered target, then exit with an error message.
307  const char *ProgName = argv[0];
308  const Target *TheTarget = getTarget(ProgName);
309  if (!TheTarget)
310    return 1;
311
312  // GetTarget() may replaced TripleName with a default triple.
313  // For safety, reconstruct the Triple object.
314  Triple TheTriple(TripleName);
315
316  ErrorOr<std::unique_ptr<MemoryBuffer>> BufferPtr =
317      MemoryBuffer::getFileOrSTDIN(InputFilename);
318  if (std::error_code EC = BufferPtr.getError()) {
319    WithColor::error() << InputFilename << ": " << EC.message() << '\n';
320    return 1;
321  }
322
323  // Apply overrides to llvm-mca specific options.
324  processViewOptions();
325
326  if (!MCPU.compare("native"))
327    MCPU = llvm::sys::getHostCPUName();
328
329  std::unique_ptr<MCSubtargetInfo> STI(
330      TheTarget->createMCSubtargetInfo(TripleName, MCPU, MATTR));
331  if (!STI->isCPUStringValid(MCPU))
332    return 1;
333
334  if (!PrintInstructionTables && !STI->getSchedModel().isOutOfOrder()) {
335    WithColor::error() << "please specify an out-of-order cpu. '" << MCPU
336                       << "' is an in-order cpu.\n";
337    return 1;
338  }
339
340  if (!STI->getSchedModel().hasInstrSchedModel()) {
341    WithColor::error()
342        << "unable to find instruction-level scheduling information for"
343        << " target triple '" << TheTriple.normalize() << "' and cpu '" << MCPU
344        << "'.\n";
345
346    if (STI->getSchedModel().InstrItineraries)
347      WithColor::note()
348          << "cpu '" << MCPU << "' provides itineraries. However, "
349          << "instruction itineraries are currently unsupported.\n";
350    return 1;
351  }
352
353  std::unique_ptr<MCRegisterInfo> MRI(TheTarget->createMCRegInfo(TripleName));
354  assert(MRI && "Unable to create target register info!");
355
356  MCTargetOptions MCOptions = InitMCTargetOptionsFromFlags();
357  std::unique_ptr<MCAsmInfo> MAI(
358      TheTarget->createMCAsmInfo(*MRI, TripleName, MCOptions));
359  assert(MAI && "Unable to create target asm info!");
360
361  MCObjectFileInfo MOFI;
362  SourceMgr SrcMgr;
363
364  // Tell SrcMgr about this buffer, which is what the parser will pick up.
365  SrcMgr.AddNewSourceBuffer(std::move(*BufferPtr), SMLoc());
366
367  MCContext Ctx(MAI.get(), MRI.get(), &MOFI, &SrcMgr);
368
369  MOFI.InitMCObjectFileInfo(TheTriple, /* PIC= */ false, Ctx);
370
371  std::unique_ptr<buffer_ostream> BOS;
372
373  std::unique_ptr<MCInstrInfo> MCII(TheTarget->createMCInstrInfo());
374
375  std::unique_ptr<MCInstrAnalysis> MCIA(
376      TheTarget->createMCInstrAnalysis(MCII.get()));
377
378  // Parse the input and create CodeRegions that llvm-mca can analyze.
379  mca::AsmCodeRegionGenerator CRG(*TheTarget, SrcMgr, Ctx, *MAI, *STI, *MCII);
380  Expected<const mca::CodeRegions &> RegionsOrErr = CRG.parseCodeRegions();
381  if (!RegionsOrErr) {
382    if (auto Err =
383            handleErrors(RegionsOrErr.takeError(), [](const StringError &E) {
384              WithColor::error() << E.getMessage() << '\n';
385            })) {
386      // Default case.
387      WithColor::error() << toString(std::move(Err)) << '\n';
388    }
389    return 1;
390  }
391  const mca::CodeRegions &Regions = *RegionsOrErr;
392
393  // Early exit if errors were found by the code region parsing logic.
394  if (!Regions.isValid())
395    return 1;
396
397  if (Regions.empty()) {
398    WithColor::error() << "no assembly instructions found.\n";
399    return 1;
400  }
401
402  // Now initialize the output file.
403  auto OF = getOutputStream();
404  if (std::error_code EC = OF.getError()) {
405    WithColor::error() << EC.message() << '\n';
406    return 1;
407  }
408
409  unsigned AssemblerDialect = CRG.getAssemblerDialect();
410  if (OutputAsmVariant >= 0)
411    AssemblerDialect = static_cast<unsigned>(OutputAsmVariant);
412  std::unique_ptr<MCInstPrinter> IP(TheTarget->createMCInstPrinter(
413      Triple(TripleName), AssemblerDialect, *MAI, *MCII, *MRI));
414  if (!IP) {
415    WithColor::error()
416        << "unable to create instruction printer for target triple '"
417        << TheTriple.normalize() << "' with assembly variant "
418        << AssemblerDialect << ".\n";
419    return 1;
420  }
421
422  // Set the display preference for hex vs. decimal immediates.
423  IP->setPrintImmHex(PrintImmHex);
424
425  std::unique_ptr<ToolOutputFile> TOF = std::move(*OF);
426
427  const MCSchedModel &SM = STI->getSchedModel();
428
429  // Create an instruction builder.
430  mca::InstrBuilder IB(*STI, *MCII, *MRI, MCIA.get());
431
432  // Create a context to control ownership of the pipeline hardware.
433  mca::Context MCA(*MRI, *STI);
434
435  mca::PipelineOptions PO(MicroOpQueue, DecoderThroughput, DispatchWidth,
436                          RegisterFileSize, LoadQueueSize, StoreQueueSize,
437                          AssumeNoAlias, EnableBottleneckAnalysis);
438
439  // Number each region in the sequence.
440  unsigned RegionIdx = 0;
441
442  std::unique_ptr<MCCodeEmitter> MCE(
443      TheTarget->createMCCodeEmitter(*MCII, *MRI, Ctx));
444
445  std::unique_ptr<MCAsmBackend> MAB(TheTarget->createMCAsmBackend(
446      *STI, *MRI, InitMCTargetOptionsFromFlags()));
447
448  for (const std::unique_ptr<mca::CodeRegion> &Region : Regions) {
449    // Skip empty code regions.
450    if (Region->empty())
451      continue;
452
453    // Don't print the header of this region if it is the default region, and
454    // it doesn't have an end location.
455    if (Region->startLoc().isValid() || Region->endLoc().isValid()) {
456      TOF->os() << "\n[" << RegionIdx++ << "] Code Region";
457      StringRef Desc = Region->getDescription();
458      if (!Desc.empty())
459        TOF->os() << " - " << Desc;
460      TOF->os() << "\n\n";
461    }
462
463    // Lower the MCInst sequence into an mca::Instruction sequence.
464    ArrayRef<MCInst> Insts = Region->getInstructions();
465    mca::CodeEmitter CE(*STI, *MAB, *MCE, Insts);
466    std::vector<std::unique_ptr<mca::Instruction>> LoweredSequence;
467    for (const MCInst &MCI : Insts) {
468      Expected<std::unique_ptr<mca::Instruction>> Inst =
469          IB.createInstruction(MCI);
470      if (!Inst) {
471        if (auto NewE = handleErrors(
472                Inst.takeError(),
473                [&IP, &STI](const mca::InstructionError<MCInst> &IE) {
474                  std::string InstructionStr;
475                  raw_string_ostream SS(InstructionStr);
476                  WithColor::error() << IE.Message << '\n';
477                  IP->printInst(&IE.Inst, 0, "", *STI, SS);
478                  SS.flush();
479                  WithColor::note()
480                      << "instruction: " << InstructionStr << '\n';
481                })) {
482          // Default case.
483          WithColor::error() << toString(std::move(NewE));
484        }
485        return 1;
486      }
487
488      LoweredSequence.emplace_back(std::move(Inst.get()));
489    }
490
491    mca::SourceMgr S(LoweredSequence, PrintInstructionTables ? 1 : Iterations);
492
493    if (PrintInstructionTables) {
494      //  Create a pipeline, stages, and a printer.
495      auto P = std::make_unique<mca::Pipeline>();
496      P->appendStage(std::make_unique<mca::EntryStage>(S));
497      P->appendStage(std::make_unique<mca::InstructionTables>(SM));
498      mca::PipelinePrinter Printer(*P);
499
500      // Create the views for this pipeline, execute, and emit a report.
501      if (PrintInstructionInfoView) {
502        Printer.addView(std::make_unique<mca::InstructionInfoView>(
503            *STI, *MCII, CE, ShowEncoding, Insts, *IP));
504      }
505      Printer.addView(
506          std::make_unique<mca::ResourcePressureView>(*STI, *IP, Insts));
507
508      if (!runPipeline(*P))
509        return 1;
510
511      Printer.printReport(TOF->os());
512      continue;
513    }
514
515    // Create a basic pipeline simulating an out-of-order backend.
516    auto P = MCA.createDefaultPipeline(PO, S);
517    mca::PipelinePrinter Printer(*P);
518
519    if (PrintSummaryView)
520      Printer.addView(
521          std::make_unique<mca::SummaryView>(SM, Insts, DispatchWidth));
522
523    if (EnableBottleneckAnalysis) {
524      Printer.addView(std::make_unique<mca::BottleneckAnalysis>(
525          *STI, *IP, Insts, S.getNumIterations()));
526    }
527
528    if (PrintInstructionInfoView)
529      Printer.addView(std::make_unique<mca::InstructionInfoView>(
530          *STI, *MCII, CE, ShowEncoding, Insts, *IP));
531
532    if (PrintDispatchStats)
533      Printer.addView(std::make_unique<mca::DispatchStatistics>());
534
535    if (PrintSchedulerStats)
536      Printer.addView(std::make_unique<mca::SchedulerStatistics>(*STI));
537
538    if (PrintRetireStats)
539      Printer.addView(std::make_unique<mca::RetireControlUnitStatistics>(SM));
540
541    if (PrintRegisterFileStats)
542      Printer.addView(std::make_unique<mca::RegisterFileStatistics>(*STI));
543
544    if (PrintResourcePressureView)
545      Printer.addView(
546          std::make_unique<mca::ResourcePressureView>(*STI, *IP, Insts));
547
548    if (PrintTimelineView) {
549      unsigned TimelineIterations =
550          TimelineMaxIterations ? TimelineMaxIterations : 10;
551      Printer.addView(std::make_unique<mca::TimelineView>(
552          *STI, *IP, Insts, std::min(TimelineIterations, S.getNumIterations()),
553          TimelineMaxCycles));
554    }
555
556    if (!runPipeline(*P))
557      return 1;
558
559    Printer.printReport(TOF->os());
560
561    // Clear the InstrBuilder internal state in preparation for another round.
562    IB.clear();
563  }
564
565  TOF->keep();
566  return 0;
567}
568