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