src/plugins/ctf/common/metadata/decoder.h

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