1 #ifndef _METADATA_DECODER_H
2 #define _METADATA_DECODER_H
5 * Copyright 2016-2017 - Philippe Proulx <pproulx@efficios.com>
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:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
21 #include <babeltrace2/babeltrace.h>
23 #include "common/macros.h"
25 /* A CTF metadata decoder object */
26 struct ctf_metadata_decoder
;
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,
37 /* Decoding configuration */
38 struct ctf_metadata_decoder_config
{
39 bt_logging_level log_level
;
42 bt_self_component
*self_comp
;
44 int64_t clock_class_offset_s
;
45 int64_t clock_class_offset_ns
;
49 * Creates a CTF metadata decoder.
51 * Returns `NULL` on error.
54 struct ctf_metadata_decoder
*ctf_metadata_decoder_create(
55 const struct ctf_metadata_decoder_config
*config
);
58 * Destroys a CTF metadata decoder that you created with
59 * ctf_metadata_decoder_create().
62 void ctf_metadata_decoder_destroy(
63 struct ctf_metadata_decoder
*metadata_decoder
);
66 * Decodes a new chunk of CTF metadata.
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.
74 * The metadata can be packetized or not.
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:
83 * First call: event { name = hell
84 * Second call: event { name = hello_world; ... };
86 * If the conversion from the metadata text to CTF IR objects fails,
87 * this function returns `CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR`.
89 * If everything goes as expected, this function returns
90 * `CTF_METADATA_DECODER_STATUS_OK`.
93 enum ctf_metadata_decoder_status
ctf_metadata_decoder_decode(
94 struct ctf_metadata_decoder
*metadata_decoder
, FILE *fp
);
97 bt_trace_class
*ctf_metadata_decoder_get_ir_trace_class(
98 struct ctf_metadata_decoder
*mdec
);
101 struct ctf_trace_class
*ctf_metadata_decoder_borrow_ctf_trace_class(
102 struct ctf_metadata_decoder
*mdec
);
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.
109 bool ctf_metadata_decoder_is_packetized(FILE *fp
, int *byte_order
,
110 bt_logging_level log_level
,
111 bt_self_component
*self_comp
);
114 * Decodes a packetized metadata file stream to a NULL-terminated
115 * text buffer using the given byte order.
118 int ctf_metadata_decoder_packetized_file_stream_to_buf(FILE *fp
,
119 char **buf
, int byte_order
, bool *is_uuid_set
,
120 uint8_t *uuid
, bt_logging_level log_level
,
121 bt_self_component
*self_comp
);
124 bool ctf_metadata_decoder_is_packet_version_valid(unsigned int major
,
127 return major
== 1 && minor
== 8;
130 #endif /* _METADATA_DECODER_H */