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 "cpp-common/vendor/fmt/format.h" /* IWYU pragma: keep */
20 #include "../metadata/tsdl/ctf-meta.hpp"
26 } /* namespace bt2c */
31 * Event-driven CTF binary field class reader (BFCR).
33 * This is a common, internal API used by CTF source plugins. It allows
34 * a binary CTF IR field class to be decoded from user-provided buffers.
35 * As the class is decoded (and, possibly, its nested classes),
36 * registered user callback functions are called.
38 * This API is only concerned with reading one CTF class at a time from
39 * one or more buffer of bytes. It does not know CTF dynamic scopes,
40 * events, or streams. Sequence lengths and selected variant classes are
41 * requested to the user when needed.
45 * Binary class reader API status codes.
50 BT_BFCR_STATUS_ENOMEM = -5,
52 * The binary stream reader reached the end of the user-provided
53 * buffer, but data is still needed to finish decoding the
56 * The user needs to call bt_bfcr_continue() as long as
57 * #BT_BFCR_STATUS_EOF is returned to complete the decoding
58 * process of a given class.
60 BT_BFCR_STATUS_EOF = 1,
62 /** Invalid argument. */
63 BT_BFCR_STATUS_INVAL = -3,
66 BT_BFCR_STATUS_ERROR = -1,
68 /** Everything okay. */
69 BT_BFCR_STATUS_OK = 0,
72 inline const char *format_as(bt_bfcr_status status) noexcept
75 case BT_BFCR_STATUS_ENOMEM:
76 return "BT_BFCR_STATUS_ENOMEM";
78 case BT_BFCR_STATUS_EOF:
79 return "BT_BFCR_STATUS_EOF";
81 case BT_BFCR_STATUS_INVAL:
82 return "BT_BFCR_STATUS_INVAL";
84 case BT_BFCR_STATUS_ERROR:
85 return "BT_BFCR_STATUS_ERROR";
87 case BT_BFCR_STATUS_OK:
88 return "BT_BFCR_STATUS_OK";
95 typedef enum bt_bfcr_status (*bt_bfcr_unsigned_int_cb_func)(uint64_t, struct ctf_field_class *,
99 * Field class reader user callback functions.
104 * Field class callback functions.
106 * This CTF binary class reader is event-driven. The following
107 * functions are called during the decoding process, either when
108 * a compound class begins/ends, or when a basic class is
109 * completely decoded (along with its value).
111 * Each function also receives the CTF field class associated
112 * with the call, and user data (registered to the class reader
115 * Actual trace IR fields are \em not created here; this would
116 * be the responsibility of a class reader's user (the provider
117 * of those callback functions).
119 * All the class callback functions return one of the following
122 * - <b>#BT_BFCR_STATUS_OK</b>: Everything is okay;
123 * continue the decoding process.
124 * - <b>#BT_BFCR_STATUS_ERROR</b>: General error (reported
125 * to class reader's user).
127 * Any member of this structure may be set to \c NULL, should
128 * a specific message be not needed.
133 * Called when a signed integer class is completely
134 * decoded. This could also be the supporting signed
135 * integer class of an enumeration class (\p class will
138 * @param value Signed integer value
139 * @param class Integer or enumeration class
140 * @param data User data
141 * @returns #BT_BFCR_STATUS_OK or
142 * #BT_BFCR_STATUS_ERROR
144 enum bt_bfcr_status (*signed_int)(int64_t value, struct ctf_field_class *cls, void *data);
147 * Called when an unsigned integer class is completely
148 * decoded. This could also be the supporting signed
149 * integer class of an enumeration class (\p class will
152 * @param value Unsigned integer value
153 * @param class Integer or enumeration class
154 * @param data User data
155 * @returns #BT_BFCR_STATUS_OK or
156 * #BT_BFCR_STATUS_ERROR
158 bt_bfcr_unsigned_int_cb_func unsigned_int;
161 * Called when a floating point number class is
162 * completely decoded.
164 * @param value Floating point number value
165 * @param class Floating point number class
166 * @param data User data
167 * @returns #BT_BFCR_STATUS_OK or
168 * #BT_BFCR_STATUS_ERROR
170 enum bt_bfcr_status (*floating_point)(double value, struct ctf_field_class *cls,
174 * Called when a string class begins.
176 * All the following user callback function calls will
177 * be made to bt_bfcr_cbs::classes::string(), each of
178 * them providing one substring of the complete string
181 * @param class Beginning 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_begin)(struct ctf_field_class *cls, void *data);
189 * Called when a string class's substring is decoded
190 * (between a call to bt_bfcr_cbs::classes::string_begin()
191 * and a call to bt_bfcr_cbs::classes::string_end()).
193 * @param value String value (\em not null-terminated)
194 * @param len String value length
195 * @param class String class
196 * @param data User data
197 * @returns #BT_BFCR_STATUS_OK or
198 * #BT_BFCR_STATUS_ERROR
200 enum bt_bfcr_status (*string)(const char *value, size_t len, struct ctf_field_class *cls,
204 * Called when a string class ends.
206 * @param class Ending string class
207 * @param data User data
208 * @returns #BT_BFCR_STATUS_OK or
209 * #BT_BFCR_STATUS_ERROR
211 enum bt_bfcr_status (*string_end)(struct ctf_field_class *cls, void *data);
214 * Called when a compound class begins.
216 * All the following class callback function calls will
217 * signal sequential elements of this compound class,
218 * until the next corresponding
219 * bt_bfcr_cbs::classes::compound_end() is called.
221 * If \p class is a variant class, then only one class
222 * callback function call will follow before the call to
223 * bt_bfcr_cbs::classes::compound_end(). This single
224 * call indicates the selected class of this variant
227 * @param class Beginning compound class
228 * @param data User data
229 * @returns #BT_BFCR_STATUS_OK or
230 * #BT_BFCR_STATUS_ERROR
232 enum bt_bfcr_status (*compound_begin)(struct ctf_field_class *cls, void *data);
235 * Called when a compound class ends.
237 * @param class Ending compound class
238 * @param data User data
239 * @returns #BT_BFCR_STATUS_OK or
240 * #BT_BFCR_STATUS_ERROR
242 enum bt_bfcr_status (*compound_end)(struct ctf_field_class *cls, void *data);
246 * Query callback functions are used when the class reader needs
247 * dynamic information, i.e. a sequence class's current length
248 * or a variant class's current selected class.
250 * Both functions need to be set unless it is known that no
251 * sequences or variants will have to be decoded.
256 * Called to query the current length of a given sequence
259 * @param class Sequence class
260 * @param data User data
261 * @returns Sequence length or
262 * #BT_BFCR_STATUS_ERROR on error
264 int64_t (*get_sequence_length)(struct ctf_field_class *cls, void *data);
267 * Called to query the current selected class of a given
270 * @param class Variant class
271 * @param data User data
272 * @returns Current selected class (owned by
273 * this) or \c NULL on error
275 struct ctf_field_class *(*borrow_variant_selected_field_class)(struct ctf_field_class *cls,
281 * Creates a CTF binary class reader.
283 * @param cbs User callback functions
284 * @param data User data (passed to user callback functions)
285 * @returns New binary class reader on success, or \c NULL on error
287 struct bt_bfcr *bt_bfcr_create(struct bt_bfcr_cbs cbs, void *data, const bt2c::Logger& logger);
290 * Destroys a CTF binary class reader, freeing all internal resources.
292 * @param bfcr Binary class reader
294 void bt_bfcr_destroy(struct bt_bfcr *bfcr);
297 * Decodes a given CTF class from a buffer of bytes.
299 * The number of \em bits consumed by this function is returned.
301 * The \p status output parameter is where a status is written, amongst
304 * - <b>#BT_BFCR_STATUS_OK</b>: Decoding is done.
305 * - <b>#BT_BFCR_STATUS_EOF</b>: The end of the buffer was reached,
306 * but more data is needed to finish the decoding process of the
307 * requested class. The user needs to call bt_bfcr_continue()
308 * as long as #BT_BFCR_STATUS_EOF is returned to complete the
309 * decoding process of the original class.
310 * - <b>#BT_BFCR_STATUS_INVAL</b>: Invalid argument.
311 * - <b>#BT_BFCR_STATUS_ERROR</b>: General error.
313 * Calling this function resets the class reader's internal state. If
314 * #BT_BFCR_STATUS_EOF is returned, bt_bfcr_continue() needs to
315 * be called next, \em not bt_bfcr_decode().
317 * @param bfcr Binary class reader
318 * @param class Field class to decode
320 * @param offset Offset of first bit from \p buf (bits)
321 * @param packet_offset Offset of \p offset within the CTF
322 * binary packet containing \p class (bits)
323 * @param sz Size of buffer in bytes (from \p buf)
324 * @param status Returned status (see description above)
325 * @returns Number of consumed bits
327 size_t bt_bfcr_start(struct bt_bfcr *bfcr, struct ctf_field_class *cls, const uint8_t *buf,
328 size_t offset, size_t packet_offset, size_t sz, enum bt_bfcr_status *status);
331 * Continues the decoding process a given CTF class.
333 * The number of bits consumed by this function is returned.
335 * The \p status output parameter is where a status is placed, amongst
338 * - <b>#BT_BFCR_STATUS_OK</b>: decoding is done.
339 * - <b>#BT_BFCR_STATUS_EOF</b>: the end of the buffer was reached,
340 * but more data is needed to finish the decoding process of the
341 * requested class. The user needs to call bt_bfcr_continue()
342 * as long as #BT_BFCR_STATUS_EOF is returned to complete the
343 * decoding process of the original class.
344 * - <b>#BT_BFCR_STATUS_INVAL</b>: invalid argument.
345 * - <b>#BT_BFCR_STATUS_ERROR</b>: general error.
347 * @param bfcr Binary class reader
349 * @param sz Size of buffer in bytes (from \p offset)
350 * @param status Returned status (see description above)
351 * @returns Number of consumed bits
353 size_t bt_bfcr_continue(struct bt_bfcr *bfcr, const uint8_t *buf, size_t sz,
354 enum bt_bfcr_status *status);
356 void bt_bfcr_set_unsigned_int_cb(struct bt_bfcr *bfcr, bt_bfcr_unsigned_int_cb_func cb);
358 #endif /* CTF_BFCR_H */