2 * SPDX-License-Identifier: MIT
4 * Copyright (c) 2015-2016 EfficiOS Inc. and Linux Foundation
5 * Copyright (c) 2015-2016 Philippe Proulx <pproulx@efficios.com>
7 * Babeltrace - CTF binary field class reader (BFCR)
16 #include <babeltrace2/babeltrace.h>
17 #include "common/macros.h"
19 #include "../metadata/ctf-meta.hpp"
24 * Event-driven CTF binary field class reader (BFCR).
26 * This is a common, internal API used by CTF source plugins. It allows
27 * a binary CTF IR field class to be decoded from user-provided buffers.
28 * As the class is decoded (and, possibly, its nested classes),
29 * registered user callback functions are called.
31 * This API is only concerned with reading one CTF class at a time from
32 * one or more buffer of bytes. It does not know CTF dynamic scopes,
33 * events, or streams. Sequence lengths and selected variant classes are
34 * requested to the user when needed.
38 * Binary class reader API status codes.
43 BT_BFCR_STATUS_ENOMEM = -5,
45 * The binary stream reader reached the end of the user-provided
46 * buffer, but data is still needed to finish decoding the
49 * The user needs to call bt_bfcr_continue() as long as
50 * #BT_BFCR_STATUS_EOF is returned to complete the decoding
51 * process of a given class.
53 BT_BFCR_STATUS_EOF = 1,
55 /** Invalid argument. */
56 BT_BFCR_STATUS_INVAL = -3,
59 BT_BFCR_STATUS_ERROR = -1,
61 /** Everything okay. */
62 BT_BFCR_STATUS_OK = 0,
65 /** Field class reader. */
68 typedef enum bt_bfcr_status (*bt_bfcr_unsigned_int_cb_func)(uint64_t, struct ctf_field_class *,
72 * Field class reader user callback functions.
77 * Field class callback functions.
79 * This CTF binary class reader is event-driven. The following
80 * functions are called during the decoding process, either when
81 * a compound class begins/ends, or when a basic class is
82 * completely decoded (along with its value).
84 * Each function also receives the CTF field class associated
85 * with the call, and user data (registered to the class reader
88 * Actual trace IR fields are \em not created here; this would
89 * be the responsibility of a class reader's user (the provider
90 * of those callback functions).
92 * All the class callback functions return one of the following
95 * - <b>#BT_BFCR_STATUS_OK</b>: Everything is okay;
96 * continue the decoding process.
97 * - <b>#BT_BFCR_STATUS_ERROR</b>: General error (reported
98 * to class reader's user).
100 * Any member of this structure may be set to \c NULL, should
101 * a specific message be not needed.
106 * Called when a signed integer class is completely
107 * decoded. This could also be the supporting signed
108 * integer class of an enumeration class (\p class will
111 * @param value Signed integer value
112 * @param class Integer or enumeration class
113 * @param data User data
114 * @returns #BT_BFCR_STATUS_OK or
115 * #BT_BFCR_STATUS_ERROR
117 enum bt_bfcr_status (*signed_int)(int64_t value, struct ctf_field_class *cls, void *data);
120 * Called when an unsigned integer class is completely
121 * decoded. This could also be the supporting signed
122 * integer class of an enumeration class (\p class will
125 * @param value Unsigned integer value
126 * @param class Integer or enumeration class
127 * @param data User data
128 * @returns #BT_BFCR_STATUS_OK or
129 * #BT_BFCR_STATUS_ERROR
131 bt_bfcr_unsigned_int_cb_func unsigned_int;
134 * Called when a floating point number class is
135 * completely decoded.
137 * @param value Floating point number value
138 * @param class Floating point number class
139 * @param data User data
140 * @returns #BT_BFCR_STATUS_OK or
141 * #BT_BFCR_STATUS_ERROR
143 enum bt_bfcr_status (*floating_point)(double value, struct ctf_field_class *cls,
147 * Called when a string class begins.
149 * All the following user callback function calls will
150 * be made to bt_bfcr_cbs::classes::string(), each of
151 * them providing one substring of the complete string
154 * @param class Beginning string class
155 * @param data User data
156 * @returns #BT_BFCR_STATUS_OK or
157 * #BT_BFCR_STATUS_ERROR
159 enum bt_bfcr_status (*string_begin)(struct ctf_field_class *cls, void *data);
162 * Called when a string class's substring is decoded
163 * (between a call to bt_bfcr_cbs::classes::string_begin()
164 * and a call to bt_bfcr_cbs::classes::string_end()).
166 * @param value String value (\em not null-terminated)
167 * @param len String value length
168 * @param class String class
169 * @param data User data
170 * @returns #BT_BFCR_STATUS_OK or
171 * #BT_BFCR_STATUS_ERROR
173 enum bt_bfcr_status (*string)(const char *value, size_t len, struct ctf_field_class *cls,
177 * Called when a string class ends.
179 * @param class Ending string class
180 * @param data User data
181 * @returns #BT_BFCR_STATUS_OK or
182 * #BT_BFCR_STATUS_ERROR
184 enum bt_bfcr_status (*string_end)(struct ctf_field_class *cls, void *data);
187 * Called when a compound class begins.
189 * All the following class callback function calls will
190 * signal sequential elements of this compound class,
191 * until the next corresponding
192 * bt_bfcr_cbs::classes::compound_end() is called.
194 * If \p class is a variant class, then only one class
195 * callback function call will follow before the call to
196 * bt_bfcr_cbs::classes::compound_end(). This single
197 * call indicates the selected class of this variant
200 * @param class Beginning compound class
201 * @param data User data
202 * @returns #BT_BFCR_STATUS_OK or
203 * #BT_BFCR_STATUS_ERROR
205 enum bt_bfcr_status (*compound_begin)(struct ctf_field_class *cls, void *data);
208 * Called when a compound class ends.
210 * @param class Ending compound class
211 * @param data User data
212 * @returns #BT_BFCR_STATUS_OK or
213 * #BT_BFCR_STATUS_ERROR
215 enum bt_bfcr_status (*compound_end)(struct ctf_field_class *cls, void *data);
219 * Query callback functions are used when the class reader needs
220 * dynamic information, i.e. a sequence class's current length
221 * or a variant class's current selected class.
223 * Both functions need to be set unless it is known that no
224 * sequences or variants will have to be decoded.
229 * Called to query the current length of a given sequence
232 * @param class Sequence class
233 * @param data User data
234 * @returns Sequence length or
235 * #BT_BFCR_STATUS_ERROR on error
237 int64_t (*get_sequence_length)(struct ctf_field_class *cls, void *data);
240 * Called to query the current selected class of a given
243 * @param class Variant class
244 * @param data User data
245 * @returns Current selected class (owned by
246 * this) or \c NULL on error
248 struct ctf_field_class *(*borrow_variant_selected_field_class)(struct ctf_field_class *cls,
254 * Creates a CTF binary class reader.
256 * @param cbs User callback functions
257 * @param data User data (passed to user callback functions)
258 * @returns New binary class reader on success, or \c NULL on error
261 struct bt_bfcr *bt_bfcr_create(struct bt_bfcr_cbs cbs, void *data, bt_logging_level log_level,
262 bt_self_component *self_comp);
265 * Destroys a CTF binary class reader, freeing all internal resources.
267 * @param bfcr Binary class reader
270 void bt_bfcr_destroy(struct bt_bfcr *bfcr);
273 * Decodes a given CTF class from a buffer of bytes.
275 * The number of \em bits consumed by this function is returned.
277 * The \p status output parameter is where a status is written, amongst
280 * - <b>#BT_BFCR_STATUS_OK</b>: Decoding is done.
281 * - <b>#BT_BFCR_STATUS_EOF</b>: The end of the buffer was reached,
282 * but more data is needed to finish the decoding process of the
283 * requested class. The user needs to call bt_bfcr_continue()
284 * as long as #BT_BFCR_STATUS_EOF is returned to complete the
285 * decoding process of the original class.
286 * - <b>#BT_BFCR_STATUS_INVAL</b>: Invalid argument.
287 * - <b>#BT_BFCR_STATUS_ERROR</b>: General error.
289 * Calling this function resets the class reader's internal state. If
290 * #BT_BFCR_STATUS_EOF is returned, bt_bfcr_continue() needs to
291 * be called next, \em not bt_bfcr_decode().
293 * @param bfcr Binary class reader
294 * @param class Field class to decode
296 * @param offset Offset of first bit from \p buf (bits)
297 * @param packet_offset Offset of \p offset within the CTF
298 * binary packet containing \p class (bits)
299 * @param sz Size of buffer in bytes (from \p buf)
300 * @param status Returned status (see description above)
301 * @returns Number of consumed bits
304 size_t bt_bfcr_start(struct bt_bfcr *bfcr, struct ctf_field_class *cls, const uint8_t *buf,
305 size_t offset, size_t packet_offset, size_t sz, enum bt_bfcr_status *status);
308 * Continues the decoding process a given CTF class.
310 * The number of bits consumed by this function is returned.
312 * The \p status output parameter is where a status is placed, amongst
315 * - <b>#BT_BFCR_STATUS_OK</b>: decoding is done.
316 * - <b>#BT_BFCR_STATUS_EOF</b>: the end of the buffer was reached,
317 * but more data is needed to finish the decoding process of the
318 * requested class. The user needs to call bt_bfcr_continue()
319 * as long as #BT_BFCR_STATUS_EOF is returned to complete the
320 * decoding process of the original class.
321 * - <b>#BT_BFCR_STATUS_INVAL</b>: invalid argument.
322 * - <b>#BT_BFCR_STATUS_ERROR</b>: general error.
324 * @param bfcr Binary class reader
326 * @param sz Size of buffer in bytes (from \p offset)
327 * @param status Returned status (see description above)
328 * @returns Number of consumed bits
331 size_t bt_bfcr_continue(struct bt_bfcr *bfcr, const uint8_t *buf, size_t sz,
332 enum bt_bfcr_status *status);
335 void bt_bfcr_set_unsigned_int_cb(struct bt_bfcr *bfcr, bt_bfcr_unsigned_int_cb_func cb);
337 static inline const char *bt_bfcr_status_string(enum bt_bfcr_status status)
340 case BT_BFCR_STATUS_ENOMEM:
342 case BT_BFCR_STATUS_EOF:
344 case BT_BFCR_STATUS_INVAL:
346 case BT_BFCR_STATUS_ERROR:
348 case BT_BFCR_STATUS_OK:
355 #endif /* CTF_BFCR_H */