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

[Matt Davis via Phabricator via llvm-commits]

mattd created this revision.
mattd added a reviewer: andreadb.
Herald added subscribers: gbedwell, tschuett.

- 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).


https://reviews.llvm.org/D50745

Files:
  tools/llvm-mca/Stage.h


Index: tools/llvm-mca/Stage.h
===================================================================
--- tools/llvm-mca/Stage.h
+++ tools/llvm-mca/Stage.h
@@ -24,6 +24,16 @@
 
 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;
@@ -49,34 +59,43 @@
   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.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D50745.160717.patch
Type: text/x-patch
Size: 4137 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20180814/dcc43d1f/attachment.bin>