Commit | Line | Data |
---|---|---|
827b30c1 DS |
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 | ||
f5464725 JD |
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. | |
827b30c1 DS |
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 | ||
f60efc0e JD |
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 | ||
827b30c1 DS |
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 | |
46df6b28 | 126 | information. There are six top-level scopes (defined in the ctf_scope enum) |
827b30c1 DS |
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 | ||
f5464725 JD |
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. | |
827b30c1 DS |
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 | ||
f5464725 JD |
165 | Depending on the field type, we can get informations about the field with the |
166 | following functions: | |
827b30c1 DS |
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 | ||
f5464725 JD |
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: | |
827b30c1 DS |
195 | * bt_ctf_get_uint64(); |
196 | * bt_ctf_get_int64(); | |
197 | * bt_ctf_get_char_array(); | |
6ab22097 JD |
198 | * bt_ctf_get_string(); |
199 | * bt_ctf_get_enum_int(); | |
200 | * bt_ctf_get_enum_str(). | |
827b30c1 DS |
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. |