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