1 /* SPDX-License-Identifier: (GPL-2.0 OR LGPL-2.1)
3 * lib/ringbuffer/frontend.h
5 * Ring Buffer Library Synchronization Header (API).
7 * Copyright (C) 2005-2012 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
9 * See ring_buffer_frontend.c for more information on wait-free algorithms.
12 #ifndef _LIB_RING_BUFFER_FRONTEND_H
13 #define _LIB_RING_BUFFER_FRONTEND_H
15 #include <linux/pipe_fs_i.h>
16 #include <linux/rcupdate.h>
17 #include <linux/cpumask.h>
18 #include <linux/module.h>
19 #include <linux/bitops.h>
20 #include <linux/splice.h>
21 #include <linux/string.h>
22 #include <linux/timer.h>
23 #include <linux/sched.h>
24 #include <linux/cache.h>
25 #include <linux/time.h>
26 #include <linux/slab.h>
27 #include <linux/init.h>
28 #include <linux/stat.h>
29 #include <linux/cpu.h>
32 #include <asm/atomic.h>
33 #include <asm/local.h>
35 /* Internal helpers */
36 #include <wrapper/ringbuffer/frontend_internal.h>
38 /* Max ring buffer nesting count, see lib_ring_buffer_get_cpu(). */
39 #define RING_BUFFER_MAX_NESTING 4
41 /* Buffer creation/removal and setup operations */
44 * switch_timer_interval is the time interval (in us) to fill sub-buffers with
45 * padding to let readers get those sub-buffers. Used for live streaming.
47 * read_timer_interval is the time interval (in us) to wake up pending readers.
49 * buf_addr is a pointer the the beginning of the preallocated buffer contiguous
50 * address mapping. It is used only by RING_BUFFER_STATIC configuration. It can
51 * be set to NULL for other backends.
55 struct channel
*channel_create(const struct lib_ring_buffer_config
*config
,
56 const char *name
, void *priv
,
58 size_t subbuf_size
, size_t num_subbuf
,
59 unsigned int switch_timer_interval
,
60 unsigned int read_timer_interval
);
63 * channel_destroy returns the private data pointer. It finalizes all channel's
64 * buffers, waits for readers to release all references, and destroys the
68 void *channel_destroy(struct channel
*chan
);
71 /* Buffer read operations */
74 * Iteration on channel cpumask needs to issue a read barrier to match the write
75 * barrier in cpu hotplug. It orders the cpumask read before read of per-cpu
76 * buffer data. The per-cpu buffer is never removed by cpu hotplug; teardown is
77 * only performed at channel destruction.
79 #define for_each_channel_cpu(cpu, chan) \
81 ({ (cpu) = cpumask_next(cpu, (chan)->backend.cpumask); \
82 smp_read_barrier_depends(); (cpu) < nr_cpu_ids; });)
84 extern struct lib_ring_buffer
*channel_get_ring_buffer(
85 const struct lib_ring_buffer_config
*config
,
86 struct channel
*chan
, int cpu
);
87 extern int lib_ring_buffer_open_read(struct lib_ring_buffer
*buf
);
88 extern void lib_ring_buffer_release_read(struct lib_ring_buffer
*buf
);
91 * Read sequence: snapshot, many get_subbuf/put_subbuf, move_consumer.
93 extern int lib_ring_buffer_snapshot(struct lib_ring_buffer
*buf
,
94 unsigned long *consumed
,
95 unsigned long *produced
);
96 extern int lib_ring_buffer_snapshot_sample_positions(
97 struct lib_ring_buffer
*buf
,
98 unsigned long *consumed
,
99 unsigned long *produced
);
100 extern void lib_ring_buffer_move_consumer(struct lib_ring_buffer
*buf
,
101 unsigned long consumed_new
);
103 extern int lib_ring_buffer_get_subbuf(struct lib_ring_buffer
*buf
,
104 unsigned long consumed
);
105 extern void lib_ring_buffer_put_subbuf(struct lib_ring_buffer
*buf
);
107 void lib_ring_buffer_set_quiescent_channel(struct channel
*chan
);
108 void lib_ring_buffer_clear_quiescent_channel(struct channel
*chan
);
111 * lib_ring_buffer_get_next_subbuf/lib_ring_buffer_put_next_subbuf are helpers
112 * to read sub-buffers sequentially.
114 static inline int lib_ring_buffer_get_next_subbuf(struct lib_ring_buffer
*buf
)
118 ret
= lib_ring_buffer_snapshot(buf
, &buf
->cons_snapshot
,
119 &buf
->prod_snapshot
);
122 ret
= lib_ring_buffer_get_subbuf(buf
, buf
->cons_snapshot
);
126 static inline void lib_ring_buffer_put_next_subbuf(struct lib_ring_buffer
*buf
)
128 lib_ring_buffer_put_subbuf(buf
);
129 lib_ring_buffer_move_consumer(buf
, subbuf_align(buf
->cons_snapshot
,
133 extern void channel_reset(struct channel
*chan
);
134 extern void lib_ring_buffer_reset(struct lib_ring_buffer
*buf
);
137 unsigned long lib_ring_buffer_get_offset(const struct lib_ring_buffer_config
*config
,
138 struct lib_ring_buffer
*buf
)
140 return v_read(config
, &buf
->offset
);
144 unsigned long lib_ring_buffer_get_consumed(const struct lib_ring_buffer_config
*config
,
145 struct lib_ring_buffer
*buf
)
147 return atomic_long_read(&buf
->consumed
);
151 * Must call lib_ring_buffer_is_finalized before reading counters (memory
152 * ordering enforced with respect to trace teardown).
155 int lib_ring_buffer_is_finalized(const struct lib_ring_buffer_config
*config
,
156 struct lib_ring_buffer
*buf
)
158 int finalized
= READ_ONCE(buf
->finalized
);
160 * Read finalized before counters.
167 int lib_ring_buffer_channel_is_finalized(const struct channel
*chan
)
169 return chan
->finalized
;
173 int lib_ring_buffer_channel_is_disabled(const struct channel
*chan
)
175 return atomic_read(&chan
->record_disabled
);
179 unsigned long lib_ring_buffer_get_read_data_size(
180 const struct lib_ring_buffer_config
*config
,
181 struct lib_ring_buffer
*buf
)
183 return subbuffer_get_read_data_size(config
, &buf
->backend
);
187 unsigned long lib_ring_buffer_get_records_count(
188 const struct lib_ring_buffer_config
*config
,
189 struct lib_ring_buffer
*buf
)
191 return v_read(config
, &buf
->records_count
);
195 unsigned long lib_ring_buffer_get_records_overrun(
196 const struct lib_ring_buffer_config
*config
,
197 struct lib_ring_buffer
*buf
)
199 return v_read(config
, &buf
->records_overrun
);
203 unsigned long lib_ring_buffer_get_records_lost_full(
204 const struct lib_ring_buffer_config
*config
,
205 struct lib_ring_buffer
*buf
)
207 return v_read(config
, &buf
->records_lost_full
);
211 unsigned long lib_ring_buffer_get_records_lost_wrap(
212 const struct lib_ring_buffer_config
*config
,
213 struct lib_ring_buffer
*buf
)
215 return v_read(config
, &buf
->records_lost_wrap
);
219 unsigned long lib_ring_buffer_get_records_lost_big(
220 const struct lib_ring_buffer_config
*config
,
221 struct lib_ring_buffer
*buf
)
223 return v_read(config
, &buf
->records_lost_big
);
227 unsigned long lib_ring_buffer_get_records_read(
228 const struct lib_ring_buffer_config
*config
,
229 struct lib_ring_buffer
*buf
)
231 return v_read(config
, &buf
->backend
.records_read
);
234 #endif /* _LIB_RING_BUFFER_FRONTEND_H */
This page took 0.03611 seconds and 6 git commands to generate.