more POSIX wrappers added and improved docs

darshan-log-format.h

@@ -53,12 +53,22 @@ static char * const darshan_module_names[] =
     "PNETCDF"
 };
 
+/* the darshan_log_map structure is used to indicate the location of
+ * specific module data in a Darshan log. Note that 'off' and 'len' are
+ * the respective offset and length of the data in the file, in *uncompressed*
+ * terms -- this is nonintuitive since the data is compressed, but this is
+ * done so we can utilize the gzread interface for all Darshan log reading
+ * utilities. 
+ */
 struct darshan_log_map
 {
     uint64_t off;
     uint64_t len;
 };
 
+/* the darshan header stores critical metadata needed for correctly
+ * reading the contents of the corresponding Darshan log
+ */
 struct darshan_header
 {
     char version_string[8];
@@ -67,7 +77,7 @@ struct darshan_header
     struct darshan_log_map mod_map[DARSHAN_MAX_MODS];
 };
 
-/* statistics for the job as a whole */
+/* job-level metadata stored for this application */
 #define DARSHAN_JOB_METADATA_LEN 1024 /* including null terminator! */
 struct darshan_job
 {
@@ -79,6 +89,7 @@ struct darshan_job
     char metadata[DARSHAN_JOB_METADATA_LEN];
 };
 
+/* minimal record stored for each file/object accessed by Darshan */
 struct darshan_record
 {
     char* name;

darshan-posix-log-format.h

@@ -8,6 +8,7 @@
 
 #include "darshan-log-format.h"
 
+/* integer statistics for POSIX file records */
 enum darshan_posix_indices
 {
     POSIX_OPENS,              /* count of posix opens */
@@ -27,16 +28,16 @@ enum darshan_posix_indices
     POSIX_FDSYNCS,
 #endif
     POSIX_MODE,                /* mode of file */
-#if 0
     POSIX_BYTES_READ,          /* total bytes read */
     POSIX_BYTES_WRITTEN,       /* total bytes written */
     POSIX_MAX_BYTE_READ,       /* highest offset byte read */
     POSIX_MAX_BYTE_WRITTEN,    /* highest offset byte written */
-    CONSEC_READS,              /* count of consecutive reads */
-    CONSEC_WRITES,             /* count of consecutive writes */
-    SEQ_READS,                 /* count of sequential reads */
-    SEQ_WRITES,                /* count of sequential writes */
-    RW_SWITCHES,               /* number of times switched between read and write */
+    POSIX_CONSEC_READS,        /* count of consecutive reads */
+    POSIX_CONSEC_WRITES,       /* count of consecutive writes */ 
+    POSIX_SEQ_READS,           /* count of sequential reads */
+    POSIX_SEQ_WRITES,          /* count of sequential writes */
+    POSIX_RW_SWITCHES,         /* number of times switched between read and write */
+#if 0
     MEM_NOT_ALIGNED,           /* count of accesses not mem aligned */
     MEM_ALIGNMENT,             /* mem alignment in bytes */
     FILE_NOT_ALIGNED,          /* count of accesses not file aligned */
@@ -95,7 +96,7 @@ enum darshan_posix_indices
     POSIX_NUM_INDICES,
 };
 
-/* floating point statistics */
+/* floating point statistics for POSIX file records */
 enum darshan_posix_f_indices
 {
     /* NOTE: adjust cp_normalize_timestamps() function if any TIMESTAMPS are
@@ -126,6 +127,14 @@ enum darshan_posix_f_indices
     POSIX_F_NUM_INDICES,
 };
 
+/* file record structure for POSIX files. a record is created and stored for
+ * every POSIX file opened by the original application. For the POSIX module,
+ * the record includes:
+ *      - a corresponding record identifier (created by hashing the file path)
+ *      - the rank of the process which opened the file (-1 for shared files)
+ *      - integer file I/O statistics (open, read/write counts, etc)
+ *      - floating point I/O statistics (timestamps, cumulative timers, etc.)
+ */
 struct darshan_posix_file
 {
     darshan_record_id f_id;

darshan-runtime/darshan.h

@@ -66,6 +66,41 @@
 
 /* macros for manipulating module's counter variables */
 /* NOTE: */
+#define DARSHAN_COUNTER_SET(__rec_p, __counter, __value) do{ \
+    (__rec_p)->counters[__counter] = __value; \
+} while(0)
+
+#define DARSHAN_COUNTER_F_SET(__rec_p, __counter, __value) do{ \
+    (__rec_p)->fcounters[__counter] = __value; \
+} while(0)
+
+#define DARSHAN_COUNTER_INC(__rec_p, __counter, __value) do{ \
+    (__rec_p)->counters[__counter] = __value; \
+} while(0)
+
+#define DARSHAN_COUNTER_F_INC(__rec_p, __counter, __value) do{ \
+    (__rec_p)->fcounters[__counter] = __value; \
+} while(0)
+
+#define DARSHAN_COUNTER_F_INC_NO_OVERLAP(__rec_p, __tm1, __tm2, __last, __counter) do{ \
+    if(__tm1 > __last) \
+        DARSHAN_COUNTER_F_INC(__rec_p, __counter, (__tm2 - __tm1)); \
+    else \
+        DARSHAN_COUNTER_F_INC(__rec_p, __counter, (__tm2 - __last)); \
+    if(__tm2 > __last) \
+        __last = __tm2; \
+} while(0)
+
+#define DARSHAN_COUNTER_VALUE(__rec_p, __counter) \
+    ((__rec_p)->counters[__counter])
+
+#define DARSHAN_COUNTER_F_VALUE(__rec_p, __counter) \
+    ((__rec_p)->fcounters[__counter])
+
+#define DARSHAN_COUNTER_MAX(__rec_p, __counter, __value) do{ \
+    if((__rec_p)->counters[__counter] < __value) \
+        (__rec_p)->counters[__counter] = __value; \
+} while(0)
 
 /* module developers provide the following functions to darshan-core */
 struct darshan_module_funcs

darshan-util/darshan-posix-parser.c

@@ -177,6 +177,15 @@ int main(int argc, char **argv)
             "\t\tPOSIX_FREADS:\t%"PRIu64"\n"
             "\t\tPOSIX_FWRITES:\t%"PRIu64"\n"
             "\t\tPOSIX_MODE:\t%"PRIu64"\n"
+            "\t\tPOSIX_BYTES_READ:\t%"PRIu64"\n"
+            "\t\tPOSIX_BYTES_WRITTEN:\t%"PRIu64"\n"
+            "\t\tPOSIX_MAX_BYTE_READ:\t%"PRIu64"\n"
+            "\t\tPOSIX_MAX_BYTE_WRITTEN:\t%"PRIu64"\n"
+            "\t\tPOSIX_CONSEC_READS:\t%"PRIu64"\n"
+            "\t\tPOSIX_CONSEC_WRITES:\t%"PRIu64"\n"
+            "\t\tPOSIX_SEQ_READS:\t%"PRIu64"\n"
+            "\t\tPOSIX_SEQ_WRITES:\t%"PRIu64"\n"
+            "\t\tPOSIX_RW_SWITCHES:\t%"PRIu64"\n"
             "\t\tPOSIX_MAX_READ_TIME_SIZE:\t%"PRIu64"\n"
             "\t\tPOSIX_MAX_WRITE_TIME_SIZE:\t%"PRIu64"\n"
             "\t\tPOSIX_F_OPEN_TIMESTAMP:\t%lf\n"
@@ -196,6 +205,15 @@ int main(int argc, char **argv)
             next_file.counters[POSIX_FREADS],
             next_file.counters[POSIX_FWRITES],
             next_file.counters[POSIX_MODE],
+            next_file.counters[POSIX_BYTES_READ],
+            next_file.counters[POSIX_BYTES_WRITTEN],
+            next_file.counters[POSIX_MAX_BYTE_READ],
+            next_file.counters[POSIX_MAX_BYTE_WRITTEN],
+            next_file.counters[POSIX_CONSEC_READS],
+            next_file.counters[POSIX_CONSEC_WRITES],
+            next_file.counters[POSIX_SEQ_READS],
+            next_file.counters[POSIX_SEQ_WRITES],
+            next_file.counters[POSIX_RW_SWITCHES],
             next_file.counters[POSIX_MAX_READ_TIME_SIZE],
             next_file.counters[POSIX_MAX_WRITE_TIME_SIZE],
             next_file.fcounters[POSIX_F_OPEN_TIMESTAMP],