LwRB

group LWRB

Lightweight ring buffer manager.

Defines

LWRB_FLAG_READ_ALL
LWRB_FLAG_WRITE_ALL

Typedefs

typedef atomic_ulong lwrb_sz_atomic_t

Atomic type for size variable. Default value is set to be unsigned 32-bits type.

typedef unsigned long lwrb_sz_t

Size variable for all library operations. Default value is set to be unsigned 32-bits type.

typedef void (*lwrb_evt_fn)(struct lwrb *buff, lwrb_evt_type_t evt, lwrb_sz_t bp)

Event callback function type.

Param buff

[in] Buffer handle for event

Param evt

[in] Event type

Param bp

[in] Number of bytes written or read (when used), depends on event type

Enums

enum lwrb_evt_type_t

Event type for buffer operations.

Values:

enumerator LWRB_EVT_READ

Read event

enumerator LWRB_EVT_WRITE

Write event

enumerator LWRB_EVT_RESET

Reset event

Functions

uint8_t lwrb_init(lwrb_t *buff, void *buffdata, lwrb_sz_t size)

Initialize buffer handle to default values with size and buffer data array.

Parameters
  • buff[in] Ring buffer instance

  • buffdata[in] Pointer to memory to use as buffer data

  • size[in] Size of buffdata in units of bytes Maximum number of bytes buffer can hold is size - 1

Returns

1 on success, 0 otherwise

uint8_t lwrb_is_ready(lwrb_t *buff)

Check if buff is initialized and ready to use.

Parameters

buff[in] Ring buffer instance

Returns

1 if ready, 0 otherwise

void lwrb_free(lwrb_t *buff)

Free buffer memory.

Note

Since implementation does not use dynamic allocation, it just sets buffer handle to NULL

Parameters

buff[in] Ring buffer instance

void lwrb_reset(lwrb_t *buff)

Resets buffer to default values. Buffer size is not modified.

Note

This function is not thread safe. When used, application must ensure there is no active read/write operation

Parameters

buff[in] Ring buffer instance

void lwrb_set_evt_fn(lwrb_t *buff, lwrb_evt_fn fn)

Set event function callback for different buffer operations.

Parameters
  • buff[in] Ring buffer instance

  • evt_fn[in] Callback function

void lwrb_set_arg(lwrb_t *buff, void *arg)

Set custom buffer argument, that can be retrieved in the event function.

Parameters
  • buff[in] Ring buffer instance

  • arg[in] Custom user argument

void *lwrb_get_arg(lwrb_t *buff)

Get custom buffer argument, previously set with lwrb_set_arg.

Parameters

buff[in] Ring buffer instance

Returns

User argument, previously set with lwrb_set_arg

lwrb_sz_t lwrb_write(lwrb_t *buff, const void *data, lwrb_sz_t btw)

Write data to buffer. Copies data from data array to buffer and marks buffer as full for maximum btw number of bytes.

Parameters
  • buff[in] Ring buffer instance

  • data[in] Pointer to data to write into buffer

  • btw[in] Number of bytes to write

Returns

Number of bytes written to buffer. When returned value is less than btw, there was no enough memory available to copy full data array.

lwrb_sz_t lwrb_read(lwrb_t *buff, void *data, lwrb_sz_t btr)

Read data from buffer. Copies data from buffer to data array and marks buffer as free for maximum btr number of bytes.

Parameters
  • buff[in] Ring buffer instance

  • data[out] Pointer to output memory to copy buffer data to

  • btr[in] Number of bytes to read

Returns

Number of bytes read and copied to data array

lwrb_sz_t lwrb_peek(const lwrb_t *buff, lwrb_sz_t skip_count, void *data, lwrb_sz_t btp)

Read from buffer without changing read pointer (peek only)

Parameters
  • buff[in] Ring buffer instance

  • skip_count[in] Number of bytes to skip before reading data

  • data[out] Pointer to output memory to copy buffer data to

  • btp[in] Number of bytes to peek

Returns

Number of bytes peeked and written to output array

uint8_t lwrb_write_ex(lwrb_t *buff, const void *data, lwrb_sz_t btw, lwrb_sz_t *bw, uint16_t flags)

Write extended functionality.

Parameters
  • buff – Ring buffer instance

  • data – Pointer to data to write into buffer

  • btw – Number of bytes to write

  • bw – Output pointer to write number of bytes written

  • flags – Optional flags. LWRB_FLAG_WRITE_ALL: Request to write all data (up to btw). Will early return if no memory available

Returns

1 if write operation OK, 0 otherwise

uint8_t lwrb_read_ex(lwrb_t *buff, void *data, lwrb_sz_t btr, lwrb_sz_t *br, uint16_t flags)

Write extended functionality.

Parameters
  • buff – Ring buffer instance

  • data – Pointer to memory to write read data from buffer

  • btr – Number of bytes to read

  • br – Output pointer to write number of bytes read

  • flags – Optional flags LWRB_FLAG_READ_ALL: Request to read all data (up to btr). Will early return if no enough bytes in the buffer

Returns

1 if read operation OK, 0 otherwise

lwrb_sz_t lwrb_get_free(const lwrb_t *buff)

Get available size in buffer for write operation.

Parameters

buff[in] Ring buffer instance

Returns

Number of free bytes in memory

lwrb_sz_t lwrb_get_full(const lwrb_t *buff)

Get number of bytes currently available in buffer.

Parameters

buff[in] Ring buffer instance

Returns

Number of bytes ready to be read

void *lwrb_get_linear_block_read_address(const lwrb_t *buff)

Get linear address for buffer for fast read.

Parameters

buff[in] Ring buffer instance

Returns

Linear buffer start address

lwrb_sz_t lwrb_get_linear_block_read_length(const lwrb_t *buff)

Get length of linear block address before it overflows for read operation.

Parameters

buff[in] Ring buffer instance

Returns

Linear buffer size in units of bytes for read operation

lwrb_sz_t lwrb_skip(lwrb_t *buff, lwrb_sz_t len)

Skip (ignore; advance read pointer) buffer data Marks data as read in the buffer and increases free memory for up to len bytes.

Note

Useful at the end of streaming transfer such as DMA

Parameters
  • buff[in] Ring buffer instance

  • len[in] Number of bytes to skip and mark as read

Returns

Number of bytes skipped

void *lwrb_get_linear_block_write_address(const lwrb_t *buff)

Get linear address for buffer for fast read.

Parameters

buff[in] Ring buffer instance

Returns

Linear buffer start address

lwrb_sz_t lwrb_get_linear_block_write_length(const lwrb_t *buff)

Get length of linear block address before it overflows for write operation.

Parameters

buff[in] Ring buffer instance

Returns

Linear buffer size in units of bytes for write operation

lwrb_sz_t lwrb_advance(lwrb_t *buff, lwrb_sz_t len)

Advance write pointer in the buffer. Similar to skip function but modifies write pointer instead of read.

Note

Useful when hardware is writing to buffer and application needs to increase number of bytes written to buffer by hardware

Parameters
  • buff[in] Ring buffer instance

  • len[in] Number of bytes to advance

Returns

Number of bytes advanced for write operation

uint8_t lwrb_find(const lwrb_t *buff, const void *bts, lwrb_sz_t len, lwrb_sz_t start_offset, lwrb_sz_t *found_idx)

Searches for a needle in an array, starting from given offset.

Note

This function is not thread-safe.

Parameters
  • buff – Ring buffer to search for needle in

  • bts – Constant byte array sequence to search for in a buffer

  • len – Length of the

    • bts array

  • start_offset – Start offset in the buffer

  • found_idx – Pointer to variable to write index in array where bts has been found Must not be set to NULL

Returns

1 if

  • bts found, 0 otherwise

lwrb_sz_t lwrb_overwrite(lwrb_t *buff, const void *data, lwrb_sz_t btw)
lwrb_sz_t lwrb_move(lwrb_t *dest, lwrb_t *src)
struct lwrb_t
#include <lwrb.h>

Buffer structure.

Public Members

uint8_t *buff

Pointer to buffer data. Buffer is considered initialized when buff != NULL and size > 0

lwrb_sz_t size

Size of buffer data. Size of actual buffer is 1 byte less than value holds

lwrb_sz_atomic_t r

Next read pointer. Buffer is considered empty when r == w and full when w == r - 1

lwrb_sz_atomic_t w

Next write pointer. Buffer is considered empty when r == w and full when w == r - 1

lwrb_evt_fn evt_fn

Pointer to event callback function

void *arg

Event custom user argument