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 "cpp-common/vendor/fmt/format.h" /* IWYU pragma: keep */
  19
  20 #include "../metadata/tsdl/ctf-meta.hpp"
  21
  22 namespace bt2c {
  23
  24 class Logger;
  25
  26 } /* namespace bt2c */
  27
  28 /**
  29  * @file bfcr.h
  30  *
  31  * Event-driven CTF binary field class reader (BFCR).
  32  *
  33  * This is a common, internal API used by CTF source plugins. It allows
  34  * a binary CTF IR field class to be decoded from user-provided buffers.
  35  * As the class is decoded (and, possibly, its nested classes),
  36  * registered user callback functions are called.
  37  *
  38  * This API is only concerned with reading one CTF class at a time from
  39  * one or more buffer of bytes. It does not know CTF dynamic scopes,
  40  * events, or streams. Sequence lengths and selected variant classes are
  41  * requested to the user when needed.
  42  */
  43
  44 /**
  45  * Binary class reader API status codes.
  46  */
  47 enum bt_bfcr_status
  48 {
  49     /** Out of memory. */
  50     BT_BFCR_STATUS_ENOMEM = -5,
  51     /**
  52      * The binary stream reader reached the end of the user-provided
  53      * buffer, but data is still needed to finish decoding the
  54      * requested class.
  55      *
  56      * The user needs to call bt_bfcr_continue() as long as
  57      * #BT_BFCR_STATUS_EOF is returned to complete the decoding
  58      * process of a given class.
  59      */
  60     BT_BFCR_STATUS_EOF = 1,
  61
  62     /** Invalid argument. */
  63     BT_BFCR_STATUS_INVAL = -3,
  64
  65     /** General error. */
  66     BT_BFCR_STATUS_ERROR = -1,
  67
  68     /** Everything okay. */
  69     BT_BFCR_STATUS_OK = 0,
  70 };
  71
  72 inline const char *format_as(bt_bfcr_status status) noexcept
  73 {
  74     switch (status) {
  75     case BT_BFCR_STATUS_ENOMEM:
  76         return "BT_BFCR_STATUS_ENOMEM";
  77
  78     case BT_BFCR_STATUS_EOF:
  79         return "BT_BFCR_STATUS_EOF";
  80
  81     case BT_BFCR_STATUS_INVAL:
  82         return "BT_BFCR_STATUS_INVAL";
  83
  84     case BT_BFCR_STATUS_ERROR:
  85         return "BT_BFCR_STATUS_ERROR";
  86
  87     case BT_BFCR_STATUS_OK:
  88         return "BT_BFCR_STATUS_OK";
  89         break;
  90     }
  91
  92     bt_common_abort();
  93 }
  94
  95 typedef enum bt_bfcr_status (*bt_bfcr_unsigned_int_cb_func)(uint64_t, struct ctf_field_class *,
  96                                                             void *);
  97
  98 /*
  99  * Field class reader user callback functions.
 100  */
 101 struct bt_bfcr_cbs
 102 {
 103     /**
 104      * Field class callback functions.
 105      *
 106      * This CTF binary class reader is event-driven. The following
 107      * functions are called during the decoding process, either when
 108      * a compound class begins/ends, or when a basic class is
 109      * completely decoded (along with its value).
 110      *
 111      * Each function also receives the CTF field class associated
 112      * with the call, and user data (registered to the class reader
 113      * calling them).
 114      *
 115      * Actual trace IR fields are \em not created here; this would
 116      * be the responsibility of a class reader's user (the provider
 117      * of those callback functions).
 118      *
 119      * All the class callback functions return one of the following
 120      * values:
 121      *
 122      *   - <b>#BT_BFCR_STATUS_OK</b>: Everything is okay;
 123      *     continue the decoding process.
 124      *   - <b>#BT_BFCR_STATUS_ERROR</b>: General error (reported
 125      *     to class reader's user).
 126      *
 127      * Any member of this structure may be set to \c NULL, should
 128      * a specific message be not needed.
 129      */
 130     struct
 131     {
 132         /**
 133          * Called when a signed integer class is completely
 134          * decoded. This could also be the supporting signed
 135          * integer class of an enumeration class (\p class will
 136          * indicate this).
 137          *
 138          * @param value         Signed integer value
 139          * @param class         Integer or enumeration class
 140          * @param data          User data
 141          * @returns             #BT_BFCR_STATUS_OK or
 142          *                      #BT_BFCR_STATUS_ERROR
 143          */
 144         enum bt_bfcr_status (*signed_int)(int64_t value, struct ctf_field_class *cls, void *data);
 145
 146         /**
 147          * Called when an unsigned integer class is completely
 148          * decoded. This could also be the supporting signed
 149          * integer class of an enumeration class (\p class will
 150          * indicate this).
 151          *
 152          * @param value         Unsigned integer value
 153          * @param class         Integer or enumeration class
 154          * @param data          User data
 155          * @returns             #BT_BFCR_STATUS_OK or
 156          *                      #BT_BFCR_STATUS_ERROR
 157          */
 158         bt_bfcr_unsigned_int_cb_func unsigned_int;
 159
 160         /**
 161          * Called when a floating point number class is
 162          * completely decoded.
 163          *
 164          * @param value         Floating point number value
 165          * @param class         Floating point number class
 166          * @param data          User data
 167          * @returns             #BT_BFCR_STATUS_OK or
 168          *                      #BT_BFCR_STATUS_ERROR
 169          */
 170         enum bt_bfcr_status (*floating_point)(double value, struct ctf_field_class *cls,
 171                                               void *data);
 172
 173         /**
 174          * Called when a string class begins.
 175          *
 176          * All the following user callback function calls will
 177          * be made to bt_bfcr_cbs::classes::string(), each of
 178          * them providing one substring of the complete string
 179          * class's value.
 180          *
 181          * @param class         Beginning string class
 182          * @param data          User data
 183          * @returns             #BT_BFCR_STATUS_OK or
 184          *                      #BT_BFCR_STATUS_ERROR
 185          */
 186         enum bt_bfcr_status (*string_begin)(struct ctf_field_class *cls, void *data);
 187
 188         /**
 189          * Called when a string class's substring is decoded
 190          * (between a call to bt_bfcr_cbs::classes::string_begin()
 191          * and a call to bt_bfcr_cbs::classes::string_end()).
 192          *
 193          * @param value         String value (\em not null-terminated)
 194          * @param len           String value length
 195          * @param class         String class
 196          * @param data          User data
 197          * @returns             #BT_BFCR_STATUS_OK or
 198          *                      #BT_BFCR_STATUS_ERROR
 199          */
 200         enum bt_bfcr_status (*string)(const char *value, size_t len, struct ctf_field_class *cls,
 201                                       void *data);
 202
 203         /**
 204          * Called when a string class ends.
 205          *
 206          * @param class         Ending string class
 207          * @param data          User data
 208          * @returns             #BT_BFCR_STATUS_OK or
 209          *                      #BT_BFCR_STATUS_ERROR
 210          */
 211         enum bt_bfcr_status (*string_end)(struct ctf_field_class *cls, void *data);
 212
 213         /**
 214          * Called when a compound class begins.
 215          *
 216          * All the following class callback function calls will
 217          * signal sequential elements of this compound class,
 218          * until the next corresponding
 219          * bt_bfcr_cbs::classes::compound_end() is called.
 220          *
 221          * If \p class is a variant class, then only one class
 222          * callback function call will follow before the call to
 223          * bt_bfcr_cbs::classes::compound_end(). This single
 224          * call indicates the selected class of this variant
 225          * class.
 226          *
 227          * @param class         Beginning compound class
 228          * @param data          User data
 229          * @returns             #BT_BFCR_STATUS_OK or
 230          *                      #BT_BFCR_STATUS_ERROR
 231          */
 232         enum bt_bfcr_status (*compound_begin)(struct ctf_field_class *cls, void *data);
 233
 234         /**
 235          * Called when a compound class ends.
 236          *
 237          * @param class         Ending compound class
 238          * @param data          User data
 239          * @returns             #BT_BFCR_STATUS_OK or
 240          *                      #BT_BFCR_STATUS_ERROR
 241          */
 242         enum bt_bfcr_status (*compound_end)(struct ctf_field_class *cls, void *data);
 243     } classes;
 244
 245     /**
 246      * Query callback functions are used when the class reader needs
 247      * dynamic information, i.e. a sequence class's current length
 248      * or a variant class's current selected class.
 249      *
 250      * Both functions need to be set unless it is known that no
 251      * sequences or variants will have to be decoded.
 252      */
 253     struct
 254     {
 255         /**
 256          * Called to query the current length of a given sequence
 257          * class.
 258          *
 259          * @param class         Sequence class
 260          * @param data          User data
 261          * @returns             Sequence length or
 262          *                      #BT_BFCR_STATUS_ERROR on error
 263          */
 264         int64_t (*get_sequence_length)(struct ctf_field_class *cls, void *data);
 265
 266         /**
 267          * Called to query the current selected class of a given
 268          * variant class.
 269          *
 270          * @param class         Variant class
 271          * @param data          User data
 272          * @returns             Current selected class (owned by
 273          *                      this) or \c NULL on error
 274          */
 275         struct ctf_field_class *(*borrow_variant_selected_field_class)(struct ctf_field_class *cls,
 276                                                                        void *data);
 277     } query;
 278 };
 279
 280 /**
 281  * Creates a CTF binary class reader.
 282  *
 283  * @param cbs           User callback functions
 284  * @param data          User data (passed to user callback functions)
 285  * @returns             New binary class reader on success, or \c NULL on error
 286  */
 287 struct bt_bfcr *bt_bfcr_create(struct bt_bfcr_cbs cbs, void *data, const bt2c::Logger& logger);
 288
 289 /**
 290  * Destroys a CTF binary class reader, freeing all internal resources.
 291  *
 292  * @param bfcr  Binary class reader
 293  */
 294 void bt_bfcr_destroy(struct bt_bfcr *bfcr);
 295
 296 /**
 297  * Decodes a given CTF class from a buffer of bytes.
 298  *
 299  * The number of \em bits consumed by this function is returned.
 300  *
 301  * The \p status output parameter is where a status is written, amongst
 302  * the following:
 303  *
 304  *   - <b>#BT_BFCR_STATUS_OK</b>: Decoding is done.
 305  *   - <b>#BT_BFCR_STATUS_EOF</b>: The end of the buffer was reached,
 306  *     but more data is needed to finish the decoding process of the
 307  *     requested class. The user needs to call bt_bfcr_continue()
 308  *     as long as #BT_BFCR_STATUS_EOF is returned to complete the
 309  *     decoding process of the original class.
 310  *   - <b>#BT_BFCR_STATUS_INVAL</b>: Invalid argument.
 311  *   - <b>#BT_BFCR_STATUS_ERROR</b>: General error.
 312  *
 313  * Calling this function resets the class reader's internal state. If
 314  * #BT_BFCR_STATUS_EOF is returned, bt_bfcr_continue() needs to
 315  * be called next, \em not bt_bfcr_decode().
 316  *
 317  * @param bfcr                  Binary class reader
 318  * @param class                 Field class to decode
 319  * @param buf                   Buffer
 320  * @param offset                Offset of first bit from \p buf (bits)
 321  * @param packet_offset         Offset of \p offset within the CTF
 322  *                              binary packet containing \p class (bits)
 323  * @param sz                    Size of buffer in bytes (from \p buf)
 324  * @param status                Returned status (see description above)
 325  * @returns                     Number of consumed bits
 326  */
 327 size_t bt_bfcr_start(struct bt_bfcr *bfcr, struct ctf_field_class *cls, const uint8_t *buf,
 328                      size_t offset, size_t packet_offset, size_t sz, enum bt_bfcr_status *status);
 329
 330 /**
 331  * Continues the decoding process a given CTF class.
 332  *
 333  * The number of bits consumed by this function is returned.
 334  *
 335  * The \p status output parameter is where a status is placed, amongst
 336  * the following:
 337  *
 338  *   - <b>#BT_BFCR_STATUS_OK</b>: decoding is done.
 339  *   - <b>#BT_BFCR_STATUS_EOF</b>: the end of the buffer was reached,
 340  *     but more data is needed to finish the decoding process of the
 341  *     requested class. The user needs to call bt_bfcr_continue()
 342  *     as long as #BT_BFCR_STATUS_EOF is returned to complete the
 343  *     decoding process of the original class.
 344  *   - <b>#BT_BFCR_STATUS_INVAL</b>: invalid argument.
 345  *   - <b>#BT_BFCR_STATUS_ERROR</b>: general error.
 346  *
 347  * @param bfcr          Binary class reader
 348  * @param buf           Buffer
 349  * @param sz            Size of buffer in bytes (from \p offset)
 350  * @param status        Returned status (see description above)
 351  * @returns             Number of consumed bits
 352  */
 353 size_t bt_bfcr_continue(struct bt_bfcr *bfcr, const uint8_t *buf, size_t sz,
 354                         enum bt_bfcr_status *status);
 355
 356 void bt_bfcr_set_unsigned_int_cb(struct bt_bfcr *bfcr, bt_bfcr_unsigned_int_cb_func cb);
 357
 358 #endif /* CTF_BFCR_H */