plugins/ctf/common/bfcr/bfcr.h

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