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