Rename struct lib_ring_buffer* to struct lttng_ust_lib_ring_buffer*
[lttng-ust.git] / include / ust / ringbuffer-config.h
CommitLineData
a6352fd4
MD
1#ifndef _LINUX_RING_BUFFER_CONFIG_H
2#define _LINUX_RING_BUFFER_CONFIG_H
3
4/*
5 * linux/ringbuffer/config.h
6 *
7 * Copyright (C) 2010 - Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
8 *
9 * Ring buffer configuration header. Note: after declaring the standard inline
10 * functions, clients should also include linux/ringbuffer/api.h.
11 *
12 * Dual LGPL v2.1/GPL v2 license.
13 */
14
15#include <errno.h>
8cb5d813
MD
16#include "ust/lttng-tracer.h"
17#include "ust/usterr-signal-safe.h"
a6352fd4
MD
18#include "ust/kcompat/kcompat.h"
19#include "ust/align.h"
20
4cfec15c 21struct lttng_ust_lib_ring_buffer;
a6352fd4 22struct channel;
4cfec15c
MD
23struct lttng_ust_lib_ring_buffer_config;
24struct lttng_ust_lib_ring_buffer_ctx;
38fae1d3 25struct lttng_ust_shm_handle *handle;
a6352fd4
MD
26
27/*
28 * Ring buffer client callbacks. Only used by slow path, never on fast path.
29 * For the fast path, record_header_size(), ring_buffer_clock_read() should be
30 * provided as inline functions too. These may simply return 0 if not used by
31 * the client.
32 */
4cfec15c 33struct lttng_ust_lib_ring_buffer_client_cb {
a6352fd4
MD
34 /* Mandatory callbacks */
35
36 /* A static inline version is also required for fast path */
37 u64 (*ring_buffer_clock_read) (struct channel *chan);
4cfec15c 38 size_t (*record_header_size) (const struct lttng_ust_lib_ring_buffer_config *config,
a6352fd4
MD
39 struct channel *chan, size_t offset,
40 size_t *pre_header_padding,
4cfec15c 41 struct lttng_ust_lib_ring_buffer_ctx *ctx);
a6352fd4
MD
42
43 /* Slow path only, at subbuffer switch */
44 size_t (*subbuffer_header_size) (void);
4cfec15c 45 void (*buffer_begin) (struct lttng_ust_lib_ring_buffer *buf, u64 tsc,
1d498196 46 unsigned int subbuf_idx,
38fae1d3 47 struct lttng_ust_shm_handle *handle);
4cfec15c 48 void (*buffer_end) (struct lttng_ust_lib_ring_buffer *buf, u64 tsc,
1d498196 49 unsigned int subbuf_idx, unsigned long data_size,
38fae1d3 50 struct lttng_ust_shm_handle *handle);
a6352fd4
MD
51
52 /* Optional callbacks (can be set to NULL) */
53
54 /* Called at buffer creation/finalize */
4cfec15c 55 int (*buffer_create) (struct lttng_ust_lib_ring_buffer *buf, void *priv,
1d498196 56 int cpu, const char *name,
38fae1d3 57 struct lttng_ust_shm_handle *handle);
a6352fd4
MD
58 /*
59 * Clients should guarantee that no new reader handle can be opened
60 * after finalize.
61 */
4cfec15c 62 void (*buffer_finalize) (struct lttng_ust_lib_ring_buffer *buf,
1d498196 63 void *priv, int cpu,
38fae1d3 64 struct lttng_ust_shm_handle *handle);
a6352fd4
MD
65
66 /*
67 * Extract header length, payload length and timestamp from event
68 * record. Used by buffer iterators. Timestamp is only used by channel
69 * iterator.
70 */
4cfec15c
MD
71 void (*record_get) (const struct lttng_ust_lib_ring_buffer_config *config,
72 struct channel *chan, struct lttng_ust_lib_ring_buffer *buf,
a6352fd4 73 size_t offset, size_t *header_len,
1d498196 74 size_t *payload_len, u64 *timestamp,
38fae1d3 75 struct lttng_ust_shm_handle *handle);
a6352fd4
MD
76};
77
78/*
79 * Ring buffer instance configuration.
80 *
81 * Declare as "static const" within the client object to ensure the inline fast
82 * paths can be optimized.
83 *
84 * alloc/sync pairs:
85 *
86 * RING_BUFFER_ALLOC_PER_CPU and RING_BUFFER_SYNC_PER_CPU :
87 * Per-cpu buffers with per-cpu synchronization. Tracing must be performed
88 * with preemption disabled (lib_ring_buffer_get_cpu() and
89 * lib_ring_buffer_put_cpu()).
90 *
91 * RING_BUFFER_ALLOC_PER_CPU and RING_BUFFER_SYNC_GLOBAL :
92 * Per-cpu buffer with global synchronization. Tracing can be performed with
93 * preemption enabled, statistically stays on the local buffers.
94 *
95 * RING_BUFFER_ALLOC_GLOBAL and RING_BUFFER_SYNC_PER_CPU :
96 * Should only be used for buffers belonging to a single thread or protected
97 * by mutual exclusion by the client. Note that periodical sub-buffer switch
98 * should be disabled in this kind of configuration.
99 *
100 * RING_BUFFER_ALLOC_GLOBAL and RING_BUFFER_SYNC_GLOBAL :
101 * Global shared buffer with global synchronization.
102 *
103 * wakeup:
104 *
105 * RING_BUFFER_WAKEUP_BY_TIMER uses per-cpu deferrable timers to poll the
106 * buffers and wake up readers if data is ready. Mainly useful for tracers which
107 * don't want to call into the wakeup code on the tracing path. Use in
108 * combination with "read_timer_interval" channel_create() argument.
109 *
110 * RING_BUFFER_WAKEUP_BY_WRITER directly wakes up readers when a subbuffer is
111 * ready to read. Lower latencies before the reader is woken up. Mainly suitable
112 * for drivers.
113 *
114 * RING_BUFFER_WAKEUP_NONE does not perform any wakeup whatsoever. The client
115 * has the responsibility to perform wakeups.
116 */
4cfec15c 117struct lttng_ust_lib_ring_buffer_config {
a6352fd4
MD
118 enum {
119 RING_BUFFER_ALLOC_PER_CPU,
120 RING_BUFFER_ALLOC_GLOBAL,
121 } alloc;
122 enum {
123 RING_BUFFER_SYNC_PER_CPU, /* Wait-free */
124 RING_BUFFER_SYNC_GLOBAL, /* Lock-free */
125 } sync;
126 enum {
127 RING_BUFFER_OVERWRITE, /* Overwrite when buffer full */
128 RING_BUFFER_DISCARD, /* Discard when buffer full */
129 } mode;
130 enum {
131 RING_BUFFER_SPLICE,
132 RING_BUFFER_MMAP,
133 RING_BUFFER_READ, /* TODO */
134 RING_BUFFER_ITERATOR,
135 RING_BUFFER_NONE,
136 } output;
137 enum {
138 RING_BUFFER_PAGE,
139 RING_BUFFER_VMAP, /* TODO */
140 RING_BUFFER_STATIC, /* TODO */
141 } backend;
142 enum {
143 RING_BUFFER_NO_OOPS_CONSISTENCY,
144 RING_BUFFER_OOPS_CONSISTENCY,
145 } oops;
146 enum {
147 RING_BUFFER_IPI_BARRIER,
148 RING_BUFFER_NO_IPI_BARRIER,
149 } ipi;
150 enum {
151 RING_BUFFER_WAKEUP_BY_TIMER, /* wake up performed by timer */
152 RING_BUFFER_WAKEUP_BY_WRITER, /*
153 * writer wakes up reader,
154 * not lock-free
155 * (takes spinlock).
156 */
157 } wakeup;
158 /*
159 * tsc_bits: timestamp bits saved at each record.
160 * 0 and 64 disable the timestamp compression scheme.
161 */
162 unsigned int tsc_bits;
4cfec15c 163 struct lttng_ust_lib_ring_buffer_client_cb cb;
a6352fd4
MD
164};
165
166/*
167 * ring buffer context
168 *
169 * Context passed to lib_ring_buffer_reserve(), lib_ring_buffer_commit(),
170 * lib_ring_buffer_try_discard_reserve(), lib_ring_buffer_align_ctx() and
171 * lib_ring_buffer_write().
172 */
4cfec15c 173struct lttng_ust_lib_ring_buffer_ctx {
a6352fd4
MD
174 /* input received by lib_ring_buffer_reserve(), saved here. */
175 struct channel *chan; /* channel */
176 void *priv; /* client private data */
38fae1d3 177 struct lttng_ust_shm_handle *handle; /* shared-memory handle */
a6352fd4
MD
178 size_t data_size; /* size of payload */
179 int largest_align; /*
180 * alignment of the largest element
181 * in the payload
182 */
183 int cpu; /* processor id */
184
185 /* output from lib_ring_buffer_reserve() */
4cfec15c 186 struct lttng_ust_lib_ring_buffer *buf; /*
a6352fd4
MD
187 * buffer corresponding to processor id
188 * for this channel
189 */
190 size_t slot_size; /* size of the reserved slot */
191 unsigned long buf_offset; /* offset following the record header */
192 unsigned long pre_offset; /*
193 * Initial offset position _before_
194 * the record is written. Positioned
195 * prior to record header alignment
196 * padding.
197 */
198 u64 tsc; /* time-stamp counter value */
199 unsigned int rflags; /* reservation flags */
200};
201
202/**
203 * lib_ring_buffer_ctx_init - initialize ring buffer context
204 * @ctx: ring buffer context to initialize
205 * @chan: channel
206 * @priv: client private data
207 * @data_size: size of record data payload
208 * @largest_align: largest alignment within data payload types
209 * @cpu: processor id
210 */
211static inline
4cfec15c 212void lib_ring_buffer_ctx_init(struct lttng_ust_lib_ring_buffer_ctx *ctx,
a6352fd4
MD
213 struct channel *chan, void *priv,
214 size_t data_size, int largest_align,
38fae1d3 215 int cpu, struct lttng_ust_shm_handle *handle)
a6352fd4
MD
216{
217 ctx->chan = chan;
218 ctx->priv = priv;
219 ctx->data_size = data_size;
220 ctx->largest_align = largest_align;
221 ctx->cpu = cpu;
222 ctx->rflags = 0;
1d498196 223 ctx->handle = handle;
a6352fd4
MD
224}
225
226/*
227 * Reservation flags.
228 *
229 * RING_BUFFER_RFLAG_FULL_TSC
230 *
231 * This flag is passed to record_header_size() and to the primitive used to
232 * write the record header. It indicates that the full 64-bit time value is
233 * needed in the record header. If this flag is not set, the record header needs
234 * only to contain "tsc_bits" bit of time value.
235 *
236 * Reservation flags can be added by the client, starting from
237 * "(RING_BUFFER_FLAGS_END << 0)". It can be used to pass information from
238 * record_header_size() to lib_ring_buffer_write_record_header().
239 */
240#define RING_BUFFER_RFLAG_FULL_TSC (1U << 0)
241#define RING_BUFFER_RFLAG_END (1U << 1)
242
243/*
244 * We need to define RING_BUFFER_ALIGN_ATTR so it is known early at
245 * compile-time. We have to duplicate the "config->align" information and the
246 * definition here because config->align is used both in the slow and fast
247 * paths, but RING_BUFFER_ALIGN_ATTR is only available for the client code.
248 */
249#ifdef RING_BUFFER_ALIGN
250
251# define RING_BUFFER_ALIGN_ATTR /* Default arch alignment */
252
253/*
254 * Calculate the offset needed to align the type.
255 * size_of_type must be non-zero.
256 */
257static inline
258unsigned int lib_ring_buffer_align(size_t align_drift, size_t size_of_type)
259{
260 return offset_align(align_drift, size_of_type);
261}
262
263#else
264
265# define RING_BUFFER_ALIGN_ATTR __attribute__((packed))
266
267/*
268 * Calculate the offset needed to align the type.
269 * size_of_type must be non-zero.
270 */
271static inline
272unsigned int lib_ring_buffer_align(size_t align_drift, size_t size_of_type)
273{
274 return 0;
275}
276
277#endif
278
279/**
280 * lib_ring_buffer_align_ctx - Align context offset on "alignment"
281 * @ctx: ring buffer context.
282 */
283static inline
4cfec15c 284void lib_ring_buffer_align_ctx(struct lttng_ust_lib_ring_buffer_ctx *ctx,
a6352fd4
MD
285 size_t alignment)
286{
287 ctx->buf_offset += lib_ring_buffer_align(ctx->buf_offset,
288 alignment);
289}
290
291/*
292 * lib_ring_buffer_check_config() returns 0 on success.
293 * Used internally to check for valid configurations at channel creation.
294 */
295static inline
4cfec15c 296int lib_ring_buffer_check_config(const struct lttng_ust_lib_ring_buffer_config *config,
a6352fd4
MD
297 unsigned int switch_timer_interval,
298 unsigned int read_timer_interval)
299{
300 if (config->alloc == RING_BUFFER_ALLOC_GLOBAL
301 && config->sync == RING_BUFFER_SYNC_PER_CPU
302 && switch_timer_interval)
303 return -EINVAL;
304 return 0;
305}
306
8d8a24c8 307#include <ust/vatomic.h>
a6352fd4
MD
308
309#endif /* _LINUX_RING_BUFFER_CONFIG_H */
This page took 0.035141 seconds and 4 git commands to generate.