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>
21 * Event-driven CTF binary field class reader (BFCR).
23 * This is a common, internal API used by CTF source plugins. It allows
24 * a binary CTF IR field class to be decoded from user-provided buffers.
25 * As the class is decoded (and, possibly, its nested classes),
26 * registered user callback functions are called.
28 * This API is only concerned with reading one CTF class at a time from
29 * one or more buffer of bytes. It does not know CTF dynamic scopes,
30 * events, or streams. Sequence lengths and selected variant classes are
31 * requested to the user when needed.
35 * Binary class reader API status codes.
40 BT_BFCR_STATUS_ENOMEM = -5,
42 * The binary stream reader reached the end of the user-provided
43 * buffer, but data is still needed to finish decoding the
46 * The user needs to call bt_bfcr_continue() as long as
47 * #BT_BFCR_STATUS_EOF is returned to complete the decoding
48 * process of a given class.
50 BT_BFCR_STATUS_EOF = 1,
52 /** Invalid argument. */
53 BT_BFCR_STATUS_INVAL = -3,
56 BT_BFCR_STATUS_ERROR = -1,
58 /** Everything okay. */
59 BT_BFCR_STATUS_OK = 0,
62 typedef enum bt_bfcr_status (*bt_bfcr_unsigned_int_cb_func)(uint64_t, struct ctf_field_class *,
66 * Field class reader user callback functions.
71 * Field class callback functions.
73 * This CTF binary class reader is event-driven. The following
74 * functions are called during the decoding process, either when
75 * a compound class begins/ends, or when a basic class is
76 * completely decoded (along with its value).
78 * Each function also receives the CTF field class associated
79 * with the call, and user data (registered to the class reader
82 * Actual trace IR fields are \em not created here; this would
83 * be the responsibility of a class reader's user (the provider
84 * of those callback functions).
86 * All the class callback functions return one of the following
89 * - <b>#BT_BFCR_STATUS_OK</b>: Everything is okay;
90 * continue the decoding process.
91 * - <b>#BT_BFCR_STATUS_ERROR</b>: General error (reported
92 * to class reader's user).
94 * Any member of this structure may be set to \c NULL, should
95 * a specific message be not needed.
100 * Called when a signed integer class is completely
101 * decoded. This could also be the supporting signed
102 * integer class of an enumeration class (\p class will
105 * @param value Signed integer value
106 * @param class Integer or enumeration class
107 * @param data User data
108 * @returns #BT_BFCR_STATUS_OK or
109 * #BT_BFCR_STATUS_ERROR
111 enum bt_bfcr_status (*signed_int)(int64_t value, struct ctf_field_class *cls, void *data);
114 * Called when an unsigned integer class is completely
115 * decoded. This could also be the supporting signed
116 * integer class of an enumeration class (\p class will
119 * @param value Unsigned integer value
120 * @param class Integer or enumeration class
121 * @param data User data
122 * @returns #BT_BFCR_STATUS_OK or
123 * #BT_BFCR_STATUS_ERROR
125 bt_bfcr_unsigned_int_cb_func unsigned_int;
128 * Called when a floating point number class is
129 * completely decoded.
131 * @param value Floating point number value
132 * @param class Floating point number class
133 * @param data User data
134 * @returns #BT_BFCR_STATUS_OK or
135 * #BT_BFCR_STATUS_ERROR
137 enum bt_bfcr_status (*floating_point)(double value, struct ctf_field_class *cls,
141 * Called when a string class begins.
143 * All the following user callback function calls will
144 * be made to bt_bfcr_cbs::classes::string(), each of
145 * them providing one substring of the complete string
148 * @param class Beginning string class
149 * @param data User data
150 * @returns #BT_BFCR_STATUS_OK or
151 * #BT_BFCR_STATUS_ERROR
153 enum bt_bfcr_status (*string_begin)(struct ctf_field_class *cls, void *data);
156 * Called when a string class's substring is decoded
157 * (between a call to bt_bfcr_cbs::classes::string_begin()
158 * and a call to bt_bfcr_cbs::classes::string_end()).
160 * @param value String value (\em not null-terminated)
161 * @param len String value length
162 * @param class String class
163 * @param data User data
164 * @returns #BT_BFCR_STATUS_OK or
165 * #BT_BFCR_STATUS_ERROR
167 enum bt_bfcr_status (*string)(const char *value, size_t len, struct ctf_field_class *cls,
171 * Called when a string class ends.
173 * @param class Ending string class
174 * @param data User data
175 * @returns #BT_BFCR_STATUS_OK or
176 * #BT_BFCR_STATUS_ERROR
178 enum bt_bfcr_status (*string_end)(struct ctf_field_class *cls, void *data);
181 * Called when a compound class begins.
183 * All the following class callback function calls will
184 * signal sequential elements of this compound class,
185 * until the next corresponding
186 * bt_bfcr_cbs::classes::compound_end() is called.
188 * If \p class is a variant class, then only one class
189 * callback function call will follow before the call to
190 * bt_bfcr_cbs::classes::compound_end(). This single
191 * call indicates the selected class of this variant
194 * @param class Beginning compound class
195 * @param data User data
196 * @returns #BT_BFCR_STATUS_OK or
197 * #BT_BFCR_STATUS_ERROR
199 enum bt_bfcr_status (*compound_begin)(struct ctf_field_class *cls, void *data);
202 * Called when a compound class ends.
204 * @param class Ending compound class
205 * @param data User data
206 * @returns #BT_BFCR_STATUS_OK or
207 * #BT_BFCR_STATUS_ERROR
209 enum bt_bfcr_status (*compound_end)(struct ctf_field_class *cls, void *data);
213 * Query callback functions are used when the class reader needs
214 * dynamic information, i.e. a sequence class's current length
215 * or a variant class's current selected class.
217 * Both functions need to be set unless it is known that no
218 * sequences or variants will have to be decoded.
223 * Called to query the current length of a given sequence
226 * @param class Sequence class
227 * @param data User data
228 * @returns Sequence length or
229 * #BT_BFCR_STATUS_ERROR on error
231 int64_t (*get_sequence_length)(struct ctf_field_class *cls, void *data);
234 * Called to query the current selected class of a given
237 * @param class Variant class
238 * @param data User data
239 * @returns Current selected class (owned by
240 * this) or \c NULL on error
242 struct ctf_field_class *(*borrow_variant_selected_field_class)(struct ctf_field_class *cls,
248 * Creates a CTF binary class reader.
250 * @param cbs User callback functions
251 * @param data User data (passed to user callback functions)
252 * @returns New binary class reader on success, or \c NULL on error
254 struct bt_bfcr *bt_bfcr_create(struct bt_bfcr_cbs cbs, void *data, bt_logging_level log_level,
255 bt_self_component *self_comp);
258 * Destroys a CTF binary class reader, freeing all internal resources.
260 * @param bfcr Binary class reader
262 void bt_bfcr_destroy(struct bt_bfcr *bfcr);
265 * Decodes a given CTF class from a buffer of bytes.
267 * The number of \em bits consumed by this function is returned.
269 * The \p status output parameter is where a status is written, amongst
272 * - <b>#BT_BFCR_STATUS_OK</b>: Decoding is done.
273 * - <b>#BT_BFCR_STATUS_EOF</b>: The end of the buffer was reached,
274 * but more data is needed to finish the decoding process of the
275 * requested class. The user needs to call bt_bfcr_continue()
276 * as long as #BT_BFCR_STATUS_EOF is returned to complete the
277 * decoding process of the original class.
278 * - <b>#BT_BFCR_STATUS_INVAL</b>: Invalid argument.
279 * - <b>#BT_BFCR_STATUS_ERROR</b>: General error.
281 * Calling this function resets the class reader's internal state. If
282 * #BT_BFCR_STATUS_EOF is returned, bt_bfcr_continue() needs to
283 * be called next, \em not bt_bfcr_decode().
285 * @param bfcr Binary class reader
286 * @param class Field class to decode
288 * @param offset Offset of first bit from \p buf (bits)
289 * @param packet_offset Offset of \p offset within the CTF
290 * binary packet containing \p class (bits)
291 * @param sz Size of buffer in bytes (from \p buf)
292 * @param status Returned status (see description above)
293 * @returns Number of consumed bits
295 size_t bt_bfcr_start(struct bt_bfcr *bfcr, struct ctf_field_class *cls, const uint8_t *buf,
296 size_t offset, size_t packet_offset, size_t sz, enum bt_bfcr_status *status);
299 * Continues the decoding process a given CTF class.
301 * The number of bits consumed by this function is returned.
303 * The \p status output parameter is where a status is placed, amongst
306 * - <b>#BT_BFCR_STATUS_OK</b>: decoding is done.
307 * - <b>#BT_BFCR_STATUS_EOF</b>: the end of the buffer was reached,
308 * but more data is needed to finish the decoding process of the
309 * requested class. The user needs to call bt_bfcr_continue()
310 * as long as #BT_BFCR_STATUS_EOF is returned to complete the
311 * decoding process of the original class.
312 * - <b>#BT_BFCR_STATUS_INVAL</b>: invalid argument.
313 * - <b>#BT_BFCR_STATUS_ERROR</b>: general error.
315 * @param bfcr Binary class reader
317 * @param sz Size of buffer in bytes (from \p offset)
318 * @param status Returned status (see description above)
319 * @returns Number of consumed bits
321 size_t bt_bfcr_continue(struct bt_bfcr *bfcr, const uint8_t *buf, size_t sz,
322 enum bt_bfcr_status *status);
324 void bt_bfcr_set_unsigned_int_cb(struct bt_bfcr *bfcr, bt_bfcr_unsigned_int_cb_func cb);
326 static inline const char *bt_bfcr_status_string(enum bt_bfcr_status status)
329 case BT_BFCR_STATUS_ENOMEM:
331 case BT_BFCR_STATUS_EOF:
333 case BT_BFCR_STATUS_INVAL:
335 case BT_BFCR_STATUS_ERROR:
337 case BT_BFCR_STATUS_OK:
344 #endif /* CTF_BFCR_H */