LwRB
- group LWRB
Lightweight ring buffer manager.
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
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 issize - 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 maximumbtw
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 maximumbtr
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
ifbts found,
0
otherwise
-
struct lwrb_t
- #include <lwrb.h>
Buffer structure.
Public Members
-
uint8_t *buff
Pointer to buffer data. Buffer is considered initialized when
buff != NULL
andsize > 0
-
lwrb_sz_atomic_t r
Next read pointer. Buffer is considered empty when
r == w
and full whenw == r - 1
-
lwrb_sz_atomic_t w
Next write pointer. Buffer is considered empty when
r == w
and full whenw == r - 1
-
lwrb_evt_fn evt_fn
Pointer to event callback function
-
void *arg
Event custom user argument
-
uint8_t *buff
-
typedef atomic_ulong lwrb_sz_atomic_t