Loading...
Searching...
No Matches
ringbuf.h File Reference
`#include <l4/shmc/shmc.h>`
`#include <l4/util/assert.h>`
`#include <l4/sys/compiler.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)
| Get ring buffer head pointer.
#define | L4SHMC_RINGBUF_DATA(ringbuf)
| Get ring buffer data pointer.
#define | L4SHMC_RINGBUF_DATA_SIZE(ringbuf)
| 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

References L4_CV.

## 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

References L4_CV.

## 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

References L4_CV.

## 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

References L4_CV.

## 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

References L4_CV.

## 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

References L4_CV.

## 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

References L4_CV.

## 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

References L4_CV, and L4_END_DECLS.

## 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

References L4_CV.

## 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

References L4_CV.

## 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

References L4_CV.

## 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

References L4_CV.

## 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

References L4_CV.