[babeltrace.git] / src / plugins / ctf / common / metadata / decoder.h

/*
 * SPDX-License-Identifier: MIT
 *
 * Copyright 2016-2017 Philippe Proulx <pproulx@efficios.com>
 */

#ifndef _METADATA_DECODER_H
#define _METADATA_DECODER_H

#include <stdint.h>
#include <stdbool.h>

#include <babeltrace2/babeltrace.h>

#include "common/macros.h"
#include "common/uuid.h"

struct ctf_trace_class;

/* A CTF metadata decoder object */
struct ctf_metadata_decoder;

/* CTF metadata decoder status */
enum ctf_metadata_decoder_status {
	CTF_METADATA_DECODER_STATUS_OK			= 0,
	CTF_METADATA_DECODER_STATUS_NONE		= 1,
	CTF_METADATA_DECODER_STATUS_ERROR		= -1,
	CTF_METADATA_DECODER_STATUS_INCOMPLETE		= -2,
	CTF_METADATA_DECODER_STATUS_INVAL_VERSION	= -3,
	CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR	= -4,
};

/* Decoding configuration */
struct ctf_metadata_decoder_config {
	/* Active log level to use */
	bt_logging_level log_level;

	/* Component to use for logging (can be `NULL`); weak */
	bt_self_component *self_comp;

	/* Additional clock class offset to apply */
	int64_t clock_class_offset_s;
	int64_t clock_class_offset_ns;
	bool force_clock_class_origin_unix_epoch;

	/* True to create trace class objects */
	bool create_trace_class;

	/*
	 * True to keep the plain text when content is appended with
	 * ctf_metadata_decoder_append_content().
	 */
	bool keep_plain_text;
};

/*
 * Creates a CTF metadata decoder.
 *
 * Returns `NULL` on error.
 */
BT_HIDDEN
struct ctf_metadata_decoder *ctf_metadata_decoder_create(
		const struct ctf_metadata_decoder_config *config);

/*
 * Destroys a CTF metadata decoder that you created with
 * ctf_metadata_decoder_create().
 */
BT_HIDDEN
void ctf_metadata_decoder_destroy(
		struct ctf_metadata_decoder *metadata_decoder);

/*
 * Appends content to the metadata decoder.
 *
 * This function reads the metadata from the current position of `fp`
 * until the end of this file stream.
 *
 * The metadata can be packetized or not.
 *
 * The metadata chunk needs to be complete and lexically scannable, that
 * is, zero or more complete top-level blocks. If it's incomplete, this
 * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`. If this
 * function returns `CTF_METADATA_DECODER_STATUS_INCOMPLETE`, then you
 * need to call it again with the _same_ metadata and more to make it
 * complete. For example:
 *
 *     First call:  event { name = hell
 *     Second call: event { name = hello_world; ... };
 *
 * If everything goes as expected, this function returns
 * `CTF_METADATA_DECODER_STATUS_OK`.
 */
BT_HIDDEN
enum ctf_metadata_decoder_status ctf_metadata_decoder_append_content(
		struct ctf_metadata_decoder *metadata_decoder, FILE *fp);

/*
 * Returns the trace IR trace class of this metadata decoder (new
 * reference).
 *
 * Returns `NULL` if there's none yet or if the metadata decoder is not
 * configured to create trace classes.
 */
BT_HIDDEN
bt_trace_class *ctf_metadata_decoder_get_ir_trace_class(
		struct ctf_metadata_decoder *mdec);

/*
 * Returns the CTF IR trace class of this metadata decoder.
 *
 * Returns `NULL` if there's none yet or if the metadata decoder is not
 * configured to create trace classes.
 */
BT_HIDDEN
struct ctf_trace_class *ctf_metadata_decoder_borrow_ctf_trace_class(
		struct ctf_metadata_decoder *mdec);

/*
 * Checks whether or not a given metadata file stream `fp` is
 * packetized, setting `is_packetized` accordingly on success. On
 * success, also sets `*byte_order` to the byte order of the first
 * packet.
 *
 * This function uses `log_level` and `self_comp` for logging purposes.
 * `self_comp` can be `NULL` if not available.
 */
BT_HIDDEN
int ctf_metadata_decoder_is_packetized(FILE *fp, bool *is_packetized,
		int *byte_order, bt_logging_level log_level,
		bt_self_component *self_comp);

/*
 * Returns the byte order of the decoder's metadata stream as set by the
 * last call to ctf_metadata_decoder_append_content().
 *
 * Returns -1 if unknown (plain text content).
 */
BT_HIDDEN
int ctf_metadata_decoder_get_byte_order(struct ctf_metadata_decoder *mdec);

/*
 * Returns the UUID of the decoder's metadata stream as set by the last
 * call to ctf_metadata_decoder_append_content().
 */
BT_HIDDEN
int ctf_metadata_decoder_get_uuid(
		struct ctf_metadata_decoder *mdec, bt_uuid_t uuid);

/*
 * Returns the UUID of the decoder's trace class, if available.
 *
 * Returns:
 *
 * * `CTF_METADATA_DECODER_STATUS_OK`: success.
 * * `CTF_METADATA_DECODER_STATUS_NONE`: no UUID.
 * * `CTF_METADATA_DECODER_STATUS_INCOMPLETE`: missing metadata content.
 */
BT_HIDDEN
enum ctf_metadata_decoder_status ctf_metadata_decoder_get_trace_class_uuid(
		struct ctf_metadata_decoder *mdec, bt_uuid_t uuid);

/*
 * Returns the metadata decoder's current metadata text.
 */
BT_HIDDEN
const char *ctf_metadata_decoder_get_text(struct ctf_metadata_decoder *mdec);

static inline
bool ctf_metadata_decoder_is_packet_version_valid(unsigned int major,
		unsigned int minor)
{
	return major == 1 && minor == 8;
}

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