ltt/branches/poly/include/ltt/ltt.h

   1 #ifndef LTT_H
   2 #define LTT_H
   3
   4 #include <ltt/LTTTypes.h>
   5
   6 /* A trace is associated with a tracing session run on a single, possibly
   7    multi-cpu, system. It is defined as a pathname to a directory containing
   8    all the relevant trace files. All the tracefiles for a trace were
   9    generated in a single system for the same time period by the same
  10    trace daemon. They simply contain different events. Typically control
  11    tracefiles contain the important events (process creations and registering
  12    tracing facilities) for all CPUs, and one file for each CPU contains all
  13    the events for that CPU. All the tracefiles within the same trace directory
  14    then use the exact same id numbers for event types.
  15
  16    A tracefile (LttTracefile) contains a list of events (LttEvent) sorted
  17    by time for each CPU; events from different CPUs may be slightly out of
  18    order, especially using the (possibly drifting) cycle counters as
  19    time unit.
  20
  21    A facility is a list of event types (LttEventType), declared in a special
  22    eventdefs file. A corresponding checksum differentiates different
  23    facilities which would have the same name but a different content
  24    (e.g., different versions). The files are stored within the trace
  25    directory and are accessed automatically upon opening a trace.
  26    The list of facilities (and associated checksum) used in a trace
  27    must be known in order to properly decode the contained events. An event
  28    is stored in the "facilities" control tracefile to denote each different
  29    facility used.
  30
  31    Event types (LttEventType) refer to data types (LttType) describing
  32    their content. The data types supported are integer and unsigned integer
  33    (of various length), enumerations (a special form of unsigned integer),
  34    floating point (of various length), fixed size arrays, sequence
  35    (variable sized arrays), structures and null terminated strings.
  36    The elements of arrays and sequences, and the data members for
  37    structures, may be of any nested data type (LttType).
  38
  39    An LttField is a special object to denote a specific, possibly nested,
  40    field within an event type. Suppose an event type socket_connect is a
  41    structure containing two data members, source and destination, of type
  42    socket_address. Type socket_address contains two unsigned integer
  43    data members, ip and port. An LttField is different from a data type
  44    structure member since it can denote a specific nested field, like the
  45    source port, and store associated access information (byte offset within
  46    the event data). The LttField objects are trace specific since the
  47    contained information (byte offsets) may vary with the architecture
  48    associated to the trace. */
  49
  50 typedef struct _LttTrace LttTrace;
  51
  52 typedef struct _LttTracefile LttTracefile;
  53
  54 typedef struct _LttFacility LttFacility;
  55
  56 typedef struct _LttEventType LttEventType;
  57
  58 typedef struct _LttType LttType;
  59
  60 typedef struct _LttField LttField;
  61
  62 typedef struct _LttEvent LttEvent;
  63
  64 typedef struct _LttSystemDescription LttSystemDescription;
  65
  66 /* Checksums are used to differentiate facilities which have the same name
  67    but differ. */
  68
  69 typedef unsigned long LttChecksum;
  70
  71
  72 /* Events are usually stored with the easily obtained CPU clock cycle count,
  73    ltt_cycle_count. This can be converted to the real time value, ltt_time,
  74    using linear interpolation between regularly sampled values (e.g. a few
  75    times per second) of the real time clock with their corresponding
  76    cycle count values. */
  77
  78 typedef struct _LttTime {
  79   unsigned long tv_sec;
  80   unsigned long tv_nsec;
  81 } LttTime;
  82
  83
  84 typedef struct _TimeInterval{
  85   LttTime startTime;
  86   LttTime endTime;
  87 } TimeInterval;
  88
  89
  90 typedef uint64_t LttCycleCount;
  91
  92 #define NANSECOND_CONST       1000000000
  93
  94 /* Event positions are used to seek within a tracefile based on
  95    the block number and event position within the block. */
  96
  97 typedef struct _LttEventPosition LttEventPosition;
  98
  99
 100 /* Differences between architectures include word sizes, endianess,
 101    alignment, floating point format and calling conventions. For a
 102    packed binary trace, endianess and size matter, assuming that the
 103    floating point format is standard (and is seldom used anyway). */
 104
 105 typedef enum _LttArchSize
 106 { LTT_LP32, LTT_ILP32, LTT_LP64, LTT_ILP64, LTT_UNKNOWN
 107 } LttArchSize;
 108
 109
 110 typedef enum _LttArchEndian
 111 { LTT_LITTLE_ENDIAN, LTT_BIG_ENDIAN
 112 } LttArchEndian;
 113
 114 /* Time operation macros for LttTime (struct timespec) */
 115 /*  (T3 = T2 - T1) */
 116 #define TimeSub(T3, T2, T1) \
 117 do \
 118 {\
 119   (T3).tv_sec  = (T2).tv_sec  - (T1).tv_sec;  \
 120   if((T2).tv_nsec < (T1).tv_nsec)\
 121     {\
 122     (T3).tv_sec--;\
 123     (T3).tv_nsec = NANSECOND_CONST - (T1).tv_nsec + (T2).tv_nsec;\
 124     }\
 125   else\
 126     {\
 127     (T3).tv_nsec = (T2).tv_nsec - (T1).tv_nsec;\
 128     }\
 129 } while(0)
 130
 131 /*  (T3 = T2 + T1) */
 132 #define TimeAdd(T3, T2, T1) \
 133 do \
 134 {\
 135   (T3).tv_sec  = (T2).tv_sec  + (T1).tv_sec;  \
 136   (T3).tv_nsec = (T2).tv_nsec + (T1).tv_nsec; \
 137   if((T3).tv_nsec >= NANSECOND_CONST)\
 138     {\
 139     (T3).tv_sec += (T3).tv_nsec / NANSECOND_CONST;\
 140     (T3).tv_nsec = (T3).tv_nsec % NANSECOND_CONST;\
 141     }\
 142 } while(0)
 143
 144 /*  (T2 = T1 * FLOAT) */
 145 /* WARNING : use this multiplicator carefully : on 32 bits, multiplying
 146  * by more than 4 could overflow the tv_nsec.
 147  */
 148 #define TimeMul(T2, T1, FLOAT) \
 149 do \
 150 {\
 151   (T2).tv_sec  = (T1).tv_sec  * (FLOAT);  \
 152   (T2).tv_nsec = (T1).tv_nsec * (FLOAT);  \
 153   if((T2).tv_nsec >= NANSECOND_CONST)\
 154     {\
 155     (T2).tv_sec += (T2).tv_nsec / NANSECOND_CONST;\
 156     (T2).tv_nsec = (T2).tv_nsec % NANSECOND_CONST;\
 157     }\
 158 } while(0)
 159
 160
 161
 162
 163 #include <ltt/ltt-private.h>
 164
 165
 166 #endif // LTT_H