src/plugins/ctf/common/src/bfcr/bfcr.hpp

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (c) 2015-2016 EfficiOS Inc. and Linux Foundation
   5  * Copyright (c) 2015-2016 Philippe Proulx <pproulx@efficios.com>
   6  *
   7  * Babeltrace - CTF binary field class reader (BFCR)
   8  */
   9
  10 #ifndef CTF_BFCR_H
  11 #define CTF_BFCR_H
  12
  13 #include <stddef.h>
  14 #include <stdint.h>
  15
  16 #include <babeltrace2/babeltrace.h>
  17
  18 #include "../metadata/tsdl/ctf-meta.hpp"
  19
  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  */
  39 enum 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,
  53
  54     /** Invalid argument. */
  55     BT_BFCR_STATUS_INVAL = -3,
  56
  57     /** General error. */
  58     BT_BFCR_STATUS_ERROR = -1,
  59
  60     /** Everything okay. */
  61     BT_BFCR_STATUS_OK = 0,
  62 };
  63
  64 typedef enum bt_bfcr_status (*bt_bfcr_unsigned_int_cb_func)(uint64_t, struct ctf_field_class *,
  65                                                             void *);
  66
  67 /*
  68  * Field class reader user callback functions.
  69  */
  70 struct 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);
 114
 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;
 128
 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);
 141
 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);
 156
 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);
 171
 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);
 181
 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);
 202
 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;
 213
 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);
 234
 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;
 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  */
 256 struct bt_bfcr *bt_bfcr_create(struct bt_bfcr_cbs cbs, void *data, bt_logging_level log_level,
 257                                bt_self_component *self_comp);
 258
 259 /**
 260  * Destroys a CTF binary class reader, freeing all internal resources.
 261  *
 262  * @param bfcr  Binary class reader
 263  */
 264 void 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  */
 297 size_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);
 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  */
 323 size_t bt_bfcr_continue(struct bt_bfcr *bfcr, const uint8_t *buf, size_t sz,
 324                         enum bt_bfcr_status *status);
 325
 326 void bt_bfcr_set_unsigned_int_cb(struct bt_bfcr *bfcr, bt_bfcr_unsigned_int_cb_func cb);
 327
 328 static inline const char *bt_bfcr_status_string(enum bt_bfcr_status status)
 329 {
 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     }
 342
 343     bt_common_abort();
 344 }
 345
 346 #endif /* CTF_BFCR_H */