Memory Management
[Nut/OS API]

Collaboration diagram for Memory Management:
Dynamic memory management. More...

Defines

#define NUTMEM_GUARD_BYTES   0
#define NUT_HEAP_OVERHEAD   (sizeof(HEAPNODE) - sizeof(HEAPNODE *))
 Number of bytes used for management information.
#define NUTMEM_HEAPNODE_MIN   (sizeof(HEAPNODE) + (2 * NUTMEM_GUARD_BYTES))
 Minimum size of a node.

Functions

void * malloc (size_t len)
 Allocate a block from heap memory.
void free (void *p)
 Return a block to heap memory.
void * realloc (void *ptr, size_t len)
 Reallocate a block from heap memory.
void * NutHeapRootAlloc (HEAPNODE **root, size_t size)
 Allocate a block from heap memory.
void * NutHeapRootAllocClear (HEAPNODE **root, size_t size)
 Allocate an initialized block from heap memory.
int NutHeapRootFree (HEAPNODE **root, void *block)
 Return a block to heap memory.
void NutHeapRootAdd (HEAPNODE **root, void *addr, size_t size)
 Add a new memory region to the heap.
size_t NutHeapRootAvailable (HEAPNODE **root)
 Return the total number of bytes available.
size_t NutHeapRootRegionAvailable (HEAPNODE **root)
 Return the size of the largest block available.
void * NutHeapRootRealloc (HEAPNODE **root, void *block, size_t size)
 Change the size of an allocated memory block.
int NutHeapCheck (void)
 Check consistency of heap.
void NutHeapDump (void *stream)
 Dump heap memory to a given stream.

Variables

HEAPNODEheapFreeList
 List of free nodes in normal memory.

Detailed Description

Dynamic memory management.

Dynamic memory allocations are made from the heap. The heap is a global resource containing all of the free memory in the system. The heap is handled as a linked list of unused blocks of memory, the so called free-list.

The heap manager uses best fit, address ordered algorithm to keep the free-list as unfragmented as possible. This strategy is intended to ensure that more useful allocations can be made. We end up with relatively few large free blocks rather than lots of small ones.


Define Documentation

#define NUTMEM_GUARD_BYTES   0

Definition at line 65 of file heap.c.

Referenced by NutHeapRootAlloc(), NutHeapRootFree(), and NutHeapRootRealloc().

#define NUT_HEAP_OVERHEAD   (sizeof(HEAPNODE) - sizeof(HEAPNODE *))

Number of bytes used for management information.

Definition at line 69 of file heap.c.

Referenced by NutHeapRootAlloc(), NutHeapRootAvailable(), NutHeapRootFree(), NutHeapRootRealloc(), and NutHeapRootRegionAvailable().

#define NUTMEM_HEAPNODE_MIN   (sizeof(HEAPNODE) + (2 * NUTMEM_GUARD_BYTES))

Minimum size of a node.

Definition at line 73 of file heap.c.

Referenced by NutHeapRootAlloc(), and NutHeapRootRealloc().


Function Documentation

void* malloc ( size_t  len  ) 

Allocate a block from heap memory.

This function simply calls NutHeapAlloc(). It overrides the function of the runtime library, when the application is linked with nutcrt or nutcrtf.

Parameters:
len Size of the requested memory block.
Returns:
Pointer to the allocated memory block if the function is successful or NULL if the requested amount of memory is not available.

Definition at line 64 of file malloc.c.

References ENOMEM, errno, and NutHeapAlloc.

void free ( void *  p  ) 

Return a block to heap memory.

This function simply calls NutHeapFree(). It overrides the function of the runtime library, when the application is linked with nutcrt or nutcrtf.

Parameters:
p Points to a memory block previously allocated through a call to malloc().

Definition at line 84 of file malloc.c.

References NutHeapFree.

void* realloc ( void *  ptr,
size_t  len 
)

Reallocate a block from heap memory.

This function simply calls NutHeapRealloc(). It overrides the function of the runtime library, when the application is linked with nutcrt or nutcrtf.

Parameters:
ptr Pointer to memory block previously allocated with malloc to be reallocated. If this is NULL, a new block is allocated.
len Size of the requested memory block.
Returns:
Pointer to the reallocated memory block if the function is successful or NULL if the requested amount of memory is not available.

Definition at line 66 of file realloc.c.

References ENOMEM, errno, and NutHeapRealloc.

void* NutHeapRootAlloc ( HEAPNODE **  root,
size_t  size 
)

Allocate a block from heap memory.

This functions allocates a memory block of the specified size and returns a pointer to that block.

The actual size of the allocated block is larger than the requested size because of space required for maintenance information. This additional information is invisible to the application.

The routine looks for the smallest block that will meet the required size and releases it to the caller. If the block being requested is usefully smaller than the smallest free block then the block from which the request is being met is split in two. The unused portion is put back into the free-list.

The contents of the allocated block is unspecified. To allocate a block with all bytes set to zero use NutHeapAllocClear().

Parameters:
root Points to the linked list of free nodes.
size Size of the requested memory block.
Returns:
Pointer to the allocated memory block if the function is successful or NULL if no free block of the requested size is available.

Definition at line 201 of file heap.c.

References _HEAPNODE::hn_next, _HEAPNODE::hn_size, NUT_HEAP_OVERHEAD, NUTMEM_GUARD_BYTES, NUTMEM_HEAPNODE_MIN, and NUTMEM_TOP_ALIGN.

void* NutHeapRootAllocClear ( HEAPNODE **  root,
size_t  size 
)

Allocate an initialized block from heap memory.

This functions allocates a memory block of the specified size with all bytes initialized to zero and returns a pointer to that block.

Parameters:
root Points to the linked list of free nodes.
size Size of the requested memory block.
Returns:
Pointer to the allocated memory block if the function is successful or NULL if the requested amount of memory is not available.

Definition at line 296 of file heap.c.

References memset(), and NutHeapRootAlloc().

int NutHeapRootFree ( HEAPNODE **  root,
void *  block 
)

Return a block to heap memory.

An application calls this function, when a previously allocated memory block is no longer needed.

The heap manager checks, if the released block adjoins any other free regions. If it does, then the adjacent free regions are joined together to form one larger region.

Parameters:
root Points to the linked list of free nodes.
block Points to a memory block previously allocated.
Returns:
0 on success, -1 if the caller tried to free a block which had been previously released, -2 if the block had been corrupted. Furthermore, -3 is returned if block is a NULL pointer, but using this may change as C99 allows this.

Definition at line 328 of file heap.c.

References _HEAPNODE::hn_next, _HEAPNODE::hn_size, NUT_HEAP_OVERHEAD, NUTMEM_GUARD_BYTES, and NUTPANIC().

void NutHeapRootAdd ( HEAPNODE **  root,
void *  addr,
size_t  size 
)

Add a new memory region to the heap.

This function can be called more than once to manage non-continous memory regions. It is automatically called by Nut/OS during initialization.

Parameters:
addr Start address of the memory region.
size Number of bytes of the memory region.

Definition at line 435 of file heap.c.

References _HEAPNODE::hn_size, NutHeapRootFree(), NUTMEM_BOTTOM_ALIGN, and NUTMEM_TOP_ALIGN.

size_t NutHeapRootAvailable ( HEAPNODE **  root  ) 

Return the total number of bytes available.

Returns:
Number of bytes.

Definition at line 452 of file heap.c.

References _HEAPNODE::hn_next, _HEAPNODE::hn_size, and NUT_HEAP_OVERHEAD.

size_t NutHeapRootRegionAvailable ( HEAPNODE **  root  ) 

Return the size of the largest block available.

Returns:
Number of bytes.

Definition at line 470 of file heap.c.

References _HEAPNODE::hn_next, _HEAPNODE::hn_size, and NUT_HEAP_OVERHEAD.

void* NutHeapRootRealloc ( HEAPNODE **  root,
void *  block,
size_t  size 
)

Change the size of an allocated memory block.

If more memory is requested than available at that block the data is copied to a new, bigger block.

Parameters:
block Points to a previously allocated memory block. If NULL, then this call is equivalent to NutHeapRootAlloc().
size The requested new size. If 0, then this call is equivalent to NutHeapRootFree().
Returns:
A pointer to the memory block on success or NULL on failures.

Definition at line 501 of file heap.c.

References _HEAPNODE::hn_next, _HEAPNODE::hn_size, memcpy(), NUT_HEAP_OVERHEAD, NutHeapRootAlloc(), NutHeapRootFree(), NUTMEM_GUARD_BYTES, NUTMEM_HEAPNODE_MIN, and NUTMEM_TOP_ALIGN.

int NutHeapCheck ( void   ) 

Check consistency of heap.

Right now this function will just return 0 unless NUTDEBUG_HEAP is defined.

Returns:
-1 if any error has been detected, 0 otherwise.

Definition at line 638 of file heap.c.

void NutHeapDump ( void *  stream  ) 

Dump heap memory to a given stream.

Definition at line 657 of file heap.c.

References fprintf(), _HEAPNODE::hn_next, and _HEAPNODE::hn_size.


Variable Documentation

HEAPNODE* heapFreeList

List of free nodes in normal memory.

Definition at line 79 of file heap.c.


© 2000-2007 by egnite Software GmbH - visit http://www.ethernut.de/