Ring buffer

nRF5 SDK v15.2.0
Data Structures | Macros | Functions

Functions for controlling the 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)
Function for initializing 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 a buffer back to the 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 the 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 the ring buffer (must be a 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.

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

Parameters
[in] p_ringbuf Pointer to the ring buffer instance.
[in] pp_data Pointer to the pointer to the allocated buffer.
[in,out] p_length Pointer to length. Length is set to the 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 copies available data from the ring buffer to a user buffer.

Parameters
[in] p_ringbuf Pointer to the 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 copies a user buffer to the ring buffer.

Parameters
[in] p_ringbuf Pointer to the 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 a buffer back to the ring buffer.

When a 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 the 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.

This function attempts to get the requested amount of data from the ring buffer. If a 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 a start flag is not set, then exclusive access check is omitted.

Parameters
[in] p_ringbuf Pointer to the ring buffer instance.
[in] pp_data Pointer to the pointer to the buffer with data.
[in,out] p_length Pointer to length. Length is set to the requested amount and filled by the function with the 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 )

Function for initializing a ring buffer instance.

Parameters
p_ringbuf Pointer to the 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 an 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 the ring buffer instance.
[in] length Amount of bytes to put.
Returns
NRF_SUCCESS on successful put or error.