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
  20 struct bt_ctf_trace;
  21
  22 /* A CTF metadata decoder object */
  23 struct ctf_metadata_decoder;
  24
  25 /* CTF metadata decoder status */
  26 enum ctf_metadata_decoder_status {
  27         CTF_METADATA_DECODER_STATUS_OK                  = 0,
  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 /*
  35  * Creates a CTF metadata decoder with `err` as the error stream (can
  36  * be `NULL` to disable error output). `clock_class_offset_ns` is an
  37  * offset to apply to the decoded clock classes's offsets.
  38  *
  39  * Returns `NULL` on error.
  40  */
  41 BT_HIDDEN
  42 struct ctf_metadata_decoder *ctf_metadata_decoder_create(FILE *err,
  43                 uint64_t clock_class_offset_ns);
  44
  45 /*
  46  * Destroys a CTF metadata decoder that you created with
  47  * ctf_metadata_decoder_create().
  48  */
  49 BT_HIDDEN
  50 void ctf_metadata_decoder_destroy(
  51                 struct ctf_metadata_decoder *metadata_decoder);
  52
  53 /*
  54  * Decodes a new chunk of CTF metadata.
  55  *
  56  * This function reads the metadata from the current position of `fp`
  57  * until the end of this file stream. If it finds new information (new
  58  * event class, new stream class, or new clock class), it appends this
  59  * information to the decoder's trace object (as returned by
  60  * ctf_metadata_get_trace()), or it creates this trace.
  61  *
  62  * The metadata can be packetized or not.
  63  *
  64  * The metadata chunk needs to be complete and scannable, that is,
  65  * zero or more complete top-level blocks. If it's incomplete, this
  66  * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`. If this
  67  * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`, then you
  68  * need to call it again with the same metadata and more to make it
  69  * complete. For example:
  70  *
  71  *     First call:  event { name = hell
  72  *     Second call: event { name = hello_world; ... };
  73  *
  74  * If the conversion from the metadata text to CTF IR objects fails,
  75  * this function returns `CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR`.
  76  *
  77  * If everything goes as expected, this function returns
  78  * `CTF_METADATA_DECODER_STATUS_OK`.
  79  */
  80 BT_HIDDEN
  81 enum ctf_metadata_decoder_status ctf_metadata_decoder_decode(
  82                 struct ctf_metadata_decoder *metadata_decoder, FILE *fp);
  83
  84 /*
  85  * Returns a new reference to the current CTF IR trace object which is
  86  * the result of the metadata decoding process.
  87  *
  88  * The trace object, once created, remains the same until you call
  89  * ctf_metadata_decoder_destroy().
  90  */
  91 BT_HIDDEN
  92 struct bt_ctf_trace *ctf_metadata_decoder_get_trace(
  93                 struct ctf_metadata_decoder *metadata_decoder);
  94
  95 /*
  96  * Checks whether or not a given metadata file stream is packetized, and
  97  * if so, sets `*byte_order` to the byte order of the first packet.
  98  */
  99 BT_HIDDEN
 100 bool ctf_metadata_decoder_is_packetized(FILE *fp, int *byte_order);
 101
 102 /*
 103  * Decodes a packetized metadata file stream to a NULL-terminated
 104  * text buffer using the given byte order.
 105  */
 106 BT_HIDDEN
 107 int ctf_metadata_decoder_packetized_file_stream_to_buf(
 108                 FILE *fp, char **buf, int byte_order);
 109
 110 #endif /* _METADATA_DECODER_H */