nRF5 SDK  v15.2.0
Choose documentation:
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Block memory allocator

This module handles block memory allocator features. More...

Modules

 Block allocator module configuration
 
 Macros for preparing debug flags for block allocator module.
 

Data Structures

struct  nrf_balloc_cb_t
 Block memory allocator control block. More...
 
struct  nrf_balloc_t
 Block memory allocator pool instance. The pool is made of elements of the same size. More...
 

Macros

#define NRF_BALLOC_LOG_NAME   balloc
 Name of the module used for logger messaging.
 
#define NRF_BALLOC_HAS_NAME   0
 
#define NRF_BALLOC_DEFAULT_DEBUG_FLAGS   0
 Default debug flags for Block memory allocator. This is used by the NRF_BALLOC_DEF macro. Flags can be changed in SDK configuration header file.
 
#define NRF_BALLOC_BLOCK_SIZE(_element_size, _debug_flags)   ALIGN_NUM(sizeof(uint32_t), (_element_size))
 Get total memory consumed by single block (element size with overhead caused by debug flags). More...
 
#define NRF_BALLOC_ELEMENT_SIZE(_p_balloc)   (_p_balloc)->block_size
 Get element size ( excluding debugging overhead is present) flags). More...
 
#define __NRF_BALLOC_ASSIGN_DEBUG_FLAGS(_debug_flags)
 
#define __NRF_BALLOC_ASSIGN_POOL_NAME(_name)
 
#define NRF_BALLOC_DBG_DEF(_name, _element_size, _pool_size, _debug_flags)
 Create a block allocator instance with custom debug flags. More...
 
#define NRF_BALLOC_DEF(_name, _element_size, _pool_size)   NRF_BALLOC_DBG_DEF(_name, _element_size, _pool_size, NRF_BALLOC_DEFAULT_DEBUG_FLAGS)
 Create a block allocator instance. More...
 
#define NRF_BALLOC_INTERFACE_DEC(_type, _name)
 Create a block allocator interface. More...
 
#define NRF_BALLOC_INTERFACE_CUSTOM_DEF(_attr, _type, _name, _p_pool)
 Define a custom block allocator interface. More...
 
#define NRF_BALLOC_INTERFACE_DEF(_type, _name, _p_pool)   NRF_BALLOC_INTERFACE_CUSTOM_DEF(/* empty */, _type, _name, _p_pool)
 Define block allocator interface. More...
 
#define NRF_BALLOC_INTERFACE_LOCAL_DEF(_type, _name, _p_pool)   NRF_BALLOC_INTERFACE_CUSTOM_DEF(static, _type, _name, _p_pool)
 Define a local block allocator interface. More...
 

Functions

ret_code_t nrf_balloc_init (nrf_balloc_t const *p_pool)
 Function for initializing a block memory allocator pool. More...
 
void * nrf_balloc_alloc (nrf_balloc_t const *p_pool)
 Function for allocating an element from the pool. More...
 
void nrf_balloc_free (nrf_balloc_t const *p_pool, void *p_element)
 Function for freeing an element back to the pool. More...
 
__STATIC_INLINE uint8_t nrf_balloc_max_utilization_get (nrf_balloc_t const *p_pool)
 Function for getting maximum memory pool utilization. More...
 
__STATIC_INLINE uint8_t nrf_balloc_utilization_get (nrf_balloc_t const *p_pool)
 Function for getting current memory pool utilization. More...
 

Detailed Description

This module handles block memory allocator features.

Macro Definition Documentation

#define NRF_BALLOC_BLOCK_SIZE (   _element_size,
  _debug_flags 
)    ALIGN_NUM(sizeof(uint32_t), (_element_size))

Get total memory consumed by single block (element size with overhead caused by debug flags).

Parameters
[in]_element_sizeSize of an element.
[in]_debug_flagsDebug flags.
#define NRF_BALLOC_DBG_DEF (   _name,
  _element_size,
  _pool_size,
  _debug_flags 
)
Value:
STATIC_ASSERT((_pool_size) <= UINT8_MAX); \
static uint8_t CONCAT_2(_name, _nrf_balloc_pool_stack)[(_pool_size)]; \
static uint32_t CONCAT_2(_name,_nrf_balloc_pool_mem) \
[NRF_BALLOC_BLOCK_SIZE(_element_size, _debug_flags) * (_pool_size) / sizeof(uint32_t)]; \
static nrf_balloc_cb_t CONCAT_2(_name,_nrf_balloc_cb); \
NRF_LOG_INSTANCE_REGISTER(NRF_BALLOC_LOG_NAME, _name, \
NRF_BALLOC_CONFIG_LOG_LEVEL : NRF_LOG_SEVERITY_NONE); \
NRF_SECTION_ITEM_REGISTER(nrf_balloc, const nrf_balloc_t _name) = \
{ \
.p_cb = &CONCAT_2(_name,_nrf_balloc_cb), \
.p_stack_base = CONCAT_2(_name,_nrf_balloc_pool_stack), \
.p_stack_limit = CONCAT_2(_name,_nrf_balloc_pool_stack) + (_pool_size), \
.p_memory_begin = CONCAT_2(_name,_nrf_balloc_pool_mem), \
.block_size = NRF_BALLOC_BLOCK_SIZE(_element_size, _debug_flags), \
__NRF_BALLOC_ASSIGN_POOL_NAME(_name) \
__NRF_BALLOC_ASSIGN_DEBUG_FLAGS(_debug_flags) \
}

Create a block allocator instance with custom debug flags.

Note
This macro reserves memory for the given block allocator instance.
Parameters
[in]_nameName of the allocator.
[in]_element_sizeSize of one element.
[in]_pool_sizeSize of the pool.
[in]_debug_flagsDebug flags (Macros for preparing debug flags for block allocator module.).
#define NRF_BALLOC_DEF (   _name,
  _element_size,
  _pool_size 
)    NRF_BALLOC_DBG_DEF(_name, _element_size, _pool_size, NRF_BALLOC_DEFAULT_DEBUG_FLAGS)

Create a block allocator instance.

Note
This macro reserves memory for the given block allocator instance.
Parameters
[in]_nameName of the allocator.
[in]_element_sizeSize of one element.
[in]_pool_sizeSize of the pool.
#define NRF_BALLOC_ELEMENT_SIZE (   _p_balloc)    (_p_balloc)->block_size

Get element size ( excluding debugging overhead is present) flags).

Parameters
[in]_p_ballocPointer to balloc instance.
#define NRF_BALLOC_INTERFACE_CUSTOM_DEF (   _attr,
  _type,
  _name,
  _p_pool 
)
Value:
_attr _type * CONCAT_2(_name,_alloc)(void) \
{ \
GCC_PRAGMA("GCC diagnostic push") \
GCC_PRAGMA("GCC diagnostic ignored \"-Waddress\"") \
ASSERT((_p_pool) != NULL); \
ASSERT((_p_pool)->block_size >= \
NRF_BALLOC_BLOCK_SIZE(sizeof(_type), (_p_pool)->debug_flags)); \
GCC_PRAGMA("GCC diagnostic pop") \
return (_type *)(nrf_balloc_alloc(_p_pool)); \
} \
\
_attr void CONCAT_2(_name,_free)(_type * p_element) \
{ \
GCC_PRAGMA("GCC diagnostic push") \
GCC_PRAGMA("GCC diagnostic ignored \"-Waddress\"") \
ASSERT((_p_pool) != NULL); \
ASSERT((_p_pool)->block_size >= \
NRF_BALLOC_BLOCK_SIZE(sizeof(_type), (_p_pool)->debug_flags)); \
GCC_PRAGMA("GCC diagnostic pop") \
nrf_balloc_free((_p_pool), p_element); \
}

Define a custom block allocator interface.

Parameters
[in]_attrFunction attribute that will be added to allocator function definition.
[in]_typeType which is allocated.
[in]_nameName of the allocator.
[in]_p_poolPool from which data will be allocated.
#define NRF_BALLOC_INTERFACE_DEC (   _type,
  _name 
)
Value:
_type * CONCAT_2(_name,_alloc)(void); \
void CONCAT_2(_name,_free)(_type * p_element)

Create a block allocator interface.

Parameters
[in]_typeType which is allocated.
[in]_nameName of the allocator.
#define NRF_BALLOC_INTERFACE_DEF (   _type,
  _name,
  _p_pool 
)    NRF_BALLOC_INTERFACE_CUSTOM_DEF(/* empty */, _type, _name, _p_pool)

Define block allocator interface.

Parameters
[in]_typeType which is allocated.
[in]_nameName of the allocator.
[in]_p_poolPool from which data will be allocated.
#define NRF_BALLOC_INTERFACE_LOCAL_DEF (   _type,
  _name,
  _p_pool 
)    NRF_BALLOC_INTERFACE_CUSTOM_DEF(static, _type, _name, _p_pool)

Define a local block allocator interface.

Parameters
[in]_typeType which is allocated.
[in]_nameName of the allocator.
[in]_p_poolPool from which data will be allocated.

Function Documentation

void* nrf_balloc_alloc ( nrf_balloc_t const *  p_pool)

Function for allocating an element from the pool.

Note
This module guarantees that the returned memory is aligned to 4.
Parameters
[in]p_poolPointer to the memory pool from which the element will be allocated.
Returns
Allocated element or NULL if the specified pool is empty.
void nrf_balloc_free ( nrf_balloc_t const *  p_pool,
void *  p_element 
)

Function for freeing an element back to the pool.

Parameters
[in]p_poolPointer to the memory pool.
[in]p_elementElement to be freed.
ret_code_t nrf_balloc_init ( nrf_balloc_t const *  p_pool)

Function for initializing a block memory allocator pool.

Parameters
[out]p_poolPointer to the pool that is to be initialized.
Returns
NRF_SUCCESS on success, otherwise error code.
__STATIC_INLINE uint8_t nrf_balloc_max_utilization_get ( nrf_balloc_t const *  p_pool)

Function for getting maximum memory pool utilization.

Parameters
[in]p_poolPointer to the memory pool instance.
Returns
Maximum number of elements allocated from the pool.
__STATIC_INLINE uint8_t nrf_balloc_utilization_get ( nrf_balloc_t const *  p_pool)

Function for getting current memory pool utilization.

Parameters
[in]p_poolPointer to the memory pool instance.
Returns
Maximum number of elements allocated from the pool.