plugins/ctf/common/btr/btr.h

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