Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Heap APIs

Data Structures

struct  k_heap
 

Macros

#define K_HEAP_DEFINE(name, bytes)
 Define a static k_heap.
 
#define K_HEAP_DEFINE_NOCACHE(name, bytes)    Z_HEAP_DEFINE_IN_SECT(name, bytes, __nocache)
 Define a static k_heap in uncached memory.
 

Functions

void k_heap_init (struct k_heap *h, void *mem, size_t bytes)
 Initialize a k_heap.
 
void * k_heap_aligned_alloc (struct k_heap *h, size_t align, size_t bytes, k_timeout_t timeout)
 Allocate aligned memory from a k_heap.
 
void * k_heap_alloc (struct k_heap *h, size_t bytes, k_timeout_t timeout)
 Allocate memory from a k_heap.
 
void * k_heap_realloc (struct k_heap *h, void *ptr, size_t bytes, k_timeout_t timeout)
 Reallocate memory from a k_heap.
 
void k_heap_free (struct k_heap *h, void *mem)
 Free memory allocated by k_heap_alloc()
 
void * k_aligned_alloc (size_t align, size_t size)
 Allocate memory from the heap with a specified alignment.
 
void * k_malloc (size_t size)
 Allocate memory from the heap.
 
void k_free (void *ptr)
 Free memory allocated from heap.
 
void * k_calloc (size_t nmemb, size_t size)
 Allocate memory from heap, array style.
 
void * k_realloc (void *ptr, size_t size)
 Expand the size of an existing allocation.
 

Detailed Description

Macro Definition Documentation

◆ K_HEAP_DEFINE

#define K_HEAP_DEFINE (   name,
  bytes 
)

#include <zephyr/kernel.h>

Value:
Z_HEAP_DEFINE_IN_SECT(name, bytes, \
__noinit_named(kheap_buf_##name))

Define a static k_heap.

This macro defines and initializes a static memory region and k_heap of the requested size. After kernel start, &name can be used as if k_heap_init() had been called.

Note that this macro enforces a minimum size on the memory region to accommodate metadata requirements. Very small heaps will be padded to fit.

Parameters
nameSymbol name for the struct k_heap object
bytesSize of memory region, in bytes

◆ K_HEAP_DEFINE_NOCACHE

#define K_HEAP_DEFINE_NOCACHE (   name,
  bytes 
)     Z_HEAP_DEFINE_IN_SECT(name, bytes, __nocache)

#include <zephyr/kernel.h>

Define a static k_heap in uncached memory.

This macro defines and initializes a static memory region and k_heap of the requested size in uncached memory. After kernel start, &name can be used as if k_heap_init() had been called.

Note that this macro enforces a minimum size on the memory region to accommodate metadata requirements. Very small heaps will be padded to fit.

Parameters
nameSymbol name for the struct k_heap object
bytesSize of memory region, in bytes

Function Documentation

◆ k_aligned_alloc()

void * k_aligned_alloc ( size_t  align,
size_t  size 
)

#include <zephyr/kernel.h>

Allocate memory from the heap with a specified alignment.

This routine provides semantics similar to aligned_alloc(); memory is allocated from the heap with a specified alignment. However, one minor difference is that k_aligned_alloc() accepts any non-zero size, whereas aligned_alloc() only accepts a size that is an integral multiple of align.

Above, aligned_alloc() refers to: C11 standard (ISO/IEC 9899:2011): 7.22.3.1 The aligned_alloc function (p: 347-348)

Parameters
alignAlignment of memory requested (in bytes).
sizeAmount of memory requested (in bytes).
Returns
Address of the allocated memory if successful; otherwise NULL.

◆ k_calloc()

void * k_calloc ( size_t  nmemb,
size_t  size 
)

#include <zephyr/kernel.h>

Allocate memory from heap, array style.

This routine provides traditional calloc() semantics. Memory is allocated from the heap memory pool and zeroed.

Parameters
nmembNumber of elements in the requested array
sizeSize of each array element (in bytes).
Returns
Address of the allocated memory if successful; otherwise NULL.

◆ k_free()

void k_free ( void *  ptr)

#include <zephyr/kernel.h>

Free memory allocated from heap.

This routine provides traditional free() semantics. The memory being returned must have been allocated from the heap memory pool.

If ptr is NULL, no operation is performed.

Parameters
ptrPointer to previously allocated memory.

◆ k_heap_aligned_alloc()

void * k_heap_aligned_alloc ( struct k_heap h,
size_t  align,
size_t  bytes,
k_timeout_t  timeout 
)

#include <zephyr/kernel.h>

Allocate aligned memory from a k_heap.

Behaves in all ways like k_heap_alloc(), except that the returned memory (if available) will have a starting address in memory which is a multiple of the specified power-of-two alignment value in bytes. The resulting memory can be returned to the heap using k_heap_free().

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.
Function properties (list may not be complete)
isr-ok
Parameters
hHeap from which to allocate
alignAlignment in bytes, must be a power of two
bytesNumber of bytes requested
timeoutHow long to wait, or K_NO_WAIT
Returns
Pointer to memory the caller can now use

◆ k_heap_alloc()

void * k_heap_alloc ( struct k_heap h,
size_t  bytes,
k_timeout_t  timeout 
)

#include <zephyr/kernel.h>

Allocate memory from a k_heap.

Allocates and returns a memory buffer from the memory region owned by the heap. If no memory is available immediately, the call will block for the specified timeout (constructed via the standard timeout API, or K_NO_WAIT or K_FOREVER) waiting for memory to be freed. If the allocation cannot be performed by the expiration of the timeout, NULL will be returned. Allocated memory is aligned on a multiple of pointer sizes.

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.
Function properties (list may not be complete)
isr-ok
Parameters
hHeap from which to allocate
bytesDesired size of block to allocate
timeoutHow long to wait, or K_NO_WAIT
Returns
A pointer to valid heap memory, or NULL

◆ k_heap_free()

void k_heap_free ( struct k_heap h,
void *  mem 
)

#include <zephyr/kernel.h>

Free memory allocated by k_heap_alloc()

Returns the specified memory block, which must have been returned from k_heap_alloc(), to the heap for use by other callers. Passing a NULL block is legal, and has no effect.

Parameters
hHeap to which to return the memory
memA valid memory block, or NULL

◆ k_heap_init()

void k_heap_init ( struct k_heap h,
void *  mem,
size_t  bytes 
)

#include <zephyr/kernel.h>

Initialize a k_heap.

This constructs a synchronized k_heap object over a memory region specified by the user. Note that while any alignment and size can be passed as valid parameters, internal alignment restrictions inside the inner sys_heap mean that not all bytes may be usable as allocated memory.

Parameters
hHeap struct to initialize
memPointer to memory.
bytesSize of memory region, in bytes

◆ k_heap_realloc()

void * k_heap_realloc ( struct k_heap h,
void *  ptr,
size_t  bytes,
k_timeout_t  timeout 
)

#include <zephyr/kernel.h>

Reallocate memory from a k_heap.

Reallocates and returns a memory buffer from the memory region owned by the heap. If no memory is available immediately, the call will block for the specified timeout (constructed via the standard timeout API, or K_NO_WAIT or K_FOREVER) waiting for memory to be freed. If the allocation cannot be performed by the expiration of the timeout, NULL will be returned. Reallocated memory is aligned on a multiple of pointer sizes.

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.
Function properties (list may not be complete)
isr-ok
Parameters
hHeap from which to allocate
ptrOriginal pointer returned from a previous allocation
bytesDesired size of block to allocate
timeoutHow long to wait, or K_NO_WAIT
Returns
Pointer to memory the caller can now use, or NULL

◆ k_malloc()

void * k_malloc ( size_t  size)

#include <zephyr/kernel.h>

Allocate memory from the heap.

This routine provides traditional malloc() semantics. Memory is allocated from the heap memory pool. Allocated memory is aligned on a multiple of pointer sizes.

Parameters
sizeAmount of memory requested (in bytes).
Returns
Address of the allocated memory if successful; otherwise NULL.

◆ k_realloc()

void * k_realloc ( void *  ptr,
size_t  size 
)

#include <zephyr/kernel.h>

Expand the size of an existing allocation.

Returns a pointer to a new memory region with the same contents, but a different allocated size. If the new allocation can be expanded in place, the pointer returned will be identical. Otherwise the data will be copies to a new block and the old one will be freed as per sys_heap_free(). If the specified size is smaller than the original, the block will be truncated in place and the remaining memory returned to the heap. If the allocation of a new block fails, then NULL will be returned and the old block will not be freed or modified.

Parameters
ptrOriginal pointer returned from a previous allocation
sizeAmount of memory requested (in bytes).
Returns
Pointer to memory the caller can now use, or NULL.