#include <linux/kmemcheck.h>
#include <linux/mm.h>
#include <linux/seq_file.h>

Data Structures
struct	ring_buffer_event

Macros
#define	ring_buffer_alloc(size, flags)

#define	RING_BUFFER_ALL_CPUS -1

Enumerations
enum	ring_buffer_type { RINGBUF_TYPE_DATA_TYPE_LEN_MAX = 28, RINGBUF_TYPE_PADDING, RINGBUF_TYPE_TIME_EXTEND, RINGBUF_TYPE_TIME_STAMP }

enum	ring_buffer_flags { RB_FL_OVERWRITE = 1 << 0 }

Functions
unsigned	ring_buffer_event_length (struct ring_buffer_event *event)

void *	ring_buffer_event_data (struct ring_buffer_event *event)

void	ring_buffer_discard_commit (struct ring_buffer buffer, struct ring_buffer_event event)

struct ring_buffer *	__ring_buffer_alloc (unsigned long size, unsigned flags, struct lock_class_key *key)

void	ring_buffer_free (struct ring_buffer *buffer)

int	ring_buffer_resize (struct ring_buffer *buffer, unsigned long size, int cpu)

void	ring_buffer_change_overwrite (struct ring_buffer *buffer, int val)

struct ring_buffer_event *	ring_buffer_lock_reserve (struct ring_buffer *buffer, unsigned long length)

int	ring_buffer_unlock_commit (struct ring_buffer buffer, struct ring_buffer_event event)

int	ring_buffer_write (struct ring_buffer buffer, unsigned long length, void data)

struct ring_buffer_event *	ring_buffer_peek (struct ring_buffer buffer, int cpu, u64 ts, unsigned long *lost_events)

struct ring_buffer_event *	ring_buffer_consume (struct ring_buffer buffer, int cpu, u64 ts, unsigned long *lost_events)

struct ring_buffer_iter *	ring_buffer_read_prepare (struct ring_buffer *buffer, int cpu)

void	ring_buffer_read_prepare_sync (void)

void	ring_buffer_read_start (struct ring_buffer_iter *iter)

void	ring_buffer_read_finish (struct ring_buffer_iter *iter)

struct ring_buffer_event *	ring_buffer_iter_peek (struct ring_buffer_iter iter, u64 ts)

struct ring_buffer_event *	ring_buffer_read (struct ring_buffer_iter iter, u64 ts)

void	ring_buffer_iter_reset (struct ring_buffer_iter *iter)

int	ring_buffer_iter_empty (struct ring_buffer_iter *iter)

unsigned long	ring_buffer_size (struct ring_buffer *buffer, int cpu)

void	ring_buffer_reset_cpu (struct ring_buffer *buffer, int cpu)

void	ring_buffer_reset (struct ring_buffer *buffer)

int	ring_buffer_empty (struct ring_buffer *buffer)

int	ring_buffer_empty_cpu (struct ring_buffer *buffer, int cpu)

void	ring_buffer_record_disable (struct ring_buffer *buffer)

void	ring_buffer_record_enable (struct ring_buffer *buffer)

void	ring_buffer_record_off (struct ring_buffer *buffer)

void	ring_buffer_record_on (struct ring_buffer *buffer)

int	ring_buffer_record_is_on (struct ring_buffer *buffer)

void	ring_buffer_record_disable_cpu (struct ring_buffer *buffer, int cpu)

void	ring_buffer_record_enable_cpu (struct ring_buffer *buffer, int cpu)

unsigned long	ring_buffer_oldest_event_ts (struct ring_buffer *buffer, int cpu)

unsigned long	ring_buffer_bytes_cpu (struct ring_buffer *buffer, int cpu)

unsigned long	ring_buffer_entries (struct ring_buffer *buffer)

unsigned long	ring_buffer_overruns (struct ring_buffer *buffer)

unsigned long	ring_buffer_entries_cpu (struct ring_buffer *buffer, int cpu)

unsigned long	ring_buffer_overrun_cpu (struct ring_buffer *buffer, int cpu)

unsigned long	ring_buffer_commit_overrun_cpu (struct ring_buffer *buffer, int cpu)

u64	ring_buffer_time_stamp (struct ring_buffer *buffer, int cpu)

void	ring_buffer_normalize_time_stamp (struct ring_buffer buffer, int cpu, u64 ts)

void	ring_buffer_set_clock (struct ring_buffer buffer, u64(clock)(void))

size_t	ring_buffer_page_len (void *page)

void *	ring_buffer_alloc_read_page (struct ring_buffer *buffer, int cpu)

void	ring_buffer_free_read_page (struct ring_buffer buffer, void data)

int	ring_buffer_read_page (struct ring_buffer buffer, void *data_page, size_t len, int cpu, int full)

int	ring_buffer_print_entry_header (struct trace_seq *s)

int	ring_buffer_print_page_header (struct trace_seq *s)

Macro Definition Documentation

#define RING_BUFFER_ALL_CPUS -1

Definition at line 99 of file ring_buffer.h.

#define ring_buffer_alloc	(	size,
		flags
	)

Value:

({                          \
    static struct lock_class_key __key;     \
    __ring_buffer_alloc((size), (flags), &__key);   \
})

Definition at line 93 of file ring_buffer.h.

Enumeration Type Documentation

enum ring_buffer_flags

Enumerator:

RB_FL_OVERWRITE

Definition at line 189 of file ring_buffer.h.

enum ring_buffer_type

enum ring_buffer_type - internal ring buffer types

: Left over page padding or discarded event If time_delta is 0: array is ignored size is variable depending on how much padding is needed If time_delta is non zero: array[0] holds the actual length size = 4 + length (bytes)

: Extend the time delta array[0] = time delta (28 .. 59) size = 8 bytes

: Sync time stamp with external clock array[0] = tv_nsec array[1..2] = tv_sec size = 16 bytes

<= : Data record If type_len is zero: array[0] holds the actual length array[1..(length+3)/4] holds data size = 4 + length (bytes) else length = type_len << 2 array[0..(length+3)/4-1] holds data size = 4 + length (bytes)

Enumerator:

RINGBUF_TYPE_DATA_TYPE_LEN_MAX
RINGBUF_TYPE_PADDING
RINGBUF_TYPE_TIME_EXTEND
RINGBUF_TYPE_TIME_STAMP

Definition at line 54 of file ring_buffer.h.

Function Documentation

struct ring_buffer* __ring_buffer_alloc	(	unsigned long	size,
		unsigned	flags,
		struct lock_class_key *	key
	)

read

ring_buffer_alloc - allocate a new ring_buffer : the size in bytes per cpu that is needed. : attributes to set for the ring buffer.

Currently the only flag that is available is the RB_FL_OVERWRITE flag. This flag means that the buffer will overwrite old data when the buffer wraps. If this flag is not set, the buffer will drop data when the tail hits the head.

Definition at line 1136 of file ring_buffer.c.

void* ring_buffer_alloc_read_page	(	struct ring_buffer *	buffer,
		int	cpu
	)

ring_buffer_alloc_read_page - allocate a page to read from buffer : the buffer to allocate for.

This function is used in conjunction with ring_buffer_read_page. When reading a full page from the ring buffer, these functions can be used to speed up the process. The calling function should allocate a few pages first with this function. Then when it needs to get pages from the ring buffer, it passes the result of this function into ring_buffer_read_page, which will swap the page that was allocated, with the read page of the buffer.

Returns: The page allocated, or NULL on error.

Definition at line 4102 of file ring_buffer.c.

unsigned long ring_buffer_bytes_cpu	(	struct ring_buffer *	buffer,
		int	cpu
	)

ring_buffer_bytes_cpu - get the number of bytes consumed in a cpu buffer : The ring buffer : The per CPU buffer to read from.

Definition at line 2967 of file ring_buffer.c.

void ring_buffer_change_overwrite	(	struct ring_buffer *	buffer,
		int	val
	)

Definition at line 1653 of file ring_buffer.c.

unsigned long ring_buffer_commit_overrun_cpu	(	struct ring_buffer *	buffer,
		int	cpu
	)

ring_buffer_commit_overrun_cpu - get the number of overruns caused by commits : The ring buffer : The per CPU buffer to get the number of overruns from

Definition at line 3026 of file ring_buffer.c.

struct ring_buffer_event* ring_buffer_consume	(	struct ring_buffer *	buffer,
		int	cpu,
		u64 *	ts,
		unsigned long *	lost_events
	)

read

ring_buffer_consume - return an event and consume it : The ring buffer to get the next event from : the cpu to read the buffer from : a variable to store the timestamp (may be NULL) : a variable to store if events were lost (may be NULL)

Returns the next event in the ring buffer, and that event is consumed. Meaning, that sequential reads will keep returning a different event, and eventually empty the ring buffer if the producer is slower.

Definition at line 3645 of file ring_buffer.c.

void ring_buffer_discard_commit	(	struct ring_buffer *	buffer,
		struct ring_buffer_event *	event
	)

ring_buffer_commit_discard - discard an event that has not been committed : the ring buffer : non committed event to discard

Sometimes an event that is in the ring buffer needs to be ignored. This function lets the user discard an event in the ring buffer and then that event will not be read later.

This function only works if it is called before the the item has been committed. It will try to free the event from the ring buffer if another event has not been added behind it.

If another event has been added behind it, it will set the event up as discarded, and perform the commit.

If this function is called, do not call ring_buffer_unlock_commit on the event.

Definition at line 2673 of file ring_buffer.c.

int ring_buffer_empty ( struct ring_buffer * buffer )

rind_buffer_empty - is the ring buffer empty? : The ring buffer to test

Definition at line 3950 of file ring_buffer.c.

int ring_buffer_empty_cpu	(	struct ring_buffer *	buffer,
		int	cpu
	)

ring_buffer_empty_cpu - is a cpu buffer of a ring buffer empty? : The ring buffer : The CPU buffer to test

Definition at line 3984 of file ring_buffer.c.

unsigned long ring_buffer_entries ( struct ring_buffer * buffer )

ring_buffer_entries - get the number of entries in a buffer : The ring buffer

Returns the total number of entries in the ring buffer (all CPU entries)

Definition at line 3048 of file ring_buffer.c.

unsigned long ring_buffer_entries_cpu	(	struct ring_buffer *	buffer,
		int	cpu
	)

ring_buffer_entries_cpu - get the number of entries in a cpu buffer : The ring buffer : The per CPU buffer to get the entries from.

Definition at line 2987 of file ring_buffer.c.

void* ring_buffer_event_data ( struct ring_buffer_event * event )

ring_buffer_event_data - return the data of the event : the event to get the data from

Definition at line 315 of file ring_buffer.c.

unsigned ring_buffer_event_length ( struct ring_buffer_event * event )

ring_buffer_event_length - return the length of the event : the event to get the length of

Returns the size of the data load of a data event. If the event is something other than a data event, it returns the size of the event itself. With the exception of a TIME EXTEND, where it still returns the size of the data load of the data event after it.

Definition at line 280 of file ring_buffer.c.

void ring_buffer_free ( struct ring_buffer * buffer )

ring_buffer_free - free a ring buffer. : the buffer to free.

Definition at line 1220 of file ring_buffer.c.

void ring_buffer_free_read_page	(	struct ring_buffer *	buffer,
		void *	data
	)

ring_buffer_free_read_page - free an allocated read page : the buffer the page was allocate for : the page to free

Free a page allocated from ring_buffer_alloc_read_page.

Definition at line 4127 of file ring_buffer.c.

int ring_buffer_iter_empty ( struct ring_buffer_iter * iter )

ring_buffer_iter_empty - check if an iterator has no more to read : The iterator to check

Definition at line 3136 of file ring_buffer.c.

struct ring_buffer_event* ring_buffer_iter_peek	(	struct ring_buffer_iter *	iter,
		u64 *	ts
	)

read

ring_buffer_iter_peek - peek at the next event to be read : The ring buffer iterator : The timestamp counter of this event.

This will return the event that will be read next, but does not increment the iterator.

Definition at line 3616 of file ring_buffer.c.

void ring_buffer_iter_reset ( struct ring_buffer_iter * iter )

ring_buffer_iter_reset - reset an iterator : The iterator to reset

Resets the iterator, so that it will start from the beginning again.

Definition at line 3116 of file ring_buffer.c.

struct ring_buffer_event* ring_buffer_lock_reserve	(	struct ring_buffer *	buffer,
		unsigned long	length
	)

read

ring_buffer_lock_reserve - reserve a part of the buffer : the ring buffer to reserve from : the length of the data to reserve (excluding event header)

Returns a reseverd event on the ring buffer to copy directly to. The user of this interface will need to get the body to write into and can use the ring_buffer_event_data() interface.

The length is the length of the data needed, not the event length which also includes the event header.

Must be paired with ring_buffer_unlock_commit, unless NULL is returned. If NULL is returned, then nothing has been allocated or locked.

Definition at line 2492 of file ring_buffer.c.

void ring_buffer_normalize_time_stamp	(	struct ring_buffer *	buffer,
		int	cpu,
		u64 *	ts
	)

Definition at line 544 of file ring_buffer.c.

unsigned long ring_buffer_oldest_event_ts	(	struct ring_buffer *	buffer,
		int	cpu
	)

ring_buffer_oldest_event_ts - get the oldest event timestamp from the buffer : The ring buffer : The per CPU buffer to read from.

Definition at line 2934 of file ring_buffer.c.

unsigned long ring_buffer_overrun_cpu	(	struct ring_buffer *	buffer,
		int	cpu
	)

ring_buffer_overrun_cpu - get the number of overruns in a cpu_buffer : The ring buffer : The per CPU buffer to get the number of overruns from

Definition at line 3005 of file ring_buffer.c.

unsigned long ring_buffer_overruns ( struct ring_buffer * buffer )

ring_buffer_overruns - get the number of overruns in buffer : The ring buffer

Returns the total number of overruns in the ring buffer (all CPU entries)

Definition at line 3071 of file ring_buffer.c.

size_t ring_buffer_page_len ( void * page )

Definition at line 382 of file ring_buffer.c.

struct ring_buffer_event* ring_buffer_peek	(	struct ring_buffer *	buffer,
		int	cpu,
		u64 *	ts,
		unsigned long *	lost_events
	)

read

ring_buffer_peek - peek at the next event to be read : The ring buffer to read : The cpu to peak at : The timestamp counter of this event. : a variable to store if events were lost (may be NULL)

This will return the event that will be read next, but does not consume the data.

Definition at line 3578 of file ring_buffer.c.

int ring_buffer_print_entry_header ( struct trace_seq * s )

Definition at line 31 of file ring_buffer.c.

int ring_buffer_print_page_header ( struct trace_seq * s )

Definition at line 413 of file ring_buffer.c.

struct ring_buffer_event* ring_buffer_read	(	struct ring_buffer_iter *	iter,
		u64 *	ts
	)

read

ring_buffer_read - read the next item in the ring buffer by the iterator : The ring buffer iterator : The time stamp of the event read.

This reads the next event in the ring buffer and increments the iterator.

Definition at line 3812 of file ring_buffer.c.

void ring_buffer_read_finish ( struct ring_buffer_iter * iter )

ring_buffer_finish - finish reading the iterator of the buffer : The iterator retrieved by ring_buffer_start

This re-enables the recording to the buffer, and frees the iterator.

Definition at line 3783 of file ring_buffer.c.

int ring_buffer_read_page	(	struct ring_buffer *	buffer,
		void **	data_page,
		size_t	len,
		int	cpu,
		int	full
	)

ring_buffer_read_page - extract a page from the ring buffer : buffer to extract from : the page to use allocated from ring_buffer_alloc_read_page : amount to extract : the cpu of the buffer to extract : should the extraction only happen when the page is full.

This function will pull out a page from the ring buffer and consume it. must be the address of the variable that was returned from ring_buffer_alloc_read_page. This is because the page might be used to swap with a page in the ring buffer.

for example: rpage = ring_buffer_alloc_read_page(buffer); if (!rpage) return error; ret = ring_buffer_read_page(buffer, &rpage, len, cpu, 0); if (ret >= 0) process_page(rpage, ret);

When is set, the function will not return true unless the writer is off the reader page.

Note: it is up to the calling functions to handle sleeps and wakeups. The ring buffer can be used anywhere in the kernel and can not blindly call wake_up. The layer that uses the ring buffer must be responsible for that.

Returns: >=0 if data has been transferred, returns the offset of consumed data. <0 if no data has been transferred.

Definition at line 4166 of file ring_buffer.c.

struct ring_buffer_iter* ring_buffer_read_prepare	(	struct ring_buffer *	buffer,
		int	cpu
	)

read

ring_buffer_read_prepare - Prepare for a non consuming read of the buffer : The ring buffer to read from : The cpu buffer to iterate over

This performs the initial preparations necessary to iterate through the buffer. Memory is allocated, buffer recording is disabled, and the iterator pointer is returned to the caller.

Disabling buffer recordng prevents the reading from being corrupted. This is not a consuming read, so a producer is not expected.

After a sequence of ring_buffer_read_prepare calls, the user is expected to make at least one call to ring_buffer_prepare_sync. Afterwards, ring_buffer_read_start is invoked to get things going for real.

This overall must be paired with ring_buffer_finish.

Definition at line 3708 of file ring_buffer.c.

void ring_buffer_read_prepare_sync ( void )

ring_buffer_read_prepare_sync - Synchronize a set of prepare calls

All previously invoked ring_buffer_read_prepare calls to prepare iterators will be synchronized. Afterwards, read_buffer_read_start calls on those iterators are allowed.

Definition at line 3739 of file ring_buffer.c.

void ring_buffer_read_start ( struct ring_buffer_iter * iter )

ring_buffer_read_start - start a non consuming read of the buffer : The iterator returned by ring_buffer_read_prepare

This finalizes the startup of an iteration through the buffer. The iterator comes from a call to ring_buffer_read_prepare and an intervening ring_buffer_read_prepare_sync must have been performed.

Must be paired with ring_buffer_finish.

Definition at line 3757 of file ring_buffer.c.

void ring_buffer_record_disable ( struct ring_buffer * buffer )

ring_buffer_record_disable - stop all writes into the buffer : The ring buffer to stop writes to.

This prevents all writes to the buffer. Any attempt to write to the buffer after this will fail and return NULL.

The caller should call synchronize_sched() after this.

Definition at line 2798 of file ring_buffer.c.

void ring_buffer_record_disable_cpu	(	struct ring_buffer *	buffer,
		int	cpu
	)

ring_buffer_record_disable_cpu - stop all writes into the cpu_buffer : The ring buffer to stop writes to. : The CPU buffer to stop

This prevents all writes to the buffer. Any attempt to write to the buffer after this will fail and return NULL.

The caller should call synchronize_sched() after this.

Definition at line 2884 of file ring_buffer.c.

void ring_buffer_record_enable ( struct ring_buffer * buffer )

ring_buffer_record_enable - enable writes to the buffer : The ring buffer to enable writes

Note, multiple disables will need the same number of enables to truly enable the writing (much like preempt_disable).

Definition at line 2811 of file ring_buffer.c.

void ring_buffer_record_enable_cpu	(	struct ring_buffer *	buffer,
		int	cpu
	)

ring_buffer_record_enable_cpu - enable writes to the buffer : The ring buffer to enable writes : The CPU to enable.

Note, multiple disables will need the same number of enables to truly enable the writing (much like preempt_disable).

Definition at line 2904 of file ring_buffer.c.

int ring_buffer_record_is_on ( struct ring_buffer * buffer )

ring_buffer_record_is_on - return true if the ring buffer can write : The ring buffer to see if write is enabled

Returns true if the ring buffer is in a state that it accepts writes.

Definition at line 2869 of file ring_buffer.c.

void ring_buffer_record_off ( struct ring_buffer * buffer )

ring_buffer_record_off - stop all writes into the buffer : The ring buffer to stop writes to.

This prevents all writes to the buffer. Any attempt to write to the buffer after this will fail and return NULL.

This is different than ring_buffer_record_disable() as it works like an on/off switch, where as the disable() version must be paired with a enable().

Definition at line 2828 of file ring_buffer.c.

void ring_buffer_record_on ( struct ring_buffer * buffer )

ring_buffer_record_on - restart writes into the buffer : The ring buffer to start writes to.

This enables all writes to the buffer that was disabled by ring_buffer_record_off().

This is different than ring_buffer_record_enable() as it works like an on/off switch, where as the enable() version must be paired with a disable().

Definition at line 2851 of file ring_buffer.c.

void ring_buffer_reset ( struct ring_buffer * buffer )

ring_buffer_reset - reset a ring buffer : The ring buffer to reset all cpu buffers

Definition at line 3937 of file ring_buffer.c.

void ring_buffer_reset_cpu	(	struct ring_buffer *	buffer,
		int	cpu
	)

ring_buffer_reset_cpu - reset a ring buffer per CPU buffer : The ring buffer to reset a per cpu buffer of : The CPU buffer to be reset

Definition at line 3900 of file ring_buffer.c.

int ring_buffer_resize	(	struct ring_buffer *	buffer,
		unsigned long	size,
		int	cpu_id
	)

ring_buffer_resize - resize the ring buffer : the buffer to resize. : the new size.

Minimum size is 2 * BUF_PAGE_SIZE.

Returns 0 on success and < 0 on failure.

Definition at line 1478 of file ring_buffer.c.

void ring_buffer_set_clock	(	struct ring_buffer *	buffer,
		u64(*)(void)	clock
	)

Definition at line 1242 of file ring_buffer.c.

unsigned long ring_buffer_size	(	struct ring_buffer *	buffer,
		int	cpu
	)

ring_buffer_size - return the size of the ring buffer (in bytes) : The ring buffer.

Definition at line 3839 of file ring_buffer.c.

u64 ring_buffer_time_stamp	(	struct ring_buffer *	buffer,
		int	cpu
	)

Definition at line 532 of file ring_buffer.c.

int ring_buffer_unlock_commit	(	struct ring_buffer *	buffer,
		struct ring_buffer_event *	event
	)

ring_buffer_unlock_commit - commit a reserved : The buffer to commit to : The event pointer to commit.

This commits the data to the ring buffer, and releases any locks held.

Must be paired with ring_buffer_lock_reserve.

Definition at line 2583 of file ring_buffer.c.

int ring_buffer_write	(	struct ring_buffer *	buffer,
		unsigned long	length,
		void *	data
	)

ring_buffer_write - write data to the buffer without reserving : The ring buffer to write to. : The length of the data being written (excluding the event header) : The data to write to the buffer.

This is like ring_buffer_lock_reserve and ring_buffer_unlock_commit as one function. If you already have the data to write to the buffer, it may be easier to simply call this function.

Note, like ring_buffer_lock_reserve, the length is the length of the data and not the length of the event which would hold the header.

Definition at line 2724 of file ring_buffer.c.

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation