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