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)
17 #include <babeltrace2/babeltrace.h>
19 #include "common/macros.h"
21 #include "../metadata/ctf-meta.hpp"
26 * Event-driven CTF binary field class reader (BFCR).
28 * This is a common, internal API used by CTF source plugins. It allows
29 * a binary CTF IR field class to be decoded from user-provided buffers.
30 * As the class is decoded (and, possibly, its nested classes),
31 * registered user callback functions are called.
33 * This API is only concerned with reading one CTF class at a time from
34 * one or more buffer of bytes. It does not know CTF dynamic scopes,
35 * events, or streams. Sequence lengths and selected variant classes are
36 * requested to the user when needed.
40 * Binary class reader API status codes.
45 BT_BFCR_STATUS_ENOMEM = -5,
47 * The binary stream reader reached the end of the user-provided
48 * buffer, but data is still needed to finish decoding the
51 * The user needs to call bt_bfcr_continue() as long as
52 * #BT_BFCR_STATUS_EOF is returned to complete the decoding
53 * process of a given class.
55 BT_BFCR_STATUS_EOF = 1,
57 /** Invalid argument. */
58 BT_BFCR_STATUS_INVAL = -3,
61 BT_BFCR_STATUS_ERROR = -1,
63 /** Everything okay. */
64 BT_BFCR_STATUS_OK = 0,
67 /** Field class reader. */
70 typedef enum bt_bfcr_status (*bt_bfcr_unsigned_int_cb_func)(uint64_t, struct ctf_field_class *,
74 * Field class reader user callback functions.
79 * Field class callback functions.
81 * This CTF binary class reader is event-driven. The following
82 * functions are called during the decoding process, either when
83 * a compound class begins/ends, or when a basic class is
84 * completely decoded (along with its value).
86 * Each function also receives the CTF field class associated
87 * with the call, and user data (registered to the class reader
90 * Actual trace IR fields are \em not created here; this would
91 * be the responsibility of a class reader's user (the provider
92 * of those callback functions).
94 * All the class callback functions return one of the following
97 * - <b>#BT_BFCR_STATUS_OK</b>: Everything is okay;
98 * continue the decoding process.
99 * - <b>#BT_BFCR_STATUS_ERROR</b>: General error (reported
100 * to class reader's user).
102 * Any member of this structure may be set to \c NULL, should
103 * a specific message be not needed.
108 * Called when a signed integer class is completely
109 * decoded. This could also be the supporting signed
110 * integer class of an enumeration class (\p class will
113 * @param value Signed integer value
114 * @param class Integer or enumeration class
115 * @param data User data
116 * @returns #BT_BFCR_STATUS_OK or
117 * #BT_BFCR_STATUS_ERROR
119 enum bt_bfcr_status (*signed_int)(int64_t value, struct ctf_field_class *cls, void *data);
122 * Called when an unsigned integer class is completely
123 * decoded. This could also be the supporting signed
124 * integer class of an enumeration class (\p class will
127 * @param value Unsigned integer value
128 * @param class Integer or enumeration class
129 * @param data User data
130 * @returns #BT_BFCR_STATUS_OK or
131 * #BT_BFCR_STATUS_ERROR
133 bt_bfcr_unsigned_int_cb_func unsigned_int;
136 * Called when a floating point number class is
137 * completely decoded.
139 * @param value Floating point number value
140 * @param class Floating point number class
141 * @param data User data
142 * @returns #BT_BFCR_STATUS_OK or
143 * #BT_BFCR_STATUS_ERROR
145 enum bt_bfcr_status (*floating_point)(double value, struct ctf_field_class *cls,
149 * Called when a string class begins.
151 * All the following user callback function calls will
152 * be made to bt_bfcr_cbs::classes::string(), each of
153 * them providing one substring of the complete string
156 * @param class Beginning string class
157 * @param data User data
158 * @returns #BT_BFCR_STATUS_OK or
159 * #BT_BFCR_STATUS_ERROR
161 enum bt_bfcr_status (*string_begin)(struct ctf_field_class *cls, void *data);
164 * Called when a string class's substring is decoded
165 * (between a call to bt_bfcr_cbs::classes::string_begin()
166 * and a call to bt_bfcr_cbs::classes::string_end()).
168 * @param value String value (\em not null-terminated)
169 * @param len String value length
170 * @param class String class
171 * @param data User data
172 * @returns #BT_BFCR_STATUS_OK or
173 * #BT_BFCR_STATUS_ERROR
175 enum bt_bfcr_status (*string)(const char *value, size_t len, struct ctf_field_class *cls,
179 * Called when a string class ends.
181 * @param class Ending string class
182 * @param data User data
183 * @returns #BT_BFCR_STATUS_OK or
184 * #BT_BFCR_STATUS_ERROR
186 enum bt_bfcr_status (*string_end)(struct ctf_field_class *cls, void *data);
189 * Called when a compound class begins.
191 * All the following class callback function calls will
192 * signal sequential elements of this compound class,
193 * until the next corresponding
194 * bt_bfcr_cbs::classes::compound_end() is called.
196 * If \p class is a variant class, then only one class
197 * callback function call will follow before the call to
198 * bt_bfcr_cbs::classes::compound_end(). This single
199 * call indicates the selected class of this variant
202 * @param class Beginning compound class
203 * @param data User data
204 * @returns #BT_BFCR_STATUS_OK or
205 * #BT_BFCR_STATUS_ERROR
207 enum bt_bfcr_status (*compound_begin)(struct ctf_field_class *cls, void *data);
210 * Called when a compound class ends.
212 * @param class Ending compound class
213 * @param data User data
214 * @returns #BT_BFCR_STATUS_OK or
215 * #BT_BFCR_STATUS_ERROR
217 enum bt_bfcr_status (*compound_end)(struct ctf_field_class *cls, void *data);
221 * Query callback functions are used when the class reader needs
222 * dynamic information, i.e. a sequence class's current length
223 * or a variant class's current selected class.
225 * Both functions need to be set unless it is known that no
226 * sequences or variants will have to be decoded.
231 * Called to query the current length of a given sequence
234 * @param class Sequence class
235 * @param data User data
236 * @returns Sequence length or
237 * #BT_BFCR_STATUS_ERROR on error
239 int64_t (*get_sequence_length)(struct ctf_field_class *cls, void *data);
242 * Called to query the current selected class of a given
245 * @param class Variant class
246 * @param data User data
247 * @returns Current selected class (owned by
248 * this) or \c NULL on error
250 struct ctf_field_class *(*borrow_variant_selected_field_class)(struct ctf_field_class *cls,
256 * Creates a CTF binary class reader.
258 * @param cbs User callback functions
259 * @param data User data (passed to user callback functions)
260 * @returns New binary class reader on success, or \c NULL on error
262 struct bt_bfcr *bt_bfcr_create(struct bt_bfcr_cbs cbs, void *data, bt_logging_level log_level,
263 bt_self_component *self_comp);
266 * Destroys a CTF binary class reader, freeing all internal resources.
268 * @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
303 size_t bt_bfcr_start(struct bt_bfcr *bfcr, struct ctf_field_class *cls, const uint8_t *buf,
304 size_t offset, size_t packet_offset, size_t sz, enum bt_bfcr_status *status);
307 * Continues the decoding process a given CTF class.
309 * The number of bits consumed by this function is returned.
311 * The \p status output parameter is where a status is placed, amongst
314 * - <b>#BT_BFCR_STATUS_OK</b>: decoding is done.
315 * - <b>#BT_BFCR_STATUS_EOF</b>: the end of the buffer was reached,
316 * but more data is needed to finish the decoding process of the
317 * requested class. The user needs to call bt_bfcr_continue()
318 * as long as #BT_BFCR_STATUS_EOF is returned to complete the
319 * decoding process of the original class.
320 * - <b>#BT_BFCR_STATUS_INVAL</b>: invalid argument.
321 * - <b>#BT_BFCR_STATUS_ERROR</b>: general error.
323 * @param bfcr Binary class reader
325 * @param sz Size of buffer in bytes (from \p offset)
326 * @param status Returned status (see description above)
327 * @returns Number of consumed bits
329 size_t bt_bfcr_continue(struct bt_bfcr *bfcr, const uint8_t *buf, size_t sz,
330 enum bt_bfcr_status *status);
332 void bt_bfcr_set_unsigned_int_cb(struct bt_bfcr *bfcr, bt_bfcr_unsigned_int_cb_func cb);
334 static inline const char *bt_bfcr_status_string(enum bt_bfcr_status status)
337 case BT_BFCR_STATUS_ENOMEM:
339 case BT_BFCR_STATUS_EOF:
341 case BT_BFCR_STATUS_INVAL:
343 case BT_BFCR_STATUS_ERROR:
345 case BT_BFCR_STATUS_OK:
352 #endif /* CTF_BFCR_H */