src/plugins/ctf/common/src/metadata/tsdl/decoder.hpp

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