Collaboration diagram for Memory Heaps:

Detailed Description

Heap Allocator related APIs.

Operation mode

The heap allocator implements a first-fit strategy and its APIs are functionally equivalent to the usual malloc() and free() library functions. The main difference is that the OS heap APIs are guaranteed to be thread safe and there is the ability to return memory blocks aligned to arbitrary powers of two.

Precondition: In order to use the heap APIs the CH_CFG_USE_HEAP option must be enabled in chconf.h.

Note: Compatible with RT and NIL.

Macros
#define	CH_HEAP_ALIGNMENT 8U
	Minimum alignment used for heap. More...

#define	CH_HEAP_AREA(name, size)
	Allocation of an aligned static heap buffer. More...

Typedefs
typedef struct memory_heap	memory_heap_t
	Type of a memory heap. More...

typedef union heap_header	heap_header_t
	Type of a memory heap header. More...

Data Structures
union	heap_header
	Memory heap block header. More...

struct	memory_heap
	Structure describing a memory heap. More...

Functions
void	_heap_init (void)
	Initializes the default heap. More...

void	chHeapObjectInit (memory_heap_t heapp, void buf, size_t size)
	Initializes a memory heap from a static memory area. More...

void *	chHeapAllocAligned (memory_heap_t *heapp, size_t size, unsigned align)
	Allocates a block of memory from the heap by using the first-fit algorithm. More...

void	chHeapFree (void *p)
	Frees a previously allocated memory block. More...

size_t	chHeapStatus (memory_heap_t heapp, size_t totalp, size_t *largestp)
	Reports the heap status. More...

static void *	chHeapAlloc (memory_heap_t *heapp, size_t size)
	Allocates a block of memory from the heap by using the first-fit algorithm. More...

static size_t	chHeapGetSize (const void *p)
	Returns the size of an allocated block. More...

Variables
static memory_heap_t	default_heap
	Default heap descriptor. More...

Macro Definition Documentation

#define CH_HEAP_ALIGNMENT 8U

Minimum alignment used for heap.

Note: Cannot use the sizeof operator in this macro.

Definition at line 46 of file chheap.h.

Referenced by chHeapAlloc(), chHeapAllocAligned(), chHeapFree(), chHeapObjectInit(), and chHeapStatus().

#define CH_HEAP_AREA	(	name,
		size
	)

Value:

ALIGNED_VAR(CH_HEAP_ALIGNMENT) \

uint8_t name[MEM_ALIGN_NEXT((size), CH_HEAP_ALIGNMENT)]

CH_HEAP_ALIGNMENT

#define CH_HEAP_ALIGNMENT

Minimum alignment used for heap.

Definition: chheap.h:46

MEM_ALIGN_NEXT

#define MEM_ALIGN_NEXT(p, a)

Aligns to the next aligned memory address.

Definition: chalign.h:78

Allocation of an aligned static heap buffer.

Definition at line 118 of file chheap.h.

Typedef Documentation

typedef struct memory_heap memory_heap_t

Type of a memory heap.

Definition at line 76 of file chheap.h.

typedef union heap_header heap_header_t

Type of a memory heap header.

Definition at line 81 of file chheap.h.

Function Documentation

void _heap_init ( void )

Initializes the default heap.

Function Class:: Not an API, this function is for internal use only.

Definition at line 107 of file chheap.c.

References chCoreAllocAlignedWithOffset(), chMtxObjectInit(), chSemObjectInit(), memory_heap::header, memory_heap::mtx, and memory_heap::provider.

Referenced by chSysInit().

Here is the call graph for this function:

void chHeapObjectInit	(	memory_heap_t *	heapp,
		void *	buf,
		size_t	size
	)

Initializes a memory heap from a static memory area.

Note: The heap buffer base and size are adjusted if the passed buffer is not aligned to CH_HEAP_ALIGNMENT. This mean that the effective heap size can be less than size.

Parameters

[out]	heapp	pointer to the memory heap descriptor to be initialized
[in]	buf	heap buffer base
[in]	size	heap size

Function Class:: Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 131 of file chheap.c.

References CH_HEAP_ALIGNMENT, chDbgCheck, chMtxObjectInit(), chSemObjectInit(), memory_heap::header, MEM_ALIGN_NEXT, memory_heap::mtx, and memory_heap::provider.

Here is the call graph for this function:

void * chHeapAllocAligned	(	memory_heap_t *	heapp,
		size_t	size,
		unsigned	align
	)

Allocates a block of memory from the heap by using the first-fit algorithm.

The allocated block is guaranteed to be properly aligned to the specified alignment.

Parameters

[in]	heapp	pointer to a heap descriptor or `NULL` in order to access the default heap.
[in]	size	the size of the block to be allocated. Note that the allocated block may be a bit bigger than the requested size for alignment and fragmentation reasons.
[in]	align	desired memory alignment

Returns: A pointer to the aligned allocated block.

Return values

NULL	if the block cannot be allocated.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 172 of file chheap.c.

References CH_HEAP_ALIGNMENT, chDbgCheck, default_heap, memory_heap::header, MEM_ALIGN_NEXT, MEM_IS_VALID_ALIGNMENT, and memory_heap::provider.

Referenced by chHeapAlloc(), and chThdCreateFromHeap().

void chHeapFree ( void * p )

Frees a previously allocated memory block.

Parameters

[in] p pointer to the memory block to be freed

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 293 of file chheap.c.

References CH_HEAP_ALIGNMENT, chDbgAssert, chDbgCheck, memory_heap::header, MEM_ALIGN_NEXT, and MEM_IS_ALIGNED.

Referenced by chThdRelease().

size_t chHeapStatus	(	memory_heap_t *	heapp,
		size_t *	totalp,
		size_t *	largestp
	)

Reports the heap status.

Note: This function is meant to be used in the test suite, it should not be really useful for the application code.

Parameters

[in]	heapp	pointer to a heap descriptor or `NULL` in order to access the default heap.
[in]	totalp	pointer to a variable that will receive the total fragmented free space or `NULL`
[in]	largestp	pointer to a variable that will receive the largest free free block found space or `NULL`

Returns: The number of fragments in the heap.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 357 of file chheap.c.

References CH_HEAP_ALIGNMENT, default_heap, and memory_heap::header.

static void* chHeapAlloc	(	memory_heap_t *	heapp,
		size_t	size
	)

inlinestatic

Allocates a block of memory from the heap by using the first-fit algorithm.

The allocated block is guaranteed to be properly aligned for a pointer data type.

Parameters

[in]	heapp	pointer to a heap descriptor or `NULL` in order to access the default heap.
[in]	size	the size of the block to be allocated. Note that the allocated block may be a bit bigger than the requested size for alignment and fragmentation reasons.

Returns: A pointer to the allocated block.

Return values

NULL	if the block cannot be allocated.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 158 of file chheap.h.

References CH_HEAP_ALIGNMENT, and chHeapAllocAligned().

Here is the call graph for this function:

static size_t chHeapGetSize ( const void * p )

inlinestatic

Returns the size of an allocated block.

Note: The returned value is the requested size, the real size is the same value aligned to the next CH_HEAP_ALIGNMENT multiple.

Parameters

[in] p pointer to the memory block

Returns: Size of the block.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 173 of file chheap.h.

Referenced by chFactoryGetBufferSize().

Variable Documentation

memory_heap_t default_heap

static

Default heap descriptor.

Definition at line 92 of file chheap.c.

Referenced by chHeapAllocAligned(), and chHeapStatus().

Detailed Description

Operation mode

Macros

Typedefs

Data Structures

Functions

Variables

Macro Definition Documentation

Typedef Documentation

Function Documentation

Variable Documentation