/* Obtain the trace unique integer id associated with the type of
this event */
-unsigned ltt_event_eventtype_id(ltt_event *e);
+unsigned ltt_event_eventtype_id(LttEvent *e);
/* Facility and type for the event */
-ltt_facility *ltt_event_facility(ltt_event *e);
+LttFacility *ltt_event_facility(LttEvent *e);
-ltt_eventtype *ltt_event_eventtype(ltt_event *e);
+LttEventType *ltt_event_eventtype(LttEvent *e);
/* Root field for the event */
-ltt_field *ltt_event_field(ltt_event *e);
+LttField *ltt_event_field(LttEvent *e);
/* Time and cycle count for the event */
-ltt_time ltt_event_time(ltt_event *e);
+LttTime ltt_event_time(LttEvent *e);
-ltt_cycle_count ltt_event_cycle_count(ltt_event *e);
+LttCycleCount ltt_event_cycle_count(LttEvent *e);
-/* CPU id and system name of the event */
+/* CPU id of the event */
-unsigned ltt_event_cpu_id(ltt_event *e);
-
-char *ltt_event_system_name(ltt_event *e);
+unsigned ltt_event_cpu_id(LttEvent *e);
/* Pointer to the raw data for the event. This should not be used directly
unless prepared to do all the architecture specific conversions. */
-void *ltt_event_data(ltt_event *e);
+void *ltt_event_data(LttEvent *e);
/* The number of elements in a sequence field is specific to each event.
This function returns the number of elements for an array or sequence
field in an event. */
-unsigned ltt_event_field_element_number(ltt_event *e, ltt_field *f);
+unsigned ltt_event_field_element_number(LttEvent *e, LttField *f);
/* Set the currently selected element for a sequence or array field. */
-int ltt_event_field_element_select(ltt_event *e, ltt_field *f, unsigned i);
+void ltt_event_field_element_select(LttEvent *e, LttField *f, unsigned i);
/* These functions extract data from an event after architecture specific
conversions. */
-unsigned ltt_event_get_unsigned(ltt_event *e, ltt_field *f);
+unsigned ltt_event_get_unsigned(LttEvent *e, LttField *f);
-int ltt_event_get_int(ltt_event *e, ltt_field *f);
+int ltt_event_get_int(LttEvent *e, LttField *f);
-unsigned long ltt_event_get_long_unsigned(ltt_event *e, ltt_field *f);
+unsigned long ltt_event_get_long_unsigned(LttEvent *e, LttField *f);
-long int ltt_event_get_long_int(ltt_event *e, ltt_field *f);
+long int ltt_event_get_long_int(LttEvent *e, LttField *f);
-float ltt_event_get_float(ltt_event *e, ltt_field *f);
+float ltt_event_get_float(LttEvent *e, LttField *f);
-double ltt_event_get_double(ltt_event *e, ltt_field *f);
+double ltt_event_get_double(LttEvent *e, LttField *f);
/* The string obtained is only valid until the next read from
the same tracefile. */
-char *ltt_event_get_string(ltt_event *e, ltt_field *f);
+char *ltt_event_get_string(LttEvent *e, LttField *f);
#endif // EVENT_H
with a facility are released when the trace is closed. Each facility
is characterized by its name and checksum. */
-char *ltt_facility_name(ltt_facility *f);
+char *ltt_facility_name(LttFacility *f);
-ltt_checksum ltt_facility_checksum(ltt_facility *f);
+LttChecksum ltt_facility_checksum(LttFacility *f);
/* Discover the event types within the facility. The event type integer id
type id within the trace is the relative id + the facility base event
id. */
-unsigned ltt_facility_base_id(ltt_facility *f);
+unsigned ltt_facility_base_id(LttFacility *f);
-unsigned ltt_facility_eventtype_number(ltt_facility *f);
+unsigned ltt_facility_eventtype_number(LttFacility *f);
-ltt_eventtype *ltt_facility_eventtype_get(ltt_facility *f, unsigned i);
+LttEventType *ltt_facility_eventtype_get(LttFacility *f, unsigned i);
-ltt_eventtype *ltt_facility_eventtype_get_by_name(ltt_facility *f, char *name);
+LttEventType *ltt_facility_eventtype_get_by_name(LttFacility *f, char *name);
#endif // FACILITY_H
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 a "control"
- tracefile contains the important events (process creations and registering
+ 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 .event files are stored within the trace directory, or
- in the default path, and are accessed automatically upon opening a trace.
+ 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 "control" tracefile to denote each different
- "facility used".
+ 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 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 trace 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 trace. */
-typedef struct _ltt_trace ltt_trace;
+typedef struct _LttTrace LttTrace;
-typedef struct _ltt_tracefile ltt_tracefile;
+typedef struct _LttTracefile LttTracefile;
-typedef struct _ltt_facility ltt_facility;
+typedef struct _LttFacility LttFacility;
-typedef struct _ltt_eventtype ltt_eventtype;
+typedef struct _LttEventType LttEventType;
-typedef struct _ltt_type ltt_type;
+typedef struct _LttType LttType;
-typedef struct _ltt_field ltt_field;
+typedef struct _LttField LttField;
-typedef struct _ltt_event ltt_event;
+typedef struct _LttEvent LttEvent;
/* 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 timespec LttTime;
-typedef uint64_t ltt_cycle_count;
+typedef uint64_t LttCycleCount;
/* Differences between architectures include word sizes, endianess,
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
+typedef enum _LttArchSize
{ LTT_LP32, LTT_ILP32, LTT_LP64, LTT_ILP64, LTT_UNKNOWN
-} ltt_arch_size;
+} LttArchSize;
-typedef enum _ltt_arch_endian
+typedef enum _LttArchEndian
{ LTT_LITTLE_ENDIAN, LTT_BIG_ENDIAN
-} ltt_arch_endian;
+} LttArchEndian;
#include <ltt/ltt.h>
/* A trace is specified as a pathname to the directory containing all the
- associated data (control tracefile, per cpu tracefiles, event
+ associated data (control tracefiles, per cpu tracefiles, event
descriptions...).
When a trace is closed, all the associated facilities, types and fields
are released as well. */
-ltt_trace *ltt_trace_open(char *pathname);
+LttTrace *ltt_trace_open(char *pathname);
-void ltt_trace_close(ltt_trace *t);
+void ltt_trace_close(LttTrace *t);
-/* A trace may be queried for its architecture type (e.g., "i386",
- "powerpc", "powerpcle", "s390", "s390x"), its architecture variant
- (e.g., "att" versus "sun" for m68k), its operating system (e.g., "linux",
- "bsd"), its generic architecture, and the machine identity (e.g., system
- host name). All character strings belong to the associated tracefile
- and are freed when it is closed. */
+/* The characteristics of the system on which the trace was obtained
+ is described in a LttSystemDescription structure. */
+typedef struct _LttSystemDescription {
+ char *description;
+ char *node_name;
+ char *domainname;
+ unsigned nb_cpu;
+ LttArchSize size;
+ LttArchEndian endian;
+ char *kernel_name;
+ char *kernel_release;
+ char *kernel_version;
+ char *machine;
+ char *processor;
+ char *hardware_platform;
+ char *operating_system;
+ unsigned ltt_major_version;
+ unsigned ltt_minor_version;
+ unsigned ltt_block_size;
+ LttTime trace_start;
+ LttTime trace_end;
+} LttSystemDescription;
-char *ltt_tracefile_arch_type(ltt_trace *t);
+LttSystemDescription *ltt_trace_system_description(LttTrace *t)
-char *ltt_tracefile_arch_variant(ltt_trace *t);
-char *ltt_tracefile_system_type(ltt_trace *t);
+/* Functions to discover the facilities in the trace. Once the number
+ of facilities is known, they may be accessed by position. Multiple
+ versions of a facility (same name, different checksum) have consecutive
+ positions. */
-ltt_arch_size ltt_tracefile_arch_size(ltt_trace *t);
+unsigned ltt_trace_facility_number(LttTrace *t);
-ltt_arch_endian ltt_tracefile_arch_endian(ltt_trace *t);
+LttFacility *ltt_trace_facility_get(LttTrace *t, unsigned i);
-/* Hostname of the system where the trace was recorded */
+/* Look for a facility by name. It returns the number of facilities found
+ and sets the position argument to the first found. Returning 0, the named
+ facility is unknown, returning 1, the named facility is at the specified
+ position, returning n, the facilities are from position to
+ position + n - 1. */
-char *ltt_trace_system_name(ltt_tracefile *t);
+unsigned ltt_trace_facility_find(LttTrace *t, char *name, unsigned *position);
-/* SMP multi-processors have 2 or more CPUs */
-
-unsigned ltt_trace_cpu_number(ltt_trace *t);
-
-
-/* Start and end time of the trace and its duration */
-
-ltt_time ltt_tracefile_time_start(ltt_trace *t);
-
-ltt_time ltt_tracefile_time_end(ltt_trace *t);
-
-ltt_time ltt_tracefile_duration(ltt_tracefile *t);
+/* Functions to discover all the event types in the trace */
+unsigned ltt_trace_eventtype_number(LttTrace *t);
-/* Functions to discover the facilities in the trace */
+LttEventType *ltt_trace_eventtype_get(LttTrace *t, unsigned i);
-unsigned ltt_trace_facility_number(ltt_trace *t);
-ltt_facility *ltt_trace_facility_get(ltt_trace *t, unsigned i);
+/* There is one "per cpu" tracefile for each CPU, numbered from 0 to
+ the maximum number of CPU in the system. When the number of CPU installed
+ is less than the maximum, some positions are unused. There are also a
+ number of "control" tracefiles (facilities, interrupts...). */
-ltt_facility *ltt_trace_facility_get_by_name(ltt_trace *t, char *name);
+unsigned ltt_trace_control_tracefile_number(LttTrace *t);
+unsigned ltt_trace_per_cpu_tracefile_number(LttTrace *t);
-/* Functions to discover all the event types in the trace */
-unsigned ltt_trace_eventtype_number(ltt_tracefile *t);
+/* It is possible to search for the tracefiles by name or by CPU position.
+ The index within the tracefiles of the same type is returned if found
+ and a negative value otherwise. */
-ltt_eventtype *ltt_trace_eventtype_get(ltt_tracefile *t, unsigned i);
+int ltt_trace_control_tracefile_find(LttTrace *t, char *name);
+int ltt_trace_per_cpu_tracefile_find(LttTrace *t, unsigned i);
-/* A trace typically contains one "control" tracefile with important events
- (for all CPUs), and one tracefile with ordinary events per cpu.
- The tracefiles in a trace may be enumerated for each category
- (all cpu and per cpu). The total number of tracefiles and of CPUs
- may also be obtained. */
-unsigned int ltt_trace_tracefile_number(ltt_trace *t);
+/* Get a specific tracefile */
-unsigned int ltt_trace_tracefile_number_per_cpu(ltt_trace *t);
+LttTracefile *ltt_trace_control_tracefile_get(LttTrace *t, unsigned i);
-unsigned int ltt_trace_tracefile_number_all_cpu(ltt_trace *t);
+LttTracefile *ltt_trace_per_cpu_tracefile_get(LttTrace *t, unsigned i);
-ltt_tracefile *ltt_trace_tracefile_get_per_cpu(ltt_trace *t, unsigned i);
-ltt_tracefile *ltt_trace_tracefile_get_all_cpu(ltt_trace *t, unsigned i);
+/* Get the name of a tracefile */
-char *ltt_tracefile_name(ltt_tracefile *tf);
+char *ltt_tracefile_name(LttTracefile *tf);
/* Seek to the first event of the trace with time larger or equal to time */
-int ltt_tracefile_seek_time(ltt_tracefile *t, ltt_time time);
+void ltt_tracefile_seek_time(LttTracefile *t, LttTime time);
/* Read the next event */
-ltt_event *ltt_tracefile_read(ltt_tracefile *t);
+LttEvent *ltt_tracefile_read(LttTracefile *t);
#endif // TRACE_H
/* Different types allowed */
-typedef enum _ltt_type_enum
+typedef enum _LttTypeEnum
{ LTT_INT, LTT_UINT, LTT_FLOAT, LTT_STRING, LTT_ENUM, LTT_ARRAY,
LTT_SEQUENCE, LTT_STRUCT
-} ltt_type_enum;
+} LttTypeEnum;
/* All event types, data types and fields belong to their trace and
/* Obtain the name, description, facility, facility relative id, global id,
type and root field for an eventtype */
-char *ltt_eventtype_name(ltt_eventtype *et);
+char *ltt_eventtype_name(LttEventType *et);
-char *ltt_eventtype_description(ltt_eventtype *et);
+char *ltt_eventtype_description(LttEventType *et);
-ltt_facility *ltt_eventtype_facility(ltt_eventtype *et);
+LttFacility *ltt_eventtype_facility(LttEventType *et);
-unsigned *ltt_eventtype_relative_id(ltt_eventtype *et);
+unsigned *ltt_eventtype_relative_id(LttEventType *et);
-unsigned *ltt_eventtype_id(ltt_eventtype *et);
+unsigned *ltt_eventtype_id(LttEventType *et);
-ltt_type *ltt_eventtype_type(ltt_eventtype *et);
+LttType *ltt_eventtype_type(LttEventType *et);
-ltt_field *ltt_eventtype_field(ltt_eventtype *et);
+LttField *ltt_eventtype_field(LttEventType *et);
/* obtain the type name and size. The size is the number of bytes for
primitive types (INT, UINT, FLOAT, ENUM), or the size for the unsigned
integer length count for sequences. */
-char *ltt_type_name(ltt_type *t);
+char *ltt_type_name(LttType *t);
-ltt_type_enum ltt_type_class(ltt_type *t);
+LttTypeEnum ltt_type_class(LttType *t);
-unsigned ltt_type_size(ltt_tracefile * tf, ltt_type *t);
+unsigned ltt_type_size(LttTracefile *tf, LttType *t);
/* The type of nested elements for arrays and sequences. */
-ltt_type *ltt_type_element_type(ltt_type *t);
+LttType *ltt_type_element_type(LttType *t);
/* The number of elements for arrays. */
-unsigned ltt_type_element_number(ltt_type *t);
+unsigned ltt_type_element_number(LttType *t);
/* The number of data members for structures. */
-unsigned ltt_type_member_number(ltt_type *t);
+unsigned ltt_type_member_number(LttType *t);
/* The type of a data member in a structure. */
-ltt_type *ltt_type_member_type(ltt_type *t, unsigned i);
+LttType *ltt_type_member_type(LttType *t, unsigned i);
/* For enumerations, obtain the symbolic string associated with a value
(0 to n - 1 for an enumeration of n elements). */
-char *ltt_enum_string_get(ltt_type *t, unsigned i);
+char *ltt_enum_string_get(LttType *t, unsigned i);
/* The fields form a tree representing a depth first search of the
selected element among all the (identically typed) elements. For structures,
a nested field exists for each data member. Each field stores the
platform/trace specific offset values (for efficient access) and
- points back to the corresponding ltt_type for the rest. */
+ points back to the corresponding LttType for the rest. */
-ltt_field *ltt_field_element(ltt_field *f);
+LttField *ltt_field_element(LttField *f);
-ltt_field *ltt_field_member(ltt_field *f, unsigned i);
+LttField *ltt_field_member(LttField *f, unsigned i);
-ltt_type *ltt_field_type(ltt_field *f);
+LttType *ltt_field_type(LttField *f);
#endif // TYPE_H
projects / lttv.git / commitdiff
