1 #ifndef _LINUX_RING_BUFFER_FRONTEND_H
2 #define _LINUX_RING_BUFFER_FRONTEND_H
5 * linux/ringbuffer/frontend.h
7 * (C) Copyright 2005-2010 - Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
9 * Ring Buffer Library Synchronization Header (API).
12 * Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
14 * See ring_buffer_frontend.c for more information on wait-free algorithms.
16 * Dual LGPL v2.1/GPL v2 license.
19 #include <urcu/compiler.h>
20 #include <urcu/uatomic.h>
23 /* Internal helpers */
24 #include "frontend_internal.h"
26 /* Buffer creation/removal and setup operations */
29 * switch_timer_interval is the time interval (in us) to fill sub-buffers with
30 * padding to let readers get those sub-buffers. Used for live streaming.
32 * read_timer_interval is the time interval (in us) to wake up pending readers.
34 * buf_addr is a pointer the the beginning of the preallocated buffer contiguous
35 * address mapping. It is used only by RING_BUFFER_STATIC configuration. It can
36 * be set to NULL for other backends.
38 * priv_data (output) is set to a pointer into a "priv_data_len"-sized
39 * memory area for client-specific data. This memory is managed by lib
40 * ring buffer. priv_data_align is the alignment required for the
45 struct lttng_ust_shm_handle
*channel_create(const struct lttng_ust_lib_ring_buffer_config
*config
,
48 size_t priv_data_align
,
49 size_t priv_data_size
,
51 size_t subbuf_size
, size_t num_subbuf
,
52 unsigned int switch_timer_interval
,
53 unsigned int read_timer_interval
,
54 int *shm_fd
, int *wait_fd
,
55 uint64_t *memory_map_size
);
57 /* channel_handle_create - for consumer. */
59 struct lttng_ust_shm_handle
*channel_handle_create(int shm_fd
, int wait_fd
,
60 uint64_t memory_map_size
);
62 /* channel_handle_add_stream - for consumer. */
64 int channel_handle_add_stream(struct lttng_ust_shm_handle
*handle
,
65 int shm_fd
, int wait_fd
, uint64_t memory_map_size
);
68 * channel_destroy finalizes all channel's buffers, waits for readers to
69 * release all references, and destroys the channel.
72 void channel_destroy(struct channel
*chan
, struct lttng_ust_shm_handle
*handle
,
76 /* Buffer read operations */
79 * Iteration on channel cpumask needs to issue a read barrier to match the write
80 * barrier in cpu hotplug. It orders the cpumask read before read of per-cpu
81 * buffer data. The per-cpu buffer is never removed by cpu hotplug; teardown is
82 * only performed at channel destruction.
84 #define for_each_channel_cpu(cpu, chan) \
85 for_each_possible_cpu(cpu)
87 extern struct lttng_ust_lib_ring_buffer
*channel_get_ring_buffer(
88 const struct lttng_ust_lib_ring_buffer_config
*config
,
89 struct channel
*chan
, int cpu
,
90 struct lttng_ust_shm_handle
*handle
,
91 int *shm_fd
, int *wait_fd
,
92 uint64_t *memory_map_size
);
93 extern int lib_ring_buffer_open_read(struct lttng_ust_lib_ring_buffer
*buf
,
94 struct lttng_ust_shm_handle
*handle
,
96 extern void lib_ring_buffer_release_read(struct lttng_ust_lib_ring_buffer
*buf
,
97 struct lttng_ust_shm_handle
*handle
,
101 * Read sequence: snapshot, many get_subbuf/put_subbuf, move_consumer.
103 extern int lib_ring_buffer_snapshot(struct lttng_ust_lib_ring_buffer
*buf
,
104 unsigned long *consumed
,
105 unsigned long *produced
,
106 struct lttng_ust_shm_handle
*handle
);
107 extern void lib_ring_buffer_move_consumer(struct lttng_ust_lib_ring_buffer
*buf
,
108 unsigned long consumed_new
,
109 struct lttng_ust_shm_handle
*handle
);
111 extern int lib_ring_buffer_get_subbuf(struct lttng_ust_lib_ring_buffer
*buf
,
112 unsigned long consumed
,
113 struct lttng_ust_shm_handle
*handle
);
114 extern void lib_ring_buffer_put_subbuf(struct lttng_ust_lib_ring_buffer
*buf
,
115 struct lttng_ust_shm_handle
*handle
);
118 * lib_ring_buffer_get_next_subbuf/lib_ring_buffer_put_next_subbuf are helpers
119 * to read sub-buffers sequentially.
121 static inline int lib_ring_buffer_get_next_subbuf(struct lttng_ust_lib_ring_buffer
*buf
,
122 struct lttng_ust_shm_handle
*handle
)
126 ret
= lib_ring_buffer_snapshot(buf
, &buf
->cons_snapshot
,
127 &buf
->prod_snapshot
, handle
);
130 ret
= lib_ring_buffer_get_subbuf(buf
, buf
->cons_snapshot
, handle
);
135 void lib_ring_buffer_put_next_subbuf(struct lttng_ust_lib_ring_buffer
*buf
,
136 struct lttng_ust_shm_handle
*handle
)
138 lib_ring_buffer_put_subbuf(buf
, handle
);
139 lib_ring_buffer_move_consumer(buf
, subbuf_align(buf
->cons_snapshot
,
140 shmp(handle
, buf
->backend
.chan
)), handle
);
143 extern void channel_reset(struct channel
*chan
);
144 extern void lib_ring_buffer_reset(struct lttng_ust_lib_ring_buffer
*buf
,
145 struct lttng_ust_shm_handle
*handle
);
148 unsigned long lib_ring_buffer_get_offset(const struct lttng_ust_lib_ring_buffer_config
*config
,
149 struct lttng_ust_lib_ring_buffer
*buf
)
151 return v_read(config
, &buf
->offset
);
155 unsigned long lib_ring_buffer_get_consumed(const struct lttng_ust_lib_ring_buffer_config
*config
,
156 struct lttng_ust_lib_ring_buffer
*buf
)
158 return uatomic_read(&buf
->consumed
);
162 * Must call lib_ring_buffer_is_finalized before reading counters (memory
163 * ordering enforced with respect to trace teardown).
166 int lib_ring_buffer_is_finalized(const struct lttng_ust_lib_ring_buffer_config
*config
,
167 struct lttng_ust_lib_ring_buffer
*buf
)
169 int finalized
= CMM_ACCESS_ONCE(buf
->finalized
);
171 * Read finalized before counters.
178 int lib_ring_buffer_channel_is_finalized(const struct channel
*chan
)
180 return chan
->finalized
;
184 int lib_ring_buffer_channel_is_disabled(const struct channel
*chan
)
186 return uatomic_read(&chan
->record_disabled
);
190 unsigned long lib_ring_buffer_get_read_data_size(
191 const struct lttng_ust_lib_ring_buffer_config
*config
,
192 struct lttng_ust_lib_ring_buffer
*buf
,
193 struct lttng_ust_shm_handle
*handle
)
195 return subbuffer_get_read_data_size(config
, &buf
->backend
, handle
);
199 unsigned long lib_ring_buffer_get_records_count(
200 const struct lttng_ust_lib_ring_buffer_config
*config
,
201 struct lttng_ust_lib_ring_buffer
*buf
)
203 return v_read(config
, &buf
->records_count
);
207 unsigned long lib_ring_buffer_get_records_overrun(
208 const struct lttng_ust_lib_ring_buffer_config
*config
,
209 struct lttng_ust_lib_ring_buffer
*buf
)
211 return v_read(config
, &buf
->records_overrun
);
215 unsigned long lib_ring_buffer_get_records_lost_full(
216 const struct lttng_ust_lib_ring_buffer_config
*config
,
217 struct lttng_ust_lib_ring_buffer
*buf
)
219 return v_read(config
, &buf
->records_lost_full
);
223 unsigned long lib_ring_buffer_get_records_lost_wrap(
224 const struct lttng_ust_lib_ring_buffer_config
*config
,
225 struct lttng_ust_lib_ring_buffer
*buf
)
227 return v_read(config
, &buf
->records_lost_wrap
);
231 unsigned long lib_ring_buffer_get_records_lost_big(
232 const struct lttng_ust_lib_ring_buffer_config
*config
,
233 struct lttng_ust_lib_ring_buffer
*buf
)
235 return v_read(config
, &buf
->records_lost_big
);
239 unsigned long lib_ring_buffer_get_records_read(
240 const struct lttng_ust_lib_ring_buffer_config
*config
,
241 struct lttng_ust_lib_ring_buffer
*buf
)
243 return v_read(config
, &buf
->backend
.records_read
);
246 #endif /* _LINUX_RING_BUFFER_FRONTEND_H */