Memory Slab APIs

Macros
#define	K_MEM_SLAB_DEFINE_IN_SECT(name, in_section, slab_block_size, slab_num_blocks, slab_align)
	Statically define and initialize a memory slab in a user-provided memory section with public (non-static) scope.
#define	K_MEM_SLAB_DEFINE(name, slab_block_size, slab_num_blocks, slab_align)
	Statically define and initialize a memory slab in a public (non-static) scope.
#define	K_MEM_SLAB_DEFINE_TYPE(name, type, slab_num_blocks)
	Statically define and initialize a memory slab for blocks of a given type in a public (non-static) scope.
#define	K_MEM_SLAB_DEFINE_IN_SECT_STATIC(name, in_section, slab_block_size, slab_num_blocks, slab_align)
	Statically define and initialize a memory slab in a user-provided memory section with private (static) scope.
#define	K_MEM_SLAB_DEFINE_STATIC(name, slab_block_size, slab_num_blocks, slab_align)
	Statically define and initialize a memory slab in a private (static) scope.
#define	K_MEM_SLAB_DEFINE_STATIC_TYPE(name, type, slab_num_blocks)
	Statically define and initialize a memory slab for blocks of a given type in a private (static) scope.

Functions
int	k_mem_slab_init (struct k_mem_slab *slab, void *buffer, size_t block_size, uint32_t num_blocks)
	Initialize a memory slab.
int	k_mem_slab_alloc (struct k_mem_slab *slab, void **mem, k_timeout_t timeout)
	Allocate memory from a memory slab.
void	k_mem_slab_free (struct k_mem_slab *slab, void *mem)
	Free memory allocated from a memory slab.
static uint32_t	k_mem_slab_num_used_get (struct k_mem_slab *slab)
	Get the number of used blocks in a memory slab.
static uint32_t	k_mem_slab_max_used_get (struct k_mem_slab *slab)
	Get the number of maximum used blocks so far in a memory slab.
static uint32_t	k_mem_slab_num_free_get (struct k_mem_slab *slab)
	Get the number of unused blocks in a memory slab.
int	k_mem_slab_runtime_stats_get (struct k_mem_slab *slab, struct sys_memory_stats *stats)
	Get the memory stats for a memory slab.
int	k_mem_slab_runtime_stats_reset_max (struct k_mem_slab *slab)
	Reset the maximum memory usage for a slab.

Detailed Description

Macro Definition Documentation

K_MEM_SLAB_DEFINE

#define K_MEM_SLAB_DEFINE	(		name,
			slab_block_size,
			slab_num_blocks,
			slab_align )

#include <zephyr/kernel.h>

Value:

K_MEM_SLAB_DEFINE_IN_SECT(name, __noinit_named(k_mem_slab_buf_##name), slab_block_size,    \
                          slab_num_blocks, slab_align)

Statically define and initialize a memory slab in a public (non-static) scope.

The memory slab's buffer contains slab_num_blocks memory blocks that are slab_block_size bytes long. The buffer is aligned to a slab_align -byte boundary. To ensure that each memory block is similarly aligned to this boundary, slab_block_size must also be a multiple of slab_align.

The memory slab can be accessed outside the module where it is defined using:

extern struct k_mem_slab <name>; 

Note

This macro cannot be used together with a static keyword. If such a use-case is desired, use K_MEM_SLAB_DEFINE_STATIC instead.

Parameters

name	Name of the memory slab.
slab_block_size	Size of each memory block (in bytes).
slab_num_blocks	Number memory blocks.
slab_align	Alignment of the memory slab's buffer (power of 2).

K_MEM_SLAB_DEFINE_IN_SECT

#define K_MEM_SLAB_DEFINE_IN_SECT	(		name,
			in_section,
			slab_block_size,
			slab_num_blocks,
			slab_align )

#include <zephyr/kernel.h>

Value:

BUILD_ASSERT(((slab_block_size) % (slab_align)) == 0,                                      \
             "slab_block_size must be a multiple of slab_align");                          \
BUILD_ASSERT((((slab_align) & ((slab_align) - 1)) == 0),                                   \
             "slab_align must be a power of 2");                                           \
char in_section __aligned(WB_UP(                                                           \
        slab_align)) _k_mem_slab_buf_##name[(slab_num_blocks) * WB_UP(slab_block_size)];   \
STRUCT_SECTION_ITERABLE(k_mem_slab, name) = Z_MEM_SLAB_INITIALIZER(                        \
        name, _k_mem_slab_buf_##name, WB_UP(slab_block_size), slab_num_blocks)

Statically define and initialize a memory slab in a user-provided memory section with public (non-static) scope.

The memory slab's buffer contains slab_num_blocks memory blocks that are slab_block_size bytes long. The buffer is aligned to a slab_align -byte boundary. To ensure that each memory block is similarly aligned to this boundary, slab_block_size must also be a multiple of slab_align.

The memory slab can be accessed outside the module where it is defined using:

extern struct k_mem_slab <name>; 

Note

This macro cannot be used together with a static keyword. If such a use-case is desired, use K_MEM_SLAB_DEFINE_IN_SECT_STATIC instead.

Parameters

name	Name of the memory slab.
in_section	Section attribute specifier such as Z_GENERIC_SECTION.
slab_block_size	Size of each memory block (in bytes).
slab_num_blocks	Number memory blocks.
slab_align	Alignment of the memory slab's buffer (power of 2).

K_MEM_SLAB_DEFINE_IN_SECT_STATIC

#define K_MEM_SLAB_DEFINE_IN_SECT_STATIC	(		name,
			in_section,
			slab_block_size,
			slab_num_blocks,
			slab_align )

#include <zephyr/kernel.h>

Value:

BUILD_ASSERT(((slab_block_size) % (slab_align)) == 0,                                      \
             "slab_block_size must be a multiple of slab_align");                          \
BUILD_ASSERT((((slab_align) & ((slab_align) - 1)) == 0),                                   \
             "slab_align must be a power of 2");                                           \
static char in_section __aligned(WB_UP(                                                    \
        slab_align)) _k_mem_slab_buf_##name[(slab_num_blocks) * WB_UP(slab_block_size)];   \
static STRUCT_SECTION_ITERABLE(k_mem_slab, name) = Z_MEM_SLAB_INITIALIZER(                 \
        name, _k_mem_slab_buf_##name, WB_UP(slab_block_size), slab_num_blocks)

Statically define and initialize a memory slab in a user-provided memory section with private (static) scope.

The memory slab's buffer contains slab_num_blocks memory blocks that are slab_block_size bytes long. The buffer is aligned to a slab_align -byte boundary. To ensure that each memory block is similarly aligned to this boundary, slab_block_size must also be a multiple of slab_align.

Parameters

name	Name of the memory slab.
in_section	Section attribute specifier such as Z_GENERIC_SECTION.
slab_block_size	Size of each memory block (in bytes).
slab_num_blocks	Number memory blocks.
slab_align	Alignment of the memory slab's buffer (power of 2).

K_MEM_SLAB_DEFINE_STATIC

#define K_MEM_SLAB_DEFINE_STATIC	(		name,
			slab_block_size,
			slab_num_blocks,
			slab_align )

#include <zephyr/kernel.h>

Value:

K_MEM_SLAB_DEFINE_IN_SECT_STATIC(name, __noinit_named(k_mem_slab_buf_##name),              \
                                 slab_block_size, slab_num_blocks, slab_align)

Statically define and initialize a memory slab in a private (static) scope.

The memory slab's buffer contains slab_num_blocks memory blocks that are slab_block_size bytes long. The buffer is aligned to a slab_align -byte boundary. To ensure that each memory block is similarly aligned to this boundary, slab_block_size must also be a multiple of slab_align.

Parameters

name	Name of the memory slab.
slab_block_size	Size of each memory block (in bytes).
slab_num_blocks	Number memory blocks.
slab_align	Alignment of the memory slab's buffer (power of 2).

K_MEM_SLAB_DEFINE_STATIC_TYPE

#define K_MEM_SLAB_DEFINE_STATIC_TYPE	(		name,
			type,
			slab_num_blocks )

#include <zephyr/kernel.h>

Value:

K_MEM_SLAB_DEFINE_STATIC(name, sizeof(type), slab_num_blocks, __alignof(type))

Statically define and initialize a memory slab for blocks of a given type in a private (static) scope.

The memory slab's buffer contains slab_num_blocks memory blocks that are the size of type. The buffer is aligned according to the alignment requirement of type.

Parameters

name	Name of the memory slab.
type	Type of each memory block.
slab_num_blocks	Number of memory blocks.

K_MEM_SLAB_DEFINE_TYPE

#define K_MEM_SLAB_DEFINE_TYPE	(		name,
			type,
			slab_num_blocks )

#include <zephyr/kernel.h>

Value:

K_MEM_SLAB_DEFINE(name, sizeof(type), slab_num_blocks, __alignof(type))

Statically define and initialize a memory slab for blocks of a given type in a public (non-static) scope.

The memory slab's buffer contains slab_num_blocks memory blocks that are the size of type. The buffer is aligned according to the alignment requirement of type.

The memory slab can be accessed outside the module where it is defined using:

extern struct k_mem_slab <name>; 

Note

This macro cannot be used together with a static keyword. If such a use-case is desired, use K_MEM_SLAB_DEFINE_STATIC_TYPE instead.

Parameters

name	Name of the memory slab.
type	Type of each memory block.
slab_num_blocks	Number of memory blocks.

Function Documentation

k_mem_slab_alloc()

int k_mem_slab_alloc ( struct k_mem_slab * slab, void ** mem, k_timeout_t timeout )

isr-ok

#include <zephyr/kernel.h>

Allocate memory from a memory slab.

This routine allocates a memory block from a memory slab.

Note

timeout must be set to K_NO_WAIT if called from ISR.

When CONFIG_MULTITHREADING=n any timeout is treated as K_NO_WAIT.

Parameters

slab	Address of the memory slab.
mem	Pointer to block address area.
timeout	Waiting period to wait for operation to complete. Use K_NO_WAIT to return without waiting, or K_FOREVER to wait as long as necessary.

Return values

0	Memory allocated. The block address area pointed at by mem is set to the starting address of the memory block.
-ENOMEM	Returned without waiting.
-EAGAIN	Waiting period timed out.
-EINVAL	Invalid data supplied

k_mem_slab_free()

void k_mem_slab_free ( struct k_mem_slab * slab, void * mem )

isr-ok

#include <zephyr/kernel.h>

Free memory allocated from a memory slab.

This routine releases a previously allocated memory block back to its associated memory slab.

Parameters

slab	Address of the memory slab.
mem	Pointer to the memory block (as returned by k_mem_slab_alloc()).

k_mem_slab_init()

int k_mem_slab_init	(	struct k_mem_slab *	slab,
		void *	buffer,
		size_t	block_size,
		uint32_t	num_blocks )

#include <zephyr/kernel.h>

Initialize a memory slab.

Initializes a memory slab, prior to its first use.

The memory slab's buffer contains slab_num_blocks memory blocks that are slab_block_size bytes long. The buffer must be aligned to an N-byte boundary matching a word boundary, where N is a power of 2 (i.e. 4 on 32-bit systems, 8, 16, ...). To ensure that each memory block is similarly aligned to this boundary, slab_block_size must also be a multiple of N.

Parameters

slab	Address of the memory slab.
buffer	Pointer to buffer used for the memory blocks.
block_size	Size of each memory block (in bytes).
num_blocks	Number of memory blocks.

Return values

0	on success
-EINVAL	invalid data supplied

k_mem_slab_max_used_get()

uint32_t k_mem_slab_max_used_get ( struct k_mem_slab * slab )

inlinestaticisr-ok

#include <zephyr/kernel.h>

Get the number of maximum used blocks so far in a memory slab.

This routine gets the maximum number of memory blocks that were allocated in slab.

Parameters

slab	Address of the memory slab.

Returns

Maximum number of allocated memory blocks.

k_mem_slab_num_free_get()

uint32_t k_mem_slab_num_free_get ( struct k_mem_slab * slab )

inlinestaticisr-ok

#include <zephyr/kernel.h>

Get the number of unused blocks in a memory slab.

This routine gets the number of memory blocks that are currently unallocated in slab.

Parameters

slab	Address of the memory slab.

Returns

Number of unallocated memory blocks.

k_mem_slab_num_used_get()

uint32_t k_mem_slab_num_used_get ( struct k_mem_slab * slab )

inlinestaticisr-ok

#include <zephyr/kernel.h>

Get the number of used blocks in a memory slab.

This routine gets the number of memory blocks that are currently allocated in slab.

Parameters

slab	Address of the memory slab.

Returns

Number of allocated memory blocks.

k_mem_slab_runtime_stats_get()

int k_mem_slab_runtime_stats_get ( struct k_mem_slab * slab, struct sys_memory_stats * stats )

isr-ok

#include <zephyr/kernel.h>

Get the memory stats for a memory slab.

This routine gets the runtime memory usage stats for the slab slab.

Parameters

slab	Address of the memory slab
stats	Pointer to memory into which to copy memory usage statistics

Return values

0	Success
-EINVAL	Any parameter points to NULL

k_mem_slab_runtime_stats_reset_max()

int k_mem_slab_runtime_stats_reset_max ( struct k_mem_slab * slab )

isr-ok

#include <zephyr/kernel.h>

Reset the maximum memory usage for a slab.

This routine resets the maximum memory usage for the slab slab to its current usage.

Parameters

slab	Address of the memory slab

Return values

0	Success
-EINVAL	Memory slab is NULL