[llvm-mca] Add a HardwareUnit and Context classes.

[mattd]

Summary

This patch moves the construction of the default backend from llvm-mca.cpp and into mca::Context. The Context class is responsible for holding ownership of the simulated hardware components. These components are subclasses of HardwareUnit. Right now the HardwareUnit is pretty bare-bones, but eventually we might want to add some common functionality across all hardware components, such as isReady() or something similar.

I have a feeling this patch will probably need some updates, but it's a start. One thing I am not particularly fond of is the rather large interface for createDefaultPipeline. That convenience routine takes a rather large set of inputs from the llvm-mca driver, where many of those inputs are generated via command line options.

One item I think we might want to change is the separating of ownership of hardware components (owned by the context) and the pipeline (which owns Stages). In short, a Pipeline owns Stages, a Context (currently) owns hardware. The Pipeline's Stages make use of the components, and thus there is a lifetime dependency generated. The components must outlive the pipeline. We could solve this by having the Context also own the Pipeline, and not return a unique_ptr<Pipeline>. Now that I think about it, I like that idea more.

[courbet]

Great, only a few nits.

tools/llvm-mca/Context.cpp

31

The comment is already on the declaration. I think you can remove it here.

tools/llvm-mca/Context.h

13

I don;t see any such "utility routines" for now. Remove ?

tools/llvm-mca/HardwareUnit.h

26

[nit] Let's make this the class anchor.

[mattd]

• Removed a comment.
• Pinned the HardwareUnit's vtable in HardwareUnit.cpp

[mattd]

Thanks for the review @courbet!

tools/llvm-mca/Context.cpp

31

Gotcha. I'll remove it.

tools/llvm-mca/Context.h

13

I was considering createDefaultPipeline a "utility routine'." I plan on adding another, similar, utility routine shortly.

tools/llvm-mca/HardwareUnit.h

26

Good call. Thanks for the suggestion. I went ahead and added an 'anchor' method instead of pinning the dtor. We already added an explicit anchor to HWEventListener.

[andreadb]

Hi Matt,

Thanks for the patch. See my comments below:

tools/llvm-mca/Context.h

12–14

We should be consistent with the terminology. I suggest to use hardware unit instead of hardware component.

39

s/addHardware/addHardwareUnit

45–49

I was wondering whether we should have a PipelineOptions struct which encapsulates all the unit options. The factory method createDefaultPipeline would take a PipelineOptions as input; that would simplify the argument list.

tools/llvm-mca/HardwareUnit.h

12–13

Hardware units.

26

Can we avoid adding method anchor()? You should be able to define the destructor in the .cpp file.

tools/llvm-mca/llvm-mca.cpp

503–506

I think the Context should be created only once, and then reused by every CodeSnippet. The Context should be the same for every CodeSnippet.

[mattd]

• Pinned HardwareUnit's vtable using the dtor.
• Updated the text to refer to "unit" instead of "component" in certain places.
• Moved the Context construction outside of the code-region loop.

[mattd]

Thanks for the review @andreadb!

[andreadb]

tools/llvm-mca/Context.h

12–13

Maybe be more specific here, and say that it provides a method to instantiate a "default" dispatch/execute/retire pipeline.
We can always update this comment in future.

45–49

I still think that - for simplicity and readability - we should wrap all those flags into a PipelineOptions struct.

We don't need to pass a MCSchedModel to createDefaultPipeline because we can always query STI to obtain it.

Even better, we can have that MCSubtargetInfo and MCRegisterInfo are passed in input to the constructor of Context, and used internally by its "utility" methods.

If we do all of this, then the createDefaultPipeline() would simply take a PipelineOptions, a SourceMgr& and a InstrBuilder&.

[mattd]

• Updated the Context{.h,cpp} comment to be a bit more specific about what 'utility' routines it possesses.
• Added a mca::PipelineOptions for simplifying the creation of the default out-of-order pipeline.

[mattd]

• Made SrcMgr a required argument for constructing a default pipeline.

[mattd]

tools/llvm-mca/Context.h

34

I not sure if we want to have the PipelineOptions struct nested within the Context class or not. I'm unbiased to either decision, and felt that exposing it as part of the root mca namespace isn't a bad decision.

45–49

That's cool with me. We will definitely need to make SourceMgr a required input to createDefaultPipeline. I made InstrBuilder a member of the PipelineOptions structl; we only ever construct that item once in llvm-mca, outside of the region generation loop.

[andreadb]

LGTM if you address the comments below.

Thanks.

tools/llvm-mca/Context.h

34

I think it is fine either way.

47–49

These last three fields are not really "options".
STI and MRI should never change, and those can be safely added to the context, and initialized at construction time.
The InstrBuilder can be passed in input to the call to createDefaultPipeline().
We can change this design in future if we see that there are better designs.

[mattd]

Thanks @andreadb. I like your suggestions. I will make them, run some tests, and land the patch.

tools/llvm-mca/CMakeLists.txt

 set(LLVM_LINK_COMPONENTS
   AllTargetsAsmPrinters
   AllTargetsAsmParsers
   AllTargetsDescs
   AllTargetsDisassemblers
   AllTargetsInfos
   MC
   MCParser
   Support
   )
 
 add_llvm_tool(llvm-mca
   CodeRegion.cpp
+  Context.cpp
   DispatchStage.cpp
   DispatchStatistics.cpp
   ExecuteStage.cpp
   FetchStage.cpp
   HWEventListener.cpp
+  HardwareUnit.cpp
   InstrBuilder.cpp
   Instruction.cpp
   InstructionInfoView.cpp
   InstructionTables.cpp
   LSUnit.cpp
   llvm-mca.cpp
   Pipeline.cpp
   PipelinePrinter.cpp

tools/llvm-mca/Context.h

+//===---------------------------- Context.h ---------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+/// \file
+///
+/// This file defines a class for holding ownership of various simulated
+/// hardware units.  A Context also provides utility routines that make
+/// use of its simulated hardware units.
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_TOOLS_LLVM_MCA_CONTEXT_H
+#define LLVM_TOOLS_LLVM_MCA_CONTEXT_H
+#include "HardwareUnit.h"
+#include "InstrBuilder.h"
+#include "Pipeline.h"
+#include "SourceMgr.h"
+#include "llvm/MC/MCRegisterInfo.h"
+#include "llvm/MC/MCSchedule.h"
+#include "llvm/MC/MCSubtargetInfo.h"
+#include <memory>
+
+namespace mca {
+
+class Context {
+  llvm::SmallVector<std::unique_ptr<HardwareUnit>, 4> Hardware;
+
+public:
+  Context() = default;
+  Context(const Context &C) = delete;
+  Context &operator=(const Context &C) = delete;
+
+  void addHardwareUnit(std::unique_ptr<HardwareUnit> H) {
+    Hardware.push_back(std::move(H));
+  }
+
+  /// Construct a basic pipeline for simulating an out-of-order pipeline.
+  /// This pipeline consists of Fetch, Dispatch, Execute, and Retire stages.
+  std::unique_ptr<Pipeline> createDefaultPipeline(
+      unsigned DispatchWidth, unsigned RegisterFileSize, unsigned LoadQueueSize,
+      unsigned StoreQueueSize, bool AssumeNoAlias, SourceMgr &Src,
+      InstrBuilder &IB, const llvm::MCSchedModel &SM,
+      const llvm::MCSubtargetInfo &STI, const llvm::MCRegisterInfo &MRI);
+};
+
+} // namespace mca
+#endif // LLVM_TOOLS_LLVM_MCA_CONTEXT_H

tools/llvm-mca/Context.cpp

+//===---------------------------- Context.cpp -------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+/// \file
+///
+/// This file defines a class for holding ownership of various simulated
+/// hardware units.  A Context also provides utility routines that make
+/// use of its simulated hardware units.
+///
+//===----------------------------------------------------------------------===//
+
+#include "Context.h"
+#include "DispatchStage.h"
+#include "ExecuteStage.h"
+#include "FetchStage.h"
+#include "RegisterFile.h"
+#include "RetireControlUnit.h"
+#include "RetireStage.h"
+#include "Scheduler.h"
+
+namespace mca {
+
+using namespace llvm;
+
+std::unique_ptr<Pipeline> Context::createDefaultPipeline(
+    unsigned DispatchWidth, unsigned RegisterFileSize, unsigned LoadQueueSize,
+    unsigned StoreQueueSize, bool AssumeNoAlias, SourceMgr &Src,
+    InstrBuilder &IB, const MCSchedModel &SM, const MCSubtargetInfo &STI,
+    const MCRegisterInfo &MRI) {
+  // Create the hardware units defining the backend.
+  auto RCU = llvm::make_unique<RetireControlUnit>(SM);
+  auto PRF = llvm::make_unique<RegisterFile>(SM, MRI, RegisterFileSize);
+  auto HWS = llvm::make_unique<Scheduler>(SM, LoadQueueSize, StoreQueueSize,
+                                          AssumeNoAlias);
+  // Create the pipeline and its stages.
+  auto P =
+      llvm::make_unique<Pipeline>(DispatchWidth, RegisterFileSize,
+                                  LoadQueueSize, StoreQueueSize, AssumeNoAlias);
+  auto F = llvm::make_unique<FetchStage>(IB, Src);
+  auto D = llvm::make_unique<DispatchStage>(STI, MRI, RegisterFileSize,
+                                            DispatchWidth, *RCU, *PRF, *HWS);
+  auto R = llvm::make_unique<RetireStage>(*RCU, *PRF);
+  auto E = llvm::make_unique<ExecuteStage>(*RCU, *HWS);
+
+  // Add the hardware to the context.
+  addHardwareUnit(std::move(RCU));
+  addHardwareUnit(std::move(PRF));
+  addHardwareUnit(std::move(HWS));
+
+  // Build the pipeline.
+  P->appendStage(std::move(F));
+  P->appendStage(std::move(D));
+  P->appendStage(std::move(R));
+  P->appendStage(std::move(E));
+  return P;
+}
+
+} // namespace mca

tools/llvm-mca/HardwareUnit.h

+//===-------------------------- HardwareUnit.h ------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+/// \file
+///
+/// This file defines a base class for describing a simulated hardware
+/// unit.  These units are used to construct a simulated backend.
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_TOOLS_LLVM_MCA_HARDWAREUNIT_H
+#define LLVM_TOOLS_LLVM_MCA_HARDWAREUNIT_H
+
+namespace mca {
+
+class HardwareUnit {
+  HardwareUnit(const HardwareUnit &H) = delete;
+  HardwareUnit &operator=(const HardwareUnit &H) = delete;
+
+public:
+  HardwareUnit() = default;
+  virtual ~HardwareUnit();
+};
+
+} // namespace mca
+#endif // LLVM_TOOLS_LLVM_MCA_HARDWAREUNIT_H

tools/llvm-mca/HardwareUnit.cpp

+//===------------------------- HardwareUnit.cpp -----------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+/// \file
+///
+/// This file defines the anchor for the base class that describes
+/// simulated hardware units.
+///
+//===----------------------------------------------------------------------===//
+
+#include "HardwareUnit.h"
+
+namespace mca {
+
+// Pin the vtable with this method.
+HardwareUnit::~HardwareUnit() = default;
+
+} // namespace mca

tools/llvm-mca/RegisterFile.h

 /// for managing hardware register files and the tracking of data dependencies
 /// between registers.
 ///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_TOOLS_LLVM_MCA_REGISTER_FILE_H
 #define LLVM_TOOLS_LLVM_MCA_REGISTER_FILE_H
 
+#include "HardwareUnit.h"
 #include "llvm/ADT/SmallVector.h"
 #include "llvm/MC/MCRegisterInfo.h"
 #include "llvm/MC/MCSchedule.h"
 
 namespace mca {
 
 class ReadState;
 class WriteState;
 class WriteRef;
 
 /// Manages hardware register files, and tracks register definitions for
 /// register renaming purposes.
-class RegisterFile {
+class RegisterFile : public HardwareUnit {
   const llvm::MCRegisterInfo &MRI;
 
   // Each register file is associated with an instance of
-  // RegisterMappingTracker. A RegisterMappingTracker tracks the number of
-  // physical registers that are dynamically allocated by the simulator.
+  // RegisterMappingTracker.
+  // A RegisterMappingTracker keeps track of the number of physical registers
+  // which have been dynamically allocated by the simulator.
   struct RegisterMappingTracker {
     // The total number of physical registers that are available in this
     // register file for register renaming purpouses.  A value of zero for this
     // field means: this register file has an unbounded number of physical
     // registers.
     const unsigned NumPhysRegs;
     // Number of physical registers that are currently in use.
     unsigned NumUsedPhysRegs;

tools/llvm-mca/RetireControlUnit.h

 ///
 /// This file simulates the hardware responsible for retiring instructions.
 ///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_TOOLS_LLVM_MCA_RETIRE_CONTROL_UNIT_H
 #define LLVM_TOOLS_LLVM_MCA_RETIRE_CONTROL_UNIT_H
 
+#include "HardwareUnit.h"
 #include "Instruction.h"
 #include "llvm/MC/MCSchedule.h"
 #include <vector>
 
 namespace mca {
 
 /// This class tracks which instructions are in-flight (i.e., dispatched but not
 /// retired) in the OoO pipeline.
 //
 /// This class checks on every cycle if/which instructions can be retired.
 /// Instructions are retired in program order.
 /// In the event of an instruction being retired, the pipeline that owns
 /// this RetireControlUnit (RCU) gets notified.
 ///
 /// On instruction retired, register updates are all architecturally
 /// committed, and any temporary registers originally allocated for the
 /// retired instruction are freed.
-struct RetireControlUnit {
+struct RetireControlUnit : public HardwareUnit {
   // A RUToken is created by the RCU for every instruction dispatched to the
   // schedulers.  These "tokens" are managed by the RCU in its token Queue.
   //
   // On every cycle ('cycleEvent'), the RCU iterates through the token queue
   // looking for any token with its 'Executed' flag set.  If a token has that
   // flag set, then the instruction has reached the write-back stage and will
   // be retired by the RCU.
   //

tools/llvm-mca/Scheduler.h

 /// A scheduler for Processor Resource Units and Processor Resource Groups.
 ///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_TOOLS_LLVM_MCA_SCHEDULER_H
 #define LLVM_TOOLS_LLVM_MCA_SCHEDULER_H
 
 #include "HWEventListener.h"
+#include "HardwareUnit.h"
 #include "Instruction.h"
 #include "LSUnit.h"
 #include "RetireControlUnit.h"
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/ADT/DenseMap.h"
 #include "llvm/ADT/SmallVector.h"
 #include "llvm/MC/MCSubtargetInfo.h"
 #include <map>

 /// to the processor pipelines, and the underlying ResourceManager is updated
 /// accordingly.  The ReadyQueue is ordered by instruction index to guarantee
 /// that the first instructions in the set are also the oldest.
 ///
 /// An Instruction is moved from the ReadyQueue the `IssuedQueue` when it is
 /// issued to a (one or more) pipeline(s). This event also causes an instruction
 /// state transition (i.e. from state IS_READY, to state IS_EXECUTING).
 /// An Instruction leaves the IssuedQueue when it reaches the write-back stage.
-class Scheduler {
+class Scheduler : public HardwareUnit {
   const llvm::MCSchedModel &SM;
 
   // Hardware resources that are managed by this scheduler.
   std::unique_ptr<ResourceManager> Resources;
   std::unique_ptr<LSUnit> LSU;
 
   using QueueEntryTy = std::pair<unsigned, Instruction *>;
   std::map<unsigned, Instruction *> WaitQueue;

tools/llvm-mca/llvm-mca.cpp

 //
 // The target defaults to the host target.
 // The cpu defaults to the 'native' host cpu.
 // The output defaults to standard output.
 //
 //===----------------------------------------------------------------------===//
 
 #include "CodeRegion.h"
-#include "DispatchStage.h"
+#include "Context.h"
 #include "DispatchStatistics.h"
-#include "ExecuteStage.h"
-#include "FetchStage.h"
 #include "InstructionInfoView.h"
 #include "InstructionTables.h"
 #include "Pipeline.h"
 #include "PipelinePrinter.h"
-#include "RegisterFile.h"
 #include "RegisterFileStatistics.h"
 #include "ResourcePressureView.h"
-#include "RetireControlUnit.h"
 #include "RetireControlUnitStatistics.h"
-#include "RetireStage.h"
-#include "Scheduler.h"
 #include "SchedulerStatistics.h"
 #include "SummaryView.h"
 #include "TimelineView.h"
 #include "llvm/MC/MCAsmInfo.h"
 #include "llvm/MC/MCContext.h"
 #include "llvm/MC/MCObjectFileInfo.h"
 #include "llvm/MC/MCParser/MCTargetAsmParser.h"
 #include "llvm/MC/MCRegisterInfo.h"
int main(int argc, char **argv) {
 
   unsigned Width = SM.IssueWidth;
   if (DispatchWidth)
     Width = DispatchWidth;
 
   // Create an instruction builder.
   mca::InstrBuilder IB(*STI, *MCII, *MRI, *MCIA);
 
+  // Create a context to control ownership of the pipeline hardware.
+  mca::Context MCA;
+
   // Number each region in the sequence.
   unsigned RegionIdx = 0;
   for (const std::unique_ptr<mca::CodeRegion> &Region : Regions) {
     // Skip empty code regions.
     if (Region->empty())
       continue;
 
     // Don't print the header of this region if it is the default region, and
if (PrintInstructionTables) {
       }
 
       IT.addView(llvm::make_unique<mca::ResourcePressureView>(*STI, *IP, S));
       IT.run();
       IT.printReport(TOF->os());
       continue;
     }
 
-    // Create the hardware components required for the pipeline.
-    mca::RetireControlUnit RCU(SM);
-    mca::RegisterFile PRF(SM, *MRI, RegisterFileSize);
-    mca::Scheduler HWS(SM, LoadQueueSize, StoreQueueSize, AssumeNoAlias);
-
-    // Create the pipeline and add stages to it.
-    auto P = llvm::make_unique<mca::Pipeline>(
-        Width, RegisterFileSize, LoadQueueSize, StoreQueueSize, AssumeNoAlias);
-    P->appendStage(llvm::make_unique<mca::FetchStage>(IB, S));
-    P->appendStage(llvm::make_unique<mca::DispatchStage>(
-        *STI, *MRI, RegisterFileSize, Width, RCU, PRF, HWS));
-    P->appendStage(llvm::make_unique<mca::RetireStage>(RCU, PRF));
-    P->appendStage(llvm::make_unique<mca::ExecuteStage>(RCU, HWS));
+    // Create a basic pipeline simulating an out-of-order backend.
+    auto P = MCA.createDefaultPipeline(Width, RegisterFileSize, LoadQueueSize,
+                                       StoreQueueSize, AssumeNoAlias, S, IB, SM,
+                                       *STI, *MRI);
     mca::PipelinePrinter Printer(*P);
 
     if (PrintSummaryView)
       Printer.addView(llvm::make_unique<mca::SummaryView>(SM, S, Width));
 
     if (PrintInstructionInfoView)
       Printer.addView(
           llvm::make_unique<mca::InstructionInfoView>(*STI, *MCII, S, *IP));