2 * SPDX-License-Identifier: MIT
4 * Copyright 2016-2017 Philippe Proulx <pproulx@efficios.com>
7 #ifndef _METADATA_DECODER_H
8 #define _METADATA_DECODER_H
12 #include <babeltrace2/babeltrace.h>
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 */
19 #include "../../../src/clk-cls-cfg.hpp"
21 /* A CTF metadata decoder object */
22 struct ctf_metadata_decoder;
24 /* CTF metadata decoder status */
25 enum ctf_metadata_decoder_status
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,
35 inline const char *format_as(ctf_metadata_decoder_status status) noexcept
38 case CTF_METADATA_DECODER_STATUS_OK:
39 return "CTF_METADATA_DECODER_STATUS_OK";
41 case CTF_METADATA_DECODER_STATUS_NONE:
42 return "CTF_METADATA_DECODER_STATUS_NONE";
44 case CTF_METADATA_DECODER_STATUS_ERROR:
45 return "CTF_METADATA_DECODER_STATUS_ERROR";
47 case CTF_METADATA_DECODER_STATUS_INCOMPLETE:
48 return "CTF_METADATA_DECODER_STATUS_INCOMPLETE";
50 case CTF_METADATA_DECODER_STATUS_INVAL_VERSION:
51 return "CTF_METADATA_DECODER_STATUS_INVAL_VERSION";
53 case CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR:
54 return "CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR";
60 /* Decoding configuration */
61 struct ctf_metadata_decoder_config
63 explicit ctf_metadata_decoder_config(const bt2c::Logger& parentLogger) :
64 logger {parentLogger, "PLUGIN/CTF/META/DECODER-CONFIG"}
70 /* Weak, used to create a bt_trace_class, if not nullptr. */
71 bt_self_component *self_comp = nullptr;
73 ctf::src::ClkClsCfg clkClsCfg;
75 /* True to create trace class objects */
76 bool create_trace_class = false;
79 * True to keep the plain text when content is appended with
80 * ctf_metadata_decoder_append_content().
82 bool keep_plain_text = false;
85 struct ctf_metadata_decoder_deleter
87 void operator()(struct ctf_metadata_decoder *decoder);
90 using ctf_metadata_decoder_up = std::unique_ptr<ctf_metadata_decoder, ctf_metadata_decoder_deleter>;
93 * Creates a CTF metadata decoder.
95 * Returns `NULL` on error.
97 ctf_metadata_decoder_up
98 ctf_metadata_decoder_create(const struct ctf_metadata_decoder_config *config);
101 * Destroys a CTF metadata decoder that you created with
102 * ctf_metadata_decoder_create().
104 void ctf_metadata_decoder_destroy(struct ctf_metadata_decoder *metadata_decoder);
107 * Appends content to the metadata decoder.
109 * This function reads the metadata from the current position of `fp`
110 * until the end of this file stream.
112 * The metadata can be packetized or not.
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:
121 * First call: event { name = hell
122 * Second call: event { name = hello_world; ... };
124 * If everything goes as expected, this function returns
125 * `CTF_METADATA_DECODER_STATUS_OK`.
127 enum ctf_metadata_decoder_status
128 ctf_metadata_decoder_append_content(struct ctf_metadata_decoder *metadata_decoder, FILE *fp);
131 * Returns the trace IR trace class of this metadata decoder (new
134 * Returns `NULL` if there's none yet or if the metadata decoder is not
135 * configured to create trace classes.
137 bt2::TraceClass::Shared ctf_metadata_decoder_get_ir_trace_class(struct ctf_metadata_decoder *mdec);
140 * Returns the CTF IR trace class of this metadata decoder.
142 * Returns `NULL` if there's none yet or if the metadata decoder is not
143 * configured to create trace classes.
145 struct ctf_trace_class *
146 ctf_metadata_decoder_borrow_ctf_trace_class(struct ctf_metadata_decoder *mdec);
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
154 int ctf_metadata_decoder_is_packetized(FILE *fp, bool *is_packetized, int *byte_order,
155 const bt2c::Logger& logger);
158 * Returns the byte order of the decoder's metadata stream as set by the
159 * last call to ctf_metadata_decoder_append_content().
161 * Returns -1 if unknown (plain text content).
163 int ctf_metadata_decoder_get_byte_order(struct ctf_metadata_decoder *mdec);
166 * Returns the UUID of the decoder's metadata stream as set by the last
167 * call to ctf_metadata_decoder_append_content().
169 int ctf_metadata_decoder_get_uuid(struct ctf_metadata_decoder *mdec, bt_uuid_t uuid);
172 * Returns the UUID of the decoder's trace class, if available.
176 * * `CTF_METADATA_DECODER_STATUS_OK`: success.
177 * * `CTF_METADATA_DECODER_STATUS_NONE`: no UUID.
178 * * `CTF_METADATA_DECODER_STATUS_INCOMPLETE`: missing metadata content.
180 enum ctf_metadata_decoder_status
181 ctf_metadata_decoder_get_trace_class_uuid(struct ctf_metadata_decoder *mdec, bt_uuid_t uuid);
184 * Returns the metadata decoder's current metadata text.
186 const char *ctf_metadata_decoder_get_text(struct ctf_metadata_decoder *mdec);
188 static inline bool ctf_metadata_decoder_is_packet_version_valid(unsigned int major,
191 return major == 1 && minor == 8;
194 #endif /* _METADATA_DECODER_H */