7548415527b4860cfedfead5d1c01ce2fe929d65
5 * Babeltrace - CTF binary type reader (BTR)
7 * Copyright (c) 2015-2016 EfficiOS Inc. and Linux Foundation
8 * Copyright (c) 2015-2016 Philippe Proulx <pproulx@efficios.com>
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:
17 * The above copyright notice and this permission notice shall be included in
18 * all copies or substantial portions of the Software.
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
32 #include <babeltrace/ctf-ir/field-types.h>
33 #include <babeltrace/babeltrace-internal.h>
38 * Event-driven CTF binary type reader (BTR).
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.
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.
52 * Binary type reader API status codes.
54 enum bt_ctf_btr_status
{
56 * The binary stream reader reached the end of the user-provided
57 * buffer, but data is still needed to finish decoding the
60 * The user needs to call bt_ctf_btr_continue() as long as
61 * #BT_CTF_BTR_STATUS_EOF is returned to complete the decoding
62 * process of a given type.
64 BT_CTF_BTR_STATUS_EOF
= -4,
66 /** Invalid argument. */
67 BT_CTF_BTR_STATUS_INVAL
= -3,
70 BT_CTF_BTR_STATUS_ERROR
= -1,
72 /** Everything okay. */
73 BT_CTF_BTR_STATUS_OK
= 0,
80 * Type reader user callback functions.
82 struct bt_ctf_btr_cbs
{
84 * Type callback functions.
86 * This CTF binary type reader is event-driven. The following
87 * functions are called during the decoding process, either when
88 * a compound type begins/ends, or when a basic type is
89 * completely decoded (along with its value).
91 * Each function also receives the CTF IR field type associated
92 * with the call, and user data (registered to the type reader
93 * calling them). This field type is a weak reference; the
94 * callback function must use bt_ctf_field_type_get() to keep
95 * its own reference of it.
97 * Actual CTF IR fields are \em not created here; this would be
98 * the responsibility of a type reader's user (the provider of
99 * those callback functions).
101 * All the type callback functions return one of the following
104 * - <b>#BT_CTF_BTR_STATUS_OK</b>: Everything is okay;
105 * continue the decoding process.
106 * - <b>#BT_CTF_BTR_STATUS_ERROR</b>: General error (reported
107 * to type reader's user).
109 * Any member of this structure may be set to \c NULL, should
110 * a specific notification be not needed.
114 * Called when a signed integer type is completely
115 * decoded. This could also be the supporting signed
116 * integer type of an enumeration type (\p type will
119 * @param value Signed integer value
120 * @param type Integer or enumeration type (weak
122 * @param data User data
123 * @returns #BT_CTF_BTR_STATUS_OK or
124 * #BT_CTF_BTR_STATUS_ERROR
126 enum bt_ctf_btr_status (* signed_int
)(int64_t value
,
127 struct bt_ctf_field_type
*type
, void *data
);
130 * Called when an unsigned integer type is completely
131 * decoded. This could also be the supporting signed
132 * integer type of an enumeration type (\p type will
135 * @param value Unsigned integer value
136 * @param type Integer or enumeration type (weak
138 * @param data User data
139 * @returns #BT_CTF_BTR_STATUS_OK or
140 * #BT_CTF_BTR_STATUS_ERROR
142 enum bt_ctf_btr_status (* unsigned_int
)(uint64_t value
,
143 struct bt_ctf_field_type
*type
, void *data
);
146 * Called when a floating point number type is
147 * completely decoded.
149 * @param value Floating point number value
150 * @param type Floating point number type (weak
152 * @param data User data
153 * @returns #BT_CTF_BTR_STATUS_OK or
154 * #BT_CTF_BTR_STATUS_ERROR
156 enum bt_ctf_btr_status (* floating_point
)(double value
,
157 struct bt_ctf_field_type
*type
, void *data
);
160 * Called when a string type begins.
162 * All the following user callback function calls will
163 * be made to bt_ctf_btr_cbs::types::string(), each of
164 * them providing one substring of the complete string
167 * @param type Beginning string type (weak reference)
168 * @param data User data
169 * @returns #BT_CTF_BTR_STATUS_OK or
170 * #BT_CTF_BTR_STATUS_ERROR
172 enum bt_ctf_btr_status (* string_begin
)(
173 struct bt_ctf_field_type
*type
, void *data
);
176 * Called when a string type's substring is decoded
177 * (between a call to bt_ctf_btr_cbs::types::string_begin()
178 * and a call to bt_ctf_btr_cbs::types::string_end()).
180 * @param value String value (\em not null-terminated)
181 * @param len String value length
182 * @param type String type (weak reference)
183 * @param data User data
184 * @returns #BT_CTF_BTR_STATUS_OK or
185 * #BT_CTF_BTR_STATUS_ERROR
187 enum bt_ctf_btr_status (* string
)(const char *value
,
188 size_t len
, struct bt_ctf_field_type
*type
,
192 * Called when a string type ends.
194 * @param type Ending string type (weak reference)
195 * @param data User data
196 * @returns #BT_CTF_BTR_STATUS_OK or
197 * #BT_CTF_BTR_STATUS_ERROR
199 enum bt_ctf_btr_status (* string_end
)(
200 struct bt_ctf_field_type
*type
, void *data
);
203 * Called when a compound type begins.
205 * All the following type callback function calls will
206 * signal sequential elements of this compound type,
207 * until the next corresponding
208 * bt_ctf_btr_cbs::types::compound_end() is called.
210 * If \p type is a variant type, then only one type
211 * callback function call will follow before the call to
212 * bt_ctf_btr_cbs::types::compound_end(). This single
213 * call indicates the selected type of this variant
216 * @param type Beginning compound type (weak reference)
217 * @param data User data
218 * @returns #BT_CTF_BTR_STATUS_OK or
219 * #BT_CTF_BTR_STATUS_ERROR
221 enum bt_ctf_btr_status (* compound_begin
)(
222 struct bt_ctf_field_type
*type
, void *data
);
225 * Called when a compound type ends.
227 * @param type Ending compound type (weak reference)
228 * @param data User data
229 * @returns #BT_CTF_BTR_STATUS_OK or
230 * #BT_CTF_BTR_STATUS_ERROR
232 enum bt_ctf_btr_status (* compound_end
)(
233 struct bt_ctf_field_type
*type
, void *data
);
237 * Query callback functions are used when the type reader needs
238 * dynamic information, i.e. a sequence type's current length
239 * or a variant type's current selected type.
241 * Both functions need to be set unless it is known that no
242 * sequences or variants will have to be decoded.
246 * Called to query the current length of a given sequence
249 * @param type Sequence type (weak reference)
250 * @param data User data
251 * @returns Sequence length or
252 * #BT_CTF_BTR_STATUS_ERROR on error
254 int64_t (* get_sequence_length
)(struct bt_ctf_field_type
*type
,
258 * Called to query the current selected type of a given
261 * @param type Variant type (weak reference)
262 * @param data User data
263 * @returns Current selected type (owned by
264 * this) or \c NULL on error
266 struct bt_ctf_field_type
* (* get_variant_type
)(
267 struct bt_ctf_field_type
*type
, void *data
);
272 * Creates a CTF binary type reader.
274 * @param cbs User callback functions
275 * @param data User data (passed to user callback functions)
276 * @param err_stream Error stream (can be \c NULL to disable)
277 * @returns New binary type reader on success, or \c NULL on error
279 struct bt_ctf_btr
*bt_ctf_btr_create(struct bt_ctf_btr_cbs cbs
, void *data
,
283 * Destroys a CTF binary type reader, freeing all internal resources.
285 * @param btr Binary type reader
287 void bt_ctf_btr_destroy(struct bt_ctf_btr
*btr
);
290 * Decodes a given CTF type from a buffer of bytes.
292 * The number of \em bits consumed by this function is returned.
294 * The \p status output parameter is where a status is written, amongst
297 * - <b>#BT_CTF_BTR_STATUS_OK</b>: Decoding is done.
298 * - <b>#BT_CTF_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_ctf_btr_continue()
301 * as long as #BT_CTF_BTR_STATUS_EOF is returned to complete the
302 * decoding process of the original type.
303 * - <b>#BT_CTF_BTR_STATUS_INVAL</b>: Invalid argument.
304 * - <b>#BT_CTF_BTR_STATUS_ERROR</b>: General error.
306 * Calling this function resets the type reader's internal state. If
307 * #BT_CTF_BTR_STATUS_EOF is returned, bt_ctf_btr_continue() needs to
308 * be called next, \em not bt_ctf_btr_decode().
310 * @param btr Binary type reader
311 * @param type Type to decode (weak reference)
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
320 size_t bt_ctf_btr_start(struct bt_ctf_btr
*btr
,
321 struct bt_ctf_field_type
*type
, const uint8_t *buf
,
322 size_t offset
, size_t packet_offset
, size_t sz
,
323 enum bt_ctf_btr_status
*status
);
326 * Continues the decoding process a given CTF type.
328 * The number of bits consumed by this function is returned.
330 * The \p status output parameter is where a status is placed, amongst
333 * - <b>#BT_CTF_BTR_STATUS_OK</b>: decoding is done.
334 * - <b>#BT_CTF_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_ctf_btr_continue()
337 * as long as #BT_CTF_BTR_STATUS_EOF is returned to complete the
338 * decoding process of the original type.
339 * - <b>#BT_CTF_BTR_STATUS_INVAL</b>: invalid argument.
340 * - <b>#BT_CTF_BTR_STATUS_ERROR</b>: general error.
342 * @param btr Binary type reader
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
348 size_t bt_ctf_btr_continue(struct bt_ctf_btr
*btr
,
349 const uint8_t *buf
, size_t sz
,
350 enum bt_ctf_btr_status
*status
);
352 #endif /* CTF_BTR_H */
This page took 0.043528 seconds and 4 git commands to generate.