#include <l4/shmc/shmc.h>
#include <l4/util/assert.h>
#include <l4/sys/thread.h>

Include dependency graph for ringbuf.h:

Data Structures
struct	l4shmc_ringbuf_head_t
	Head field of a ring buffer. More...

struct	l4shmc_ringbuf_t
	Ring buffer. More...

Macros
#define	L4SHMC_RINGBUF_HEAD(ringbuf) ((l4shmc_ringbuf_head_t*)((ringbuf)->_addr))
	Get ring buffer head pointer.

#define	L4SHMC_RINGBUF_DATA(ringbuf) (L4SHMC_RINGBUF_HEAD(ringbuf)->data)
	Get ring buffer data pointer.

#define	L4SHMC_RINGBUF_DATA_SIZE(ringbuf) ((ringbuf)->_size - sizeof(l4shmc_ringbuf_head_t))
	Get size of data area.

Functions
int	l4shmc_rb_init_buffer (l4shmc_ringbuf_t buf, l4shmc_area_t area, char const chunk_name, char const signal_name, unsigned size)
	Initialize a ring buffer by creating an SHMC chunk and the corresponding signals.

void	l4shmc_rb_deinit_buffer (l4shmc_ringbuf_t *buf)
	De-init a ring buffer.

int	l4shmc_rb_attach_sender (l4shmc_ringbuf_t buf, char const signal_name, l4_cap_idx_t owner)
	Attach to sender signal of a ring buffer.

char *	l4shmc_rb_sender_alloc_packet (l4shmc_ringbuf_head_t *head, unsigned psize)
	Allocate a packet of a given size within the ring buffer.

void	l4shmc_rb_sender_put_data (l4shmc_ringbuf_t buf, char addr, char *data, unsigned dsize)
	Copy data into a previously allocated packet.

int	l4shmc_rb_sender_next_copy_in (l4shmc_ringbuf_t buf, char data, unsigned size, int block_if_necessary)
	Copy in packet from an external data source.

void	l4shmc_rb_sender_commit_packet (l4shmc_ringbuf_t *buf)
	Tell the consumer that new data is available.

int	l4shmc_rb_init_receiver (l4shmc_ringbuf_t buf, l4shmc_area_t area, char const chunk_name, char const signal_name)
	Initialize receive buffer.

void	l4shmc_rb_attach_receiver (l4shmc_ringbuf_t *buf, l4_cap_idx_t owner)
	Attach to receiver signal of a ring buffer.

int	l4shmc_rb_receiver_wait_for_data (l4shmc_ringbuf_t *buf, int blocking)
	Check if (and optionally block until) new data is ready.

int	l4shmc_rb_receiver_copy_out (l4shmc_ringbuf_head_t head, char target, unsigned *tsize)
	Copy data out of the buffer.

void	l4shmc_rb_receiver_notify_done (l4shmc_ringbuf_t *buf)
	Notify producer that space is available.

int	l4shmc_rb_receiver_read_next_size (l4shmc_ringbuf_head_t *head)
	Have a look at the ring buffer and see which size the next packet to be read has.

Macro Definition Documentation

◆ L4SHMC_RINGBUF_DATA

#define L4SHMC_RINGBUF_DATA ( ringbuf ) (L4SHMC_RINGBUF_HEAD(ringbuf)->data)

Get ring buffer data pointer.

Parameters

ringbuf l4shmc_ringbuf_t struct

Definition at line 113 of file ringbuf.h.

◆ L4SHMC_RINGBUF_DATA_SIZE

#define L4SHMC_RINGBUF_DATA_SIZE ( ringbuf ) ((ringbuf)->_size - sizeof(l4shmc_ringbuf_head_t))

Get size of data area.

Parameters

ringbuf l4shmc_ringbuf_t struct

Definition at line 122 of file ringbuf.h.

◆ L4SHMC_RINGBUF_HEAD

#define L4SHMC_RINGBUF_HEAD ( ringbuf ) ((l4shmc_ringbuf_head_t*)((ringbuf)->_addr))

Get ring buffer head pointer.

Parameters

ringbuf l4shmc_ringbuf_t struct

Definition at line 104 of file ringbuf.h.

Function Documentation

◆ l4shmc_rb_attach_receiver()

void l4shmc_rb_attach_receiver	(	l4shmc_ringbuf_t *	buf,
		l4_cap_idx_t	owner
	)

Attach to receiver signal of a ring buffer.

Attach owner to the receiver-side signal of a ring buffer, which is triggered whenever new data has been produced.

This is split from initialization, because you may not know the owner cap when initializing the buffer.

Parameters

buf	pointer to ring buffer struct
owner	owner thread

◆ l4shmc_rb_attach_sender()

int l4shmc_rb_attach_sender	(	l4shmc_ringbuf_t *	buf,
		char const *	signal_name,
		l4_cap_idx_t	owner
	)

Attach to sender signal of a ring buffer.

Attach owner to the sender-side signal of a ring buffer, which is triggered whenever new space has been freed in the buffer for the sender to write to.

This is split from initialization, because you may not know the owner cap when initializing the buffer.

Parameters

buf	pointer to ring buffer struct
signal_name	signal base name
owner	owner thread

Returns: 0 on success, error otherwise

◆ l4shmc_rb_deinit_buffer()

void l4shmc_rb_deinit_buffer ( l4shmc_ringbuf_t * buf )

De-init a ring buffer.

Parameters

buf	pointer to ring buffer struct

◆ l4shmc_rb_init_buffer()

int l4shmc_rb_init_buffer	(	l4shmc_ringbuf_t *	buf,
		l4shmc_area_t *	area,
		char const *	chunk_name,
		char const *	signal_name,
		unsigned	size
	)

Initialize a ring buffer by creating an SHMC chunk and the corresponding signals.

This needs to be done by one of the participating parties when setting up communication channel.

Precondition: area has been attached using l4shmc_attach().

Parameters

buf	pointer to ring buffer struct
area	pointer to SHMC area
chunk_name	name of SHMC chunk to create in area
signal_name	base name for SHMC signals to create
size	chunk size

Returns: 0 on success, error otherwise

◆ l4shmc_rb_init_receiver()

int l4shmc_rb_init_receiver	(	l4shmc_ringbuf_t *	buf,
		l4shmc_area_t *	area,
		char const *	chunk_name,
		char const *	signal_name
	)

Initialize receive buffer.

Initialize the receiver-side of a ring buffer. This requires the underlying SHMC chunk and the corresponding signals to be valid already (read: to be initialized by the sender).

Precondition: chunk & signals have been created and initialized by the sender side

Parameters

buf	pointer to ring buffer struct
area	pointer to SHMC area
chunk_name	name of SHMC chunk to create in area
signal_name	base name for SHMC signals to create

Returns: 0 on success, error otherwise

◆ l4shmc_rb_receiver_copy_out()

int l4shmc_rb_receiver_copy_out	(	l4shmc_ringbuf_head_t *	head,
		char *	target,
		unsigned *	tsize
	)

Copy data out of the buffer.

Parameters

	head	ring buffer head pointer
	target	valid target buffer
[in,out]	tsize	size of target buffer (must be >= packet size!); contains the real data size

Returns: 0 on success, negative error otherwise

◆ l4shmc_rb_receiver_notify_done()

void l4shmc_rb_receiver_notify_done ( l4shmc_ringbuf_t * buf )

Notify producer that space is available.

Parameters

buf	pointer to ring buffer struct

◆ l4shmc_rb_receiver_read_next_size()

int l4shmc_rb_receiver_read_next_size ( l4shmc_ringbuf_head_t * head )

Have a look at the ring buffer and see which size the next packet to be read has.

Does not modify anything.

Returns: size of next buffer or -1 if no data available

◆ l4shmc_rb_receiver_wait_for_data()

int l4shmc_rb_receiver_wait_for_data	(	l4shmc_ringbuf_t *	buf,
		int	blocking
	)

Check if (and optionally block until) new data is ready.

Parameters

buf	pointer to ring buffer struct
blocking	block if data is not available immediately

Returns immediately, if data is available.

Returns: 0 success, data available, != 0 otherwise

◆ l4shmc_rb_sender_alloc_packet()

char * l4shmc_rb_sender_alloc_packet	(	l4shmc_ringbuf_head_t *	head,
		unsigned	psize
	)

Allocate a packet of a given size within the ring buffer.

This packet may wrap around at the end of the buffer. Users need to be aware of that.

Parameters

head	ring buffer head pointer
psize	packet size

Returns: valid address on success

Return values

NULL	if not enough space available

◆ l4shmc_rb_sender_commit_packet()

void l4shmc_rb_sender_commit_packet ( l4shmc_ringbuf_t * buf )

Tell the consumer that new data is available.

Parameters

buf	pointer to ring buffer struct

◆ l4shmc_rb_sender_next_copy_in()

int l4shmc_rb_sender_next_copy_in	(	l4shmc_ringbuf_t *	buf,
		char *	data,
		unsigned	size,
		int	block_if_necessary
	)

Copy in packet from an external data source.

This is the function you'll want to use. Just pass it a buffer pointer and let the lib do the work.

Parameters

buf	pointer to ring buffer struct
data	valid buffer
size	data size
block_if_necessary	bool: block if buffer currently full

Return values

0	on success
-L4_ENOMEM	if block == false and no space available

◆ l4shmc_rb_sender_put_data()

void l4shmc_rb_sender_put_data	(	l4shmc_ringbuf_t *	buf,
		char *	addr,
		char *	data,
		unsigned	dsize
	)

Copy data into a previously allocated packet.

This function is wrap-around aware.

Parameters

buf	pointer to ring buffer struct
addr	valid destination (allocate with alloc_packet())
data	data source
dsize	data size

Data Structures

Macros

Functions

Macro Definition Documentation

◆ L4SHMC_RINGBUF_DATA

◆ L4SHMC_RINGBUF_DATA_SIZE

◆ L4SHMC_RINGBUF_HEAD

Function Documentation

◆ l4shmc_rb_attach_receiver()

◆ l4shmc_rb_attach_sender()

◆ l4shmc_rb_deinit_buffer()

◆ l4shmc_rb_init_buffer()

◆ l4shmc_rb_init_receiver()

◆ l4shmc_rb_receiver_copy_out()

◆ l4shmc_rb_receiver_notify_done()

◆ l4shmc_rb_receiver_read_next_size()

◆ l4shmc_rb_receiver_wait_for_data()

◆ l4shmc_rb_sender_alloc_packet()

◆ l4shmc_rb_sender_commit_packet()

◆ l4shmc_rb_sender_next_copy_in()

◆ l4shmc_rb_sender_put_data()