LwRB

group LWRB

Lightweight ring buffer manager.

Defines

LWRB_VOLATILE

Enable buffer structure pointer parameter as volatile To use this feature, uncomment keyword below.

LWRB_USE_MAGIC

Adds 2 magic words to make sure if memory is corrupted application can detect wrong data pointer and maximum size.

Typedefs

void(* lwrb_evt_fn )(LWRB_VOLATILE struct lwrb *buff, lwrb_evt_type_t evt, size_t bp)

Event callback function type.

Parameters

  • [in] buff: Buffer handle for event

  • [in] evt: Event type

  • [in] bp: 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_VOLATILE lwrb_t *buff, void *buffdata, size_t size)

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

Return

1 on success, 0 otherwise

Parameters

  • [in] buff: Buffer handle

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

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

uint8_t lwrb_is_ready (LWRB_VOLATILE lwrb_t *buff)

Check if buff is initialized and ready to use.

Return

1 if ready, 0 otherwise

Parameters

  • [in] buff: Buffer handle

void lwrb_free (LWRB_VOLATILE lwrb_t *buff)

Free buffer memory.

Note

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

Parameters

  • [in] buff: Buffer handle

void lwrb_reset (LWRB_VOLATILE lwrb_t *buff)

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

Parameters

  • [in] buff: Buffer handle

void lwrb_set_evt_fn (LWRB_VOLATILE lwrb_t *buff, lwrb_evt_fn fn)

Set event function callback for different buffer operations.

Parameters

  • [in] buff: Buffer handle

  • [in] evt_fn: Callback function

size_t lwrb_write (LWRB_VOLATILE lwrb_t *buff, const void *data, size_t btw)

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

Return

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

Parameters

  • [in] buff: Buffer handle

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

  • [in] btw: Number of bytes to write

size_t lwrb_read (LWRB_VOLATILE lwrb_t *buff, void *data, size_t btr)

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

Return

Number of bytes read and copied to data array

Parameters

  • [in] buff: Buffer handle

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

  • [in] btr: Number of bytes to read

size_t lwrb_peek (LWRB_VOLATILE lwrb_t *buff, size_t skip_count, void *data, size_t btp)

Read from buffer without changing read pointer (peek only)

Return

Number of bytes peeked and written to output array

Parameters

  • [in] buff: Buffer handle

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

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

  • [in] btp: Number of bytes to peek

size_t lwrb_get_free (LWRB_VOLATILE lwrb_t *buff)

Get available size in buffer for write operation.

Return

Number of free bytes in memory

Parameters

  • [in] buff: Buffer handle

size_t lwrb_get_full (LWRB_VOLATILE lwrb_t *buff)

Get number of bytes currently available in buffer.

Return

Number of bytes ready to be read

Parameters

  • [in] buff: Buffer handle

void * lwrb_get_linear_block_read_address (LWRB_VOLATILE lwrb_t *buff)

Get linear address for buffer for fast read.

Return

Linear buffer start address

Parameters

  • [in] buff: Buffer handle

size_t lwrb_get_linear_block_read_length (LWRB_VOLATILE lwrb_t *buff)

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

Return

Linear buffer size in units of bytes for read operation

Parameters

  • [in] buff: Buffer handle

size_t lwrb_skip (LWRB_VOLATILE lwrb_t *buff, size_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

Return

Number of bytes skipped

Parameters

  • [in] buff: Buffer handle

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

void * lwrb_get_linear_block_write_address (LWRB_VOLATILE lwrb_t *buff)

Get linear address for buffer for fast read.

Return

Linear buffer start address

Parameters

  • [in] buff: Buffer handle

size_t lwrb_get_linear_block_write_length (LWRB_VOLATILE lwrb_t *buff)

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

Return

Linear buffer size in units of bytes for write operation

Parameters

  • [in] buff: Buffer handle

size_t lwrb_advance (LWRB_VOLATILE lwrb_t *buff, size_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

Return

Number of bytes advanced for write operation

Parameters

  • [in] buff: Buffer handle

  • [in] len: Number of bytes to advance

struct lwrb_t
#include <lwrb.h>

Buffer structure.

Public Members

uint32_t magic1

Magic 1 word

uint8_t *buff

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

size_t size

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

size_t r

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

size_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

uint32_t magic2

Magic 2 word