sink.text.pretty: abort on unknown field class type
[babeltrace.git] / src / plugins / ctf / common / bfcr / bfcr.hpp
CommitLineData
5cd6d0e5 1/*
0235b0db 2 * SPDX-License-Identifier: MIT
5cd6d0e5
PP
3 *
4 * Copyright (c) 2015-2016 EfficiOS Inc. and Linux Foundation
5 * Copyright (c) 2015-2016 Philippe Proulx <pproulx@efficios.com>
6 *
0235b0db 7 * Babeltrace - CTF binary field class reader (BFCR)
5cd6d0e5
PP
8 */
9
0235b0db
MJ
10#ifndef CTF_BFCR_H
11#define CTF_BFCR_H
12
5cd6d0e5 13#include <stddef.h>
c802cacb 14#include <stdint.h>
c802cacb 15
3fadfbc0 16#include <babeltrace2/babeltrace.h>
c802cacb 17
7ece2fc0
SM
18#include "common/common.h"
19
5cd6d0e5
PP
20/**
21 * @file bfcr.h
22 *
23 * Event-driven CTF binary field class reader (BFCR).
24 *
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.
29 *
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.
34 */
35
36/**
37 * Binary class reader API status codes.
38 */
4164020e
SM
39enum bt_bfcr_status
40{
41 /** Out of memory. */
42 BT_BFCR_STATUS_ENOMEM = -5,
43 /**
44 * The binary stream reader reached the end of the user-provided
45 * buffer, but data is still needed to finish decoding the
46 * requested class.
47 *
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.
51 */
52 BT_BFCR_STATUS_EOF = 1,
5cd6d0e5 53
4164020e
SM
54 /** Invalid argument. */
55 BT_BFCR_STATUS_INVAL = -3,
5cd6d0e5 56
4164020e
SM
57 /** General error. */
58 BT_BFCR_STATUS_ERROR = -1,
5cd6d0e5 59
4164020e
SM
60 /** Everything okay. */
61 BT_BFCR_STATUS_OK = 0,
5cd6d0e5
PP
62};
63
4164020e
SM
64typedef enum bt_bfcr_status (*bt_bfcr_unsigned_int_cb_func)(uint64_t, struct ctf_field_class *,
65 void *);
5cd6d0e5
PP
66
67/*
68 * Field class reader user callback functions.
69 */
4164020e
SM
70struct bt_bfcr_cbs
71{
72 /**
73 * Field class callback functions.
74 *
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).
79 *
80 * Each function also receives the CTF field class associated
81 * with the call, and user data (registered to the class reader
82 * calling them).
83 *
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).
87 *
88 * All the class callback functions return one of the following
89 * values:
90 *
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).
95 *
96 * Any member of this structure may be set to \c NULL, should
97 * a specific message be not needed.
98 */
99 struct
100 {
101 /**
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
105 * indicate this).
106 *
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
112 */
113 enum bt_bfcr_status (*signed_int)(int64_t value, struct ctf_field_class *cls, void *data);
5cd6d0e5 114
4164020e
SM
115 /**
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
119 * indicate this).
120 *
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
126 */
127 bt_bfcr_unsigned_int_cb_func unsigned_int;
5cd6d0e5 128
4164020e
SM
129 /**
130 * Called when a floating point number class is
131 * completely decoded.
132 *
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
138 */
139 enum bt_bfcr_status (*floating_point)(double value, struct ctf_field_class *cls,
140 void *data);
5cd6d0e5 141
4164020e
SM
142 /**
143 * Called when a string class begins.
144 *
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
148 * class's value.
149 *
150 * @param class Beginning string class
151 * @param data User data
152 * @returns #BT_BFCR_STATUS_OK or
153 * #BT_BFCR_STATUS_ERROR
154 */
155 enum bt_bfcr_status (*string_begin)(struct ctf_field_class *cls, void *data);
5cd6d0e5 156
4164020e
SM
157 /**
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()).
161 *
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
168 */
169 enum bt_bfcr_status (*string)(const char *value, size_t len, struct ctf_field_class *cls,
170 void *data);
5cd6d0e5 171
4164020e
SM
172 /**
173 * Called when a string class ends.
174 *
175 * @param class Ending string class
176 * @param data User data
177 * @returns #BT_BFCR_STATUS_OK or
178 * #BT_BFCR_STATUS_ERROR
179 */
180 enum bt_bfcr_status (*string_end)(struct ctf_field_class *cls, void *data);
5cd6d0e5 181
4164020e
SM
182 /**
183 * Called when a compound class begins.
184 *
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.
189 *
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
194 * class.
195 *
196 * @param class Beginning compound class
197 * @param data User data
198 * @returns #BT_BFCR_STATUS_OK or
199 * #BT_BFCR_STATUS_ERROR
200 */
201 enum bt_bfcr_status (*compound_begin)(struct ctf_field_class *cls, void *data);
5cd6d0e5 202
4164020e
SM
203 /**
204 * Called when a compound class ends.
205 *
206 * @param class Ending compound class
207 * @param data User data
208 * @returns #BT_BFCR_STATUS_OK or
209 * #BT_BFCR_STATUS_ERROR
210 */
211 enum bt_bfcr_status (*compound_end)(struct ctf_field_class *cls, void *data);
212 } classes;
5cd6d0e5 213
4164020e
SM
214 /**
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.
218 *
219 * Both functions need to be set unless it is known that no
220 * sequences or variants will have to be decoded.
221 */
222 struct
223 {
224 /**
225 * Called to query the current length of a given sequence
226 * class.
227 *
228 * @param class Sequence class
229 * @param data User data
230 * @returns Sequence length or
231 * #BT_BFCR_STATUS_ERROR on error
232 */
233 int64_t (*get_sequence_length)(struct ctf_field_class *cls, void *data);
5cd6d0e5 234
4164020e
SM
235 /**
236 * Called to query the current selected class of a given
237 * variant class.
238 *
239 * @param class Variant class
240 * @param data User data
241 * @returns Current selected class (owned by
242 * this) or \c NULL on error
243 */
244 struct ctf_field_class *(*borrow_variant_selected_field_class)(struct ctf_field_class *cls,
245 void *data);
246 } query;
5cd6d0e5
PP
247};
248
249/**
250 * Creates a CTF binary class reader.
251 *
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
255 */
4164020e
SM
256struct bt_bfcr *bt_bfcr_create(struct bt_bfcr_cbs cbs, void *data, bt_logging_level log_level,
257 bt_self_component *self_comp);
5cd6d0e5
PP
258
259/**
260 * Destroys a CTF binary class reader, freeing all internal resources.
261 *
262 * @param bfcr Binary class reader
263 */
5cd6d0e5
PP
264void bt_bfcr_destroy(struct bt_bfcr *bfcr);
265
266/**
267 * Decodes a given CTF class from a buffer of bytes.
268 *
269 * The number of \em bits consumed by this function is returned.
270 *
271 * The \p status output parameter is where a status is written, amongst
272 * the following:
273 *
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.
282 *
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().
286 *
287 * @param bfcr Binary class reader
288 * @param class Field class to decode
289 * @param buf Buffer
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
296 */
4164020e
SM
297size_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);
5cd6d0e5
PP
299
300/**
301 * Continues the decoding process a given CTF class.
302 *
303 * The number of bits consumed by this function is returned.
304 *
305 * The \p status output parameter is where a status is placed, amongst
306 * the following:
307 *
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.
316 *
317 * @param bfcr Binary class reader
318 * @param buf Buffer
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
322 */
4164020e
SM
323size_t bt_bfcr_continue(struct bt_bfcr *bfcr, const uint8_t *buf, size_t sz,
324 enum bt_bfcr_status *status);
5cd6d0e5 325
4164020e 326void bt_bfcr_set_unsigned_int_cb(struct bt_bfcr *bfcr, bt_bfcr_unsigned_int_cb_func cb);
5cd6d0e5 327
4164020e 328static inline const char *bt_bfcr_status_string(enum bt_bfcr_status status)
5cd6d0e5 329{
4164020e
SM
330 switch (status) {
331 case BT_BFCR_STATUS_ENOMEM:
332 return "ENOMEM";
333 case BT_BFCR_STATUS_EOF:
334 return "EOF";
335 case BT_BFCR_STATUS_INVAL:
336 return "INVAL";
337 case BT_BFCR_STATUS_ERROR:
338 return "ERROR";
339 case BT_BFCR_STATUS_OK:
340 return "OK";
341 }
00dff0ec 342
4164020e 343 bt_common_abort();
5cd6d0e5
PP
344}
345
346#endif /* CTF_BFCR_H */
This page took 0.095501 seconds and 4 git commands to generate.