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

   1 #ifndef LTT_H
   2 #define LTT_H
   3
   4
   5 /* A trace is associated with a tracing session run on a single, possibly
   6    multi-cpu, system. It is defined as a pathname to a directory containing
   7    all the relevant trace files. All the tracefiles for a trace were
   8    generated in a single system for the same time period by the same
   9    trace daemon. They simply contain different events. Typically a "control"
  10    tracefile contains the important events (process creations and registering
  11    tracing facilities) for all CPUs, and one file for each CPU contains all
  12    the events for that CPU. All the tracefiles within the same trace directory
  13    then use the exact same id numbers for event types.
  14
  15    A tracefile (ltt_tracefile) contains a list of events (ltt_event) sorted
  16    by time for each CPU; events from different CPUs may be slightly out of
  17    order, especially using the (possibly drifting) cycle counters as
  18    time unit.
  19
  20    A facility is a list of event types (ltt_eventtype), declared in a special
  21    .event file. An associated checksum differentiates different facilities
  22    which would have the same name but a different content (e.g., different
  23    versions). The .event files are stored within the trace directory, or
  24    in the default path, and are accessed automatically upon opening a trace.
  25    The list of facilities (and associated checksum) used in a trace
  26    must be known in order to properly decode the contained events. An event
  27    is usually stored in the "control" tracefile to denote each different
  28    "facility used".
  29
  30    Event types (ltt_eventtype) refer to data types (ltt_type) describing
  31    their content. The data types supported are integer and unsigned integer
  32    (of various length), enumerations (a special form of unsigned integer),
  33    floating point (of various length), fixed size arrays, sequence
  34    (variable sized arrays), structures and null terminated strings.
  35    The elements of arrays and sequences, and the data members for
  36    structures, may be of any nested data type (ltt_type).
  37
  38    An ltt_field is a special object to denote a specific, possibly nested,
  39    field within an event type. Suppose an event type socket_connect is a
  40    structure containing two data members, source and destination, of type
  41    socket_address. Type socket_address contains two unsigned integer
  42    data members, ip and port. An ltt_field is different from a data type
  43    structure member since it can denote a specific nested field, like the
  44    source port, and store associated access information (byte offset within
  45    the event data). The ltt_field objects are trace specific since the
  46    contained information (byte offsets) may vary with the architecture
  47    associated to the trace. */
  48
  49 typedef struct _ltt_trace ltt_trace;
  50
  51 typedef struct _ltt_tracefile ltt_tracefile;
  52
  53 typedef struct _ltt_facility ltt_facility;
  54
  55 typedef struct _ltt_eventtype ltt_eventtype;
  56
  57 typedef struct _ltt_type ltt_type;
  58
  59 typedef struct _ltt_field ltt_field;
  60
  61 typedef struct _ltt_event ltt_event;
  62
  63
  64 /* Checksums are used to differentiate facilities which have the same name
  65    but differ. */
  66
  67 typedef unsigned long ltt_checksum;
  68
  69
  70 /* Events are usually stored with the easily obtained CPU clock cycle count,
  71    ltt_cycle_count. This can be converted to the real time value, ltt_time,
  72    using linear interpolation between regularly sampled values (e.g. a few
  73    times per second) of the real time clock with their corresponding
  74    cycle count values. */
  75
  76 typedef struct timespec ltt_time;
  77
  78 typedef uint64_t ltt_cycle_count;
  79
  80
  81 /* Differences between architectures include word sizes, endianess,
  82    alignment, floating point format and calling conventions. For a
  83    packed binary trace, endianess and size matter, assuming that the
  84    floating point format is standard (and is seldom used anyway). */
  85
  86 typedef enum _ltt_arch_size
  87 { LTT_LP32, LTT_ILP32, LTT_LP64, LTT_ILP64, LTT_UNKNOWN
  88 } ltt_arch_size;
  89
  90
  91 typedef enum _ltt_arch_endian
  92 { LTT_LITTLE_ENDIAN, LTT_BIG_ENDIAN
  93 } ltt_arch_endian;
  94
  95
  96
  97 #include <ltt/ltt-private.h>
  98
  99
 100 #endif // LTT_H