--- /dev/null
+
+/* Events and their content, including the raw data, are only valid
+ until reading another event from the same tracefile.
+ Indeed, since event reading is critical to the performance,
+ the memory associated with an event may be reused at each read. */
+
+
+/* Obtain the tracefile unique integer id associated with the type of
+ this event */
+
+unsigned ltt_event_eventtype_id(ltt_event *e);
+
+
+/* Facility and type for the event */
+
+ltt_facility *ltt_event_facility(ltt_event *e);
+
+ltt_eventtype *ltt_event_eventtype(ltt_event *e);
+
+ltt_field *ltt_event_field(ltt_event *e);
+
+/* Time and cycle count for the event */
+
+ltt_time ltt_event_time(ltt_event *e);
+
+ltt_cycle_count ltt_event_cycle_count(ltt_event *e);
+
+
+/* CPU id and system name of the event */
+
+unsigned ltt_event_cpu_id(ltt_event *e);
+
+char *ltt_event_system_name(ltt_event *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);
+
+
+/* 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);
+
+
+/* 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);
+
+
+/* These functions extract data from an event after architecture specific
+ conversions. */
+
+unsigned ltt_event_get_unsigned(ltt_event *e, ltt_field *f);
+
+int ltt_event_get_int(ltt_event *e, ltt_field *f);
+
+unsigned long ltt_event_get_long_unsigned(ltt_event *e, ltt_field *f);
+
+long int ltt_event_get_long_int(ltt_event *e, ltt_field *f);
+
+float ltt_event_get_float(ltt_event *e, ltt_field *f);
+
+double ltt_event_get_double(ltt_event *e, ltt_field *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);
--- /dev/null
+
+#include <ltt/ltt.h>
+
+/* A facility is obtained from a .event file containing event type
+ declarations. The facility content must have the specified checksum.
+ The structures associated with a facility may be released with
+ a call to ltt_close_facility if its usage count is 0. */
+
+ltt_facility *ltt_facility_open(char *pathname, ltt_checksum c);
+
+int ltt_facility_close(ltt_facility *f);
+
+
+/* Obtain the name and checksum of the facility */
+
+char *ltt_facility_name(ltt_facility *f);
+
+ltt_checksum ltt_facility_checksum(ltt_facility *f);
+
+
+/* Discover the event types within the facility. The event type integer id
+ used here is specific to the trace (from 0 to nb_event_types - 1). */
+
+unsigned ltt_facility_eventtype_number(ltt_facility *f);
+
+ltt_eventtype *ltt_facility_eventtype_get(ltt_facility *f, unsigned i);
+
+ltt_eventtype *ltt_facility_eventtype_get_by_name(ltt_facility *f, char *name);
+
--- /dev/null
+
+#include <ltt/ltt-private.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
+ then use the exact same id numbers for event types.
+
+ A tracefile (ltt_tracefile) contains a list of events (ltt_event) 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
+ 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.
+
+ Event types (ltt_eventtype) refer to data types (ltt_type) 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).
+
+ 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
+ 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
+ contained information (byte offsets) may vary with the architecture
+ associated to the tracefile. */
+
+typedef struct _ltt_tracefile ltt_tracefile;
+
+typedef struct _ltt_facility ltt_facility;
+
+typedef struct _ltt_eventtype ltt_eventtype;
+
+typedef struct _ltt_type ltt_type;
+
+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. */
+
+typedef unsigned long ltt_checksum;
+
+
+/* Events are usually stored with the easily obtained CPU clock cycle count,
+ ltt_cycle_count. This can be converted to the real time value, ltt_time,
+ using linear interpolation between regularly sampled values (e.g. a few
+ times per second) of the real time clock with their corresponding
+ cycle count values. */
+
+typedef struct timespec ltt_time;
+
+typedef uint64_t ltt_cycle_count;
+
+
+
+
--- /dev/null
+
+#include <ltt/ltt.h>
+
+/* A tracefile is specified as a pathname. Facilities must be added to the
+ tracefile to declare the type of the contained events.
+
+ The ltt_tracefile_facility_add call increases the facility
+ usage count and also specifies the base of the numeric range
+ assigned to the event types in the facility for this tracefile.
+ This information is normally obtained through "facility used" events
+ stored in the tracefile.
+
+ When a tracefile is closed, all the associated facilities may be
+ automatically closed as well, if their usage count is 0, when the
+ close_facilities argument is true. */
+
+ltt_tracefile *ltt_tracefile_open(char *pathname);
+
+int ltt_tracefile_close(ltt_tracefile *t, bool close_facilities);
+
+int ltt_tracefile_facility_add(ltt_tracefile *t, ltt_facility *f, int base_id);
+
+
+/* A tracefile 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. */
+
+typedef enum _ltt_arch_size
+{ LTT_LP32, LTT_ILP32, LTT_LP64, LTT_ILP64
+} ltt_arch_size;
+
+typedef enum _ltt_arch_endian
+{ LTT_LITTLE_ENDIAN, LTT_BIG_ENDIAN
+} ltt_arch_endian;
+
+char *ltt_tracefile_arch_type(ltt_tracefile *t);
+
+char *ltt_tracefile_arch_variant(ltt_tracefile *t);
+
+ltt_arch_size *ltt_tracefile_arch_size(ltt_tracefile *t);
+
+ltt_arch_endian *ltt_tracefile_arch_endian(ltt_tracefile *t);
+
+char *ltt_tracefile_system_type(ltt_tracefile *t);
+
+char *ltt_tracefile_system_name(ltt_tracefile *t);
+
+
+/* SMP multi-processors have 2 or more CPUs */
+
+unsigned ltt_tracefile_cpu_number(ltt_tracefile *t);
+
+
+/* Does the tracefile contain events only for a single CPU? */
+
+bool ltt_tracefile_cpu_single(ltt_tracefile *t);
+
+
+/* It this is the case, which CPU? */
+
+unsigned ltt_tracefile_cpu_id(ltt_tracefile *t);
+
+
+/* Start and end time of the trace and its duration */
+
+ltt_time ltt_tracefile_time_start(ltt_tracefile *t);
+
+ltt_time ltt_tracefile_time_end(ltt_tracefile *t);
+
+ltt_time ltt_tracefile_duration(ltt_tracefile *t);
+
+
+/* Functions to discover the facilities added to the tracefile */
+
+unsigned ltt_tracefile_facility_number(ltt_tracefile *t);
+
+ltt_facility *ltt_tracefile_facility_get(ltt_tracefile *t, unsigned i);
+
+ltt_facility *ltt_tracefile_facility_get_by_name(ltt_tracefile *t, char *name);
+
+
+/* Functions to discover all the event types in the facilities added to the
+ tracefile. The event type integer id, unique for the trace, is used. */
+
+unsigned ltt_tracefile_eventtype_number(ltt_tracefile *t);
+
+ltt_eventtype *ltt_tracefile_eventtype_get(ltt_tracefile *t, unsigned i);
+
+
+/* Given an event type, find its unique id within the tracefile */
+
+unsigned ltt_tracefile_eventtype_id(ltt_tracefile *t, ltt_eventtype *et);
+
+
+/* Get the root field associated with an event type for the tracefile */
+
+ltt_field *ltt_tracefile_eventtype_root_field(ltt_tracefile *t, unsigned id);
+
+
+/* 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);
+
+
+/* Read the next event */
+
+ltt_event *ltt_tracefile_read(ltt_tracefile *t);
--- /dev/null
+
+#include <ltt/ltt.h>
+
+/* All event types and data types belong to their facilities and
+ are released at the same time. All fields belong to their tracefile and
+ are released at the same time. */
+
+char *ltt_eventtype_name(ltt_eventtype *et);
+
+char *ltt_eventtype_description(ltt_eventtype *et);
+
+ltt_type *ltt_eventtype_type(ltt_eventtype *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);
+
+ltt_type_enum *ltt_type_class(ltt_type *t);
+
+unsigned ltt_type_size(ltt_type *t);
+
+
+/* The type of nested elements for arrays and sequences. */
+
+ltt_type *ltt_type_element_type(ltt_type *t);
+
+
+/* The number of elements for arrays. */
+
+unsigned ltt_type_element_number(ltt_type *t);
+
+
+/* The number of data members for structures. */
+
+unsigned ltt_type_member_number(ltt_type *t);
+
+
+/* The type of a data member in a structure. */
+
+ltt_type *ltt_type_member_type(ltt_type *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);
+
+
+/* The fields form a tree representing a depth first search of the
+ corresponding event type directed acyclic graph. Fields for arrays and
+ sequences simply point to one nested field representing the currently
+ selected element among all the (identically typed) elements. For structures,
+ a nested field exists for each data member. Each field stores the
+ platform/tracefile specific offset values (for efficient access) and
+ points back to the corresponding ltt_type for the rest. */
+
+ltt_field *ltt_field_element(ltt_field *f);
+
+ltt_field *ltt_field_member(ltt_field *f, unsigned i);
+
+ltt_type *ltt_field_type(ltt_field *f);
+
projects / lttv.git / commitdiff
