dbfef72a69a79b6f81023d8a9942edd5544b0d14
[babeltrace.git] / plugins / ctf / common / btr / btr.h
1 #ifndef CTF_BTR_H
2 #define CTF_BTR_H
3
4 /*
5 * Babeltrace - CTF binary type reader (BTR)
6 *
7 * Copyright (c) 2015-2016 EfficiOS Inc. and Linux Foundation
8 * Copyright (c) 2015-2016 Philippe Proulx <pproulx@efficios.com>
9 *
10 * Permission is hereby granted, free of charge, to any person obtaining a copy
11 * of this software and associated documentation files (the "Software"), to deal
12 * in the Software without restriction, including without limitation the rights
13 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14 * copies of the Software, and to permit persons to whom the Software is
15 * furnished to do so, subject to the following conditions:
16 *
17 * The above copyright notice and this permission notice shall be included in
18 * all copies or substantial portions of the Software.
19 *
20 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 * SOFTWARE.
27 */
28
29 #include <stdint.h>
30 #include <stddef.h>
31 #include <stdio.h>
32 #include <babeltrace/babeltrace.h>
33 #include <babeltrace/babeltrace-internal.h>
34
35 /**
36 * @file ctf-btr.h
37 *
38 * Event-driven CTF binary type reader (BTR).
39 *
40 * This is a common, internal API used by CTF source plugins. It allows
41 * a binary CTF IR field type to be decoded from user-provided buffers.
42 * As the type is decoded (and, possibly, its nested types), registered
43 * user callback functions are called.
44 *
45 * This API is only concerned with reading one CTF type at a time from
46 * one or more buffer of bytes. It does not know CTF dynamic scopes,
47 * events, or streams. Sequence lengths and selected variant types are
48 * requested to the user when needed.
49 */
50
51 /**
52 * Binary type reader API status codes.
53 */
54 enum bt_btr_status {
55 /** Out of memory. */
56 BT_BTR_STATUS_ENOMEM = -5,
57 /**
58 * The binary stream reader reached the end of the user-provided
59 * buffer, but data is still needed to finish decoding the
60 * requested type.
61 *
62 * The user needs to call bt_btr_continue() as long as
63 * #BT_BTR_STATUS_EOF is returned to complete the decoding
64 * process of a given type.
65 */
66 BT_BTR_STATUS_EOF = 1,
67
68 /** Invalid argument. */
69 BT_BTR_STATUS_INVAL = -3,
70
71 /** General error. */
72 BT_BTR_STATUS_ERROR = -1,
73
74 /** Everything okay. */
75 BT_BTR_STATUS_OK = 0,
76 };
77
78 /** Type reader. */
79 struct bt_btr;
80
81 /*
82 * Type reader user callback functions.
83 */
84 struct bt_btr_cbs {
85 /**
86 * Type callback functions.
87 *
88 * This CTF binary type reader is event-driven. The following
89 * functions are called during the decoding process, either when
90 * a compound type begins/ends, or when a basic type is
91 * completely decoded (along with its value).
92 *
93 * Each function also receives the CTF IR field type associated
94 * with the call, and user data (registered to the type reader
95 * calling them). This field type is a weak reference; the
96 * callback function must use bt_field_type_get() to keep
97 * its own reference of it.
98 *
99 * Actual CTF IR fields are \em not created here; this would be
100 * the responsibility of a type reader's user (the provider of
101 * those callback functions).
102 *
103 * All the type callback functions return one of the following
104 * values:
105 *
106 * - <b>#BT_BTR_STATUS_OK</b>: Everything is okay;
107 * continue the decoding process.
108 * - <b>#BT_BTR_STATUS_ERROR</b>: General error (reported
109 * to type reader's user).
110 *
111 * Any member of this structure may be set to \c NULL, should
112 * a specific notification be not needed.
113 */
114 struct {
115 /**
116 * Called when a signed integer type is completely
117 * decoded. This could also be the supporting signed
118 * integer type of an enumeration type (\p type will
119 * indicate this).
120 *
121 * @param value Signed integer value
122 * @param type Integer or enumeration type (weak
123 * reference)
124 * @param data User data
125 * @returns #BT_BTR_STATUS_OK or
126 * #BT_BTR_STATUS_ERROR
127 */
128 enum bt_btr_status (* signed_int)(int64_t value,
129 struct bt_field_type *type, void *data);
130
131 /**
132 * Called when an unsigned integer type is completely
133 * decoded. This could also be the supporting signed
134 * integer type of an enumeration type (\p type will
135 * indicate this).
136 *
137 * @param value Unsigned integer value
138 * @param type Integer or enumeration type (weak
139 * reference)
140 * @param data User data
141 * @returns #BT_BTR_STATUS_OK or
142 * #BT_BTR_STATUS_ERROR
143 */
144 enum bt_btr_status (* unsigned_int)(uint64_t value,
145 struct bt_field_type *type, void *data);
146
147 /**
148 * Called when a floating point number type is
149 * completely decoded.
150 *
151 * @param value Floating point number value
152 * @param type Floating point number type (weak
153 * reference)
154 * @param data User data
155 * @returns #BT_BTR_STATUS_OK or
156 * #BT_BTR_STATUS_ERROR
157 */
158 enum bt_btr_status (* floating_point)(double value,
159 struct bt_field_type *type, void *data);
160
161 /**
162 * Called when a string type begins.
163 *
164 * All the following user callback function calls will
165 * be made to bt_btr_cbs::types::string(), each of
166 * them providing one substring of the complete string
167 * type's value.
168 *
169 * @param type Beginning string type (weak reference)
170 * @param data User data
171 * @returns #BT_BTR_STATUS_OK or
172 * #BT_BTR_STATUS_ERROR
173 */
174 enum bt_btr_status (* string_begin)(
175 struct bt_field_type *type, void *data);
176
177 /**
178 * Called when a string type's substring is decoded
179 * (between a call to bt_btr_cbs::types::string_begin()
180 * and a call to bt_btr_cbs::types::string_end()).
181 *
182 * @param value String value (\em not null-terminated)
183 * @param len String value length
184 * @param type String type (weak reference)
185 * @param data User data
186 * @returns #BT_BTR_STATUS_OK or
187 * #BT_BTR_STATUS_ERROR
188 */
189 enum bt_btr_status (* string)(const char *value,
190 size_t len, struct bt_field_type *type,
191 void *data);
192
193 /**
194 * Called when a string type ends.
195 *
196 * @param type Ending string type (weak reference)
197 * @param data User data
198 * @returns #BT_BTR_STATUS_OK or
199 * #BT_BTR_STATUS_ERROR
200 */
201 enum bt_btr_status (* string_end)(
202 struct bt_field_type *type, void *data);
203
204 /**
205 * Called when a compound type begins.
206 *
207 * All the following type callback function calls will
208 * signal sequential elements of this compound type,
209 * until the next corresponding
210 * bt_btr_cbs::types::compound_end() is called.
211 *
212 * If \p type is a variant type, then only one type
213 * callback function call will follow before the call to
214 * bt_btr_cbs::types::compound_end(). This single
215 * call indicates the selected type of this variant
216 * type.
217 *
218 * @param type Beginning compound type (weak reference)
219 * @param data User data
220 * @returns #BT_BTR_STATUS_OK or
221 * #BT_BTR_STATUS_ERROR
222 */
223 enum bt_btr_status (* compound_begin)(
224 struct bt_field_type *type, void *data);
225
226 /**
227 * Called when a compound type ends.
228 *
229 * @param type Ending compound type (weak reference)
230 * @param data User data
231 * @returns #BT_BTR_STATUS_OK or
232 * #BT_BTR_STATUS_ERROR
233 */
234 enum bt_btr_status (* compound_end)(
235 struct bt_field_type *type, void *data);
236 } types;
237
238 /**
239 * Query callback functions are used when the type reader needs
240 * dynamic information, i.e. a sequence type's current length
241 * or a variant type's current selected type.
242 *
243 * Both functions need to be set unless it is known that no
244 * sequences or variants will have to be decoded.
245 */
246 struct {
247 /**
248 * Called to query the current length of a given sequence
249 * type.
250 *
251 * @param type Sequence type (weak reference)
252 * @param data User data
253 * @returns Sequence length or
254 * #BT_BTR_STATUS_ERROR on error
255 */
256 int64_t (* get_sequence_length)(struct bt_field_type *type,
257 void *data);
258
259 /**
260 * Called to query the current selected type of a given
261 * variant type.
262 *
263 * @param type Variant type (weak reference)
264 * @param data User data
265 * @returns Current selected type (owned by
266 * this) or \c NULL on error
267 */
268 struct bt_field_type * (* borrow_variant_field_type)(
269 struct bt_field_type *type, void *data);
270 } query;
271 };
272
273 /**
274 * Creates a CTF binary type reader.
275 *
276 * @param cbs User callback functions
277 * @param data User data (passed to user callback functions)
278 * @returns New binary type reader on success, or \c NULL on error
279 */
280 struct bt_btr *bt_btr_create(struct bt_btr_cbs cbs, void *data);
281
282 /**
283 * Destroys a CTF binary type reader, freeing all internal resources.
284 *
285 * @param btr Binary type reader
286 */
287 void bt_btr_destroy(struct bt_btr *btr);
288
289 /**
290 * Decodes a given CTF type from a buffer of bytes.
291 *
292 * The number of \em bits consumed by this function is returned.
293 *
294 * The \p status output parameter is where a status is written, amongst
295 * the following:
296 *
297 * - <b>#BT_BTR_STATUS_OK</b>: Decoding is done.
298 * - <b>#BT_BTR_STATUS_EOF</b>: The end of the buffer was reached,
299 * but more data is needed to finish the decoding process of the
300 * requested type. The user needs to call bt_btr_continue()
301 * as long as #BT_BTR_STATUS_EOF is returned to complete the
302 * decoding process of the original type.
303 * - <b>#BT_BTR_STATUS_INVAL</b>: Invalid argument.
304 * - <b>#BT_BTR_STATUS_ERROR</b>: General error.
305 *
306 * Calling this function resets the type reader's internal state. If
307 * #BT_BTR_STATUS_EOF is returned, bt_btr_continue() needs to
308 * be called next, \em not bt_btr_decode().
309 *
310 * @param btr Binary type reader
311 * @param type Type to decode (weak reference)
312 * @param buf Buffer
313 * @param offset Offset of first bit from \p buf (bits)
314 * @param packet_offset Offset of \p offset within the CTF
315 * binary packet containing \p type (bits)
316 * @param sz Size of buffer in bytes (from \p buf)
317 * @param status Returned status (see description above)
318 * @returns Number of consumed bits
319 */
320 size_t bt_btr_start(struct bt_btr *btr,
321 struct bt_field_type *type, const uint8_t *buf,
322 size_t offset, size_t packet_offset, size_t sz,
323 enum bt_btr_status *status);
324
325 /**
326 * Continues the decoding process a given CTF type.
327 *
328 * The number of bits consumed by this function is returned.
329 *
330 * The \p status output parameter is where a status is placed, amongst
331 * the following:
332 *
333 * - <b>#BT_BTR_STATUS_OK</b>: decoding is done.
334 * - <b>#BT_BTR_STATUS_EOF</b>: the end of the buffer was reached,
335 * but more data is needed to finish the decoding process of the
336 * requested type. The user needs to call bt_btr_continue()
337 * as long as #BT_BTR_STATUS_EOF is returned to complete the
338 * decoding process of the original type.
339 * - <b>#BT_BTR_STATUS_INVAL</b>: invalid argument.
340 * - <b>#BT_BTR_STATUS_ERROR</b>: general error.
341 *
342 * @param btr Binary type reader
343 * @param buf Buffer
344 * @param sz Size of buffer in bytes (from \p offset)
345 * @param status Returned status (see description above)
346 * @returns Number of consumed bits
347 */
348 size_t bt_btr_continue(struct bt_btr *btr,
349 const uint8_t *buf, size_t sz,
350 enum bt_btr_status *status);
351
352 static inline
353 const char *bt_btr_status_string(enum bt_btr_status status)
354 {
355 switch (status) {
356 case BT_BTR_STATUS_ENOMEM:
357 return "BT_BTR_STATUS_ENOMEM";
358 case BT_BTR_STATUS_EOF:
359 return "BT_BTR_STATUS_EOF";
360 case BT_BTR_STATUS_INVAL:
361 return "BT_BTR_STATUS_INVAL";
362 case BT_BTR_STATUS_ERROR:
363 return "BT_BTR_STATUS_ERROR";
364 case BT_BTR_STATUS_OK:
365 return "BT_BTR_STATUS_OK";
366 default:
367 return "(unknown)";
368 }
369 }
370
371 #endif /* CTF_BTR_H */
This page took 0.044478 seconds and 3 git commands to generate.