ltt/branches/poly/ltt/ltt.h

   1 /* This file is part of the Linux Trace Toolkit trace reading library
   2  * Copyright (C) 2003-2004 Michel Dagenais
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License Version 2.1 as published by the Free Software Foundation.
   7  *
   8  * This library is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11  * Lesser General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public
  14  * License along with this library; if not, write to the
  15  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  16  * Boston, MA 02111-1307, USA.
  17  */
  18
  19 #ifndef LTT_H
  20 #define LTT_H
  21
  22 #include <glib.h>
  23 #include <ltt/time.h>
  24 #include <ltt/compiler.h>
  25
  26 /* A trace is associated with a tracing session run on a single, possibly
  27    multi-cpu, system. It is defined as a pathname to a directory containing
  28    all the relevant trace files. All the tracefiles for a trace were
  29    generated in a single system for the same time period by the same
  30    trace daemon. They simply contain different events. Typically control
  31    tracefiles contain the important events (process creations and registering
  32    tracing facilities) for all CPUs, and one file for each CPU contains all
  33    the events for that CPU. All the tracefiles within the same trace directory
  34    then use the exact same id numbers for event types.
  35
  36    A tracefile (LttTracefile) contains a list of events (LttEvent) sorted
  37    by time for each CPU; events from different CPUs may be slightly out of
  38    order, especially using the (possibly drifting) cycle counters as
  39    time unit.
  40
  41    A facility is a list of event types (LttEventType), declared in a special
  42    eventdefs file. A corresponding checksum differentiates different
  43    facilities which would have the same name but a different content
  44    (e.g., different versions). The files are stored within the trace
  45    directory and are accessed automatically upon opening a trace.
  46    The list of facilities (and associated checksum) used in a trace
  47    must be known in order to properly decode the contained events. An event
  48    is stored in the "facilities" control tracefile to denote each different
  49    facility used.
  50
  51    Event types (LttEventType) refer to data types (LttType) describing
  52    their content. The data types supported are integer and unsigned integer
  53    (of various length), enumerations (a special form of unsigned integer),
  54    floating point (of various length), fixed size arrays, sequence
  55    (variable sized arrays), structures and null terminated strings.
  56    The elements of arrays and sequences, and the data members for
  57    structures, may be of any nested data type (LttType).
  58
  59    An LttField is a special object to denote a specific, possibly nested,
  60    field within an event type. Suppose an event type socket_connect is a
  61    structure containing two data members, source and destination, of type
  62    socket_address. Type socket_address contains two unsigned integer
  63    data members, ip and port. An LttField is different from a data type
  64    structure member since it can denote a specific nested field, like the
  65    source port, and store associated access information (byte offset within
  66    the event data). The LttField objects are trace specific since the
  67    contained information (byte offsets) may vary with the architecture
  68    associated to the trace. */
  69
  70 #define NUM_FACILITIES 256
  71 #define AVG_EVENTS_PER_FACILITIES 10
  72
  73 typedef struct _LttTrace LttTrace;
  74
  75 typedef struct _LttTracefile LttTracefile;
  76
  77 typedef struct _LttFacility LttFacility;
  78
  79 typedef struct _LttEventType LttEventType;
  80
  81 typedef struct _LttType LttType;
  82
  83 typedef struct _LttField LttField;
  84
  85 typedef struct _LttEvent LttEvent;
  86
  87 typedef struct _LttSystemDescription LttSystemDescription;
  88
  89
  90 /* Checksums are used to differentiate facilities which have the same name
  91    but differ. */
  92
  93 //typedef guint32 LttChecksum;
  94
  95
  96 /* Events are usually stored with the easily obtained CPU clock cycle count,
  97    ltt_cycle_count. This can be converted to the real time value, LttTime,
  98    using linear interpolation between regularly sampled values (e.g. a few
  99    times per second) of the real time clock with their corresponding
 100    cycle count values. */
 101
 102
 103 typedef struct _TimeInterval{
 104   LttTime start_time;
 105   LttTime end_time;
 106 } TimeInterval;
 107
 108
 109 typedef guint64 LttCycleCount;
 110
 111
 112 /* Event positions are used to seek within a tracefile based on
 113    the block number and event position within the block. */
 114
 115 typedef struct _LttEventPosition LttEventPosition;
 116
 117
 118 /* Differences between architectures include word sizes, endianess,
 119    alignment, floating point format and calling conventions. For a
 120    packed binary trace, endianess and size matter, assuming that the
 121    floating point format is standard (and is seldom used anyway). */
 122
 123 typedef enum _LttArchSize
 124 { LTT_LP32, LTT_ILP32, LTT_LP64, LTT_ILP64, LTT_UNKNOWN
 125 } LttArchSize;
 126
 127
 128 typedef enum _LttArchEndian
 129 { LTT_LITTLE_ENDIAN, LTT_BIG_ENDIAN
 130 } LttArchEndian;
 131
 132 typedef enum _LttTypeEnum
 133 { LTT_INT, LTT_UINT, LTT_POINTER, LTT_LONG, LTT_ULONG, LTT_SIZE_T,
 134   LTT_SSIZE_T, LTT_OFF_T, LTT_FLOAT, LTT_STRING, LTT_ENUM, LTT_ARRAY,
 135   LTT_SEQUENCE, LTT_STRUCT, LTT_UNION
 136 } LttTypeEnum;
 137
 138
 139 #endif // LTT_H