5c06198ec1f3a721414fd221cdf089db143ff82c
[babeltrace.git] / 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 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.
This page took 0.0508 seconds and 3 git commands to generate.