Memory Management
[Nut/OS API]

Collaboration diagram for Memory Management:

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.


Defines

#define MEMOVHD   (sizeof(size_t) + sizeof(0xDEADBEEF))
 Overhead for each allocated memory clock.

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 * NutHeapAlloc (size_t size)
 Allocate a block from heap memory.
void * NutHeapAllocClear (size_t size)
 Allocate an initialized block from heap memory.
void * NutHeapRealloc (void *block, size_t size)
 Change the size of a memoryblock. If more memory is requested than available at that block the data is copied to a new, bigger block.
int NutHeapFree (void *block)
 Return a block to heap memory.
void NutHeapAdd (void *addr, size_t size)
 Add a new memory region to the free heap.
size_t NutHeapAvailable (void)
 Return the number of bytes available.

Variables

HEAPNODE *volatile heapFreeList
 List of free nodes.


Define Documentation

#define MEMOVHD   (sizeof(size_t) + sizeof(0xDEADBEEF))

Overhead for each allocated memory clock.

Definition at line 164 of file heap.c.

Referenced by NutHeapAlloc(), and NutHeapRealloc().


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 85 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 105 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 125 of file malloc.c.

References ENOMEM, errno, and NutHeapRealloc().

void* NutHeapAlloc ( 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().

Note:
Do not use this function in interrupt routines.
Parameters:
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 220 of file heap.c.

References __heap_trf, __heap_trs, ALLOC_THRESHOLD, fprintf(), fputs(), HEAPNODE::hn_next, HEAPNODE::hn_size, and MEMOVHD.

void* NutHeapAllocClear ( 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:
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 326 of file heap.c.

References memset(), and NutHeapAlloc().

void* NutHeapRealloc ( void *  block,
size_t  size 
)

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

Parameters:
block Points to a memory block previously allocated through a call to NutHeapAlloc(). If block is NULL this call is equivalent to malloc.
size The size of the new allocated block.
Returns:
> NULL A poiner to the memoryblock

NULL Reallocation has faild. The data is still available at the old address.

Todo:
see if we can do some codesharing with malloc
Todo:
add some checks like reallocating free mem, etc

Definition at line 352 of file heap.c.

References __heap_trf, __heap_trs, ALLOC_THRESHOLD, fprintf(), fputs(), HEAPNODE::hn_next, HEAPNODE::hn_size, memcpy(), MEMOVHD, NutHeapAlloc(), NutHeapFree(), and REALLOC_THRESHOLD.

int NutHeapFree ( 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.

Note:
Do not use this function in interrupt routines.
Parameters:
block Points to a memory block previously allocated through a call to NutHeapAlloc().
Returns:
0 on success, -1 if the caller tried to free a block which had been previously released.

-1 if the caller tried to free a block which had been previously released.

-2 if Beef is not valid. Block will not be freed

-3 block is NULL

Definition at line 479 of file heap.c.

References __heap_trf, __heap_trs, fprintf(), fputs(), HEAPNODE::hn_next, and HEAPNODE::hn_size.

void NutHeapAdd ( void *  addr,
size_t  size 
)

Add a new memory region to the free heap.

This function is automatically called by Nut/OS during initialization.

Applications typically do not call this function.

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

Definition at line 596 of file heap.c.

References NutHeapFree().

size_t NutHeapAvailable ( void   ) 

Return the number of bytes available.

Returns:
Number of bytes.

Definition at line 613 of file heap.c.


Variable Documentation

HEAPNODE* volatile heapFreeList

List of free nodes.

Definition at line 152 of file heap.c.


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