From af67631790afbfeba01b05f7ae2ca54ae27428f1 Mon Sep 17 00:00:00 2001
From: Korey Sewell <ksewell@umich.edu>
Date: Sat, 12 Feb 2011 10:14:34 -0500
Subject: [PATCH] inorder: comments for resource sked class

---
 src/cpu/inorder/resource_sked.hh | 67 +++++++++++++++++++++++++++++---
 1 file changed, 62 insertions(+), 5 deletions(-)

diff --git a/src/cpu/inorder/resource_sked.hh b/src/cpu/inorder/resource_sked.hh
index 22e29d728..e3c0c6bc1 100644
--- a/src/cpu/inorder/resource_sked.hh
+++ b/src/cpu/inorder/resource_sked.hh
@@ -35,6 +35,17 @@
 #include <vector>
 #include <list>
 
+/** ScheduleEntry class represents a single function that an instruction
+    wants to do at any pipeline stage. For example, if an instruction
+    needs to be decoded and do a branch prediction all in one stage
+    then each of those tasks would need it's own ScheduleEntry.
+
+    Each schedule entry corresponds to some resource that the instruction
+    wants to interact with.
+
+    The file pipeline_traits.cc shows how a typical instruction schedule is
+    made up of these schedule entries.
+*/
 class ScheduleEntry {
   public:
     ScheduleEntry(int stage_num, int _priority, int res_num, int _cmd = 0,
@@ -43,43 +54,89 @@ class ScheduleEntry {
         idx(_idx), priority(_priority)
     { }
 
-    // Stage number to perform this service.
+    /** Stage number to perform this service. */
     int stageNum;
 
-    // Resource ID to access
+    /** Resource ID to access */
     int resNum;
 
-    // See specific resource for meaning
+    /** See specific resource for meaning */
     unsigned cmd;
 
-    // See specific resource for meaning
+    /** See specific resource for meaning */
     unsigned idx;
 
-    // Some Resources May Need Priority
+    /** Some Resources May Need Priority */
     int priority;
 };
 
+/** The ResourceSked maintains the complete schedule
+    for an instruction. That schedule includes what
+    resources an instruction wants to acquire at each
+    pipeline stage and is represented by a collection
+    of ScheduleEntry objects (described above) that
+    must be executed in-order.
+
+    In every pipeline stage, the InOrder model will
+    process all entries on the resource schedule for
+    that stage and then send the instruction to the next
+    stage if and only if the instruction successfully
+    completed each ScheduleEntry.
+*/
 class ResourceSked {
   public:
     typedef std::list<ScheduleEntry*>::iterator SkedIt;
 
     ResourceSked();
 
+    /** Initializee the current entry pointer to
+        pipeline stage 0 and the 1st schedule entry
+    */
     void init();
 
+    /** Goes through the remaining stages on the schedule
+        and sums all the remaining entries left to be
+        processed
+    */
     int size();
+
+    /** Is the schedule empty? */
     bool empty();
+
+    /** What is the next task for this instruction schedule? */
     ScheduleEntry* top();
+
+    /** Top() Task is completed, remove it from schedule */
     void pop();
+
+    /** Add To Schedule based on stage num and priority of
+        Schedule Entry
+    */
     void push(ScheduleEntry* sked_entry);
+
+    /** Add Schedule Entry to be in front of another Entry */
     void pushBefore(ScheduleEntry* sked_entry, int sked_cmd, int sked_cmd_idx);
+
+    /** Print what's left on the instruction schedule */
     void print();
 
   private:
+    /** Current Schedule Entry Pointer */
     SkedIt curSkedEntry;
+
+    /** The Resource Schedule: Resized to Number of Stages in
+        the constructor
+    */
     std::vector<std::list<ScheduleEntry*> > sked;
 
+    /** Find a place to insert the instruction using  the
+        schedule entries priority
+    */
     SkedIt findIterByPriority(ScheduleEntry *sked_entry, int stage_num);
+
+    /** Find a place to insert the instruction using a particular command
+        to look for.
+    */
     SkedIt findIterByCommand(ScheduleEntry *sked_entry, int stage_num,
                              int sked_cmd, int sked_cmd_idx = -1);
 };
-- 
2.30.2