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