ctf-reader-proto/ctf-btr/ctf-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/ctf-ir/field-types.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_ctf_btr_status {
  55         /**
  56          * The binary stream reader reached the end of the user-provided
  57          * buffer, but data is still needed to finish decoding the
  58          * requested type.
  59          *
  60          * The user needs to call bt_ctf_btr_continue() as long as
  61          * #BT_CTF_BTR_STATUS_EOF is returned to complete the decoding
  62          * process of a given type.
  63          */
  64         BT_CTF_BTR_STATUS_EOF =         -4,
  65
  66         /** Invalid argument. */
  67         BT_CTF_BTR_STATUS_INVAL =       -3,
  68
  69         /** General error. */
  70         BT_CTF_BTR_STATUS_ERROR =       -1,
  71
  72         /** Everything okay. */
  73         BT_CTF_BTR_STATUS_OK =          0,
  74 };
  75
  76 /** Type reader. */
  77 struct bt_ctf_btr;
  78
  79 /*
  80  * Type reader user callback functions.
  81  */
  82 struct bt_ctf_btr_cbs {
  83         /**
  84          * Type callback functions.
  85          *
  86          * This CTF binary type reader is event-driven. The following
  87          * functions are called during the decoding process, either when
  88          * a compound type begins/ends, or when a basic type is
  89          * completely decoded (along with its value).
  90          *
  91          * Each function also receives the CTF IR field type associated
  92          * with the call, and user data (registered to the type reader
  93          * calling them). This field type is a weak reference; the
  94          * callback function must use bt_ctf_field_type_get() to keep
  95          * its own reference of it.
  96          *
  97          * Actual CTF IR fields are \em not created here; this would be
  98          * the responsibility of a type reader's user (the provider of
  99          * those callback functions).
 100          *
 101          * All the type callback functions return one of the following
 102          * values:
 103          *
 104          *   - <b>#BT_CTF_BTR_STATUS_OK</b>: Everything is okay;
 105          *     continue the decoding process.
 106          *   - <b>#BT_CTF_BTR_STATUS_ERROR</b>: General error (reported
 107          *     to type reader's user).
 108          *
 109          * Any member of this structure may be set to \c NULL, should
 110          * a specific notification be not needed.
 111          */
 112         struct {
 113                 /**
 114                  * Called when a signed integer type is completely
 115                  * decoded. This could also be the supporting signed
 116                  * integer type of an enumeration type (\p type will
 117                  * indicate this).
 118                  *
 119                  * @param value         Signed integer value
 120                  * @param type          Integer or enumeration type (weak
 121                  *                      reference)
 122                  * @param data          User data
 123                  * @returns             #BT_CTF_BTR_STATUS_OK or
 124                  *                      #BT_CTF_BTR_STATUS_ERROR
 125                  */
 126                 enum bt_ctf_btr_status (* signed_int)(int64_t value,
 127                                 struct bt_ctf_field_type *type, void *data);
 128
 129                 /**
 130                  * Called when an unsigned integer type is completely
 131                  * decoded. This could also be the supporting signed
 132                  * integer type of an enumeration type (\p type will
 133                  * indicate this).
 134                  *
 135                  * @param value         Unsigned integer value
 136                  * @param type          Integer or enumeration type (weak
 137                  *                      reference)
 138                  * @param data          User data
 139                  * @returns             #BT_CTF_BTR_STATUS_OK or
 140                  *                      #BT_CTF_BTR_STATUS_ERROR
 141                  */
 142                 enum bt_ctf_btr_status (* unsigned_int)(uint64_t value,
 143                                 struct bt_ctf_field_type *type, void *data);
 144
 145                 /**
 146                  * Called when a floating point number type is
 147                  * completely decoded.
 148                  *
 149                  * @param value         Floating point number value
 150                  * @param type          Floating point number type (weak
 151                  *                      reference)
 152                  * @param data          User data
 153                  * @returns             #BT_CTF_BTR_STATUS_OK or
 154                  *                      #BT_CTF_BTR_STATUS_ERROR
 155                  */
 156                 enum bt_ctf_btr_status (* floating_point)(double value,
 157                                 struct bt_ctf_field_type *type, void *data);
 158
 159                 /**
 160                  * Called when a string type begins.
 161                  *
 162                  * All the following user callback function calls will
 163                  * be made to bt_ctf_btr_cbs::types::string(), each of
 164                  * them providing one substring of the complete string
 165                  * type's value.
 166                  *
 167                  * @param type          Beginning string type (weak reference)
 168                  * @param data          User data
 169                  * @returns             #BT_CTF_BTR_STATUS_OK or
 170                  *                      #BT_CTF_BTR_STATUS_ERROR
 171                  */
 172                 enum bt_ctf_btr_status (* string_begin)(
 173                                 struct bt_ctf_field_type *type, void *data);
 174
 175                 /**
 176                  * Called when a string type's substring is decoded
 177                  * (between a call to bt_ctf_btr_cbs::types::string_begin()
 178                  * and a call to bt_ctf_btr_cbs::types::string_end()).
 179                  *
 180                  * @param value         String value (\em not null-terminated)
 181                  * @param len           String value length
 182                  * @param type          String type (weak reference)
 183                  * @param data          User data
 184                  * @returns             #BT_CTF_BTR_STATUS_OK or
 185                  *                      #BT_CTF_BTR_STATUS_ERROR
 186                  */
 187                 enum bt_ctf_btr_status (* string)(const char *value,
 188                                 size_t len, struct bt_ctf_field_type *type,
 189                                 void *data);
 190
 191                 /**
 192                  * Called when a string type ends.
 193                  *
 194                  * @param type          Ending string type (weak reference)
 195                  * @param data          User data
 196                  * @returns             #BT_CTF_BTR_STATUS_OK or
 197                  *                      #BT_CTF_BTR_STATUS_ERROR
 198                  */
 199                 enum bt_ctf_btr_status (* string_end)(
 200                                 struct bt_ctf_field_type *type, void *data);
 201
 202                 /**
 203                  * Called when a compound type begins.
 204                  *
 205                  * All the following type callback function calls will
 206                  * signal sequential elements of this compound type,
 207                  * until the next corresponding
 208                  * bt_ctf_btr_cbs::types::compound_end() is called.
 209                  *
 210                  * If \p type is a variant type, then only one type
 211                  * callback function call will follow before the call to
 212                  * bt_ctf_btr_cbs::types::compound_end(). This single
 213                  * call indicates the selected type of this variant
 214                  * type.
 215                  *
 216                  * @param type          Beginning compound type (weak reference)
 217                  * @param data          User data
 218                  * @returns             #BT_CTF_BTR_STATUS_OK or
 219                  *                      #BT_CTF_BTR_STATUS_ERROR
 220                  */
 221                 enum bt_ctf_btr_status (* compound_begin)(
 222                                 struct bt_ctf_field_type *type, void *data);
 223
 224                 /**
 225                  * Called when a compound type ends.
 226                  *
 227                  * @param type          Ending compound type (weak reference)
 228                  * @param data          User data
 229                  * @returns             #BT_CTF_BTR_STATUS_OK or
 230                  *                      #BT_CTF_BTR_STATUS_ERROR
 231                  */
 232                 enum bt_ctf_btr_status (* compound_end)(
 233                                 struct bt_ctf_field_type *type, void *data);
 234         } types;
 235
 236         /**
 237          * Query callback functions are used when the type reader needs
 238          * dynamic information, i.e. a sequence type's current length
 239          * or a variant type's current selected type.
 240          *
 241          * Both functions need to be set unless it is known that no
 242          * sequences or variants will have to be decoded.
 243          */
 244         struct {
 245                 /**
 246                  * Called to query the current length of a given sequence
 247                  * type.
 248                  *
 249                  * @param type          Sequence type (weak reference)
 250                  * @param data          User data
 251                  * @returns             Sequence length or
 252                  *                      #BT_CTF_BTR_STATUS_ERROR on error
 253                  */
 254                 int64_t (* get_sequence_length)(struct bt_ctf_field_type *type,
 255                                 void *data);
 256
 257                 /**
 258                  * Called to query the current selected type of a given
 259                  * variant type.
 260                  *
 261                  * @param type          Variant type (weak reference)
 262                  * @param data          User data
 263                  * @returns             Current selected type (owned by
 264                  *                      this) or \c NULL on error
 265                  */
 266                 struct bt_ctf_field_type * (* get_variant_type)(
 267                                 struct bt_ctf_field_type *type, void *data);
 268         } query;
 269 };
 270
 271 /**
 272  * Creates a CTF binary type reader.
 273  *
 274  * @param cbs           User callback functions
 275  * @param data          User data (passed to user callback functions)
 276  * @param err_stream    Error stream (can be \c NULL to disable)
 277  * @returns             New binary type reader on success, or \c NULL on error
 278  */
 279 struct bt_ctf_btr *bt_ctf_btr_create(struct bt_ctf_btr_cbs cbs, void *data,
 280                 FILE *err_stream);
 281
 282 /**
 283  * Destroys a CTF binary type reader, freeing all internal resources.
 284  *
 285  * @param btr   Binary type reader
 286  */
 287 void bt_ctf_btr_destroy(struct bt_ctf_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_CTF_BTR_STATUS_OK</b>: Decoding is done.
 298  *   - <b>#BT_CTF_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_ctf_btr_continue()
 301  *     as long as #BT_CTF_BTR_STATUS_EOF is returned to complete the
 302  *     decoding process of the original type.
 303  *   - <b>#BT_CTF_BTR_STATUS_INVAL</b>: Invalid argument.
 304  *   - <b>#BT_CTF_BTR_STATUS_ERROR</b>: General error.
 305  *
 306  * Calling this function resets the type reader's internal state. If
 307  * #BT_CTF_BTR_STATUS_EOF is returned, bt_ctf_btr_continue() needs to
 308  * be called next, \em not bt_ctf_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_ctf_btr_start(struct bt_ctf_btr *btr,
 321                 struct bt_ctf_field_type *type, const uint8_t *buf,
 322                 size_t offset, size_t packet_offset, size_t sz,
 323                 enum bt_ctf_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_CTF_BTR_STATUS_OK</b>: decoding is done.
 334  *   - <b>#BT_CTF_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_ctf_btr_continue()
 337  *     as long as #BT_CTF_BTR_STATUS_EOF is returned to complete the
 338  *     decoding process of the original type.
 339  *   - <b>#BT_CTF_BTR_STATUS_INVAL</b>: invalid argument.
 340  *   - <b>#BT_CTF_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_ctf_btr_continue(struct bt_ctf_btr *btr,
 349                 const uint8_t *buf, size_t sz,
 350                 enum bt_ctf_btr_status *status);
 351
 352 #endif /* CTF_BTR_H */