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 /*
  84  * Creates a CTF metadata decoder.
  85  *
  86  * Returns `NULL` on error.
  87  */
  88 struct ctf_metadata_decoder *
  89 ctf_metadata_decoder_create(const struct ctf_metadata_decoder_config *config);
  90
  91 /*
  92  * Destroys a CTF metadata decoder that you created with
  93  * ctf_metadata_decoder_create().
  94  */
  95 void ctf_metadata_decoder_destroy(struct ctf_metadata_decoder *metadata_decoder);
  96
  97 /*
  98  * Appends content to the metadata decoder.
  99  *
 100  * This function reads the metadata from the current position of `fp`
 101  * until the end of this file stream.
 102  *
 103  * The metadata can be packetized or not.
 104  *
 105  * The metadata chunk needs to be complete and lexically scannable, that
 106  * is, zero or more complete top-level blocks. If it's incomplete, this
 107  * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`. If this
 108  * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`, then you
 109  * need to call it again with the _same_ metadata and more to make it
 110  * complete. For example:
 111  *
 112  *     First call:  event { name = hell
 113  *     Second call: event { name = hello_world; ... };
 114  *
 115  * If everything goes as expected, this function returns
 116  * `CTF_METADATA_DECODER_STATUS_OK`.
 117  */
 118 enum ctf_metadata_decoder_status
 119 ctf_metadata_decoder_append_content(struct ctf_metadata_decoder *metadata_decoder, FILE *fp);
 120
 121 /*
 122  * Returns the trace IR trace class of this metadata decoder (new
 123  * reference).
 124  *
 125  * Returns `NULL` if there's none yet or if the metadata decoder is not
 126  * configured to create trace classes.
 127  */
 128 bt_trace_class *ctf_metadata_decoder_get_ir_trace_class(struct ctf_metadata_decoder *mdec);
 129
 130 /*
 131  * Returns the CTF IR trace class of this metadata decoder.
 132  *
 133  * Returns `NULL` if there's none yet or if the metadata decoder is not
 134  * configured to create trace classes.
 135  */
 136 struct ctf_trace_class *
 137 ctf_metadata_decoder_borrow_ctf_trace_class(struct ctf_metadata_decoder *mdec);
 138
 139 /*
 140  * Checks whether or not a given metadata file stream `fp` is
 141  * packetized, setting `is_packetized` accordingly on success. On
 142  * success, also sets `*byte_order` to the byte order of the first
 143  * packet.
 144  */
 145 int ctf_metadata_decoder_is_packetized(FILE *fp, bool *is_packetized, int *byte_order,
 146                                        const bt2c::Logger& logger);
 147
 148 /*
 149  * Returns the byte order of the decoder's metadata stream as set by the
 150  * last call to ctf_metadata_decoder_append_content().
 151  *
 152  * Returns -1 if unknown (plain text content).
 153  */
 154 int ctf_metadata_decoder_get_byte_order(struct ctf_metadata_decoder *mdec);
 155
 156 /*
 157  * Returns the UUID of the decoder's metadata stream as set by the last
 158  * call to ctf_metadata_decoder_append_content().
 159  */
 160 int ctf_metadata_decoder_get_uuid(struct ctf_metadata_decoder *mdec, bt_uuid_t uuid);
 161
 162 /*
 163  * Returns the UUID of the decoder's trace class, if available.
 164  *
 165  * Returns:
 166  *
 167  * * `CTF_METADATA_DECODER_STATUS_OK`: success.
 168  * * `CTF_METADATA_DECODER_STATUS_NONE`: no UUID.
 169  * * `CTF_METADATA_DECODER_STATUS_INCOMPLETE`: missing metadata content.
 170  */
 171 enum ctf_metadata_decoder_status
 172 ctf_metadata_decoder_get_trace_class_uuid(struct ctf_metadata_decoder *mdec, bt_uuid_t uuid);
 173
 174 /*
 175  * Returns the metadata decoder's current metadata text.
 176  */
 177 const char *ctf_metadata_decoder_get_text(struct ctf_metadata_decoder *mdec);
 178
 179 static inline bool ctf_metadata_decoder_is_packet_version_valid(unsigned int major,
 180                                                                 unsigned int minor)
 181 {
 182     return major == 1 && minor == 8;
 183 }
 184
 185 #endif /* _METADATA_DECODER_H */