Memory Blocks APIs

Macros
#define	SYS_MEM_BLOCKS_DEFINE(name, blk_sz, num_blks, buf_align)
	Create a memory block object with a new backing buffer.
#define	SYS_MEM_BLOCKS_DEFINE_STATIC(name, blk_sz, num_blks, buf_align)
	Create a static memory block object with a new backing buffer.
#define	SYS_MEM_BLOCKS_DEFINE_WITH_EXT_BUF(name, blk_sz, num_blks, buf)
	Create a memory block object with a providing backing buffer.
#define	SYS_MEM_BLOCKS_DEFINE_STATIC_WITH_EXT_BUF(name, blk_sz, num_blks, buf)
	Create a static memory block object with a providing backing buffer.

Typedefs
typedef struct sys_mem_blocks	sys_mem_blocks_t
	Memory Blocks Allocator.
typedef struct sys_multi_mem_blocks	sys_multi_mem_blocks_t
	Multi Memory Blocks Allocator.
typedef sys_mem_blocks_t *(*	sys_multi_mem_blocks_choice_fn_t) (struct sys_multi_mem_blocks *group, void *cfg)
	Multi memory blocks allocator choice function.

Functions
int	sys_mem_blocks_alloc (sys_mem_blocks_t *mem_block, size_t count, void **out_blocks)
	Allocate multiple memory blocks.
int	sys_mem_blocks_alloc_contiguous (sys_mem_blocks_t *mem_block, size_t count, void **out_block)
	Allocate a contiguous set of memory blocks.
int	sys_mem_blocks_get (sys_mem_blocks_t *mem_block, void *in_block, size_t count)
	Force allocation of a specified blocks in a memory block object.
int	sys_mem_blocks_is_region_free (sys_mem_blocks_t *mem_block, void *in_block, size_t count)
	check if the region is free
int	sys_mem_blocks_free (sys_mem_blocks_t *mem_block, size_t count, void **in_blocks)
	Free multiple memory blocks.
int	sys_mem_blocks_free_contiguous (sys_mem_blocks_t *mem_block, void *block, size_t count)
	Free contiguous multiple memory blocks.
void	sys_multi_mem_blocks_init (sys_multi_mem_blocks_t *group, sys_multi_mem_blocks_choice_fn_t choice_fn)
	Initialize multi memory blocks allocator group.
void	sys_multi_mem_blocks_add_allocator (sys_multi_mem_blocks_t *group, sys_mem_blocks_t *alloc)
	Add an allocator to an allocator group.
int	sys_multi_mem_blocks_alloc (sys_multi_mem_blocks_t *group, void *cfg, size_t count, void **out_blocks, size_t *blk_size)
	Allocate memory from multi memory blocks allocator group.
int	sys_multi_mem_blocks_free (sys_multi_mem_blocks_t *group, size_t count, void **in_blocks)
	Free memory allocated from multi memory blocks allocator group.

Detailed Description

Macro Definition Documentation

SYS_MEM_BLOCKS_DEFINE

#define SYS_MEM_BLOCKS_DEFINE	(		name,
			blk_sz,
			num_blks,
			buf_align )

#include <zephyr/sys/mem_blocks.h>

Value:

        _SYS_MEM_BLOCKS_DEFINE(name, blk_sz, num_blks, buf_align,)

Create a memory block object with a new backing buffer.

Parameters

name	Name of the memory block object.
blk_sz	Size of each memory block (in bytes).
num_blks	Total number of memory blocks.
buf_align	Alignment of the memory block buffer (power of 2).

SYS_MEM_BLOCKS_DEFINE_STATIC

#define SYS_MEM_BLOCKS_DEFINE_STATIC	(		name,
			blk_sz,
			num_blks,
			buf_align )

#include <zephyr/sys/mem_blocks.h>

Value:

        _SYS_MEM_BLOCKS_DEFINE(name, blk_sz, num_blks, buf_align, static)

Create a static memory block object with a new backing buffer.

Parameters

name	Name of the memory block object.
blk_sz	Size of each memory block (in bytes).
num_blks	Total number of memory blocks.
buf_align	Alignment of the memory block buffer (power of 2).

SYS_MEM_BLOCKS_DEFINE_STATIC_WITH_EXT_BUF

#define SYS_MEM_BLOCKS_DEFINE_STATIC_WITH_EXT_BUF	(		name,
			blk_sz,
			num_blks,
			buf )

#include <zephyr/sys/mem_blocks.h>

Value:

        _SYS_MEM_BLOCKS_DEFINE_WITH_EXT_BUF(name, blk_sz, num_blks, buf, static)

Create a static memory block object with a providing backing buffer.

Parameters

name	Name of the memory block object.
blk_sz	Size of each memory block (in bytes).
num_blks	Total number of memory blocks.
buf	Backing buffer of type uint8_t.

SYS_MEM_BLOCKS_DEFINE_WITH_EXT_BUF

#define SYS_MEM_BLOCKS_DEFINE_WITH_EXT_BUF	(		name,
			blk_sz,
			num_blks,
			buf )

#include <zephyr/sys/mem_blocks.h>

Value:

        _SYS_MEM_BLOCKS_DEFINE_WITH_EXT_BUF(name, blk_sz, num_blks, buf,)

Create a memory block object with a providing backing buffer.

Parameters

name	Name of the memory block object.
blk_sz	Size of each memory block (in bytes).
num_blks	Total number of memory blocks.
buf	Backing buffer of type uint8_t.

Typedef Documentation

sys_mem_blocks_t

typedef struct sys_mem_blocks sys_mem_blocks_t

#include <zephyr/sys/mem_blocks.h>

Memory Blocks Allocator.

sys_multi_mem_blocks_choice_fn_t

typedef sys_mem_blocks_t *(* sys_multi_mem_blocks_choice_fn_t) (struct sys_multi_mem_blocks *group, void *cfg)

#include <zephyr/sys/mem_blocks.h>

Multi memory blocks allocator choice function.

This is a user-provided functions whose responsibility is selecting a specific memory blocks allocator based on the opaque cfg value, which is specified by the user as an argument to sys_multi_mem_blocks_alloc(). The callback returns a pointer to the chosen allocator where the allocation is performed.

NULL may be returned, which will cause the allocation to fail and a -EINVAL reported to the calling code.

Parameters

group	Multi memory blocks allocator structure.
cfg	An opaque user-provided value. It may be interpreted in any way by the application.

Returns

A pointer to the chosen allocator, or NULL if none is chosen.

sys_multi_mem_blocks_t

typedef struct sys_multi_mem_blocks sys_multi_mem_blocks_t

#include <zephyr/sys/mem_blocks.h>

Multi Memory Blocks Allocator.

Function Documentation

sys_mem_blocks_alloc()

int sys_mem_blocks_alloc	(	sys_mem_blocks_t *	mem_block,
		size_t	count,
		void **	out_blocks )

#include <zephyr/sys/mem_blocks.h>

Allocate multiple memory blocks.

Allocate multiple memory blocks, and place their pointers into the output array.

Parameters

[in]	mem_block	Pointer to memory block object.
[in]	count	Number of blocks to allocate.
[out]	out_blocks	Output array to be populated by pointers to the memory blocks. It must have at least count elements.

Return values

0	Successful
-EINVAL	Invalid argument supplied.
-ENOMEM	Not enough blocks for allocation.

sys_mem_blocks_alloc_contiguous()

int sys_mem_blocks_alloc_contiguous	(	sys_mem_blocks_t *	mem_block,
		size_t	count,
		void **	out_block )

#include <zephyr/sys/mem_blocks.h>

Allocate a contiguous set of memory blocks.

Allocate multiple memory blocks, and place their pointers into the output array.

Parameters

[in]	mem_block	Pointer to memory block object.
[in]	count	Number of blocks to allocate.
[out]	out_block	Output pointer to the start of the allocated block set

Return values

0	Successful
-EINVAL	Invalid argument supplied.
-ENOMEM	Not enough contiguous blocks for allocation.

sys_mem_blocks_free()

int sys_mem_blocks_free	(	sys_mem_blocks_t *	mem_block,
		size_t	count,
		void **	in_blocks )

#include <zephyr/sys/mem_blocks.h>

Free multiple memory blocks.

Free multiple memory blocks according to the array of memory block pointers.

Parameters

[in]	mem_block	Pointer to memory block object.
[in]	count	Number of blocks to free.
[in]	in_blocks	Input array of pointers to the memory blocks.

Return values

0	Successful
-EINVAL	Invalid argument supplied.
-EFAULT	Invalid pointers supplied.

sys_mem_blocks_free_contiguous()

int sys_mem_blocks_free_contiguous	(	sys_mem_blocks_t *	mem_block,
		void *	block,
		size_t	count )

#include <zephyr/sys/mem_blocks.h>

Free contiguous multiple memory blocks.

Free contiguous multiple memory blocks

Parameters

[in]	mem_block	Pointer to memory block object.
[in]	block	Pointer to the first memory block
[in]	count	Number of blocks to free.

Return values

0	Successful
-EINVAL	Invalid argument supplied.
-EFAULT	Invalid pointer supplied.

sys_mem_blocks_get()

int sys_mem_blocks_get	(	sys_mem_blocks_t *	mem_block,
		void *	in_block,
		size_t	count )

#include <zephyr/sys/mem_blocks.h>

Force allocation of a specified blocks in a memory block object.

Allocate a specified blocks in a memory block object. Note: use caution when mixing sys_mem_blocks_get and sys_mem_blocks_alloc, allocation may take any of the free memory space

Parameters

[in]	mem_block	Pointer to memory block object.
[in]	in_block	Address of the first required block to allocate
[in]	count	Number of blocks to allocate.

Return values

0	Successful
-EINVAL	Invalid argument supplied.
-ENOMEM	Some of blocks are taken and cannot be allocated

sys_mem_blocks_is_region_free()

int sys_mem_blocks_is_region_free	(	sys_mem_blocks_t *	mem_block,
		void *	in_block,
		size_t	count )

#include <zephyr/sys/mem_blocks.h>

check if the region is free

Parameters

[in]	mem_block	Pointer to memory block object.
[in]	in_block	Address of the first block to check
[in]	count	Number of blocks to check.

Return values

1	All memory blocks are free
0	At least one of the memory blocks is taken

sys_multi_mem_blocks_add_allocator()

void sys_multi_mem_blocks_add_allocator	(	sys_multi_mem_blocks_t *	group,
		sys_mem_blocks_t *	alloc )

#include <zephyr/sys/mem_blocks.h>

Add an allocator to an allocator group.

This adds a known allocator to an existing multi memory blocks allocator group.

Parameters

group	Multi memory blocks allocator structure.
alloc	Allocator to add

sys_multi_mem_blocks_alloc()

int sys_multi_mem_blocks_alloc	(	sys_multi_mem_blocks_t *	group,
		void *	cfg,
		size_t	count,
		void **	out_blocks,
		size_t *	blk_size )

#include <zephyr/sys/mem_blocks.h>

Allocate memory from multi memory blocks allocator group.

Just as for sys_mem_blocks_alloc(), allocates multiple blocks of memory. Takes an opaque configuration pointer passed to the choice function, which is used by integration code to choose an allocator.

Parameters

[in]	group	Multi memory blocks allocator structure.
[in]	cfg	Opaque configuration parameter, as for sys_multi_mem_blocks_choice_fn_t
[in]	count	Number of blocks to allocate
[out]	out_blocks	Output array to be populated by pointers to the memory blocks. It must have at least count elements.
[out]	blk_size	If not NULL, output the block size of the chosen allocator.

Return values

0	Successful
-EINVAL	Invalid argument supplied, or no allocator chosen.
-ENOMEM	Not enough blocks for allocation.

sys_multi_mem_blocks_free()

int sys_multi_mem_blocks_free	(	sys_multi_mem_blocks_t *	group,
		size_t	count,
		void **	in_blocks )

#include <zephyr/sys/mem_blocks.h>

Free memory allocated from multi memory blocks allocator group.

Free previous allocated memory blocks from sys_multi_mem_blocks_alloc().

Note that all blocks in in_blocks must be from the same allocator.

Parameters

[in]	group	Multi memory blocks allocator structure.
[in]	count	Number of blocks to free.
[in]	in_blocks	Input array of pointers to the memory blocks.

Return values

0	Successful
-EINVAL	Invalid argument supplied, or no allocator chosen.
-EFAULT	Invalid pointer(s) supplied.

sys_multi_mem_blocks_init()

void sys_multi_mem_blocks_init	(	sys_multi_mem_blocks_t *	group,
		sys_multi_mem_blocks_choice_fn_t	choice_fn )

#include <zephyr/sys/mem_blocks.h>

Initialize multi memory blocks allocator group.

Initialize a sys_multi_mem_block struct with the specified choice function. Note that individual allocator must be added later with sys_multi_mem_blocks_add_allocator.

Parameters

group	Multi memory blocks allocator structure.
choice_fn	A sys_multi_mem_blocks_choice_fn_t callback used to select the allocator to be used at allocation time