Adjust the ltt API to reflect that facilities, types and fields belong to

[lttv.git] / ltt / branches / poly / include / ltt / ltt.h

diff --git a/ltt/branches/poly/include/ltt/ltt.h b/ltt/branches/poly/include/ltt/ltt.h
index 2208b925005fe7bee497439f1dc2fdf0bec27024..757005306d716ce9d5c141d216fbfa12b16fb874 100644 (file)
--- a/ltt/branches/poly/include/ltt/ltt.h
+++ b/ltt/branches/poly/include/ltt/ltt.h
@@ -6,10 +6,10 @@
    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 a "control"
+   tracefile 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
    then use the exact same id numbers for event types.
 
    A tracefile (ltt_tracefile) contains a list of events (ltt_event) sorted
@@ -20,15 +20,12 @@
    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 
+   versions). The .event files are stored within the trace directory, or
+   in the default path, 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 usually stored in the "control" tracefile to denote each different 
+   "facility used". 
 
    Event types (ltt_eventtype) refer to data types (ltt_type) describing
    their content. The data types supported are integer and unsigned integer 
@@ -40,15 +37,17 @@
 
    An ltt_field 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 
    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 ltt_field 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_trace ltt_trace;
+
 typedef struct _ltt_tracefile ltt_tracefile;
 
 typedef struct _ltt_facility ltt_facility;
@@ -62,14 +61,6 @@ typedef struct _ltt_field ltt_field;
 typedef struct _ltt_event ltt_event;
 
 
-/* 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;
-
-
 /* Checksums are used to differentiate facilities which have the same name
    but differ. */
 
@@ -86,10 +77,17 @@ typedef struct timespec ltt_time;
 
 typedef uint64_t ltt_cycle_count;
 
+
+/* 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 _ltt_arch_size 
 { LTT_LP32, LTT_ILP32, LTT_LP64, LTT_ILP64, LTT_UNKNOWN 
 } ltt_arch_size;
 
+
 typedef enum _ltt_arch_endian
 { LTT_LITTLE_ENDIAN, LTT_BIG_ENDIAN
 } ltt_arch_endian;