src/plugins/ctf/common/metadata/decoder.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright 2016-2017 Philippe Proulx <pproulx@efficios.com>
   5  */
   6
   7 #ifndef _METADATA_DECODER_H
   8 #define _METADATA_DECODER_H
   9
  10 #include <stdint.h>
  11 #include <stdbool.h>
  12
  13 #include <babeltrace2/babeltrace.h>
  14
  15 #include "common/macros.h"
  16 #include "common/uuid.h"
  17
  18 struct ctf_trace_class;
  19
  20 /* A CTF metadata decoder object */
  21 struct ctf_metadata_decoder;
  22
  23 /* CTF metadata decoder status */
  24 enum ctf_metadata_decoder_status {
  25         CTF_METADATA_DECODER_STATUS_OK                  = 0,
  26         CTF_METADATA_DECODER_STATUS_NONE                = 1,
  27         CTF_METADATA_DECODER_STATUS_ERROR               = -1,
  28         CTF_METADATA_DECODER_STATUS_INCOMPLETE          = -2,
  29         CTF_METADATA_DECODER_STATUS_INVAL_VERSION       = -3,
  30         CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR    = -4,
  31 };
  32
  33 /* Decoding configuration */
  34 struct ctf_metadata_decoder_config {
  35         /* Active log level to use */
  36         bt_logging_level log_level;
  37
  38         /* Component to use for logging (can be `NULL`); weak */
  39         bt_self_component *self_comp;
  40
  41         /* Additional clock class offset to apply */
  42         int64_t clock_class_offset_s;
  43         int64_t clock_class_offset_ns;
  44         bool force_clock_class_origin_unix_epoch;
  45
  46         /* True to create trace class objects */
  47         bool create_trace_class;
  48
  49         /*
  50          * True to keep the plain text when content is appended with
  51          * ctf_metadata_decoder_append_content().
  52          */
  53         bool keep_plain_text;
  54 };
  55
  56 /*
  57  * Creates a CTF metadata decoder.
  58  *
  59  * Returns `NULL` on error.
  60  */
  61 BT_HIDDEN
  62 struct ctf_metadata_decoder *ctf_metadata_decoder_create(
  63                 const struct ctf_metadata_decoder_config *config);
  64
  65 /*
  66  * Destroys a CTF metadata decoder that you created with
  67  * ctf_metadata_decoder_create().
  68  */
  69 BT_HIDDEN
  70 void ctf_metadata_decoder_destroy(
  71                 struct ctf_metadata_decoder *metadata_decoder);
  72
  73 /*
  74  * Appends content to the metadata decoder.
  75  *
  76  * This function reads the metadata from the current position of `fp`
  77  * until the end of this file stream.
  78  *
  79  * The metadata can be packetized or not.
  80  *
  81  * The metadata chunk needs to be complete and lexically scannable, that
  82  * is, zero or more complete top-level blocks. If it's incomplete, this
  83  * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`. If this
  84  * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`, then you
  85  * need to call it again with the _same_ metadata and more to make it
  86  * complete. For example:
  87  *
  88  *     First call:  event { name = hell
  89  *     Second call: event { name = hello_world; ... };
  90  *
  91  * If everything goes as expected, this function returns
  92  * `CTF_METADATA_DECODER_STATUS_OK`.
  93  */
  94 BT_HIDDEN
  95 enum ctf_metadata_decoder_status ctf_metadata_decoder_append_content(
  96                 struct ctf_metadata_decoder *metadata_decoder, FILE *fp);
  97
  98 /*
  99  * Returns the trace IR trace class of this metadata decoder (new
 100  * reference).
 101  *
 102  * Returns `NULL` if there's none yet or if the metadata decoder is not
 103  * configured to create trace classes.
 104  */
 105 BT_HIDDEN
 106 bt_trace_class *ctf_metadata_decoder_get_ir_trace_class(
 107                 struct ctf_metadata_decoder *mdec);
 108
 109 /*
 110  * Returns the CTF IR trace class of this metadata decoder.
 111  *
 112  * Returns `NULL` if there's none yet or if the metadata decoder is not
 113  * configured to create trace classes.
 114  */
 115 BT_HIDDEN
 116 struct ctf_trace_class *ctf_metadata_decoder_borrow_ctf_trace_class(
 117                 struct ctf_metadata_decoder *mdec);
 118
 119 /*
 120  * Checks whether or not a given metadata file stream `fp` is
 121  * packetized, setting `is_packetized` accordingly on success. On
 122  * success, also sets `*byte_order` to the byte order of the first
 123  * packet.
 124  *
 125  * This function uses `log_level` and `self_comp` for logging purposes.
 126  * `self_comp` can be `NULL` if not available.
 127  */
 128 BT_HIDDEN
 129 int ctf_metadata_decoder_is_packetized(FILE *fp, bool *is_packetized,
 130                 int *byte_order, bt_logging_level log_level,
 131                 bt_self_component *self_comp);
 132
 133 /*
 134  * Returns the byte order of the decoder's metadata stream as set by the
 135  * last call to ctf_metadata_decoder_append_content().
 136  *
 137  * Returns -1 if unknown (plain text content).
 138  */
 139 BT_HIDDEN
 140 int ctf_metadata_decoder_get_byte_order(struct ctf_metadata_decoder *mdec);
 141
 142 /*
 143  * Returns the UUID of the decoder's metadata stream as set by the last
 144  * call to ctf_metadata_decoder_append_content().
 145  */
 146 BT_HIDDEN
 147 int ctf_metadata_decoder_get_uuid(
 148                 struct ctf_metadata_decoder *mdec, bt_uuid_t uuid);
 149
 150 /*
 151  * Returns the UUID of the decoder's trace class, if available.
 152  *
 153  * Returns:
 154  *
 155  * * `CTF_METADATA_DECODER_STATUS_OK`: success.
 156  * * `CTF_METADATA_DECODER_STATUS_NONE`: no UUID.
 157  * * `CTF_METADATA_DECODER_STATUS_INCOMPLETE`: missing metadata content.
 158  */
 159 BT_HIDDEN
 160 enum ctf_metadata_decoder_status ctf_metadata_decoder_get_trace_class_uuid(
 161                 struct ctf_metadata_decoder *mdec, bt_uuid_t uuid);
 162
 163 /*
 164  * Returns the metadata decoder's current metadata text.
 165  */
 166 BT_HIDDEN
 167 const char *ctf_metadata_decoder_get_text(struct ctf_metadata_decoder *mdec);
 168
 169 static inline
 170 bool ctf_metadata_decoder_is_packet_version_valid(unsigned int major,
 171                 unsigned int minor)
 172 {
 173         return major == 1 && minor == 8;
 174 }
 175
 176 #endif /* _METADATA_DECODER_H */