ringbuf.h File Reference

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

Include dependency graph for ringbuf.h:

Go to the source code of this file.

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.

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