| 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 | Finally, we have the bt_ctf_get_iter() function which returns a struct bt_iter |
| 80 | with which the iterator can be moved using one of these functions: |
| 81 | bt_iter_next(), moves the iterator to the next event |
| 82 | bt_iter_set_pos(), moves the iterator to the specified position |
| 83 | |
| 84 | To get the current position (struct bt_iter_pos) of the iterator, the function |
| 85 | bt_iter_get_pos() must be used. To create an arbitrary position based on a |
| 86 | specific time, bt_iter_create_time_pos() is the function to use. The |
| 87 | bt_iter_pos structure returned by these two functions must be freed with |
| 88 | bt_iter_free_pos() after use. |
| 89 | |
| 90 | |
| 91 | CTF Event: |
| 92 | |
| 93 | A CTF event is obtained from an iterator via the bt_ctf_iter_read_event() |
| 94 | function or via the call_data parameter of a callback. To read the data of a |
| 95 | CTF event : |
| 96 | * bt_ctf_event_name() returns the name of the event; |
| 97 | * bt_ctf_get_timestamp() returns the timestamp of the event |
| 98 | offsetted with the system clock |
| 99 | source (in ns); |
| 100 | * bt_ctf_get_cycles() returns the timestamp of the event as |
| 101 | written in the packet (in cycles). |
| 102 | |
| 103 | The payload of an event is divided in various scopes depending on the type of |
| 104 | information. There are six top-level scopes (defined in the bt_ctf_scope enum) |
| 105 | which can be accessed by the bt_ctf_get_top_level_scope() function : |
| 106 | BT_TRACE_PACKET_HEADER = 0, |
| 107 | BT_STREAM_PACKET_CONTEXT = 1, |
| 108 | BT_STREAM_EVENT_HEADER = 2, |
| 109 | BT_STREAM_EVENT_CONTEXT = 3, |
| 110 | BT_EVENT_CONTEXT = 4, |
| 111 | BT_EVENT_FIELDS = 5. |
| 112 | |
| 113 | In order to access a field or a field list, the user needs to pass a scope as |
| 114 | argument, this scope can be a top-level scope or a scope relative to an |
| 115 | arbitrary field in the case of compound types (array, sequence, structure or |
| 116 | variant) |
| 117 | |
| 118 | For more information on each scope, see the CTF specifications. |
| 119 | |
| 120 | The function to get a field list is the bt_ctf_get_field_list(). The function |
| 121 | to get the definition of a specific field is bt_ctf_get_field(). |
| 122 | |
| 123 | Once the field is obtained, we can obtain its name and type using the |
| 124 | bt_ctf_field_name() and bt_ctf_field_type() functions respectively. The |
| 125 | possible types are defined in the ctf_type_id enum: |
| 126 | CTF_TYPE_UNKNOWN = 0, |
| 127 | CTF_TYPE_INTEGER, |
| 128 | CTF_TYPE_FLOAT, |
| 129 | CTF_TYPE_ENUM, |
| 130 | CTF_TYPE_STRING, |
| 131 | CTF_TYPE_STRUCT, |
| 132 | CTF_TYPE_UNTAGGED_VARIANT, |
| 133 | CTF_TYPE_VARIANT, |
| 134 | CTF_TYPE_ARRAY, |
| 135 | CTF_TYPE_SEQUENCE, |
| 136 | NR_CTF_TYPES. |
| 137 | |
| 138 | Depending on the field type, we can get informations about the field with these |
| 139 | functions: |
| 140 | * bt_ctf_get_index() return the element at the index |
| 141 | position of an array of a sequence; |
| 142 | |
| 143 | * bt_ctf_get_array_len() return the length of an array; |
| 144 | |
| 145 | * bt_ctf_get_int_signedness() return the signedness of an integer; |
| 146 | |
| 147 | * bt_ctf_get_int_base() return the base of an integer; |
| 148 | |
| 149 | * bt_ctf_get_int_byte_order() return the byte order of an integer; |
| 150 | |
| 151 | * bt_ctf_get_int_len() return the size in bits of an integer; |
| 152 | |
| 153 | * bt_ctf_get_encoding() return the encoding of an int or a |
| 154 | string defined in the |
| 155 | ctf_string_encoding enum: |
| 156 | CTF_STRING_NONE = 0, |
| 157 | CTF_STRING_UTF8, |
| 158 | CTF_STRING_ASCII, |
| 159 | CTF_STRING_UNKNOWN. |
| 160 | |
| 161 | These functions give access to the value associated with a field : |
| 162 | * bt_ctf_get_uint64(); |
| 163 | * bt_ctf_get_int64(); |
| 164 | * bt_ctf_get_char_array(); |
| 165 | * bt_ctf_get_string(); |
| 166 | * bt_ctf_get_enum_int(); |
| 167 | * bt_ctf_get_enum_str(). |
| 168 | |
| 169 | If the field does not exist or is not of the type requested, the value returned |
| 170 | with these four functions is undefined. To check if an error occured, use the |
| 171 | bt_ctf_field_get_error() function after accessing a field. If no error |
| 172 | occured, the function will return 0. |
| 173 | |
| 174 | It is also possible to access the declaration fields, the same way as the |
| 175 | definition ones. bt_ctf_get_event_decl_list() sets a list to an array of |
| 176 | bt_ctf_event_decl pointers and bt_ctf_get_event_decl_fields() sets a list to an |
| 177 | array of bt_ctf_field_decl pointers. From the first type, the name of the |
| 178 | event can be obtained with bt_ctf_get_decl_event_name(). For the second type, |
| 179 | the field decl name is obtained with bt_ctf_get_decl_field_name(). |
| 180 | |
| 181 | The declaration functions allow the user to list the events, fields and |
| 182 | contexts fields enabled in the trace once it is opened, whereas the definition |
| 183 | functions apply on the current event being read. |
| 184 | |
| 185 | |
| 186 | Callback: |
| 187 | |
| 188 | The iterator allow the user to read the trace, in order to access the events |
| 189 | and fields, the user can either call the functions listed previously on each |
| 190 | event, or register callbacks functions that are called when specific (or all) |
| 191 | events are read. |
| 192 | |
| 193 | This is done with the bt_ctf_iter_add_callback() function. It requires a valid |
| 194 | ctf iterator as the first argument. Here are all arguments: |
| 195 | iter: trace collection iterator (input) |
| 196 | event: event to target. 0 for all events. |
| 197 | private_data: private data pointer to pass to the callback |
| 198 | flags: specific flags controlling the behavior of this callback |
| 199 | (or'd). |
| 200 | callback: function pointer to call |
| 201 | depends: struct bt_dependency detailing the required computation |
| 202 | results. Ends with 0. |
| 203 | weak_depends: struct bt_dependency detailing the optional computation |
| 204 | results that can be optionally consumed by this |
| 205 | callback. |
| 206 | provides: struct bt_dependency detailing the computation results |
| 207 | provided by this callback. |
| 208 | Ends with 0. |
| 209 | |
| 210 | "depends", "weak_depends" and "provides" memory is handled by the babeltrace |
| 211 | library after this call succeeds or fails. These objects can still be used by |
| 212 | the caller until the babeltrace iterator is destroyed, but they belong to the |
| 213 | babeltrace library. |
| 214 | |
| 215 | As of now the flags and dependencies are not used, the callbacks are |
| 216 | processed in FIFO order. |
| 217 | |
| 218 | Note: once implemented, the dependency graph will be calculated when |
| 219 | bt_ctf_iter_read_event() is executed after a bt_ctf_iter_add_callback(). It is |
| 220 | valid to create/add callbacks/read/add more callbacks/read some more. |
| 221 | |
| 222 | The callback function passed to bt_ctf_iter_add_callback() must return a |
| 223 | bt_cb_ret value: |
| 224 | BT_CB_OK = 0, |
| 225 | BT_CB_OK_STOP = 1, |
| 226 | BT_CB_ERROR_STOP = 2, |
| 227 | BT_CB_ERROR_CONTINUE = 3. |
| 228 | |
| 229 | |
| 230 | Trace handle: |
| 231 | |
| 232 | When a trace is added to a context, bt_context_add_trace() returns a trace |
| 233 | handle id. This id is associated with its corresponding trace handle. With |
| 234 | that id, it is possible to manipulate directly the trace. |
| 235 | |
| 236 | * bt_trace_handle_get_path() |
| 237 | -> returns the path of the trace handle (path to the trace). |
| 238 | |
| 239 | * bt_trace_handle_get_timestamp_begin() |
| 240 | * bt_trace_handle_get_timestamp_end() |
| 241 | -> return the creation/destruction timestamps (in ns or cycles |
| 242 | depending on the type specified) of the buffers of a |
| 243 | trace. |
| 244 | |
| 245 | * bt_ctf_event_get_handle_id() |
| 246 | -> returns the handle id associated with an event. |
| 247 | |
| 248 | |
| 249 | For more information on CTF, see the CTF documentation. |