[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

46 ↗

(On Diff #155270)

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.

49 ↗

(On Diff #155270)

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.

llvm/trunk/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() 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

llvm/trunk/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() {
   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;

llvm/trunk/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() 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);

llvm/trunk/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() {
   reclaimSchedulerResources();
   updateSchedulerQueues();
   issueReadyInstructions();
 }
 
 // Schedule the instruction for execution on the hardware.
 bool ExecuteStage::execute(InstRef &IR) {
 #ifndef NDEBUG

llvm/trunk/tools/llvm-mca/FetchStage.h

 public:
   FetchStage(InstrBuilder &IB, SourceMgr &SM) : IB(IB), SM(SM) {}
   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 cycleEnd() override final;
 };
 
 } // namespace mca
 
 #endif // LLVM_TOOLS_LLVM_MCA_FETCH_STAGE_H

llvm/trunk/tools/llvm-mca/FetchStage.cpp

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::postExecute(const InstRef &IR) { SM.updateNext(); }
+
+void FetchStage::cycleEnd() {
   // 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();
       });
+
+  // Erase instructions up to the first that hasn't been retired.
   if (It != Instructions.begin())
     Instructions.erase(Instructions.begin(), It);
-  SM.updateNext();
 }
 
 } // namespace mca

llvm/trunk/tools/llvm-mca/Pipeline.h

class Pipeline {
   Pipeline(const Pipeline &P) = delete;
   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;
 
+  void preExecuteStages(const InstRef &IR);
   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,

llvm/trunk/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::preExecuteStages(const InstRef &IR) {
+  for (const std::unique_ptr<Stage> &S : Stages)
+    S->preExecute(IR);
+}
+
 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();
 
   // Continue executing this cycle until any stage claims it cannot make
   // progress.
-  while (executeStages(IR))
+  while (true) {
+    preExecuteStages(IR);
+    if (!executeStages(IR))
+      break;
     postExecuteStages(IR);
+  }
+
+  for (auto &S : Stages)
+    S->cycleEnd();
 
   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.

llvm/trunk/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() 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

llvm/trunk/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() {
   if (RCU.isEmpty())
     return;
 
   const unsigned MaxRetirePerCycle = RCU.getMaxRetirePerCycle();
   unsigned NumRetired = 0;
   while (!RCU.isEmpty()) {
     if (MaxRetirePerCycle != 0 && NumRetired == MaxRetirePerCycle)
       break;

llvm/trunk/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.
+  /// 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() {}
+
+  /// Called once at the end of each cycle.
+  virtual void cycleEnd() {}
+
+  /// Called prior to executing the list of stages.
+  /// This can be called multiple times per cycle.
   virtual void preExecute(const InstRef &IR) {}
 
-  /// Called as a cleanup and finalization phase after main stage execution.
+  /// Called as a cleanup and finalization phase after each execution.
+  /// This will only be called if all stages return a success from their
+  /// execute callback.  This can be called multiple times per cycle.
   virtual void postExecute(const InstRef &IR) {}
 
   /// 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);
 
   /// Notify listeners of a particular hardware event.
   template <typename EventT> void notifyEvent(const EventT &Event) {
     for (HWEventListener *Listener : Listeners)
       Listener->onEvent(Event);
   }
 };
 
 } // namespace mca
 #endif // LLVM_TOOLS_LLVM_MCA_STAGE_H