Additional comments and helper functions for PrintReq.

--HG--
extra : convert_revision : 7eadf9b7db8c0289480f771271b6efe2400006d4

src/base/printable.hh

@@ -36,6 +36,11 @@
 #include <ostream>
 #include <string>
 
+/**
+ * Abstract base class for objects which support being printed
+ * to a stream for debugging.  Primarily used to support PrintReq
+ * in memory system.
+ */
 class Printable
 {
   public:

src/cpu/memtest/memtest.cc

@@ -394,15 +394,16 @@ MemTest::doRetry()
     }
 }
 
-MemTest *
-MemTestParams::create()
-{
-    return new MemTest(this);
-}
-
 
 void
 MemTest::printAddr(Addr a)
 {
     cachePort.printAddr(a);
 }
+
+
+MemTest *
+MemTestParams::create()
+{
+    return new MemTest(this);
+}

src/cpu/memtest/memtest.hh

@@ -62,6 +62,10 @@ class MemTest : public MemObject
 
     virtual Port *getPort(const std::string &if_name, int idx = -1);
 
+    /**
+     * Print state of address in memory system via PrintReq (for
+     * debugging).
+     */
     void printAddr(Addr a);
 
   protected:

src/cpu/simple/atomic.cc

@@ -783,6 +783,13 @@ AtomicSimpleCPU::tick()
 }
 
 
+void
+AtomicSimpleCPU::printAddr(Addr a)
+{
+    dcachePort.printAddr(a);
+}
+
+
 ////////////////////////////////////////////////////////////////////////
 //
 //  AtomicSimpleCPU Simulation Object

src/cpu/simple/atomic.hh

@@ -156,6 +156,12 @@ class AtomicSimpleCPU : public BaseSimpleCPU
             int size, unsigned flags);
     Fault translateDataWriteAddr(Addr vaddr, Addr &paddr,
             int size, unsigned flags);
+
+    /**
+     * Print state of address in memory system via PrintReq (for
+     * debugging).
+     */
+    void printAddr(Addr a);
 };
 
 #endif // __CPU_SIMPLE_ATOMIC_HH__

src/cpu/simple/timing.cc

@@ -822,6 +822,13 @@ TimingSimpleCPU::IprEvent::description()
 }
 
 
+void
+TimingSimpleCPU::printAddr(Addr a)
+{
+    dcachePort.printAddr(a);
+}
+
+
 ////////////////////////////////////////////////////////////////////////
 //
 //  TimingSimpleCPU Simulation Object

src/cpu/simple/timing.hh

@@ -203,6 +203,12 @@ class TimingSimpleCPU : public BaseSimpleCPU
     void completeDataAccess(PacketPtr );
     void advanceInst(Fault fault);
 
+    /**
+     * Print state of address in memory system via PrintReq (for
+     * debugging).
+     */
+    void printAddr(Addr a);
+
   private:
 
     typedef EventWrapper<TimingSimpleCPU, &TimingSimpleCPU::fetch> FetchEvent;

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;

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();

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",

src/sim/sim_object.hh

@@ -133,7 +133,7 @@ class SimObject : public Serializable, protected StartupCallback
 
     /**
      * Find the SimObject with the given name and return a pointer to
-     * it.  Priarily used for interactive debugging.  Argument is
+     * it.  Primarily used for interactive debugging.  Argument is
      * char* rather than std::string to make it callable from gdb.
      */
     static SimObject *find(const char *name);