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