From 4f8ac94549b46764df5c2dc5854a78268cb94d08 Mon Sep 17 00:00:00 2001
From: Joel Hestness <jthestness@gmail.com>
Date: Mon, 9 Jun 2014 22:01:16 -0500
Subject: [PATCH] sim: More rigorous clocking comments

The language describing the clockEdge and nextCycle functions were ambiguous,
and so were prone to misinterpretation/misuse. Clear up the comments to more
rigorously describe their functionality.
---
 src/sim/clocked_object.hh | 31 +++++++++++++++++++++----------
 1 file changed, 21 insertions(+), 10 deletions(-)

diff --git a/src/sim/clocked_object.hh b/src/sim/clocked_object.hh
index fb020f567..d878f4704 100644
--- a/src/sim/clocked_object.hh
+++ b/src/sim/clocked_object.hh
@@ -79,7 +79,8 @@ class ClockedObject : public SimObject
     ClockedObject& operator=(ClockedObject&);
 
     /**
-     *  Align cycle and tick to the next clock edge if not already done.
+     *  Align cycle and tick to the next clock edge if not already done. When
+     *  complete, tick must be at least curTick().
      */
     void update() const
     {
@@ -154,13 +155,18 @@ class ClockedObject : public SimObject
     }
 
     /**
-     * Determine the tick when a cycle begins, by default the current
-     * one, but the argument also enables the caller to determine a
-     * future cycle.
+     * Determine the tick when a cycle begins, by default the current one, but
+     * the argument also enables the caller to determine a future cycle. When
+     * curTick() is on a clock edge, the number of cycles in the parameter is
+     * added to curTick() to be returned. When curTick() is not aligned to a
+     * clock edge, the number of cycles in the parameter is added to the next
+     * clock edge.
      *
      * @param cycles The number of cycles into the future
      *
-     * @return The tick when the clock edge occurs
+     * @return The start tick when the requested clock edge occurs. Precisely,
+     * this tick can be
+     *     curTick() + [0, clockPeriod()) + clockPeriod() * cycles
      */
     inline Tick clockEdge(Cycles cycles = Cycles(0)) const
     {
@@ -175,7 +181,9 @@ class ClockedObject : public SimObject
      * Determine the current cycle, corresponding to a tick aligned to
      * a clock edge.
      *
-     * @return The current cycle count
+     * @return When curTick() is on a clock edge, return the Cycle corresponding
+     * to that clock edge. When curTick() is not on a clock edge, return the
+     * Cycle corresponding to the next clock edge.
      */
     inline Cycles curCycle() const
     {
@@ -186,11 +194,14 @@ class ClockedObject : public SimObject
     }
 
     /**
-     * Based on the clock of the object, determine the tick when the next
-     * cycle begins, in other words, return the next clock edge.
-     * (This can never be the current tick.)
+     * Based on the clock of the object, determine the start tick of the first
+     * cycle that is at least one cycle in the future. When curTick() is at the
+     * current cycle edge, this returns the next clock edge. When calling this
+     * during the middle of a cycle, this returns 2 clock edges in the future.
      *
-     * @return The tick when the next cycle starts
+     * @return The start tick of the first cycle that is at least one cycle in
+     * the future. Precisely, the returned tick can be in the range
+     *     curTick() + [clockPeriod(), 2 * clockPeriod())
      */
     Tick nextCycle() const
     { return clockEdge(Cycles(1)); }