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 *	NutHeapAlloc (size_t size)
	Allocate a block from heap memory.
void *	NutHeapAllocClear (size_t size)
	Allocate an initialized block from heap memory.
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.

---

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. Examples: pppc/pppc.c, and rs232d/rs232d.c.

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().

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.

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.

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.

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.

size_t NutHeapAvailable (  void   )

Return the number of bytes available. Returns: Number of bytes.

---