[llvm-mca] Add cycleBegin/cycleEnd callbacks to mca::Stage.

[mattd]

Summary

This patch clears up some of the semantics within the Stage class. Now, preExecute
can be called multiple times per simulated cycle. Previously preExecute was
only called once per cycle, and postExecute could have been called multiple
times.

Now, cycleStart/cycleEnd are called only once per simulated cycle.
preExecute/postExecute can be called multiple times per cycle. This
occurs because multiple execution events can occur during a single cycle.

When stages are executed (Pipeline::runCycle), the postExecute hook will
be called only if all Stages return a success from their 'execute' callback.

[mattd]

Moved the Instructions container cleanup to cycleEnd.

[mattd]

I just rebased this to fix a bad diff in the previous update.

[andreadb]

LGTM if you address the comments below.

Thanks!

tools/llvm-mca/Stage.h

45

The stage behaviour should never be dependent on the Cycle ID.
In practice (as expected) param Cycle is never used by any stage, and it can be safely removed.

48

Same.

[mattd]

Thanks for the review @andreadb! I'm totally fine with removing the Cycle formal. I added it because I thought that some user-defined Stage might find that data useful. Likewise, the pre/postExecute callbacks take InstRef references, but no existing function makes use of that either. I'd be happy to remove that InstRef formal as a NFC in another patch.

tools/llvm-mca/DispatchStage.h

DispatchStage(const llvm::MCSubtargetInfo &Subtarget,
                 RegisterFile &F, Scheduler &Sched)
       : DispatchWidth(MaxDispatchWidth), AvailableEntries(MaxDispatchWidth),
         CarryOver(0U), STI(Subtarget), RCU(R), PRF(F), SC(Sched) {}
 
   // We can always try to dispatch, so returning false is okay in this case.
   // The retire stage, which controls the RCU, might have items to complete but
   // RetireStage::hasWorkToComplete will check for that case.
   virtual bool hasWorkToComplete() const override final { return false; }
-  virtual void preExecute(const InstRef &IR) override final;
+  virtual void cycleStart(unsigned Cycle) override final;
   virtual bool execute(InstRef &IR) override final;
   void notifyDispatchStall(const InstRef &IR, unsigned EventType);
 
 #ifndef NDEBUG
   void dump() const;
 #endif
 };
 } // namespace mca
 
 #endif // LLVM_TOOLS_LLVM_MCA_DISPATCH_STAGE_H

tools/llvm-mca/DispatchStage.cpp

void DispatchStage::dispatch(InstRef IR) {
   // Reserve slots in the RCU, and notify the instruction that it has been
   // dispatched to the schedulers for execution.
   IS.dispatch(RCU.reserveSlot(IR, NumMicroOps));
 
   // Notify listeners of the "instruction dispatched" event.
   notifyInstructionDispatched(IR, RegisterFiles);
 }
 
-void DispatchStage::preExecute(const InstRef &IR) {
+void DispatchStage::cycleStart(unsigned Cycle) {
   AvailableEntries = CarryOver >= DispatchWidth ? 0 : DispatchWidth - CarryOver;
   CarryOver = CarryOver >= DispatchWidth ? CarryOver - DispatchWidth : 0U;
 }
 
 bool DispatchStage::execute(InstRef &IR) {
   const InstrDesc &Desc = IR.getInstruction()->getDesc();
   if (!isAvailable(Desc.NumMicroOps) || !canDispatch(IR))
     return false;

tools/llvm-mca/ExecuteStage.h

public:
   ExecuteStage(RetireControlUnit &R, Scheduler &S) : Stage(), RCU(R), HWS(S) {}
   ExecuteStage(const ExecuteStage &Other) = delete;
   ExecuteStage &operator=(const ExecuteStage &Other) = delete;
 
   // The ExecuteStage will always complete all of its work per call to
   // execute(), so it is never left in a 'to-be-processed' state.
   virtual bool hasWorkToComplete() const override final { return false; }
 
-  virtual void preExecute(const InstRef &IR) override final;
+  virtual void cycleStart(unsigned Cycle) override final;
   virtual bool execute(InstRef &IR) override final;
 
   void
   notifyInstructionIssued(const InstRef &IR,
                           llvm::ArrayRef<std::pair<ResourceRef, double>> Used);
   void notifyInstructionExecuted(const InstRef &IR);
   void notifyInstructionReady(const InstRef &IR);
   void notifyResourceAvailable(const ResourceRef &RR);

tools/llvm-mca/ExecuteStage.cpp

 //
 // This routine also processes the instructions that are ready for issuance.
 // These instructions are managed by the HWS's ready queue and can be accessed
 // via the Scheduler::select() routine.
 //
 // Notifications are issued to this stage's listeners when instructions are
 // moved between the HWS's queues.  In particular, when an instruction becomes
 // ready or executed.
-void ExecuteStage::preExecute(const InstRef &Unused) {
+void ExecuteStage::cycleStart(unsigned Cycle) {
   reclaimSchedulerResources();
   updateSchedulerQueues();
   issueReadyInstructions();
 }
 
 // Schedule the instruction for execution on the hardware.
 bool ExecuteStage::execute(InstRef &IR) {
 #ifndef NDEBUG

tools/llvm-mca/FetchStage.h

 namespace mca {
 
 class FetchStage : public Stage {
   using InstMap = std::map<unsigned, std::unique_ptr<Instruction>>;
   InstMap Instructions;
   InstrBuilder &IB;
   SourceMgr &SM;
 
+  // The number of times Fetch::execute has been called for this cycle.
+  // Multiple fetches can occur during a single cycle, and this is used to know
+  // when to retrieve the next instruction from the SourceManager.
+  unsigned CurrentCycleCounter;
+
 public:
-  FetchStage(InstrBuilder &IB, SourceMgr &SM) : IB(IB), SM(SM) {}
+  FetchStage(InstrBuilder &IB, SourceMgr &SM)
+      : IB(IB), SM(SM), CurrentCycleCounter(~0U) {}
   FetchStage(const FetchStage &Other) = delete;
   FetchStage &operator=(const FetchStage &Other) = delete;
 
   bool hasWorkToComplete() const override final;
   bool execute(InstRef &IR) override final;
-  void postExecute(const InstRef &IR) override final;
+  void cycleStart(unsigned Cycle) override final;
+  void cycleEnd(unsigned Cycle) override final;
 };
 
 } // namespace mca
 
 #endif // LLVM_TOOLS_LLVM_MCA_FETCH_STAGE_H

tools/llvm-mca/FetchStage.cpp

 //===----------------------------------------------------------------------===//
 
 #include "FetchStage.h"
 
 namespace mca {
 
 bool FetchStage::hasWorkToComplete() const { return SM.hasNext(); }
 
+void FetchStage::cycleStart(unsigned Cycle) { CurrentCycleCounter = 0; }
+
 bool FetchStage::execute(InstRef &IR) {
+  if (CurrentCycleCounter > 0)
+    SM.updateNext();
+  ++CurrentCycleCounter;
   if (!SM.hasNext())
     return false;
   const SourceRef SR = SM.peekNext();
   std::unique_ptr<Instruction> I = IB.createInstruction(*SR.second);
   IR = InstRef(SR.first, I.get());
   Instructions[IR.getSourceIndex()] = std::move(I);
   return true;
 }
 
-void FetchStage::postExecute(const InstRef &IR) {
+void FetchStage::cycleEnd(unsigned Cycle) {
   // Find the first instruction which hasn't been retired.
   const InstMap::iterator It =
       llvm::find_if(Instructions, [](const InstMap::value_type &KeyValuePair) {
         return !KeyValuePair.second->isRetired();
       });
   if (It != Instructions.begin())
     Instructions.erase(Instructions.begin(), It);
-  SM.updateNext();
 }
 
 } // namespace mca

tools/llvm-mca/Pipeline.h

class Pipeline {
   Pipeline &operator=(const Pipeline &P) = delete;
 
   /// An ordered list of stages that define this instruction pipeline.
   llvm::SmallVector<std::unique_ptr<Stage>, 8> Stages;
   std::set<HWEventListener *> Listeners;
   unsigned Cycles;
 
   bool executeStages(InstRef &IR);
-  void postExecuteStages(const InstRef &IR);
   bool hasWorkToProcess();
   void runCycle(unsigned Cycle);
 
 public:
   Pipeline(unsigned DispatchWidth = 0, unsigned RegisterFileSize = 0,
            unsigned LoadQueueSize = 0, unsigned StoreQueueSize = 0,
            bool AssumeNoAlias = false)
       : Cycles(0) {}

tools/llvm-mca/Pipeline.cpp

 // called on it.
 bool Pipeline::executeStages(InstRef &IR) {
   for (const std::unique_ptr<Stage> &S : Stages)
     if (!S->execute(IR))
       return false;
   return true;
 }
 
-void Pipeline::postExecuteStages(const InstRef &IR) {
-  for (const std::unique_ptr<Stage> &S : Stages)
-    S->postExecute(IR);
-}
-
 void Pipeline::run() {
   while (hasWorkToProcess())
     runCycle(Cycles++);
 }
 
 void Pipeline::runCycle(unsigned Cycle) {
   notifyCycleBegin(Cycle);
 
   // Update the stages before we do any processing for this cycle.
   InstRef IR;
   for (auto &S : Stages)
-    S->preExecute(IR);
+    S->cycleStart(Cycle);
 
   // Continue executing this cycle until any stage claims it cannot make
   // progress.
-  while (executeStages(IR))
-    postExecuteStages(IR);
+  while (true)
+    if (!executeStages(IR))
+      break;
+
+  for (auto &S : Stages)
+    S->cycleEnd(Cycle);
 
   notifyCycleEnd(Cycle);
 }
 
 void Pipeline::notifyCycleBegin(unsigned Cycle) {
   LLVM_DEBUG(dbgs() << "[E] Cycle begin: " << Cycle << '\n');
   for (HWEventListener *Listener : Listeners)
     Listener->onCycleBegin();
 }
 
 void Pipeline::notifyCycleEnd(unsigned Cycle) {
   LLVM_DEBUG(dbgs() << "[E] Cycle end: " << Cycle << "\n\n");
   for (HWEventListener *Listener : Listeners)
     Listener->onCycleEnd();
 }
 } // namespace mca.

tools/llvm-mca/RetireStage.h

public:
   RetireStage(RetireControlUnit &R, RegisterFile &F)
       : Stage(), RCU(R), PRF(F) {}
   RetireStage(const RetireStage &Other) = delete;
   RetireStage &operator=(const RetireStage &Other) = delete;
 
   virtual bool hasWorkToComplete() const override final {
     return !RCU.isEmpty();
   }
-  virtual void preExecute(const InstRef &IR) override final;
+  virtual void cycleStart(unsigned Cycle) override final;
   virtual bool execute(InstRef &IR) override final { return true; }
   void notifyInstructionRetired(const InstRef &IR);
   void onInstructionExecuted(unsigned TokenID);
 };
 
 } // namespace mca
 
 #endif // LLVM_TOOLS_LLVM_MCA_RETIRE_STAGE_H

tools/llvm-mca/RetireStage.cpp

 #include "llvm/Support/Debug.h"
 
 using namespace llvm;
 
 #define DEBUG_TYPE "llvm-mca"
 
 namespace mca {
 
-void RetireStage::preExecute(const InstRef &IR) {
+void RetireStage::cycleStart(unsigned Cycle) {
   if (RCU.isEmpty())
     return;
 
   const unsigned MaxRetirePerCycle = RCU.getMaxRetirePerCycle();
   unsigned NumRetired = 0;
   while (!RCU.isEmpty()) {
     if (MaxRetirePerCycle != 0 && NumRetired == MaxRetirePerCycle)
       break;

tools/llvm-mca/Stage.h

public:
   virtual ~Stage() = default;
 
   /// Called prior to preExecute to ensure that the stage has items that it
   /// is to process.  For example, a FetchStage might have more instructions
   /// that need to be processed, or a RCU might have items that have yet to
   /// retire.
   virtual bool hasWorkToComplete() const = 0;
 
-  /// Called as a setup phase to prepare for the main stage execution.
-  virtual void preExecute(const InstRef &IR) {}
+  /// Called once at the start of each cycle.  This can be used as a setup
+  /// phase to prepare for the executions during the cycle.
+  virtual void cycleStart(unsigned Cycle) {}
 
-  /// Called as a cleanup and finalization phase after main stage execution.
-  virtual void postExecute(const InstRef &IR) {}
+  /// Called once at the end of each cycle.
+  virtual void cycleEnd(unsigned Cycle) {}
 
   /// The primary action that this stage performs.
   /// Returning false prevents successor stages from having their 'execute'
-  /// routine called.
+  /// routine called.  This can be called multiple times during a single cycle.
   virtual bool execute(InstRef &IR) = 0;
 
   /// Add a listener to receive callbacks during the execution of this stage.
   void addListener(HWEventListener *Listener);
 
   virtual void notifyInstructionEvent(const HWInstructionEvent &Event);
 };
 
 } // namespace mca
 #endif // LLVM_TOOLS_LLVM_MCA_STAGE_H