+#ifndef LTT_H
+#define LTT_H
-#include <ltt/ltt-private.h>
+#include <ltt/LTTTypes.h>
/* A trace is associated with a tracing session run on a single, possibly
multi-cpu, system. It is defined as a pathname to a directory containing
all the relevant trace files. All the tracefiles for a trace were
generated in a single system for the same time period by the same
- trace daemon. They simply contain different events. Typically one file
- contains the important events (process creations and registering tracing
- facilities) for all CPUs, and one file for each CPU contains all the
- events for that CPU. All the tracefiles within the same trace directory
+ trace daemon. They simply contain different events. Typically control
+ tracefiles contain the important events (process creations and registering
+ tracing facilities) for all CPUs, and one file for each CPU contains all
+ the events for that CPU. All the tracefiles within the same trace directory
then use the exact same id numbers for event types.
- A tracefile (ltt_tracefile) contains a list of events (ltt_event) sorted
+ A tracefile (LttTracefile) contains a list of events (LttEvent) sorted
by time for each CPU; events from different CPUs may be slightly out of
order, especially using the (possibly drifting) cycle counters as
time unit.
- A facility is a list of event types (ltt_eventtype), declared in a special
- .event file. An associated checksum differentiates different facilities
- which would have the same name but a different content (e.g., different
- versions).
-
- The list of facilities (and associated checksum) used in a tracefile
+ A facility is a list of event types (LttEventType), declared in a special
+ eventdefs file. A corresponding checksum differentiates different
+ facilities which would have the same name but a different content
+ (e.g., different versions). The files are stored within the trace
+ directory and are accessed automatically upon opening a trace.
+ The list of facilities (and associated checksum) used in a trace
must be known in order to properly decode the contained events. An event
- is usually stored in the trace to denote each different "facility used".
- While many facilities may be present when the trace starts, new
- facilities may be introduced later as kernel modules are loaded.
- This is fine as long as the "facility used" event precedes any event
- described in that facility.
+ is stored in the "facilities" control tracefile to denote each different
+ facility used.
- Event types (ltt_eventtype) refer to data types (ltt_type) describing
+ Event types (LttEventType) refer to data types (LttType) describing
their content. The data types supported are integer and unsigned integer
(of various length), enumerations (a special form of unsigned integer),
floating point (of various length), fixed size arrays, sequence
(variable sized arrays), structures and null terminated strings.
The elements of arrays and sequences, and the data members for
- structures, may be of any nested data type (ltt_type).
+ structures, may be of any nested data type (LttType).
- An ltt_field is a special object to denote a specific, possibly nested,
+ An LttField is a special object to denote a specific, possibly nested,
field within an event type. Suppose an event type socket_connect is a
- structure containing two data membes, source and destination, of type
+ structure containing two data members, source and destination, of type
socket_address. Type socket_address contains two unsigned integer
- data members, ip and port. An ltt_field is different from a data type
+ data members, ip and port. An LttField is different from a data type
structure member since it can denote a specific nested field, like the
source port, and store associated access information (byte offset within
- the event data). The ltt_field objects are tracefile specific since the
+ the event data). The LttField objects are trace specific since the
contained information (byte offsets) may vary with the architecture
- associated to the tracefile. */
+ associated to the trace. */
-typedef struct _ltt_tracefile ltt_tracefile;
-
-typedef struct _ltt_facility ltt_facility;
+typedef struct _LttTrace LttTrace;
-typedef struct _ltt_eventtype ltt_eventtype;
+typedef struct _LttTracefile LttTracefile;
-typedef struct _ltt_type ltt_type;
+typedef struct _LttFacility LttFacility;
-typedef struct _ltt_field ltt_field;
+typedef struct _LttEventType LttEventType;
-typedef struct _ltt_event ltt_event;
+typedef struct _LttType LttType;
+typedef struct _LttField LttField;
-/* Different types allowed */
-
-typedef enum _ltt_type_enum
-{ LTT_INT, LTT_UINT, LTT_FLOAT, LTT_STRING, LTT_ENUM, LTT_ARRAY,
- LTT_SEQUENCE, LTT_STRUCT
-} ltt_type_enum;
+typedef struct _LttEvent LttEvent;
+typedef struct _LttSystemDescription LttSystemDescription;
/* Checksums are used to differentiate facilities which have the same name
but differ. */
-typedef unsigned long ltt_checksum;
+typedef unsigned long LttChecksum;
/* Events are usually stored with the easily obtained CPU clock cycle count,
times per second) of the real time clock with their corresponding
cycle count values. */
-typedef struct timespec ltt_time;
+typedef struct _LttTime {
+ unsigned long tv_sec;
+ unsigned long tv_nsec;
+} LttTime;
+
+typedef uint64_t LttCycleCount;
+
+
+/* Differences between architectures include word sizes, endianess,
+ alignment, floating point format and calling conventions. For a
+ packed binary trace, endianess and size matter, assuming that the
+ floating point format is standard (and is seldom used anyway). */
+
+typedef enum _LttArchSize
+{ LTT_LP32, LTT_ILP32, LTT_LP64, LTT_ILP64, LTT_UNKNOWN
+} LttArchSize;
+
+
+typedef enum _LttArchEndian
+{ LTT_LITTLE_ENDIAN, LTT_BIG_ENDIAN
+} LttArchEndian;
+
+/* Time operation macros for LttTime (struct timespec) */
+/* (T3 = T2 - T1) */
+#define TimeSub(T3, T2, T1) \
+do \
+{\
+ (T3).tv_sec = (T2).tv_sec - (T1).tv_sec; \
+ (T3).tv_nsec = (T2).tv_nsec - (T1).tv_nsec; \
+ if((T3).tv_nsec < 0)\
+ {\
+ (T3).tv_sec--;\
+ (T3).tv_nsec += 1000000000;\
+ }\
+} while(0)
+
+/* (T3 = T2 + T1) */
+#define TimeAdd(T3, T2, T1) \
+do \
+{\
+ (T3).tv_sec = (T2).tv_sec + (T1).tv_sec; \
+ (T3).tv_nsec = (T2).tv_nsec + (T1).tv_nsec; \
+ if((T3).tv_nsec >= 1000000000)\
+ {\
+ (T3).tv_sec += (T3).tv_nsec / 1000000000;\
+ (T3).tv_nsec = (T3).tv_nsec % 1000000000;\
+ }\
+} while(0)
+
+/* (T2 = T1 * FLOAT) */
+/* WARNING : use this multiplicator carefully : on 32 bits, multiplying
+ * by more than 4 could overflow the tv_nsec.
+ */
+#define TimeMul(T2, T1, FLOAT) \
+do \
+{\
+ (T2).tv_sec = (T1).tv_sec * (FLOAT); \
+ (T2).tv_nsec = (T1).tv_nsec * (FLOAT); \
+ if((T2).tv_nsec >= 1000000000)\
+ {\
+ (T2).tv_sec += (T2).tv_nsec / 1000000000;\
+ (T2).tv_nsec = (T2).tv_nsec % 1000000000;\
+ }\
+} while(0)
-typedef uint64_t ltt_cycle_count;
+#include <ltt/ltt-private.h>
+
+#endif // LTT_H