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
  25 /* A CTF metadata decoder object */
  26 struct ctf_metadata_decoder;
  27
  28 /* CTF metadata decoder status */
  29 enum ctf_metadata_decoder_status {
  30         CTF_METADATA_DECODER_STATUS_OK                  = 0,
  31         CTF_METADATA_DECODER_STATUS_ERROR               = -1,
  32         CTF_METADATA_DECODER_STATUS_INCOMPLETE          = -2,
  33         CTF_METADATA_DECODER_STATUS_INVAL_VERSION       = -3,
  34         CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR    = -4,
  35 };
  36
  37 /* Decoding configuration */
  38 struct ctf_metadata_decoder_config {
  39         bt_logging_level log_level;
  40
  41         /* Weak */
  42         bt_self_component *self_comp;
  43
  44         int64_t clock_class_offset_s;
  45         int64_t clock_class_offset_ns;
  46 };
  47
  48 /*
  49  * Creates a CTF metadata decoder.
  50  *
  51  * Returns `NULL` on error.
  52  */
  53 BT_HIDDEN
  54 struct ctf_metadata_decoder *ctf_metadata_decoder_create(
  55                 const struct ctf_metadata_decoder_config *config);
  56
  57 /*
  58  * Destroys a CTF metadata decoder that you created with
  59  * ctf_metadata_decoder_create().
  60  */
  61 BT_HIDDEN
  62 void ctf_metadata_decoder_destroy(
  63                 struct ctf_metadata_decoder *metadata_decoder);
  64
  65 /*
  66  * Decodes a new chunk of CTF metadata.
  67  *
  68  * This function reads the metadata from the current position of `fp`
  69  * until the end of this file stream. If it finds new information (new
  70  * event class, new stream class, or new clock class), it appends this
  71  * information to the decoder's trace object (as returned by
  72  * ctf_metadata_decoder_get_ir_trace_class()), or it creates this trace.
  73  *
  74  * The metadata can be packetized or not.
  75  *
  76  * The metadata chunk needs to be complete and scannable, that is,
  77  * zero or more complete top-level blocks. If it's incomplete, this
  78  * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`. If this
  79  * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`, then you
  80  * need to call it again with the same metadata and more to make it
  81  * complete. For example:
  82  *
  83  *     First call:  event { name = hell
  84  *     Second call: event { name = hello_world; ... };
  85  *
  86  * If the conversion from the metadata text to CTF IR objects fails,
  87  * this function returns `CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR`.
  88  *
  89  * If everything goes as expected, this function returns
  90  * `CTF_METADATA_DECODER_STATUS_OK`.
  91  */
  92 BT_HIDDEN
  93 enum ctf_metadata_decoder_status ctf_metadata_decoder_decode(
  94                 struct ctf_metadata_decoder *metadata_decoder, FILE *fp);
  95
  96 BT_HIDDEN
  97 bt_trace_class *ctf_metadata_decoder_get_ir_trace_class(
  98                 struct ctf_metadata_decoder *mdec);
  99
 100 BT_HIDDEN
 101 struct ctf_trace_class *ctf_metadata_decoder_borrow_ctf_trace_class(
 102                 struct ctf_metadata_decoder *mdec);
 103
 104 /*
 105  * Checks whether or not a given metadata file stream is packetized, and
 106  * if so, sets `*byte_order` to the byte order of the first packet.
 107  */
 108 BT_HIDDEN
 109 bool ctf_metadata_decoder_is_packetized(FILE *fp, int *byte_order,
 110                 bt_logging_level log_level,
 111                 bt_self_component *self_comp);
 112
 113 /*
 114  * Decodes a packetized metadata file stream to a NULL-terminated
 115  * text buffer using the given byte order.
 116  */
 117 BT_HIDDEN
 118 int ctf_metadata_decoder_packetized_file_stream_to_buf(
 119                 FILE *fp, char **buf, int byte_order,
 120                 bt_logging_level log_level,
 121                 bt_self_component *self_comp);
 122
 123 #endif /* _METADATA_DECODER_H */