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>
18 #include "../metadata/tsdl/ctf-meta.hpp"
23 * Event-driven CTF binary field class reader (BFCR).
25 * This is a common, internal API used by CTF source plugins. It allows
26 * a binary CTF IR field class to be decoded from user-provided buffers.
27 * As the class is decoded (and, possibly, its nested classes),
28 * registered user callback functions are called.
30 * This API is only concerned with reading one CTF class at a time from
31 * one or more buffer of bytes. It does not know CTF dynamic scopes,
32 * events, or streams. Sequence lengths and selected variant classes are
33 * requested to the user when needed.
37 * Binary class reader API status codes.
42 BT_BFCR_STATUS_ENOMEM = -5,
44 * The binary stream reader reached the end of the user-provided
45 * buffer, but data is still needed to finish decoding the
48 * The user needs to call bt_bfcr_continue() as long as
49 * #BT_BFCR_STATUS_EOF is returned to complete the decoding
50 * process of a given class.
52 BT_BFCR_STATUS_EOF = 1,
54 /** Invalid argument. */
55 BT_BFCR_STATUS_INVAL = -3,
58 BT_BFCR_STATUS_ERROR = -1,
60 /** Everything okay. */
61 BT_BFCR_STATUS_OK = 0,
64 typedef enum bt_bfcr_status (*bt_bfcr_unsigned_int_cb_func)(uint64_t, struct ctf_field_class *,
68 * Field class reader user callback functions.
73 * Field class callback functions.
75 * This CTF binary class reader is event-driven. The following
76 * functions are called during the decoding process, either when
77 * a compound class begins/ends, or when a basic class is
78 * completely decoded (along with its value).
80 * Each function also receives the CTF field class associated
81 * with the call, and user data (registered to the class reader
84 * Actual trace IR fields are \em not created here; this would
85 * be the responsibility of a class reader's user (the provider
86 * of those callback functions).
88 * All the class callback functions return one of the following
91 * - <b>#BT_BFCR_STATUS_OK</b>: Everything is okay;
92 * continue the decoding process.
93 * - <b>#BT_BFCR_STATUS_ERROR</b>: General error (reported
94 * to class reader's user).
96 * Any member of this structure may be set to \c NULL, should
97 * a specific message be not needed.
102 * Called when a signed integer class is completely
103 * decoded. This could also be the supporting signed
104 * integer class of an enumeration class (\p class will
107 * @param value Signed integer value
108 * @param class Integer or enumeration class
109 * @param data User data
110 * @returns #BT_BFCR_STATUS_OK or
111 * #BT_BFCR_STATUS_ERROR
113 enum bt_bfcr_status (*signed_int)(int64_t value, struct ctf_field_class *cls, void *data);
116 * Called when an unsigned integer class is completely
117 * decoded. This could also be the supporting signed
118 * integer class of an enumeration class (\p class will
121 * @param value Unsigned integer value
122 * @param class Integer or enumeration class
123 * @param data User data
124 * @returns #BT_BFCR_STATUS_OK or
125 * #BT_BFCR_STATUS_ERROR
127 bt_bfcr_unsigned_int_cb_func unsigned_int;
130 * Called when a floating point number class is
131 * completely decoded.
133 * @param value Floating point number value
134 * @param class Floating point number class
135 * @param data User data
136 * @returns #BT_BFCR_STATUS_OK or
137 * #BT_BFCR_STATUS_ERROR
139 enum bt_bfcr_status (*floating_point)(double value, struct ctf_field_class *cls,
143 * Called when a string class begins.
145 * All the following user callback function calls will
146 * be made to bt_bfcr_cbs::classes::string(), each of
147 * them providing one substring of the complete string
150 * @param class Beginning string class
151 * @param data User data
152 * @returns #BT_BFCR_STATUS_OK or
153 * #BT_BFCR_STATUS_ERROR
155 enum bt_bfcr_status (*string_begin)(struct ctf_field_class *cls, void *data);
158 * Called when a string class's substring is decoded
159 * (between a call to bt_bfcr_cbs::classes::string_begin()
160 * and a call to bt_bfcr_cbs::classes::string_end()).
162 * @param value String value (\em not null-terminated)
163 * @param len String value length
164 * @param class String class
165 * @param data User data
166 * @returns #BT_BFCR_STATUS_OK or
167 * #BT_BFCR_STATUS_ERROR
169 enum bt_bfcr_status (*string)(const char *value, size_t len, struct ctf_field_class *cls,
173 * Called when a string class ends.
175 * @param class Ending string class
176 * @param data User data
177 * @returns #BT_BFCR_STATUS_OK or
178 * #BT_BFCR_STATUS_ERROR
180 enum bt_bfcr_status (*string_end)(struct ctf_field_class *cls, void *data);
183 * Called when a compound class begins.
185 * All the following class callback function calls will
186 * signal sequential elements of this compound class,
187 * until the next corresponding
188 * bt_bfcr_cbs::classes::compound_end() is called.
190 * If \p class is a variant class, then only one class
191 * callback function call will follow before the call to
192 * bt_bfcr_cbs::classes::compound_end(). This single
193 * call indicates the selected class of this variant
196 * @param class Beginning compound class
197 * @param data User data
198 * @returns #BT_BFCR_STATUS_OK or
199 * #BT_BFCR_STATUS_ERROR
201 enum bt_bfcr_status (*compound_begin)(struct ctf_field_class *cls, void *data);
204 * Called when a compound class ends.
206 * @param class Ending compound class
207 * @param data User data
208 * @returns #BT_BFCR_STATUS_OK or
209 * #BT_BFCR_STATUS_ERROR
211 enum bt_bfcr_status (*compound_end)(struct ctf_field_class *cls, void *data);
215 * Query callback functions are used when the class reader needs
216 * dynamic information, i.e. a sequence class's current length
217 * or a variant class's current selected class.
219 * Both functions need to be set unless it is known that no
220 * sequences or variants will have to be decoded.
225 * Called to query the current length of a given sequence
228 * @param class Sequence class
229 * @param data User data
230 * @returns Sequence length or
231 * #BT_BFCR_STATUS_ERROR on error
233 int64_t (*get_sequence_length)(struct ctf_field_class *cls, void *data);
236 * Called to query the current selected class of a given
239 * @param class Variant class
240 * @param data User data
241 * @returns Current selected class (owned by
242 * this) or \c NULL on error
244 struct ctf_field_class *(*borrow_variant_selected_field_class)(struct ctf_field_class *cls,
250 * Creates a CTF binary class reader.
252 * @param cbs User callback functions
253 * @param data User data (passed to user callback functions)
254 * @returns New binary class reader on success, or \c NULL on error
256 struct bt_bfcr *bt_bfcr_create(struct bt_bfcr_cbs cbs, void *data, bt_logging_level log_level,
257 bt_self_component *self_comp);
260 * Destroys a CTF binary class reader, freeing all internal resources.
262 * @param bfcr Binary class reader
264 void bt_bfcr_destroy(struct bt_bfcr *bfcr);
267 * Decodes a given CTF class from a buffer of bytes.
269 * The number of \em bits consumed by this function is returned.
271 * The \p status output parameter is where a status is written, amongst
274 * - <b>#BT_BFCR_STATUS_OK</b>: Decoding is done.
275 * - <b>#BT_BFCR_STATUS_EOF</b>: The end of the buffer was reached,
276 * but more data is needed to finish the decoding process of the
277 * requested class. The user needs to call bt_bfcr_continue()
278 * as long as #BT_BFCR_STATUS_EOF is returned to complete the
279 * decoding process of the original class.
280 * - <b>#BT_BFCR_STATUS_INVAL</b>: Invalid argument.
281 * - <b>#BT_BFCR_STATUS_ERROR</b>: General error.
283 * Calling this function resets the class reader's internal state. If
284 * #BT_BFCR_STATUS_EOF is returned, bt_bfcr_continue() needs to
285 * be called next, \em not bt_bfcr_decode().
287 * @param bfcr Binary class reader
288 * @param class Field class to decode
290 * @param offset Offset of first bit from \p buf (bits)
291 * @param packet_offset Offset of \p offset within the CTF
292 * binary packet containing \p class (bits)
293 * @param sz Size of buffer in bytes (from \p buf)
294 * @param status Returned status (see description above)
295 * @returns Number of consumed bits
297 size_t bt_bfcr_start(struct bt_bfcr *bfcr, struct ctf_field_class *cls, const uint8_t *buf,
298 size_t offset, size_t packet_offset, size_t sz, enum bt_bfcr_status *status);
301 * Continues the decoding process a given CTF class.
303 * The number of bits consumed by this function is returned.
305 * The \p status output parameter is where a status is placed, amongst
308 * - <b>#BT_BFCR_STATUS_OK</b>: decoding is done.
309 * - <b>#BT_BFCR_STATUS_EOF</b>: the end of the buffer was reached,
310 * but more data is needed to finish the decoding process of the
311 * requested class. The user needs to call bt_bfcr_continue()
312 * as long as #BT_BFCR_STATUS_EOF is returned to complete the
313 * decoding process of the original class.
314 * - <b>#BT_BFCR_STATUS_INVAL</b>: invalid argument.
315 * - <b>#BT_BFCR_STATUS_ERROR</b>: general error.
317 * @param bfcr Binary class reader
319 * @param sz Size of buffer in bytes (from \p offset)
320 * @param status Returned status (see description above)
321 * @returns Number of consumed bits
323 size_t bt_bfcr_continue(struct bt_bfcr *bfcr, const uint8_t *buf, size_t sz,
324 enum bt_bfcr_status *status);
326 void bt_bfcr_set_unsigned_int_cb(struct bt_bfcr *bfcr, bt_bfcr_unsigned_int_cb_func cb);
328 static inline const char *bt_bfcr_status_string(enum bt_bfcr_status status)
331 case BT_BFCR_STATUS_ENOMEM:
333 case BT_BFCR_STATUS_EOF:
335 case BT_BFCR_STATUS_INVAL:
337 case BT_BFCR_STATUS_ERROR:
339 case BT_BFCR_STATUS_OK:
346 #endif /* CTF_BFCR_H */