i#2006 generalize drcachesim: expand trace entry docs

Cleans up and clarifies comments in memref.h and trace_entry.h to make
these key interface points easier to understand for new tool writers.

Review-URL: https://codereview.appspot.com/312950043

clients/drcachesim/common/memref.h

@@ -1,5 +1,5 @@
 /* **********************************************************
- * Copyright (c) 2015 Google, Inc.  All rights reserved.
+ * Copyright (c) 2015-2016 Google, Inc.  All rights reserved.
  * **********************************************************/
 
 /*
@@ -30,7 +30,7 @@
  * DAMAGE.
  */
 
-/* This is the data format that the simulator takes as input */
+/* This is the data format that the simulator and analysis tools take as input. */
 
 #ifndef _MEMREF_H_
 #define _MEMREF_H_ 1
@@ -47,12 +47,17 @@ typedef int_least64_t memref_tid_t;
 typedef struct _memref_t {
     memref_pid_t pid;
     memref_tid_t tid;
+
+    // The types are shared with trace_entry_t, but the types
+    // TRACE_TYPE_INSTR_BUNDLE, TRACE_TYPE_*_FLUSH_END, TRACE_TYPE_THREAD, and
+    // TRACE_TYPE_PID never show up here and are only found in trace_entry_t.
+    // The reader_t class places their data into other parts of memref_t.
     unsigned short type; // trace_type_t
 
-    // Fields below are here at not valid for TRACE_TYPE_THREAD_EXIT.
+    // Fields below here are not valid for TRACE_TYPE_THREAD_EXIT.
 
     size_t size;
-    addr_t addr;
+    addr_t addr; // Data or instruction address.
 
     // The pc field is only used for read, write, and prefetch entries.
     // XXX: should we remove it from here and have the simulator compute it

clients/drcachesim/common/trace_entry.h

@@ -48,6 +48,8 @@
 
 typedef uintptr_t addr_t;
 
+// The type identifier for trace entries in the raw trace_entry_t passed to
+// reader_t and the exposed memref_t passed to analysis tools.
 // XXX: if we want to rely on a recent C++ standard we could try to get
 // this enum to be just 2 bytes instead of an int and give it qualified names.
 // N.B.: when adding new values, be sure to update trace_type_names[].
@@ -74,12 +76,15 @@ typedef enum {
     TRACE_TYPE_PREFETCH_INSTR,
 
     // These entries describe an instruction fetch memory reference.
-    // The trace stream always has the instr fetch prior to data refs,
+    // The trace_entry_t stream always has the instr fetch prior to data refs,
     // which the reader can use to obtain the PC for data references.
+    // For memref_t, the instruction address is in the addr field.
     TRACE_TYPE_INSTR,
     // These entries describe a bundle of consecutive instruction fetch
     // memory references.  The trace stream always has a single instr fetch
     // prior to instr bundles which the reader can use to obtain the starting PC.
+    // This entry type is hidden by reader_t and expanded into a series of
+    // TRACE_TYPE_INSTR entries for memref_t.
     TRACE_TYPE_INSTR_BUNDLE,
 
     // A cache flush:
@@ -90,21 +95,24 @@ typedef enum {
     // the start address of flush, and one entry has type TRACE_TYPE_*_FLUSH_END
     // for the end address (exclusive) of flush.
     // The size field of both entries should be 0.
+    // The _END entries are hidden by reader_t as memref_t has space for the size.
     TRACE_TYPE_INSTR_FLUSH,
     TRACE_TYPE_INSTR_FLUSH_END,
     TRACE_TYPE_DATA_FLUSH,
     TRACE_TYPE_DATA_FLUSH_END,
 
     // These entries indicate that all subsequent memory references (until the
     // next entry of this type) came from the thread whose id is in the addr
-    // field:
+    // field.
+    // These entries are hidden by reader_t and turned into memref_t.tid.
     TRACE_TYPE_THREAD,
 
     // This entry indicates that the thread whose id is in the addr field exited:
     TRACE_TYPE_THREAD_EXIT,
 
     // These entries indicate which process the current thread belongs to.
     // The process id is in the addr field.
+    // These entries are hidden by reader_t and turned into memref_t.pid.
     TRACE_TYPE_PID,
 } trace_type_t;
 
@@ -116,6 +124,8 @@ type_is_prefetch(unsigned short type)
     return (type >= TRACE_TYPE_PREFETCH && type <= TRACE_TYPE_PREFETCH_INSTR);
 }
 
+// This is the data format generated by the online tracer.
+// The reader_t class transforms this into memref_t before handing to analysis tools.
 // Each trace entry is a <type, size, addr> tuple representing:
 // - a memory reference
 // - an instr fetch