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

#ifndef _METADATA_DECODER_H
#define _METADATA_DECODER_H

/*
 * Copyright 2016-2017 - Philippe Proulx <pproulx@efficios.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 */

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

#include <babeltrace2/babeltrace.h>

#include "common/macros.h"

/* 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_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 {
	bt_logging_level log_level;

	/* Weak */
	bt_self_component *self_comp;

	int64_t clock_class_offset_s;
	int64_t clock_class_offset_ns;
};

/*
 * 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);

/*
 * Decodes a new chunk of CTF metadata.
 *
 * This function reads the metadata from the current position of `fp`
 * until the end of this file stream. If it finds new information (new
 * event class, new stream class, or new clock class), it appends this
 * information to the decoder's trace object (as returned by
 * ctf_metadata_decoder_get_ir_trace_class()), or it creates this trace.
 *
 * The metadata can be packetized or not.
 *
 * The metadata chunk needs to be complete and 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 the conversion from the metadata text to CTF IR objects fails,
 * this function returns `CTF_METADATA_DECODER_STATUS_IR_VISITOR_ERROR`.
 *
 * If everything goes as expected, this function returns
 * `CTF_METADATA_DECODER_STATUS_OK`.
 */
BT_HIDDEN
enum ctf_metadata_decoder_status ctf_metadata_decoder_decode(
		struct ctf_metadata_decoder *metadata_decoder, FILE *fp);

BT_HIDDEN
bt_trace_class *ctf_metadata_decoder_get_ir_trace_class(
		struct ctf_metadata_decoder *mdec);

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 is packetized, and
 * if so, sets `*byte_order` to the byte order of the first packet.
 */
BT_HIDDEN
bool ctf_metadata_decoder_is_packetized(FILE *fp, int *byte_order,
		bt_logging_level log_level,
		bt_self_component *self_comp);

/*
 * Decodes a packetized metadata file stream to a NULL-terminated
 * text buffer using the given byte order.
 */
BT_HIDDEN
int ctf_metadata_decoder_packetized_file_stream_to_buf(FILE *fp,
		char **buf, int byte_order, bool *is_uuid_set,
		uint8_t *uuid, bt_logging_level log_level,
		bt_self_component *self_comp);

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
1e649dff PP	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>
a2a54545	19	#include <stdbool.h>
1e649dff	20
3fadfbc0	21	#include <babeltrace2/babeltrace.h>
1e649dff	22
91d81473 MJ	23	#include "common/macros.h"
91d81473 MJ	24
1e649dff PP	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
a2a54545 PP	37	/* Decoding configuration */
a2a54545 PP	38	struct ctf_metadata_decoder_config {
0746848c	39	bt_logging_level log_level;
f7b785ac PP	40
	41	/* Weak */
	42	bt_self_component *self_comp;
	43
a2a54545 PP	44	int64_t clock_class_offset_s;
a2a54545 PP	45	int64_t clock_class_offset_ns;
a2a54545 PP	46	};
a2a54545 PP	47
1e649dff	48	/*
862ca4ed	49	* Creates a CTF metadata decoder.
1e649dff PP	50	*
	51	* Returns `NULL` on error.
	52	*/
	53	BT_HIDDEN
55314f2a	54	struct ctf_metadata_decoder *ctf_metadata_decoder_create(
862ca4ed	55	const struct ctf_metadata_decoder_config *config);
1e649dff PP	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
862ca4ed	72	* ctf_metadata_decoder_get_ir_trace_class()), or it creates this trace.
1e649dff PP	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
1e649dff	96	BT_HIDDEN
b19ff26f	97	bt_trace_class *ctf_metadata_decoder_get_ir_trace_class(
44c440bc PP	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);
1e649dff PP	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
0746848c	109	bool ctf_metadata_decoder_is_packetized(FILE fp, int byte_order,
f7b785ac PP	110	bt_logging_level log_level,
f7b785ac PP	111	bt_self_component *self_comp);
1e649dff PP	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
3c8252a5 PP	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,
f7b785ac	121	bt_self_component *self_comp);
1e649dff	122
3c8252a5 PP	123	static inline
	124	bool ctf_metadata_decoder_is_packet_version_valid(unsigned int major,
	125	unsigned int minor)
	126	{
	127	return major == 1 && minor == 8;
	128	}
	129
1e649dff	130	#endif /* _METADATA_DECODER_H */