[llvm-mca] Update the comments for the mca:::Stage class. NFC.

[mattd]

Summary

• Updated to reflect the recent changes to the mca::Status return value for Stage::execute.
• Updated to be clearer (e.g., use the word 'processing' in place of 'execute' where it makes sense).

[andreadb]

Hi Matt,

Thanks for this patch. See my comments below.

Thanks
-Andrea

tools/llvm-mca/Stage.h

33

here "primary action" is repeated in the same sentence.

75

s/the clock cycle/this cycle

93–94

This is what I find particularly difficult to read. Maybe you should explain this part a bit better.
Basically, 'execute' is _only_ called on instructions that have been added to the pipeline in the current cycle.

Also (surprisingly) method 'execute' is called on every stage of the pipeline. We shouldn't be calling it if we know that a new instruction hasn't been moved to the next stage during this cycle. At the moment, it is called on every stage of the pipeline regardless of whether the new instruction has successfully transitioned to the next stage.
I find this design a bit awkward and hard to follow. We should revisit this design soon as this doesn't feel right.

"Stop" means:

• this stage cannot process any more instructions during this cycle.

There may be several reasons why a Stage returns "Stop". The most common case is: "this stage has run out of resources, so it cannot accept new instructions during this cycle".

Add an example:

(example: there is a limit to how many instructions can be dispatched to the schedulers every cycle. Basically, the dispatch throughput cannot be infinite, and there is a constraint on the maximum size of a dispatch group. At some point, the DispatchStage has to "stop").

"Continue" means: this stage has still resources to "execute" instruction during this same cycle. Unfortunately, it doesn't say if the instruction was successfully processed! So, this may be a bit misleading. Also, it doesn't say if the instruction is allowed to transition to the next stage. If we don't change this design, then we should early-exit from the loop (it makes no sense to call execute(IR) on a next stage, if IR is still stuck on a previous stage!).

[mattd]

Abandoning this change, it is outdated.

tools/llvm-mca/Stage.h

 #include "HWEventListener.h"
 #include "llvm/Support/Error.h"
 #include <set>
 
 namespace mca {
 
 class InstRef;
 
+/// The Stage class represents a stage of an instruction pipeline.  Stages
+/// have three main callback methods that are responsible for fulfilling the
+/// logic of what the stage represents.  These three callbacks are:
+/// preExecute, execute, and postExecute.  These routines are called by the
+/// Pipeline class to prepare, process, and cleanup an instruction (InstRef).
+/// The primary action of a stage is its 'execute' method, which takes as input
+/// an InstRef and can perform the stage's primary action with respect to that
+/// instruction.  That instruction is passed from stage-to-stage by the
+/// pipeline.  The pre/execute/post methods can be called multiple times
+/// per clock cycle.
 class Stage {
   Stage(const Stage &Other) = delete;
   Stage &operator=(const Stage &Other) = delete;
   std::set<HWEventListener *> Listeners;
 
 public:
   /// A Stage's execute() returns Continue, Stop, or an error.  Returning
   /// Continue means that the stage successfully completed its 'execute'

 
 protected:
   const std::set<HWEventListener *> &getListeners() const { return Listeners; }
 
 public:
   Stage();
   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.
+  /// Called prior to processing any instructions within a pipeline.
+  /// This method is called once per clock cycle, and is used to determine if
+  /// the pipeline has completed all cycles necessary to simulate processing of
+  /// the instructions within a CodeRegion.  For example, a FetchStage might
+  /// have more instructions that need to be processed, or a RCU might have
+  /// items that have yet to retire.  This method can be used to tell the
+  /// pipeline that this stage has work remaining. If any stage returns
+  /// true, then pipeline processing will continue and process the next clock
+  /// cycle.
   virtual bool hasWorkToComplete() const = 0;
 
-  /// Called once at the start of each cycle.  This can be used as a setup
-  /// phase to prepare for the executions during the cycle.
+  /// Called by the pipeline once at the start of each clock cycle.
+  /// This can be used as a setup phase to prepare for any work that is
+  /// to be processed by this stage during the clock cycle.
   virtual void cycleStart() {}
 
-  /// Called once at the end of each cycle.
+  /// Called by the pipeline once at the end of each clock cycle.
   virtual void cycleEnd() {}
 
-  /// Called prior to executing the list of stages.
-  /// This can be called multiple times per cycle.
+  /// Called by the pipeline prior to calling 'execute' on its list of stages.
+  /// This can be called multiple times per clock cycle.
   virtual void preExecute() {}
 
-  /// 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.
+  /// Called by the pipeline as a cleanup and finalization phase after running
+  /// the 'execute' method for all of the stages it owns.
+  /// This will only be called if all of the pipeline's stages return
+  /// 'Continue' from their 'execute' method.  This can be called multiple
+  /// times per clock cycle.
   virtual void postExecute() {}
 
-  /// The primary action that this stage performs.
-  /// Returning false prevents successor stages from having their 'execute'
-  /// routine called.  This can be called multiple times during a single cycle.
+  /// The primary action that this stage performs on an instruction (InstRef).
+  /// Returning 'Stop' prevents successor stages during this cycle from having
+  /// their 'execute' method called.  This can be called multiple times during
+  /// a clock cycle.
   virtual Status execute(InstRef &IR) = 0;
 
-  /// Add a listener to receive callbacks during the execution of this stage.
+  /// Add a listener to receive callbacks during the processing 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