---

Heap Management
[Nut/OS API]

Dynamic memory management. More...

Functions
void *	malloc (size_t len)
	Allocate a block from heap memory.
void	free (void *p)
	Return a block to heap memory.
void *	NutHeapAlloc (u_short size)
	Allocate a block from heap memory.
void *	NutHeapAllocClear (u_short size)
	Allocate an initialized block from heap memory.
int	NutHeapFree (void *block)
	Return a block to heap memory.
void	NutHeapAdd (void *addr, u_short size)
	Add a new memory region to the free heap.
u_short	NutHeapAvailable (void)
	Return the number of bytes available.
Variables
HEAPNODE *volatile	heapFreeList
	List of free nodes.
u_short	available
	Number of bytes available.

---

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.

---

Function Documentation

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* 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.

void NutHeapAdd (  void *    addr, u_short    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.

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

u_short NutHeapAvailable (  void    )

Return the number of bytes available. Returns: Number of bytes. Examples: httpd/httpserv.c, playmp3/playmp3.c, portdio/portdio.c, tcps/tcps.c, and timers/timers.c.

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.

---

Variable Documentation

u_short available

Number of bytes available.

HEAPNODE* volatile heapFreeList

List of free nodes.

---