doc/API.txt

   1 Babeltrace API documentation
   2
   3 Babeltrace provides trace read and write libraries, as well as a trace
   4 converter. A plugin can be created for any trace format to allow its
   5 conversion to/from another trace format.
   6
   7 The main format expected to be converted to/from is the Common Trace
   8 Format (CTF). The latest version of the CTF specification can be found at:
   9         git tree:   git://git.efficios.com/ctf.git
  10         gitweb:     http://git.efficios.com/?p=ctf.git
  11
  12 This document describes the main concepts to use the libbabeltrace,
  13 which exposes the Babeltrace trace reading capability.
  14
  15
  16 TERMINOLOGY
  17 ¯¯¯¯¯¯¯¯¯¯¯
  18
  19 * A "callback" is a reference to a piece of executable code (such as a
  20   function) that is passed as an argument to another piece of code
  21   (like another function).
  22
  23 * A "context" is a structure that represents an object in which a trace
  24   collection is opened.
  25
  26 * An "iterator" is a structure that enables the user to traverse a trace.
  27
  28 * A "trace handle" is a unique identifier representing a trace file.
  29   It allows the user to manipulate a trace directly.
  30
  31 * The "declaration" of a field or an event, is the structure which contains
  32   the representaion of an object as declared in the metadata. All the
  33   declarations of all events and fields can be accessed as soon as the trace is
  34   open, but of course they contain no trace data, just the layout.
  35
  36 * The "definition" of a field or an event is the structure in which the actual
  37   trace data is contained. When we read an event in the trace, we access its
  38   definition and we can access all the field definitions contained in all the
  39   scopes of this event to the get the actual data.
  40
  41 * "Scopes" allow specifying the level at which the information about the
  42   current event must be fetched: event header, event payload, event context,
  43   stream context. Compound-type (arrays, structures, sequences and variants)
  44   fields are relative scopes which contain fields.
  45
  46
  47 USAGE
  48 ¯¯¯¯¯¯
  49
  50 Context:
  51
  52 In order to use libbabeltrace to read a trace, the first step is to create a
  53 context structure and to add a trace to it. This is done using the
  54 bt_context_create() and bt_context_add_trace() functions. As long as this
  55 context structure is allocated and the trace is valid, the trace can be
  56 manipulated by the library.
  57
  58 The context can be destroyed by calling one more bt_context_put() than
  59 bt_context_get(), functions which respectively decrement and increment the
  60 refcount of the context. These functions ensures that the context won't be
  61 destroyed when it is in use.
  62
  63 Once a trace is added to the context, it can be read and seeked using iterators
  64 and callbacks.
  65
  66
  67 Iterator:
  68
  69 An iterator can be created using the bt_iter_create() function. As of now, only
  70 ctf iterator are supported. These are used to traverse a ctf-formatted trace.
  71 Such iterators can be created with bt_ctf_iter_create().
  72
  73 While creating an iterator, a begin and an end position may be specified. To do
  74 so, one or two struct bt_iter_pos must be passed. Such struct have two
  75 attributes: type and u. "type" is the seek type, can be either:
  76         BT_SEEK_TIME
  77         BT_SEEK_RESTORE
  78         BT_SEEK_CUR
  79         BT_SEEK_BEGIN
  80         BT_SEEK_END
  81 and "u" is a union of the seek time (if using BT_SEEK_TIME) and the restore
  82 position (if using BT_SEEK_RESTORE).
  83
  84 Once the iterator is created, various functions become available. We have
  85 bt_ctf_iter_read_event() which returns the ctf event of the trace where the
  86 iterator is set. There is also bt_ctf_iter_destroy() which frees the iterator.
  87 Note that only one iterator can be created in a context at the same time. If
  88 more than one iterator is being created for the same context, the second
  89 creation will return NULL. The previous iterator must be destroyed before
  90 creation of the new iterator. In the future, creation of multiples iterators
  91 will be allowed.
  92
  93 The bt_ctf_iter_read_event_flags() function has the same behaviour as
  94 bt_ctf_iter_read_event() but takes an additionnal flag pointer. This flag is
  95 used to inform the user if a special condition occured while reading the event.
  96 As of now, only the BT_ITER_LOST_EVENTS is handled, it informs the user that
  97 some events were discarded by the tracer. To get the number of events lost
  98 immediately prior to the last event read, the user can call the
  99 bt_ctf_get_lost_events_count() function.
 100
 101 Finally, we have the bt_ctf_get_iter() function which returns a struct bt_iter
 102 with which the iterator can be moved using one of these functions:
 103         bt_iter_next(),         moves the iterator to the next event
 104         bt_iter_set_pos(),      moves the iterator to the specified position
 105
 106 To get the current position (struct bt_iter_pos) of the iterator, the function
 107 bt_iter_get_pos() must be used. To create an arbitrary position based on a
 108 specific time, bt_iter_create_time_pos() is the function to use. The
 109 bt_iter_pos structure returned by these two functions must be freed with
 110 bt_iter_free_pos() after use.
 111
 112
 113 CTF Event:
 114
 115 A CTF event is obtained from an iterator via the bt_ctf_iter_read_event()
 116 function or via the call_data parameter of a callback. To read the data of a
 117 CTF event :
 118         * bt_ctf_event_name()           returns the name of the event;
 119         * bt_ctf_get_timestamp()        returns the timestamp of the event
 120                                         offsetted with the system clock
 121                                         source (in ns);
 122         * bt_ctf_get_cycles()           returns the timestamp of the event as
 123                                         written in the packet (in cycles).
 124
 125 The payload of an event is divided in various scopes depending on the type of
 126 information. There are six top-level scopes (defined in the bt_ctf_scope enum)
 127 which can be accessed by the bt_ctf_get_top_level_scope() function :
 128         BT_TRACE_PACKET_HEADER          = 0,
 129         BT_STREAM_PACKET_CONTEXT        = 1,
 130         BT_STREAM_EVENT_HEADER          = 2,
 131         BT_STREAM_EVENT_CONTEXT         = 3,
 132         BT_EVENT_CONTEXT                = 4,
 133         BT_EVENT_FIELDS                 = 5.
 134
 135 In order to access a field or a field list, the user needs to pass a scope as
 136 argument, this scope can be a top-level scope or a scope relative to an
 137 arbitrary field in the case of compound types (array, sequence, structure or
 138 variant)
 139
 140 For more information on each scope, see the CTF specifications.
 141
 142 The bt_ctf_get_field_list() function gives access to the list of fields in the
 143 current event. The bt_ctf_get_field() function gives acces to of a specific
 144 field of an event.
 145
 146 The bt_ctf_get_event_decl_list() and bt_ctf_get_decl_fields() functions give
 147 respectively access to the list of the events declared in a trace and the list
 148 of the fields declared in an event.
 149
 150 Once the field is obtained, we can obtain its name and type using the
 151 bt_ctf_field_name() and bt_ctf_field_type() functions respectively. The
 152 possible types are defined in the ctf_type_id enum:
 153         CTF_TYPE_UNKNOWN = 0,
 154         CTF_TYPE_INTEGER,
 155         CTF_TYPE_FLOAT,
 156         CTF_TYPE_ENUM,
 157         CTF_TYPE_STRING,
 158         CTF_TYPE_STRUCT,
 159         CTF_TYPE_UNTAGGED_VARIANT,
 160         CTF_TYPE_VARIANT,
 161         CTF_TYPE_ARRAY,
 162         CTF_TYPE_SEQUENCE,
 163         NR_CTF_TYPES.
 164
 165 Depending on the field type, we can get informations about the field with the
 166 following functions:
 167         * bt_ctf_get_index()            return the element at the index
 168                                         position of an array of a sequence;
 169
 170         * bt_ctf_get_array_len()        return the length of an array;
 171
 172         * bt_ctf_get_int_signedness()   return the signedness of an integer;
 173
 174         * bt_ctf_get_int_base()         return the base of an integer;
 175
 176         * bt_ctf_get_int_byte_order()   return the byte order of an integer;
 177
 178         * bt_ctf_get_int_len()          return the size in bits of an integer;
 179
 180         * bt_ctf_get_encoding()         return the encoding of an int or a
 181                                         string defined in the
 182                                         ctf_string_encoding enum:
 183                                                 CTF_STRING_NONE = 0,
 184                                                 CTF_STRING_UTF8,
 185                                                 CTF_STRING_ASCII,
 186                                                 CTF_STRING_UNKNOWN.
 187
 188 All of these functions require a field declaration as parameter, depending on
 189 the source type of data (struct definition* or struct bt_ctf_field_decl*), the
 190 user might have to call bt_ctf_get_decl_from_def() or
 191 bt_ctf_get_decl_from_field_decl().
 192
 193 The following functions give access to the value associated with a field
 194 defintion:
 195         * bt_ctf_get_uint64();
 196         * bt_ctf_get_int64();
 197         * bt_ctf_get_char_array();
 198         * bt_ctf_get_string();
 199         * bt_ctf_get_enum_int();
 200         * bt_ctf_get_enum_str().
 201
 202 If the field does not exist or is not of the type requested, the value returned
 203 with these four functions is undefined. To check if an error occured, use the
 204 bt_ctf_field_get_error() function after accessing a field. If no error
 205 occured, the function will return 0.
 206
 207 It is also possible to access the declaration fields, the same way as the
 208 definition ones. bt_ctf_get_event_decl_list() sets a list to an array of
 209 bt_ctf_event_decl pointers and bt_ctf_get_event_decl_fields() sets a list to an
 210 array of bt_ctf_field_decl pointers.  From the first type, the name of the
 211 event can be obtained with bt_ctf_get_decl_event_name().  For the second type,
 212 the field decl name is obtained with bt_ctf_get_decl_field_name().
 213
 214 The declaration functions allow the user to list the events, fields and
 215 contexts fields enabled in the trace once it is opened, whereas the definition
 216 functions apply on the current event being read.
 217
 218
 219 Callback:
 220
 221 The iterator allow the user to read the trace, in order to access the events
 222 and fields, the user can either call the functions listed previously on each
 223 event, or register callbacks functions that are called when specific (or all)
 224 events are read.
 225
 226 This is done with the bt_ctf_iter_add_callback() function. It requires a valid
 227 ctf iterator as the first argument. Here are all arguments:
 228         iter: trace collection iterator (input)
 229         event: event to target. 0 for all events.
 230         private_data: private data pointer to pass to the callback
 231         flags: specific flags controlling the behavior of this callback
 232                 (or'd).
 233         callback: function pointer to call
 234         depends: struct bt_dependency detailing the required computation
 235                 results.  Ends with 0.
 236         weak_depends: struct bt_dependency detailing the optional computation
 237                 results that can be optionally consumed by this
 238                 callback.
 239         provides: struct bt_dependency detailing the computation results
 240                 provided by this callback.
 241                 Ends with 0.
 242
 243 "depends", "weak_depends" and "provides" memory is handled by the babeltrace
 244 library after this call succeeds or fails. These objects can still be used by
 245 the caller until the babeltrace iterator is destroyed, but they belong to the
 246 babeltrace library.
 247
 248 As of now the flags and dependencies are not used, the callbacks are
 249 processed in FIFO order.
 250
 251 Note: once implemented, the dependency graph will be calculated when
 252 bt_ctf_iter_read_event() is executed after a bt_ctf_iter_add_callback(). It is
 253 valid to create/add callbacks/read/add more callbacks/read some more.
 254
 255 The callback function passed to bt_ctf_iter_add_callback() must return a
 256 bt_cb_ret value:
 257         BT_CB_OK                = 0,
 258         BT_CB_OK_STOP           = 1,
 259         BT_CB_ERROR_STOP        = 2,
 260         BT_CB_ERROR_CONTINUE    = 3.
 261
 262
 263 Trace handle:
 264
 265 When a trace is added to a context, bt_context_add_trace() returns a trace
 266 handle id.  This id is associated with its corresponding trace handle.  With
 267 that id, it is possible to manipulate directly the trace.
 268
 269         * bt_trace_handle_get_path()
 270                 -> returns the path of the trace handle (path to the trace).
 271
 272         * bt_trace_handle_get_timestamp_begin()
 273         * bt_trace_handle_get_timestamp_end()
 274                 -> return the creation/destruction timestamps (in ns or cycles
 275                         depending on the type specified) of the buffers of a
 276                         trace.
 277
 278         * bt_ctf_event_get_handle_id()
 279                 -> returns the handle id associated with an event.
 280
 281
 282 For more information on CTF, see the CTF documentation.