xref: /linux/include/linux/ring_buffer.h (revision 1744a21d57d9c60136461adb6afa85e51b3e94d9)
17a8e76a3SSteven Rostedt #ifndef _LINUX_RING_BUFFER_H
27a8e76a3SSteven Rostedt #define _LINUX_RING_BUFFER_H
37a8e76a3SSteven Rostedt 
4*1744a21dSVegard Nossum #include <linux/kmemcheck.h>
57a8e76a3SSteven Rostedt #include <linux/mm.h>
67a8e76a3SSteven Rostedt #include <linux/seq_file.h>
77a8e76a3SSteven Rostedt 
87a8e76a3SSteven Rostedt struct ring_buffer;
97a8e76a3SSteven Rostedt struct ring_buffer_iter;
107a8e76a3SSteven Rostedt 
117a8e76a3SSteven Rostedt /*
12c3706f00SWenji Huang  * Don't refer to this struct directly, use functions below.
137a8e76a3SSteven Rostedt  */
147a8e76a3SSteven Rostedt struct ring_buffer_event {
15*1744a21dSVegard Nossum 	kmemcheck_bitfield_begin(bitfield);
16334d4169SLai Jiangshan 	u32		type_len:5, time_delta:27;
17*1744a21dSVegard Nossum 	kmemcheck_bitfield_end(bitfield);
18*1744a21dSVegard Nossum 
197a8e76a3SSteven Rostedt 	u32		array[];
207a8e76a3SSteven Rostedt };
217a8e76a3SSteven Rostedt 
227a8e76a3SSteven Rostedt /**
237a8e76a3SSteven Rostedt  * enum ring_buffer_type - internal ring buffer types
247a8e76a3SSteven Rostedt  *
252d622719STom Zanussi  * @RINGBUF_TYPE_PADDING:	Left over page padding or discarded event
262d622719STom Zanussi  *				 If time_delta is 0:
277a8e76a3SSteven Rostedt  *				  array is ignored
287a8e76a3SSteven Rostedt  *				  size is variable depending on how much
297a8e76a3SSteven Rostedt  *				  padding is needed
302d622719STom Zanussi  *				 If time_delta is non zero:
31334d4169SLai Jiangshan  *				  array[0] holds the actual length
32334d4169SLai Jiangshan  *				  size = 4 + length (bytes)
337a8e76a3SSteven Rostedt  *
347a8e76a3SSteven Rostedt  * @RINGBUF_TYPE_TIME_EXTEND:	Extend the time delta
357a8e76a3SSteven Rostedt  *				 array[0] = time delta (28 .. 59)
367a8e76a3SSteven Rostedt  *				 size = 8 bytes
377a8e76a3SSteven Rostedt  *
387a8e76a3SSteven Rostedt  * @RINGBUF_TYPE_TIME_STAMP:	Sync time stamp with external clock
397a8e76a3SSteven Rostedt  *				 array[0]    = tv_nsec
40361b73d5SLai Jiangshan  *				 array[1..2] = tv_sec
417a8e76a3SSteven Rostedt  *				 size = 16 bytes
427a8e76a3SSteven Rostedt  *
43334d4169SLai Jiangshan  * <= @RINGBUF_TYPE_DATA_TYPE_LEN_MAX:
44334d4169SLai Jiangshan  *				Data record
45334d4169SLai Jiangshan  *				 If type_len is zero:
467a8e76a3SSteven Rostedt  *				  array[0] holds the actual length
47361b73d5SLai Jiangshan  *				  array[1..(length+3)/4] holds data
48334d4169SLai Jiangshan  *				  size = 4 + length (bytes)
497a8e76a3SSteven Rostedt  *				 else
50334d4169SLai Jiangshan  *				  length = type_len << 2
51361b73d5SLai Jiangshan  *				  array[0..(length+3)/4-1] holds data
52361b73d5SLai Jiangshan  *				  size = 4 + length (bytes)
537a8e76a3SSteven Rostedt  */
547a8e76a3SSteven Rostedt enum ring_buffer_type {
55334d4169SLai Jiangshan 	RINGBUF_TYPE_DATA_TYPE_LEN_MAX = 28,
567a8e76a3SSteven Rostedt 	RINGBUF_TYPE_PADDING,
577a8e76a3SSteven Rostedt 	RINGBUF_TYPE_TIME_EXTEND,
587a8e76a3SSteven Rostedt 	/* FIXME: RINGBUF_TYPE_TIME_STAMP not implemented */
597a8e76a3SSteven Rostedt 	RINGBUF_TYPE_TIME_STAMP,
607a8e76a3SSteven Rostedt };
617a8e76a3SSteven Rostedt 
627a8e76a3SSteven Rostedt unsigned ring_buffer_event_length(struct ring_buffer_event *event);
637a8e76a3SSteven Rostedt void *ring_buffer_event_data(struct ring_buffer_event *event);
647a8e76a3SSteven Rostedt 
657a8e76a3SSteven Rostedt /**
667a8e76a3SSteven Rostedt  * ring_buffer_event_time_delta - return the delta timestamp of the event
677a8e76a3SSteven Rostedt  * @event: the event to get the delta timestamp of
687a8e76a3SSteven Rostedt  *
697a8e76a3SSteven Rostedt  * The delta timestamp is the 27 bit timestamp since the last event.
707a8e76a3SSteven Rostedt  */
717a8e76a3SSteven Rostedt static inline unsigned
727a8e76a3SSteven Rostedt ring_buffer_event_time_delta(struct ring_buffer_event *event)
737a8e76a3SSteven Rostedt {
747a8e76a3SSteven Rostedt 	return event->time_delta;
757a8e76a3SSteven Rostedt }
767a8e76a3SSteven Rostedt 
77fa1b47ddSSteven Rostedt /*
78fa1b47ddSSteven Rostedt  * ring_buffer_event_discard can discard any event in the ring buffer.
79fa1b47ddSSteven Rostedt  *   it is up to the caller to protect against a reader from
80fa1b47ddSSteven Rostedt  *   consuming it or a writer from wrapping and replacing it.
81fa1b47ddSSteven Rostedt  *
82fa1b47ddSSteven Rostedt  * No external protection is needed if this is called before
83fa1b47ddSSteven Rostedt  * the event is commited. But in that case it would be better to
84fa1b47ddSSteven Rostedt  * use ring_buffer_discard_commit.
85fa1b47ddSSteven Rostedt  *
86fa1b47ddSSteven Rostedt  * Note, if an event that has not been committed is discarded
87fa1b47ddSSteven Rostedt  * with ring_buffer_event_discard, it must still be committed.
88fa1b47ddSSteven Rostedt  */
892d622719STom Zanussi void ring_buffer_event_discard(struct ring_buffer_event *event);
902d622719STom Zanussi 
917a8e76a3SSteven Rostedt /*
92fa1b47ddSSteven Rostedt  * ring_buffer_discard_commit will remove an event that has not
93fa1b47ddSSteven Rostedt  *   ben committed yet. If this is used, then ring_buffer_unlock_commit
94fa1b47ddSSteven Rostedt  *   must not be called on the discarded event. This function
95fa1b47ddSSteven Rostedt  *   will try to remove the event from the ring buffer completely
96fa1b47ddSSteven Rostedt  *   if another event has not been written after it.
97fa1b47ddSSteven Rostedt  *
98fa1b47ddSSteven Rostedt  * Example use:
99fa1b47ddSSteven Rostedt  *
100fa1b47ddSSteven Rostedt  *  if (some_condition)
101fa1b47ddSSteven Rostedt  *    ring_buffer_discard_commit(buffer, event);
102fa1b47ddSSteven Rostedt  *  else
103fa1b47ddSSteven Rostedt  *    ring_buffer_unlock_commit(buffer, event);
104fa1b47ddSSteven Rostedt  */
105fa1b47ddSSteven Rostedt void ring_buffer_discard_commit(struct ring_buffer *buffer,
106fa1b47ddSSteven Rostedt 				struct ring_buffer_event *event);
107fa1b47ddSSteven Rostedt 
108fa1b47ddSSteven Rostedt /*
1097a8e76a3SSteven Rostedt  * size is in bytes for each per CPU buffer.
1107a8e76a3SSteven Rostedt  */
1117a8e76a3SSteven Rostedt struct ring_buffer *
1121f8a6a10SPeter Zijlstra __ring_buffer_alloc(unsigned long size, unsigned flags, struct lock_class_key *key);
1131f8a6a10SPeter Zijlstra 
1141f8a6a10SPeter Zijlstra /*
1151f8a6a10SPeter Zijlstra  * Because the ring buffer is generic, if other users of the ring buffer get
1161f8a6a10SPeter Zijlstra  * traced by ftrace, it can produce lockdep warnings. We need to keep each
1171f8a6a10SPeter Zijlstra  * ring buffer's lock class separate.
1181f8a6a10SPeter Zijlstra  */
1191f8a6a10SPeter Zijlstra #define ring_buffer_alloc(size, flags)			\
1201f8a6a10SPeter Zijlstra ({							\
1211f8a6a10SPeter Zijlstra 	static struct lock_class_key __key;		\
1221f8a6a10SPeter Zijlstra 	__ring_buffer_alloc((size), (flags), &__key);	\
1231f8a6a10SPeter Zijlstra })
1241f8a6a10SPeter Zijlstra 
1257a8e76a3SSteven Rostedt void ring_buffer_free(struct ring_buffer *buffer);
1267a8e76a3SSteven Rostedt 
1277a8e76a3SSteven Rostedt int ring_buffer_resize(struct ring_buffer *buffer, unsigned long size);
1287a8e76a3SSteven Rostedt 
1290a987751SArnaldo Carvalho de Melo struct ring_buffer_event *ring_buffer_lock_reserve(struct ring_buffer *buffer,
1300a987751SArnaldo Carvalho de Melo 						   unsigned long length);
1317a8e76a3SSteven Rostedt int ring_buffer_unlock_commit(struct ring_buffer *buffer,
1320a987751SArnaldo Carvalho de Melo 			      struct ring_buffer_event *event);
1337a8e76a3SSteven Rostedt int ring_buffer_write(struct ring_buffer *buffer,
1347a8e76a3SSteven Rostedt 		      unsigned long length, void *data);
1357a8e76a3SSteven Rostedt 
1367a8e76a3SSteven Rostedt struct ring_buffer_event *
1377a8e76a3SSteven Rostedt ring_buffer_peek(struct ring_buffer *buffer, int cpu, u64 *ts);
1387a8e76a3SSteven Rostedt struct ring_buffer_event *
1397a8e76a3SSteven Rostedt ring_buffer_consume(struct ring_buffer *buffer, int cpu, u64 *ts);
1407a8e76a3SSteven Rostedt 
1417a8e76a3SSteven Rostedt struct ring_buffer_iter *
1427a8e76a3SSteven Rostedt ring_buffer_read_start(struct ring_buffer *buffer, int cpu);
1437a8e76a3SSteven Rostedt void ring_buffer_read_finish(struct ring_buffer_iter *iter);
1447a8e76a3SSteven Rostedt 
1457a8e76a3SSteven Rostedt struct ring_buffer_event *
1467a8e76a3SSteven Rostedt ring_buffer_iter_peek(struct ring_buffer_iter *iter, u64 *ts);
1477a8e76a3SSteven Rostedt struct ring_buffer_event *
1487a8e76a3SSteven Rostedt ring_buffer_read(struct ring_buffer_iter *iter, u64 *ts);
1497a8e76a3SSteven Rostedt void ring_buffer_iter_reset(struct ring_buffer_iter *iter);
1507a8e76a3SSteven Rostedt int ring_buffer_iter_empty(struct ring_buffer_iter *iter);
1517a8e76a3SSteven Rostedt 
1527a8e76a3SSteven Rostedt unsigned long ring_buffer_size(struct ring_buffer *buffer);
1537a8e76a3SSteven Rostedt 
1547a8e76a3SSteven Rostedt void ring_buffer_reset_cpu(struct ring_buffer *buffer, int cpu);
1557a8e76a3SSteven Rostedt void ring_buffer_reset(struct ring_buffer *buffer);
1567a8e76a3SSteven Rostedt 
1577a8e76a3SSteven Rostedt int ring_buffer_swap_cpu(struct ring_buffer *buffer_a,
1587a8e76a3SSteven Rostedt 			 struct ring_buffer *buffer_b, int cpu);
1597a8e76a3SSteven Rostedt 
1607a8e76a3SSteven Rostedt int ring_buffer_empty(struct ring_buffer *buffer);
1617a8e76a3SSteven Rostedt int ring_buffer_empty_cpu(struct ring_buffer *buffer, int cpu);
1627a8e76a3SSteven Rostedt 
1637a8e76a3SSteven Rostedt void ring_buffer_record_disable(struct ring_buffer *buffer);
1647a8e76a3SSteven Rostedt void ring_buffer_record_enable(struct ring_buffer *buffer);
1657a8e76a3SSteven Rostedt void ring_buffer_record_disable_cpu(struct ring_buffer *buffer, int cpu);
1667a8e76a3SSteven Rostedt void ring_buffer_record_enable_cpu(struct ring_buffer *buffer, int cpu);
1677a8e76a3SSteven Rostedt 
1687a8e76a3SSteven Rostedt unsigned long ring_buffer_entries(struct ring_buffer *buffer);
1697a8e76a3SSteven Rostedt unsigned long ring_buffer_overruns(struct ring_buffer *buffer);
170e09373f2SRobert Richter unsigned long ring_buffer_entries_cpu(struct ring_buffer *buffer, int cpu);
171e09373f2SRobert Richter unsigned long ring_buffer_overrun_cpu(struct ring_buffer *buffer, int cpu);
172f0d2c681SSteven Rostedt unsigned long ring_buffer_commit_overrun_cpu(struct ring_buffer *buffer, int cpu);
173f0d2c681SSteven Rostedt unsigned long ring_buffer_nmi_dropped_cpu(struct ring_buffer *buffer, int cpu);
1747a8e76a3SSteven Rostedt 
17537886f6aSSteven Rostedt u64 ring_buffer_time_stamp(struct ring_buffer *buffer, int cpu);
17637886f6aSSteven Rostedt void ring_buffer_normalize_time_stamp(struct ring_buffer *buffer,
17737886f6aSSteven Rostedt 				      int cpu, u64 *ts);
17837886f6aSSteven Rostedt void ring_buffer_set_clock(struct ring_buffer *buffer,
17937886f6aSSteven Rostedt 			   u64 (*clock)(void));
1807a8e76a3SSteven Rostedt 
181ef7a4a16SSteven Rostedt size_t ring_buffer_page_len(void *page);
182ef7a4a16SSteven Rostedt 
183ef7a4a16SSteven Rostedt 
1848789a9e7SSteven Rostedt void *ring_buffer_alloc_read_page(struct ring_buffer *buffer);
1858789a9e7SSteven Rostedt void ring_buffer_free_read_page(struct ring_buffer *buffer, void *data);
186ef7a4a16SSteven Rostedt int ring_buffer_read_page(struct ring_buffer *buffer, void **data_page,
187ef7a4a16SSteven Rostedt 			  size_t len, int cpu, int full);
1888789a9e7SSteven Rostedt 
189d1b182a8SSteven Rostedt struct trace_seq;
190d1b182a8SSteven Rostedt 
191d1b182a8SSteven Rostedt int ring_buffer_print_entry_header(struct trace_seq *s);
192d1b182a8SSteven Rostedt int ring_buffer_print_page_header(struct trace_seq *s);
193d1b182a8SSteven Rostedt 
1947a8e76a3SSteven Rostedt enum ring_buffer_flags {
1957a8e76a3SSteven Rostedt 	RB_FL_OVERWRITE		= 1 << 0,
1967a8e76a3SSteven Rostedt };
1977a8e76a3SSteven Rostedt 
1987a8e76a3SSteven Rostedt #endif /* _LINUX_RING_BUFFER_H */
199