src/plugins/ctf/common/metadata/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 <stdbool.h>
  12 #include <stdio.h>
  13
  14 #include <babeltrace2/babeltrace.h>
  15
  16 #include "common/macros.h"
  17 #include "common/uuid.h"
  18
  19 struct ctf_trace_class;
  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 /* Decoding configuration */
  36 struct ctf_metadata_decoder_config
  37 {
  38     /* Active log level to use */
  39     bt_logging_level log_level;
  40
  41     /*
  42      * Component or component class to use for logging (exactly one of
  43      * them must be non-`NULL`); weak
  44      */
  45     bt_self_component *self_comp;
  46     bt_self_component_class *self_comp_class;
  47
  48     /* Additional clock class offset to apply */
  49     int64_t clock_class_offset_s;
  50     int64_t clock_class_offset_ns;
  51     bool force_clock_class_origin_unix_epoch;
  52
  53     /* True to create trace class objects */
  54     bool create_trace_class;
  55
  56     /*
  57      * True to keep the plain text when content is appended with
  58      * ctf_metadata_decoder_append_content().
  59      */
  60     bool keep_plain_text;
  61 };
  62
  63 /*
  64  * Creates a CTF metadata decoder.
  65  *
  66  * Returns `NULL` on error.
  67  */
  68 BT_HIDDEN
  69 struct ctf_metadata_decoder *
  70 ctf_metadata_decoder_create(const struct ctf_metadata_decoder_config *config);
  71
  72 /*
  73  * Destroys a CTF metadata decoder that you created with
  74  * ctf_metadata_decoder_create().
  75  */
  76 BT_HIDDEN
  77 void ctf_metadata_decoder_destroy(struct ctf_metadata_decoder *metadata_decoder);
  78
  79 /*
  80  * Appends content to the metadata decoder.
  81  *
  82  * This function reads the metadata from the current position of `fp`
  83  * until the end of this file stream.
  84  *
  85  * The metadata can be packetized or not.
  86  *
  87  * The metadata chunk needs to be complete and lexically scannable, that
  88  * is, zero or more complete top-level blocks. If it's incomplete, this
  89  * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`. If this
  90  * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`, then you
  91  * need to call it again with the _same_ metadata and more to make it
  92  * complete. For example:
  93  *
  94  *     First call:  event { name = hell
  95  *     Second call: event { name = hello_world; ... };
  96  *
  97  * If everything goes as expected, this function returns
  98  * `CTF_METADATA_DECODER_STATUS_OK`.
  99  */
 100 BT_HIDDEN
 101 enum ctf_metadata_decoder_status
 102 ctf_metadata_decoder_append_content(struct ctf_metadata_decoder *metadata_decoder, FILE *fp);
 103
 104 /*
 105  * Returns the trace IR trace class of this metadata decoder (new
 106  * reference).
 107  *
 108  * Returns `NULL` if there's none yet or if the metadata decoder is not
 109  * configured to create trace classes.
 110  */
 111 BT_HIDDEN
 112 bt_trace_class *ctf_metadata_decoder_get_ir_trace_class(struct ctf_metadata_decoder *mdec);
 113
 114 /*
 115  * Returns the CTF IR trace class of this metadata decoder.
 116  *
 117  * Returns `NULL` if there's none yet or if the metadata decoder is not
 118  * configured to create trace classes.
 119  */
 120 BT_HIDDEN
 121 struct ctf_trace_class *
 122 ctf_metadata_decoder_borrow_ctf_trace_class(struct ctf_metadata_decoder *mdec);
 123
 124 /*
 125  * Checks whether or not a given metadata file stream `fp` is
 126  * packetized, setting `is_packetized` accordingly on success. On
 127  * success, also sets `*byte_order` to the byte order of the first
 128  * packet.
 129  *
 130  * This function uses `log_level` and `self_comp` for logging purposes.
 131  * `self_comp` can be `NULL` if not available.
 132  */
 133 BT_HIDDEN
 134 int ctf_metadata_decoder_is_packetized(FILE *fp, bool *is_packetized, int *byte_order,
 135                                        bt_logging_level log_level, bt_self_component *self_comp);
 136
 137 /*
 138  * Returns the byte order of the decoder's metadata stream as set by the
 139  * last call to ctf_metadata_decoder_append_content().
 140  *
 141  * Returns -1 if unknown (plain text content).
 142  */
 143 BT_HIDDEN
 144 int ctf_metadata_decoder_get_byte_order(struct ctf_metadata_decoder *mdec);
 145
 146 /*
 147  * Returns the UUID of the decoder's metadata stream as set by the last
 148  * call to ctf_metadata_decoder_append_content().
 149  */
 150 BT_HIDDEN
 151 int ctf_metadata_decoder_get_uuid(struct ctf_metadata_decoder *mdec, bt_uuid_t uuid);
 152
 153 /*
 154  * Returns the UUID of the decoder's trace class, if available.
 155  *
 156  * Returns:
 157  *
 158  * * `CTF_METADATA_DECODER_STATUS_OK`: success.
 159  * * `CTF_METADATA_DECODER_STATUS_NONE`: no UUID.
 160  * * `CTF_METADATA_DECODER_STATUS_INCOMPLETE`: missing metadata content.
 161  */
 162 BT_HIDDEN
 163 enum ctf_metadata_decoder_status
 164 ctf_metadata_decoder_get_trace_class_uuid(struct ctf_metadata_decoder *mdec, bt_uuid_t uuid);
 165
 166 /*
 167  * Returns the metadata decoder's current metadata text.
 168  */
 169 BT_HIDDEN
 170 const char *ctf_metadata_decoder_get_text(struct ctf_metadata_decoder *mdec);
 171
 172 static inline bool ctf_metadata_decoder_is_packet_version_valid(unsigned int major,
 173                                                                 unsigned int minor)
 174 {
 175     return major == 1 && minor == 8;
 176 }
 177
 178 #endif /* _METADATA_DECODER_H */