Ring buffer

nRF5 SDK v15.0.0
Data Structures | Macros | Functions

Functions for controlling ring buffer. More...

Data Structures

struct nrf_ringbuf_cb_t
ring buffer instance control block. More...
struct nrf_ringbuf_t
ring buffer instance structure. More...

Macros

#define NRF_RINGBUF_DEF (_name, _size)
Macro for defining a ring buffer instance. More...

Functions

void nrf_ringbuf_init ( nrf_ringbuf_t const *p_ringbuf)
Initializes a ring buffer instance. More...
ret_code_t nrf_ringbuf_alloc ( nrf_ringbuf_t const *p_ringbuf, uint8_t **pp_data, size_t *p_length, bool start)
Function for allocating memory from a ring buffer. More...
ret_code_t nrf_ringbuf_put ( nrf_ringbuf_t const *p_ringbuf, size_t length)
Function for commiting data to a ring buffer. More...
ret_code_t nrf_ringbuf_cpy_put ( nrf_ringbuf_t const *p_ringbuf, uint8_t const *p_data, size_t *p_length)
Function for copying data directly into the ring buffer. More...
ret_code_t nrf_ringbuf_get ( nrf_ringbuf_t const *p_ringbuf, uint8_t **pp_data, size_t *p_length, bool start)
ret_code_t nrf_ringbuf_free ( nrf_ringbuf_t const *p_ringbuf, size_t length)
Function for freeing buffer back to a ring buffer. More...
ret_code_t nrf_ringbuf_cpy_get ( nrf_ringbuf_t const *p_ringbuf, uint8_t *p_data, size_t *p_length)
Function for copying data directly out of the ring buffer. More...

Detailed Description

Functions for controlling ring buffer.

Macro Definition Documentation

#define NRF_RINGBUF_DEF ( _name,
_size
)
Value:
STATIC_ASSERT ( IS_POWER_OF_TWO (_size)); \
static uint8_t CONCAT_2 (_name,_buf)[_size]; \
static nrf_ringbuf_cb_t CONCAT_2 (_name,_cb); \
static const nrf_ringbuf_t _name = { \
. p_buffer = CONCAT_2 (_name,_buf), \
.bufsize_mask = _size - 1, \
.p_cb = & CONCAT_2 (_name,_cb), \
}

Macro for defining a ring buffer instance.

Parameters
_name Instance name.
_size Size of ring buffer (must be power of 2).

Function Documentation

ret_code_t nrf_ringbuf_alloc ( nrf_ringbuf_t const * p_ringbuf ,
uint8_t ** pp_data ,
size_t * p_length ,
bool start
)

Function for allocating memory from a ring buffer.

Function attempts to allocate amount of memory requested by the user, or smaller amount if requested amount is not available. If start flag is set then exclusive access to allocation is established. nrf_ringbuf_put frees access to allocation. If start flag is not set then exclusive access check is omitted.

Parameters
[in] p_ringbuf Pointer to Ring buffer instance.
[in] pp_data Pointer to pointer to the allocated buffer.
[in,out] p_length Pointer to length. Length is set to requested amount and filled by the function with actually allocated amount.
[in] start Set to true if exclusive access should be controlled.
Return values
NRF_SUCCESS Successful allocation (can be smaller amount than requested). NRF_ERROR_BUSY Ring buffer allocation process (alloc-put) is ongoing.
ret_code_t nrf_ringbuf_cpy_get ( nrf_ringbuf_t const * p_ringbuf ,
uint8_t * p_data ,
size_t * p_length
)

Function for copying data directly out of the ring buffer.

This function is copying available data from the ring buffer to user buffer.

Parameters
[in] p_ringbuf Pointer to Ring buffer instance.
[in] p_data Pointer to the input buffer.
[in,out] p_length Amount of bytes to copy. Amount of bytes copied.
Returns
NRF_SUCCESS on successful put or error.
ret_code_t nrf_ringbuf_cpy_put ( nrf_ringbuf_t const * p_ringbuf ,
uint8_t const * p_data ,
size_t * p_length
)

Function for copying data directly into the ring buffer.

This function is copying user buffer to the ring buffer.

Parameters
[in] p_ringbuf Pointer to Ring buffer instance.
[in] p_data Pointer to the input buffer.
[in,out] p_length Amount of bytes to copy. Amount of bytes copied.
Returns
NRF_SUCCESS on successful put or error.
ret_code_t nrf_ringbuf_free ( nrf_ringbuf_t const * p_ringbuf ,
size_t length
)

Function for freeing buffer back to a ring buffer.

When buffer with data taken from the ring buffer (see nrf_ringbuf_get ) has been processed it must be freed to make it available for further use. This function frees the buffer (can be smaller amount than get).

Parameters
[in] p_ringbuf Pointer to Ring buffer instance.
[in] length Amount of bytes to free.
Returns
NRF_SUCCESS on successful put or error.
ret_code_t nrf_ringbuf_get ( nrf_ringbuf_t const * p_ringbuf ,
uint8_t ** pp_data ,
size_t * p_length ,
bool start
)

Function for getting data from the ring buffer.

Function attempts to get requested amount of data from the ring buffer. If start flag is set then exclusive access to getting data from the ring buffer is established. nrf_ringbuf_free frees access to getting data from the ring buffer. If start flag is not set then exclusive access check is omitted.

Parameters
[in] p_ringbuf Pointer to Ring buffer instance.
[in] pp_data Pointer to pointer to the buffer with data.
[in,out] p_length Pointer to length. Length is set to requested amount and filled by the function with actual amount.
[in] start Set to true if exclusive access should be controlled.
Return values
NRF_SUCCESS Successful getting (can be smaller amount than requested). NRF_ERROR_BUSY Ring buffer getting process (get-free) is ongoing.
void nrf_ringbuf_init ( nrf_ringbuf_t const * p_ringbuf )

Initializes a ring buffer instance.

Parameters
p_ringbuf Pointer to Ring buffer instance.
ret_code_t nrf_ringbuf_put ( nrf_ringbuf_t const * p_ringbuf ,
size_t length
)

Function for commiting data to a ring buffer.

When allocated buffer (see nrf_ringbuf_alloc ) has been filled with data it must be committed to make it available for nrf_ringbuf_get and nrf_ringbuf_cpy_get . This function commits the data (can be smaller amount than allocated).

Parameters
[in] p_ringbuf Pointer to Ring buffer instance.
[in] length Amount of bytes to put.
Returns
NRF_SUCCESS on successful put or error.