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 | ||
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(); | |
6ab22097 JD |
165 | * bt_ctf_get_string(); |
166 | * bt_ctf_get_enum_int(); | |
167 | * bt_ctf_get_enum_str(). | |
827b30c1 DS |
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. |