ChibiOS/NIL  3.2.2
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 42 of file chmemheaps.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)]
#define CH_HEAP_ALIGNMENT
Minimum alignment used for heap.
Definition: chmemheaps.h:42
#define MEM_ALIGN_NEXT(p, a)
Aligns to the new aligned memory address.
Definition: ch.h:781

Allocation of an aligned static heap buffer.

Definition at line 114 of file chmemheaps.h.

Typedef Documentation

typedef struct memory_heap memory_heap_t

Type of a memory heap.

Definition at line 72 of file chmemheaps.h.

typedef union heap_header heap_header_t

Type of a memory heap header.

Definition at line 77 of file chmemheaps.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 chmemheaps.c.

References chCoreAllocAlignedWithOffset(), 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]heapppointer to the memory heap descriptor to be initialized
[in]bufheap buffer base
[in]sizeheap 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 chmemheaps.c.

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

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]heapppointer to a heap descriptor or NULL in order to access the default heap.
[in]sizethe 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]aligndesired memory alignment
Returns
A pointer to the aligned allocated block.
Return values
NULLif 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 chmemheaps.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().

void chHeapFree ( void *  p)

Frees a previously allocated memory block.

Parameters
[in]ppointer 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 chmemheaps.c.

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

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]heapppointer to a heap descriptor or NULL in order to access the default heap.
[in]totalppointer to a variable that will receive the total fragmented free space or NULL
[in]largestppointer 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 chmemheaps.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]heapppointer to a heap descriptor or NULL in order to access the default heap.
[in]sizethe 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
NULLif 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 154 of file chmemheaps.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]ppointer 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 169 of file chmemheaps.h.

Referenced by chFactoryGetBufferSize().

Variable Documentation

memory_heap_t default_heap
static

Default heap descriptor.

Definition at line 92 of file chmemheaps.c.

Referenced by chHeapAllocAligned(), and chHeapStatus().