src/plugins/ctf/common/bfcr/bfcr.h

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