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