From 975e44c709f35b36e7a432bd40220e73cde614b6 Mon Sep 17 00:00:00 2001 From: compudj Date: Thu, 29 May 2003 13:22:57 +0000 Subject: [PATCH] trace reading header files git-svn-id: http://ltt.polymtl.ca/svn@16 04897980-b3bd-0310-b5e0-8ef037075253 --- ltt/branches/poly/LibLTT/event.h | 73 ++++++++++++++++++ ltt/branches/poly/LibLTT/facility.h | 29 +++++++ ltt/branches/poly/LibLTT/ltt.h | 90 ++++++++++++++++++++++ ltt/branches/poly/LibLTT/tracefile.h | 110 +++++++++++++++++++++++++++ ltt/branches/poly/LibLTT/type.h | 65 ++++++++++++++++ 5 files changed, 367 insertions(+) create mode 100644 ltt/branches/poly/LibLTT/event.h create mode 100644 ltt/branches/poly/LibLTT/facility.h create mode 100644 ltt/branches/poly/LibLTT/ltt.h create mode 100644 ltt/branches/poly/LibLTT/tracefile.h create mode 100644 ltt/branches/poly/LibLTT/type.h diff --git a/ltt/branches/poly/LibLTT/event.h b/ltt/branches/poly/LibLTT/event.h new file mode 100644 index 00000000..5570ec46 --- /dev/null +++ b/ltt/branches/poly/LibLTT/event.h @@ -0,0 +1,73 @@ + +/* 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); diff --git a/ltt/branches/poly/LibLTT/facility.h b/ltt/branches/poly/LibLTT/facility.h new file mode 100644 index 00000000..eda320f9 --- /dev/null +++ b/ltt/branches/poly/LibLTT/facility.h @@ -0,0 +1,29 @@ + +#include + +/* 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); + diff --git a/ltt/branches/poly/LibLTT/ltt.h b/ltt/branches/poly/LibLTT/ltt.h new file mode 100644 index 00000000..a06177e6 --- /dev/null +++ b/ltt/branches/poly/LibLTT/ltt.h @@ -0,0 +1,90 @@ + +#include + +/* 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; + + + + diff --git a/ltt/branches/poly/LibLTT/tracefile.h b/ltt/branches/poly/LibLTT/tracefile.h new file mode 100644 index 00000000..1477a245 --- /dev/null +++ b/ltt/branches/poly/LibLTT/tracefile.h @@ -0,0 +1,110 @@ + +#include + +/* 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); diff --git a/ltt/branches/poly/LibLTT/type.h b/ltt/branches/poly/LibLTT/type.h new file mode 100644 index 00000000..a65a3200 --- /dev/null +++ b/ltt/branches/poly/LibLTT/type.h @@ -0,0 +1,65 @@ + +#include + +/* 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); + -- 2.34.1