5 * Babeltrace - CTF binary type reader (BTR)
7 * Copyright (c) 2015-2016 EfficiOS Inc. and Linux Foundation
8 * Copyright (c) 2015-2016 Philippe Proulx <pproulx@efficios.com>
10 * Permission is hereby granted, free of charge, to any person obtaining a copy
11 * of this software and associated documentation files (the "Software"), to deal
12 * in the Software without restriction, including without limitation the rights
13 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14 * copies of the Software, and to permit persons to whom the Software is
15 * furnished to do so, subject to the following conditions:
17 * The above copyright notice and this permission notice shall be included in
18 * all copies or substantial portions of the Software.
20 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
32 #include <babeltrace/babeltrace.h>
33 #include <babeltrace/babeltrace-internal.h>
38 * Event-driven CTF binary type reader (BTR).
40 * This is a common, internal API used by CTF source plugins. It allows
41 * a binary CTF IR field type to be decoded from user-provided buffers.
42 * As the type is decoded (and, possibly, its nested types), registered
43 * user callback functions are called.
45 * This API is only concerned with reading one CTF type at a time from
46 * one or more buffer of bytes. It does not know CTF dynamic scopes,
47 * events, or streams. Sequence lengths and selected variant types are
48 * requested to the user when needed.
52 * Binary type reader API status codes.
56 BT_BTR_STATUS_ENOMEM
= -5,
58 * The binary stream reader reached the end of the user-provided
59 * buffer, but data is still needed to finish decoding the
62 * The user needs to call bt_btr_continue() as long as
63 * #BT_BTR_STATUS_EOF is returned to complete the decoding
64 * process of a given type.
66 BT_BTR_STATUS_EOF
= 1,
68 /** Invalid argument. */
69 BT_BTR_STATUS_INVAL
= -3,
72 BT_BTR_STATUS_ERROR
= -1,
74 /** Everything okay. */
82 * Type reader user callback functions.
86 * Type callback functions.
88 * This CTF binary type reader is event-driven. The following
89 * functions are called during the decoding process, either when
90 * a compound type begins/ends, or when a basic type is
91 * completely decoded (along with its value).
93 * Each function also receives the CTF IR field type associated
94 * with the call, and user data (registered to the type reader
95 * calling them). This field type is a weak reference; the
96 * callback function must use bt_field_type_get() to keep
97 * its own reference of it.
99 * Actual CTF IR fields are \em not created here; this would be
100 * the responsibility of a type reader's user (the provider of
101 * those callback functions).
103 * All the type callback functions return one of the following
106 * - <b>#BT_BTR_STATUS_OK</b>: Everything is okay;
107 * continue the decoding process.
108 * - <b>#BT_BTR_STATUS_ERROR</b>: General error (reported
109 * to type reader's user).
111 * Any member of this structure may be set to \c NULL, should
112 * a specific notification be not needed.
116 * Called when a signed integer type is completely
117 * decoded. This could also be the supporting signed
118 * integer type of an enumeration type (\p type will
121 * @param value Signed integer value
122 * @param type Integer or enumeration type (weak
124 * @param data User data
125 * @returns #BT_BTR_STATUS_OK or
126 * #BT_BTR_STATUS_ERROR
128 enum bt_btr_status (* signed_int
)(int64_t value
,
129 struct bt_field_type
*type
, void *data
);
132 * Called when an unsigned integer type is completely
133 * decoded. This could also be the supporting signed
134 * integer type of an enumeration type (\p type will
137 * @param value Unsigned integer value
138 * @param type Integer or enumeration type (weak
140 * @param data User data
141 * @returns #BT_BTR_STATUS_OK or
142 * #BT_BTR_STATUS_ERROR
144 enum bt_btr_status (* unsigned_int
)(uint64_t value
,
145 struct bt_field_type
*type
, void *data
);
148 * Called when a floating point number type is
149 * completely decoded.
151 * @param value Floating point number value
152 * @param type Floating point number type (weak
154 * @param data User data
155 * @returns #BT_BTR_STATUS_OK or
156 * #BT_BTR_STATUS_ERROR
158 enum bt_btr_status (* floating_point
)(double value
,
159 struct bt_field_type
*type
, void *data
);
162 * Called when a string type begins.
164 * All the following user callback function calls will
165 * be made to bt_btr_cbs::types::string(), each of
166 * them providing one substring of the complete string
169 * @param type Beginning string type (weak reference)
170 * @param data User data
171 * @returns #BT_BTR_STATUS_OK or
172 * #BT_BTR_STATUS_ERROR
174 enum bt_btr_status (* string_begin
)(
175 struct bt_field_type
*type
, void *data
);
178 * Called when a string type's substring is decoded
179 * (between a call to bt_btr_cbs::types::string_begin()
180 * and a call to bt_btr_cbs::types::string_end()).
182 * @param value String value (\em not null-terminated)
183 * @param len String value length
184 * @param type String type (weak reference)
185 * @param data User data
186 * @returns #BT_BTR_STATUS_OK or
187 * #BT_BTR_STATUS_ERROR
189 enum bt_btr_status (* string
)(const char *value
,
190 size_t len
, struct bt_field_type
*type
,
194 * Called when a string type ends.
196 * @param type Ending string type (weak reference)
197 * @param data User data
198 * @returns #BT_BTR_STATUS_OK or
199 * #BT_BTR_STATUS_ERROR
201 enum bt_btr_status (* string_end
)(
202 struct bt_field_type
*type
, void *data
);
205 * Called when a compound type begins.
207 * All the following type callback function calls will
208 * signal sequential elements of this compound type,
209 * until the next corresponding
210 * bt_btr_cbs::types::compound_end() is called.
212 * If \p type is a variant type, then only one type
213 * callback function call will follow before the call to
214 * bt_btr_cbs::types::compound_end(). This single
215 * call indicates the selected type of this variant
218 * @param type Beginning compound type (weak reference)
219 * @param data User data
220 * @returns #BT_BTR_STATUS_OK or
221 * #BT_BTR_STATUS_ERROR
223 enum bt_btr_status (* compound_begin
)(
224 struct bt_field_type
*type
, void *data
);
227 * Called when a compound type ends.
229 * @param type Ending compound type (weak reference)
230 * @param data User data
231 * @returns #BT_BTR_STATUS_OK or
232 * #BT_BTR_STATUS_ERROR
234 enum bt_btr_status (* compound_end
)(
235 struct bt_field_type
*type
, void *data
);
239 * Query callback functions are used when the type reader needs
240 * dynamic information, i.e. a sequence type's current length
241 * or a variant type's current selected type.
243 * Both functions need to be set unless it is known that no
244 * sequences or variants will have to be decoded.
248 * Called to query the current length of a given sequence
251 * @param type Sequence type (weak reference)
252 * @param data User data
253 * @returns Sequence length or
254 * #BT_BTR_STATUS_ERROR on error
256 int64_t (* get_sequence_length
)(struct bt_field_type
*type
,
260 * Called to query the current selected type of a given
263 * @param type Variant type (weak reference)
264 * @param data User data
265 * @returns Current selected type (owned by
266 * this) or \c NULL on error
268 struct bt_field_type
* (* borrow_variant_field_type
)(
269 struct bt_field_type
*type
, void *data
);
274 * Creates a CTF binary type reader.
276 * @param cbs User callback functions
277 * @param data User data (passed to user callback functions)
278 * @returns New binary type reader on success, or \c NULL on error
280 struct bt_btr
*bt_btr_create(struct bt_btr_cbs cbs
, void *data
);
283 * Destroys a CTF binary type reader, freeing all internal resources.
285 * @param btr Binary type reader
287 void bt_btr_destroy(struct bt_btr
*btr
);
290 * Decodes a given CTF type from a buffer of bytes.
292 * The number of \em bits consumed by this function is returned.
294 * The \p status output parameter is where a status is written, amongst
297 * - <b>#BT_BTR_STATUS_OK</b>: Decoding is done.
298 * - <b>#BT_BTR_STATUS_EOF</b>: The end of the buffer was reached,
299 * but more data is needed to finish the decoding process of the
300 * requested type. The user needs to call bt_btr_continue()
301 * as long as #BT_BTR_STATUS_EOF is returned to complete the
302 * decoding process of the original type.
303 * - <b>#BT_BTR_STATUS_INVAL</b>: Invalid argument.
304 * - <b>#BT_BTR_STATUS_ERROR</b>: General error.
306 * Calling this function resets the type reader's internal state. If
307 * #BT_BTR_STATUS_EOF is returned, bt_btr_continue() needs to
308 * be called next, \em not bt_btr_decode().
310 * @param btr Binary type reader
311 * @param type Type to decode (weak reference)
313 * @param offset Offset of first bit from \p buf (bits)
314 * @param packet_offset Offset of \p offset within the CTF
315 * binary packet containing \p type (bits)
316 * @param sz Size of buffer in bytes (from \p buf)
317 * @param status Returned status (see description above)
318 * @returns Number of consumed bits
320 size_t bt_btr_start(struct bt_btr
*btr
,
321 struct bt_field_type
*type
, const uint8_t *buf
,
322 size_t offset
, size_t packet_offset
, size_t sz
,
323 enum bt_btr_status
*status
);
326 * Continues the decoding process a given CTF type.
328 * The number of bits consumed by this function is returned.
330 * The \p status output parameter is where a status is placed, amongst
333 * - <b>#BT_BTR_STATUS_OK</b>: decoding is done.
334 * - <b>#BT_BTR_STATUS_EOF</b>: the end of the buffer was reached,
335 * but more data is needed to finish the decoding process of the
336 * requested type. The user needs to call bt_btr_continue()
337 * as long as #BT_BTR_STATUS_EOF is returned to complete the
338 * decoding process of the original type.
339 * - <b>#BT_BTR_STATUS_INVAL</b>: invalid argument.
340 * - <b>#BT_BTR_STATUS_ERROR</b>: general error.
342 * @param btr Binary type reader
344 * @param sz Size of buffer in bytes (from \p offset)
345 * @param status Returned status (see description above)
346 * @returns Number of consumed bits
348 size_t bt_btr_continue(struct bt_btr
*btr
,
349 const uint8_t *buf
, size_t sz
,
350 enum bt_btr_status
*status
);
353 const char *bt_btr_status_string(enum bt_btr_status status
)
356 case BT_BTR_STATUS_ENOMEM
:
357 return "BT_BTR_STATUS_ENOMEM";
358 case BT_BTR_STATUS_EOF
:
359 return "BT_BTR_STATUS_EOF";
360 case BT_BTR_STATUS_INVAL
:
361 return "BT_BTR_STATUS_INVAL";
362 case BT_BTR_STATUS_ERROR
:
363 return "BT_BTR_STATUS_ERROR";
364 case BT_BTR_STATUS_OK
:
365 return "BT_BTR_STATUS_OK";
371 #endif /* CTF_BTR_H */