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

   1 #ifndef _METADATA_DECODER_H
   2 #define _METADATA_DECODER_H
   3
   4 /*
   5  * Copyright 2016-2017 - Philippe Proulx <pproulx@efficios.com>
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a copy
   8  * of this software and associated documentation files (the "Software"), to deal
   9  * in the Software without restriction, including without limitation the rights
  10  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  11  * copies of the Software, and to permit persons to whom the Software is
  12  * furnished to do so, subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included in
  15  * all copies or substantial portions of the Software.
  16  */
  17
  18 #include <stdint.h>
  19 #include <stdbool.h>
  20
  21 #include <babeltrace2/babeltrace.h>
  22
  23 #include "common/macros.h"
  24 #include "common/uuid.h"
  25
  26 struct ctf_trace_class;
  27
  28 /* A CTF metadata decoder object */
  29 struct ctf_metadata_decoder;
  30
  31 /* CTF metadata decoder status */
  32 enum ctf_metadata_decoder_status {
  33         CTF_METADATA_DECODER_STATUS_OK                  = 0,
  34         CTF_METADATA_DECODER_STATUS_NONE                = 1,
  35         CTF_METADATA_DECODER_STATUS_ERROR               = -1,
  36         CTF_METADATA_DECODER_STATUS_INCOMPLETE          = -2,
  37         CTF_METADATA_DECODER_STATUS_INVAL_VERSION       = -3,
  38         CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR    = -4,
  39 };
  40
  41 /* Decoding configuration */
  42 struct ctf_metadata_decoder_config {
  43         /* Active log level to use */
  44         bt_logging_level log_level;
  45
  46         /* Component to use for logging (can be `NULL`); weak */
  47         bt_self_component *self_comp;
  48
  49         /* Additional clock class offset to apply */
  50         int64_t clock_class_offset_s;
  51         int64_t clock_class_offset_ns;
  52         bool force_clock_class_origin_unix_epoch;
  53
  54         /* True to create trace class objects */
  55         bool create_trace_class;
  56
  57         /*
  58          * True to keep the plain text when content is appended with
  59          * ctf_metadata_decoder_append_content().
  60          */
  61         bool keep_plain_text;
  62 };
  63
  64 /*
  65  * Creates a CTF metadata decoder.
  66  *
  67  * Returns `NULL` on error.
  68  */
  69 BT_HIDDEN
  70 struct ctf_metadata_decoder *ctf_metadata_decoder_create(
  71                 const struct ctf_metadata_decoder_config *config);
  72
  73 /*
  74  * Destroys a CTF metadata decoder that you created with
  75  * ctf_metadata_decoder_create().
  76  */
  77 BT_HIDDEN
  78 void ctf_metadata_decoder_destroy(
  79                 struct ctf_metadata_decoder *metadata_decoder);
  80
  81 /*
  82  * Appends content to the metadata decoder.
  83  *
  84  * This function reads the metadata from the current position of `fp`
  85  * until the end of this file stream.
  86  *
  87  * The metadata can be packetized or not.
  88  *
  89  * The metadata chunk needs to be complete and lexically scannable, that
  90  * is, zero or more complete top-level blocks. If it's incomplete, this
  91  * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`. If this
  92  * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`, then you
  93  * need to call it again with the _same_ metadata and more to make it
  94  * complete. For example:
  95  *
  96  *     First call:  event { name = hell
  97  *     Second call: event { name = hello_world; ... };
  98  *
  99  * If everything goes as expected, this function returns
 100  * `CTF_METADATA_DECODER_STATUS_OK`.
 101  */
 102 BT_HIDDEN
 103 enum ctf_metadata_decoder_status ctf_metadata_decoder_append_content(
 104                 struct ctf_metadata_decoder *metadata_decoder, FILE *fp);
 105
 106 /*
 107  * Returns the trace IR trace class of this metadata decoder (new
 108  * reference).
 109  *
 110  * Returns `NULL` if there's none yet or if the metadata decoder is not
 111  * configured to create trace classes.
 112  */
 113 BT_HIDDEN
 114 bt_trace_class *ctf_metadata_decoder_get_ir_trace_class(
 115                 struct ctf_metadata_decoder *mdec);
 116
 117 /*
 118  * Returns the CTF IR trace class of this metadata decoder.
 119  *
 120  * Returns `NULL` if there's none yet or if the metadata decoder is not
 121  * configured to create trace classes.
 122  */
 123 BT_HIDDEN
 124 struct ctf_trace_class *ctf_metadata_decoder_borrow_ctf_trace_class(
 125                 struct ctf_metadata_decoder *mdec);
 126
 127 /*
 128  * Checks whether or not a given metadata file stream `fp` is
 129  * packetized, setting `is_packetized` accordingly on success. On
 130  * success, also sets `*byte_order` to the byte order of the first
 131  * packet.
 132  *
 133  * This function uses `log_level` and `self_comp` for logging purposes.
 134  * `self_comp` can be `NULL` if not available.
 135  */
 136 BT_HIDDEN
 137 int ctf_metadata_decoder_is_packetized(FILE *fp, bool *is_packetized,
 138                 int *byte_order, bt_logging_level log_level,
 139                 bt_self_component *self_comp);
 140
 141 /*
 142  * Returns the byte order of the decoder's metadata stream as set by the
 143  * last call to ctf_metadata_decoder_append_content().
 144  *
 145  * Returns -1 if unknown (plain text content).
 146  */
 147 BT_HIDDEN
 148 int ctf_metadata_decoder_get_byte_order(struct ctf_metadata_decoder *mdec);
 149
 150 /*
 151  * Returns the UUID of the decoder's metadata stream as set by the last
 152  * call to ctf_metadata_decoder_append_content().
 153  */
 154 BT_HIDDEN
 155 int ctf_metadata_decoder_get_uuid(
 156                 struct ctf_metadata_decoder *mdec, bt_uuid_t uuid);
 157
 158 /*
 159  * Returns the UUID of the decoder's trace class, if available.
 160  *
 161  * Returns:
 162  *
 163  * * `CTF_METADATA_DECODER_STATUS_OK`: success.
 164  * * `CTF_METADATA_DECODER_STATUS_NONE`: no UUID.
 165  * * `CTF_METADATA_DECODER_STATUS_INCOMPLETE`: missing metadata content.
 166  */
 167 BT_HIDDEN
 168 enum ctf_metadata_decoder_status ctf_metadata_decoder_get_trace_class_uuid(
 169                 struct ctf_metadata_decoder *mdec, bt_uuid_t uuid);
 170
 171 /*
 172  * Returns the metadata decoder's current metadata text.
 173  */
 174 BT_HIDDEN
 175 const char *ctf_metadata_decoder_get_text(struct ctf_metadata_decoder *mdec);
 176
 177 static inline
 178 bool ctf_metadata_decoder_is_packet_version_valid(unsigned int major,
 179                 unsigned int minor)
 180 {
 181         return major == 1 && minor == 8;
 182 }
 183
 184 #endif /* _METADATA_DECODER_H */