Additional comments and helper functions for PrintReq.

--HG--
extra : convert_revision : 7eadf9b7db8c0289480f771271b6efe2400006d4

3 files changed, 35 insertions, 8 deletions

diff --git a/src/mem/cache/cache_blk.hh b/src/mem/cache/cache_blk.hh
index e7c2d1a02..bafb46a89 100644
--- a/src/mem/cache/cache_blk.hh
+++ b/src/mem/cache/cache_blk.hh
@@ -253,6 +253,12 @@ class CacheBlk
     }
 };
 
+/**
+ * Simple class to provide virtual print() method on cache blocks
+ * without allocating a vtable pointer for every single cache block.
+ * Just wrap the CacheBlk object in an instance of this before passing
+ * to a function that requires a Printable object.
+ */
 class CacheBlkPrintWrapper : public Printable
 {
     CacheBlk *blk;
diff --git a/src/mem/packet.hh b/src/mem/packet.hh
index c97413e85..30ef71507 100644
--- a/src/mem/packet.hh
+++ b/src/mem/packet.hh
@@ -299,7 +299,12 @@ class Packet : public FastAlloc, public Printable
         virtual ~SenderState() {}
     };
 
+    /**
+     * Object used to maintain state of a PrintReq.  The senderState
+     * field of a PrintReq should always be of this type.
+     */
     class PrintReqState : public SenderState {
+        /** An entry in the label stack. */
         class LabelStackEntry {
           public:
             const std::string label;
@@ -321,11 +326,23 @@ class Packet : public FastAlloc, public Printable
         PrintReqState(std::ostream &os, int verbosity = 0);
         ~PrintReqState();
 
+        /** Returns the current line prefix. */
         const std::string &curPrefix() { return *curPrefixPtr; }
+
+        /** Push a label onto the label stack, and prepend the given
+         * prefix string onto the current prefix.  Labels will only be
+         * printed if an object within the label's scope is
+         * printed. */
         void pushLabel(const std::string &lbl,
                        const std::string &prefix = "  ");
+        /** Pop a label off the label stack. */
         void popLabel();
+        /** Print all of the pending unprinted labels on the
+         * stack. Called by printObj(), so normally not called by
+         * users unless bypassing printObj(). */
         void printLabels();
+        /** Print a Printable object to os, because it matched the
+         * address on a PrintReq. */
         void printObj(Printable *obj);
     };
 
@@ -613,13 +630,7 @@ class Packet : public FastAlloc, public Printable
 
     /**
      * Check a functional request against a memory value stored in
-     * another packet (i.e. an in-transit request or response).  If
-     * possible, the request will be satisfied and transformed
-     * in-place into a response (at which point no further checking
-     * need be done).
-     *
-     * @return True if the memory location addressed by the request
-     * overlaps with the location addressed by otherPkt.
+     * another packet (i.e. an in-transit request or response).
      */
     bool checkFunctional(PacketPtr otherPkt) {
         return checkFunctional(otherPkt,
@@ -628,12 +639,18 @@ class Packet : public FastAlloc, public Printable
                                    otherPkt->getPtr<uint8_t>() : NULL);
     }
 
+    /**
+     * Push label for PrintReq (safe to call unconditionally).
+     */
     void pushLabel(const std::string &lbl) {
         if (isPrint()) {
             dynamic_cast<PrintReqState*>(senderState)->pushLabel(lbl);
         }
     }
 
+    /**
+     * Pop label for PrintReq (safe to call unconditionally).
+     */
     void popLabel() {
         if (isPrint()) {
             dynamic_cast<PrintReqState*>(senderState)->popLabel();
diff --git a/src/mem/physical.cc b/src/mem/physical.cc
index 40dc30afb..3560fc670 100644
--- a/src/mem/physical.cc
+++ b/src/mem/physical.cc
@@ -323,8 +323,12 @@ PhysicalMemory::doFunctionalAccess(PacketPtr pkt)
         TRACE_PACKET("Write");
         pkt->makeAtomicResponse();
     } else if (pkt->isPrint()) {
-        Packet::PrintReqState *prs = dynamic_cast<Packet::PrintReqState*>(pkt->senderState);
+        Packet::PrintReqState *prs =
+            dynamic_cast<Packet::PrintReqState*>(pkt->senderState);
+        // Need to call printLabels() explicitly since we're not going
+        // through printObj().
         prs->printLabels();
+        // Right now we just print the single byte at the specified address.
         ccprintf(prs->os, "%s%#x\n", prs->curPrefix(), *hostAddr);
     } else {
         panic("PhysicalMemory: unimplemented functional command %s",