[lttng-ust.git] / libringbuffer / frontend.h

/*
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 * Copyright (C) 2005-2012 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
 *
 * Ring Buffer Library Synchronization Header (API).
 *
 * See ring_buffer_frontend.c for more information on wait-free algorithms.
 */

#ifndef _LTTNG_RING_BUFFER_FRONTEND_H
#define _LTTNG_RING_BUFFER_FRONTEND_H

#include <stddef.h>
#include <stdint.h>

#include <urcu/compiler.h>
#include <urcu/uatomic.h>

#include "smp.h"

/* Internal helpers */
#include "frontend_internal.h"

/* Buffer creation/removal and setup operations */

/*
 * switch_timer_interval is the time interval (in us) to fill sub-buffers with
 * padding to let readers get those sub-buffers.  Used for live streaming.
 *
 * read_timer_interval is the time interval (in us) to wake up pending readers.
 *
 * buf_addr is a pointer the the beginning of the preallocated buffer contiguous
 * address mapping. It is used only by RING_BUFFER_STATIC configuration. It can
 * be set to NULL for other backends.
 *
 * priv_data (output) is set to a pointer into a "priv_data_len"-sized
 * memory area for client-specific data. This memory is managed by lib
 * ring buffer. priv_data_align is the alignment required for the
 * private data area.
 */

__attribute__((visibility("hidden")))
extern
struct lttng_ust_shm_handle *channel_create(const struct lttng_ust_lib_ring_buffer_config *config,
				const char *name,
				void **priv_data,
				size_t priv_data_align,
				size_t priv_data_size,
				void *priv_data_init,
				void *buf_addr,
				size_t subbuf_size, size_t num_subbuf,
				unsigned int switch_timer_interval,
				unsigned int read_timer_interval,
				const int *stream_fds, int nr_stream_fds,
				int64_t blocking_timeout);

/*
 * channel_destroy finalizes all channel's buffers, waits for readers to
 * release all references, and destroys the channel.
 */
__attribute__((visibility("hidden")))
extern
void channel_destroy(struct channel *chan, struct lttng_ust_shm_handle *handle,
		int consumer);


/* Buffer read operations */

/*
 * Iteration on channel cpumask needs to issue a read barrier to match the write
 * barrier in cpu hotplug. It orders the cpumask read before read of per-cpu
 * buffer data. The per-cpu buffer is never removed by cpu hotplug; teardown is
 * only performed at channel destruction.
 */
#define for_each_channel_cpu(cpu, chan)					\
	for_each_possible_cpu(cpu)

__attribute__((visibility("hidden")))
extern struct lttng_ust_lib_ring_buffer *channel_get_ring_buffer(
				const struct lttng_ust_lib_ring_buffer_config *config,
				struct channel *chan, int cpu,
				struct lttng_ust_shm_handle *handle,
				int *shm_fd, int *wait_fd,
				int *wakeup_fd,
				uint64_t *memory_map_size);

__attribute__((visibility("hidden")))
extern
int ring_buffer_channel_close_wait_fd(const struct lttng_ust_lib_ring_buffer_config *config,
			struct channel *chan,
			struct lttng_ust_shm_handle *handle);

__attribute__((visibility("hidden")))
extern
int ring_buffer_channel_close_wakeup_fd(const struct lttng_ust_lib_ring_buffer_config *config,
			struct channel *chan,
			struct lttng_ust_shm_handle *handle);

__attribute__((visibility("hidden")))
extern
int ring_buffer_stream_close_wait_fd(const struct lttng_ust_lib_ring_buffer_config *config,
		struct channel *chan,
		struct lttng_ust_shm_handle *handle,
		int cpu);

__attribute__((visibility("hidden")))
extern
int ring_buffer_stream_close_wakeup_fd(const struct lttng_ust_lib_ring_buffer_config *config,
		struct channel *chan,
		struct lttng_ust_shm_handle *handle,
		int cpu);

__attribute__((visibility("hidden")))
extern int lib_ring_buffer_open_read(struct lttng_ust_lib_ring_buffer *buf,
				     struct lttng_ust_shm_handle *handle);

__attribute__((visibility("hidden")))
extern void lib_ring_buffer_release_read(struct lttng_ust_lib_ring_buffer *buf,
					 struct lttng_ust_shm_handle *handle);

/*
 * Initialize signals for ring buffer. Should be called early e.g. by
 * main() in the program to affect all threads.
 */
__attribute__((visibility("hidden")))
void lib_ringbuffer_signal_init(void);

/*
 * Read sequence: snapshot, many get_subbuf/put_subbuf, move_consumer.
 */
__attribute__((visibility("hidden")))
extern int lib_ring_buffer_snapshot(struct lttng_ust_lib_ring_buffer *buf,
				    unsigned long *consumed,
				    unsigned long *produced,
				    struct lttng_ust_shm_handle *handle);

__attribute__((visibility("hidden")))
extern int lib_ring_buffer_snapshot_sample_positions(
				    struct lttng_ust_lib_ring_buffer *buf,
				    unsigned long *consumed,
				    unsigned long *produced,
				    struct lttng_ust_shm_handle *handle);

__attribute__((visibility("hidden")))
extern void lib_ring_buffer_move_consumer(struct lttng_ust_lib_ring_buffer *buf,
					  unsigned long consumed_new,
					  struct lttng_ust_shm_handle *handle);

__attribute__((visibility("hidden")))
extern int lib_ring_buffer_get_subbuf(struct lttng_ust_lib_ring_buffer *buf,
				      unsigned long consumed,
				      struct lttng_ust_shm_handle *handle);
__attribute__((visibility("hidden")))
extern void lib_ring_buffer_put_subbuf(struct lttng_ust_lib_ring_buffer *buf,
				       struct lttng_ust_shm_handle *handle);

/*
 * lib_ring_buffer_get_next_subbuf/lib_ring_buffer_put_next_subbuf are helpers
 * to read sub-buffers sequentially.
 */
static inline int lib_ring_buffer_get_next_subbuf(struct lttng_ust_lib_ring_buffer *buf,
						  struct lttng_ust_shm_handle *handle)
{
	int ret;

	ret = lib_ring_buffer_snapshot(buf, &buf->cons_snapshot,
				       &buf->prod_snapshot, handle);
	if (ret)
		return ret;
	ret = lib_ring_buffer_get_subbuf(buf, buf->cons_snapshot, handle);
	return ret;
}

static inline
void lib_ring_buffer_put_next_subbuf(struct lttng_ust_lib_ring_buffer *buf,
				     struct lttng_ust_shm_handle *handle)
{
	struct channel *chan;

	chan = shmp(handle, buf->backend.chan);
	if (!chan)
		return;
	lib_ring_buffer_put_subbuf(buf, handle);
	lib_ring_buffer_move_consumer(buf, subbuf_align(buf->cons_snapshot, chan),
			handle);
}

__attribute__((visibility("hidden")))
extern void channel_reset(struct channel *chan);

__attribute__((visibility("hidden")))
extern void lib_ring_buffer_reset(struct lttng_ust_lib_ring_buffer *buf,
				  struct lttng_ust_shm_handle *handle);

static inline
unsigned long lib_ring_buffer_get_offset(const struct lttng_ust_lib_ring_buffer_config *config,
					 struct lttng_ust_lib_ring_buffer *buf)
{
	return v_read(config, &buf->offset);
}

static inline
unsigned long lib_ring_buffer_get_consumed(const struct lttng_ust_lib_ring_buffer_config *config,
					   struct lttng_ust_lib_ring_buffer *buf)
{
	return uatomic_read(&buf->consumed);
}

/*
 * Must call lib_ring_buffer_is_finalized before reading counters (memory
 * ordering enforced with respect to trace teardown).
 */
static inline
int lib_ring_buffer_is_finalized(const struct lttng_ust_lib_ring_buffer_config *config,
				 struct lttng_ust_lib_ring_buffer *buf)
{
	int finalized = CMM_ACCESS_ONCE(buf->finalized);
	/*
	 * Read finalized before counters.
	 */
	cmm_smp_rmb();
	return finalized;
}

static inline
int lib_ring_buffer_channel_is_finalized(const struct channel *chan)
{
	return chan->finalized;
}

static inline
int lib_ring_buffer_channel_is_disabled(const struct channel *chan)
{
	return uatomic_read(&chan->record_disabled);
}

static inline
unsigned long lib_ring_buffer_get_read_data_size(
				const struct lttng_ust_lib_ring_buffer_config *config,
				struct lttng_ust_lib_ring_buffer *buf,
				struct lttng_ust_shm_handle *handle)
{
	return subbuffer_get_read_data_size(config, &buf->backend, handle);
}

static inline
unsigned long lib_ring_buffer_get_records_count(
				const struct lttng_ust_lib_ring_buffer_config *config,
				struct lttng_ust_lib_ring_buffer *buf)
{
	return v_read(config, &buf->records_count);
}

static inline
unsigned long lib_ring_buffer_get_records_overrun(
				const struct lttng_ust_lib_ring_buffer_config *config,
				struct lttng_ust_lib_ring_buffer *buf)
{
	return v_read(config, &buf->records_overrun);
}

static inline
unsigned long lib_ring_buffer_get_records_lost_full(
				const struct lttng_ust_lib_ring_buffer_config *config,
				struct lttng_ust_lib_ring_buffer *buf)
{
	return v_read(config, &buf->records_lost_full);
}

static inline
unsigned long lib_ring_buffer_get_records_lost_wrap(
				const struct lttng_ust_lib_ring_buffer_config *config,
				struct lttng_ust_lib_ring_buffer *buf)
{
	return v_read(config, &buf->records_lost_wrap);
}

static inline
unsigned long lib_ring_buffer_get_records_lost_big(
				const struct lttng_ust_lib_ring_buffer_config *config,
				struct lttng_ust_lib_ring_buffer *buf)
{
	return v_read(config, &buf->records_lost_big);
}

static inline
unsigned long lib_ring_buffer_get_records_read(
				const struct lttng_ust_lib_ring_buffer_config *config,
				struct lttng_ust_lib_ring_buffer *buf)
{
	return v_read(config, &buf->backend.records_read);
}

#endif /* _LTTNG_RING_BUFFER_FRONTEND_H */
Commit	Line	Data
	1	/*
	2	* SPDX-License-Identifier: LGPL-2.1-only
	3	*
	4	* Copyright (C) 2005-2012 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
	5	*
	6	* Ring Buffer Library Synchronization Header (API).
	7	*
	8	* See ring_buffer_frontend.c for more information on wait-free algorithms.
	9	*/
	10
	11	#ifndef _LTTNG_RING_BUFFER_FRONTEND_H
	12	#define _LTTNG_RING_BUFFER_FRONTEND_H
	13
	14	#include <stddef.h>
	15	#include <stdint.h>
	16
	17	#include <urcu/compiler.h>
	18	#include <urcu/uatomic.h>
	19
	20	#include "smp.h"
	21
	22	/* Internal helpers */
	23	#include "frontend_internal.h"
	24
	25	/* Buffer creation/removal and setup operations */
	26
	27	/*
	28	* switch_timer_interval is the time interval (in us) to fill sub-buffers with
	29	* padding to let readers get those sub-buffers. Used for live streaming.
	30	*
	31	* read_timer_interval is the time interval (in us) to wake up pending readers.
	32	*
	33	* buf_addr is a pointer the the beginning of the preallocated buffer contiguous
	34	* address mapping. It is used only by RING_BUFFER_STATIC configuration. It can
	35	* be set to NULL for other backends.
	36	*
	37	* priv_data (output) is set to a pointer into a "priv_data_len"-sized
	38	* memory area for client-specific data. This memory is managed by lib
	39	* ring buffer. priv_data_align is the alignment required for the
	40	* private data area.
	41	*/
	42
	43	__attribute__((visibility("hidden")))
	44	extern
	45	struct lttng_ust_shm_handle channel_create(const struct lttng_ust_lib_ring_buffer_config config,
	46	const char *name,
	47	void **priv_data,
	48	size_t priv_data_align,
	49	size_t priv_data_size,
	50	void *priv_data_init,
	51	void *buf_addr,
	52	size_t subbuf_size, size_t num_subbuf,
	53	unsigned int switch_timer_interval,
	54	unsigned int read_timer_interval,
	55	const int *stream_fds, int nr_stream_fds,
	56	int64_t blocking_timeout);
	57
	58	/*
	59	* channel_destroy finalizes all channel's buffers, waits for readers to
	60	* release all references, and destroys the channel.
	61	*/
	62	__attribute__((visibility("hidden")))
	63	extern
	64	void channel_destroy(struct channel chan, struct lttng_ust_shm_handle handle,
	65	int consumer);
	66
	67
	68	/* Buffer read operations */
	69
	70	/*
	71	* Iteration on channel cpumask needs to issue a read barrier to match the write
	72	* barrier in cpu hotplug. It orders the cpumask read before read of per-cpu
	73	* buffer data. The per-cpu buffer is never removed by cpu hotplug; teardown is
	74	* only performed at channel destruction.
	75	*/
	76	#define for_each_channel_cpu(cpu, chan) \
	77	for_each_possible_cpu(cpu)
	78
	79	__attribute__((visibility("hidden")))
	80	extern struct lttng_ust_lib_ring_buffer *channel_get_ring_buffer(
	81	const struct lttng_ust_lib_ring_buffer_config *config,
	82	struct channel *chan, int cpu,
	83	struct lttng_ust_shm_handle *handle,
	84	int shm_fd, int wait_fd,
	85	int *wakeup_fd,
	86	uint64_t *memory_map_size);
	87
	88	__attribute__((visibility("hidden")))
	89	extern
	90	int ring_buffer_channel_close_wait_fd(const struct lttng_ust_lib_ring_buffer_config *config,
	91	struct channel *chan,
	92	struct lttng_ust_shm_handle *handle);
	93
	94	__attribute__((visibility("hidden")))
	95	extern
	96	int ring_buffer_channel_close_wakeup_fd(const struct lttng_ust_lib_ring_buffer_config *config,
	97	struct channel *chan,
	98	struct lttng_ust_shm_handle *handle);
	99
	100	__attribute__((visibility("hidden")))
	101	extern
	102	int ring_buffer_stream_close_wait_fd(const struct lttng_ust_lib_ring_buffer_config *config,
	103	struct channel *chan,
	104	struct lttng_ust_shm_handle *handle,
	105	int cpu);
	106
	107	__attribute__((visibility("hidden")))
	108	extern
	109	int ring_buffer_stream_close_wakeup_fd(const struct lttng_ust_lib_ring_buffer_config *config,
	110	struct channel *chan,
	111	struct lttng_ust_shm_handle *handle,
	112	int cpu);
	113
	114	__attribute__((visibility("hidden")))
	115	extern int lib_ring_buffer_open_read(struct lttng_ust_lib_ring_buffer *buf,
	116	struct lttng_ust_shm_handle *handle);
	117
	118	__attribute__((visibility("hidden")))
	119	extern void lib_ring_buffer_release_read(struct lttng_ust_lib_ring_buffer *buf,
	120	struct lttng_ust_shm_handle *handle);
	121
	122	/*
	123	* Initialize signals for ring buffer. Should be called early e.g. by
	124	* main() in the program to affect all threads.
	125	*/
	126	__attribute__((visibility("hidden")))
	127	void lib_ringbuffer_signal_init(void);
	128
	129	/*
	130	* Read sequence: snapshot, many get_subbuf/put_subbuf, move_consumer.
	131	*/
	132	__attribute__((visibility("hidden")))
	133	extern int lib_ring_buffer_snapshot(struct lttng_ust_lib_ring_buffer *buf,
	134	unsigned long *consumed,
	135	unsigned long *produced,
	136	struct lttng_ust_shm_handle *handle);
	137
	138	__attribute__((visibility("hidden")))
	139	extern int lib_ring_buffer_snapshot_sample_positions(
	140	struct lttng_ust_lib_ring_buffer *buf,
	141	unsigned long *consumed,
	142	unsigned long *produced,
	143	struct lttng_ust_shm_handle *handle);
	144
	145	__attribute__((visibility("hidden")))
	146	extern void lib_ring_buffer_move_consumer(struct lttng_ust_lib_ring_buffer *buf,
	147	unsigned long consumed_new,
	148	struct lttng_ust_shm_handle *handle);
	149
	150	__attribute__((visibility("hidden")))
	151	extern int lib_ring_buffer_get_subbuf(struct lttng_ust_lib_ring_buffer *buf,
	152	unsigned long consumed,
	153	struct lttng_ust_shm_handle *handle);
	154	__attribute__((visibility("hidden")))
	155	extern void lib_ring_buffer_put_subbuf(struct lttng_ust_lib_ring_buffer *buf,
	156	struct lttng_ust_shm_handle *handle);
	157
	158	/*
	159	* lib_ring_buffer_get_next_subbuf/lib_ring_buffer_put_next_subbuf are helpers
	160	* to read sub-buffers sequentially.
	161	*/
	162	static inline int lib_ring_buffer_get_next_subbuf(struct lttng_ust_lib_ring_buffer *buf,
	163	struct lttng_ust_shm_handle *handle)
	164	{
	165	int ret;
	166
	167	ret = lib_ring_buffer_snapshot(buf, &buf->cons_snapshot,
	168	&buf->prod_snapshot, handle);
	169	if (ret)
	170	return ret;
	171	ret = lib_ring_buffer_get_subbuf(buf, buf->cons_snapshot, handle);
	172	return ret;
	173	}
	174
	175	static inline
	176	void lib_ring_buffer_put_next_subbuf(struct lttng_ust_lib_ring_buffer *buf,
	177	struct lttng_ust_shm_handle *handle)
	178	{
	179	struct channel *chan;
	180
	181	chan = shmp(handle, buf->backend.chan);
	182	if (!chan)
	183	return;
	184	lib_ring_buffer_put_subbuf(buf, handle);
	185	lib_ring_buffer_move_consumer(buf, subbuf_align(buf->cons_snapshot, chan),
	186	handle);
	187	}
	188
	189	__attribute__((visibility("hidden")))
	190	extern void channel_reset(struct channel *chan);
	191
	192	__attribute__((visibility("hidden")))
	193	extern void lib_ring_buffer_reset(struct lttng_ust_lib_ring_buffer *buf,
	194	struct lttng_ust_shm_handle *handle);
	195
	196	static inline
	197	unsigned long lib_ring_buffer_get_offset(const struct lttng_ust_lib_ring_buffer_config *config,
	198	struct lttng_ust_lib_ring_buffer *buf)
	199	{
	200	return v_read(config, &buf->offset);
	201	}
	202
	203	static inline
	204	unsigned long lib_ring_buffer_get_consumed(const struct lttng_ust_lib_ring_buffer_config *config,
	205	struct lttng_ust_lib_ring_buffer *buf)
	206	{
	207	return uatomic_read(&buf->consumed);
	208	}
	209
	210	/*
	211	* Must call lib_ring_buffer_is_finalized before reading counters (memory
	212	* ordering enforced with respect to trace teardown).
	213	*/
	214	static inline
	215	int lib_ring_buffer_is_finalized(const struct lttng_ust_lib_ring_buffer_config *config,
	216	struct lttng_ust_lib_ring_buffer *buf)
	217	{
	218	int finalized = CMM_ACCESS_ONCE(buf->finalized);
	219	/*
	220	* Read finalized before counters.
	221	*/
	222	cmm_smp_rmb();
	223	return finalized;
	224	}
	225
	226	static inline
	227	int lib_ring_buffer_channel_is_finalized(const struct channel *chan)
	228	{
	229	return chan->finalized;
	230	}
	231
	232	static inline
	233	int lib_ring_buffer_channel_is_disabled(const struct channel *chan)
	234	{
	235	return uatomic_read(&chan->record_disabled);
	236	}
	237
	238	static inline
	239	unsigned long lib_ring_buffer_get_read_data_size(
	240	const struct lttng_ust_lib_ring_buffer_config *config,
	241	struct lttng_ust_lib_ring_buffer *buf,
	242	struct lttng_ust_shm_handle *handle)
	243	{
	244	return subbuffer_get_read_data_size(config, &buf->backend, handle);
	245	}
	246
	247	static inline
	248	unsigned long lib_ring_buffer_get_records_count(
	249	const struct lttng_ust_lib_ring_buffer_config *config,
	250	struct lttng_ust_lib_ring_buffer *buf)
	251	{
	252	return v_read(config, &buf->records_count);
	253	}
	254
	255	static inline
	256	unsigned long lib_ring_buffer_get_records_overrun(
	257	const struct lttng_ust_lib_ring_buffer_config *config,
	258	struct lttng_ust_lib_ring_buffer *buf)
	259	{
	260	return v_read(config, &buf->records_overrun);
	261	}
	262
	263	static inline
	264	unsigned long lib_ring_buffer_get_records_lost_full(
	265	const struct lttng_ust_lib_ring_buffer_config *config,
	266	struct lttng_ust_lib_ring_buffer *buf)
	267	{
	268	return v_read(config, &buf->records_lost_full);
	269	}
	270
	271	static inline
	272	unsigned long lib_ring_buffer_get_records_lost_wrap(
	273	const struct lttng_ust_lib_ring_buffer_config *config,
	274	struct lttng_ust_lib_ring_buffer *buf)
	275	{
	276	return v_read(config, &buf->records_lost_wrap);
	277	}
	278
	279	static inline
	280	unsigned long lib_ring_buffer_get_records_lost_big(
	281	const struct lttng_ust_lib_ring_buffer_config *config,
	282	struct lttng_ust_lib_ring_buffer *buf)
	283	{
	284	return v_read(config, &buf->records_lost_big);
	285	}
	286
	287	static inline
	288	unsigned long lib_ring_buffer_get_records_read(
	289	const struct lttng_ust_lib_ring_buffer_config *config,
	290	struct lttng_ust_lib_ring_buffer *buf)
	291	{
	292	return v_read(config, &buf->backend.records_read);
	293	}
	294
	295	#endif /* _LTTNG_RING_BUFFER_FRONTEND_H */