FreeRTOS Memory Management ( IAR )

http://www.freertos.org/a00111.html

The RTOS kernel allocates RAM each time a task, queue, mutex, software timer or semaphore is created.

The standard C library malloc() and free() functions can sometimes be used for this purpose, but ...

1. they are not always available on embedded systems,
2. they take up valuable code space,
3. they are not thread safe, and
4. they are not deterministic (the amount of time taken to execute the function will differ from call to call)

... so more often than not an alternative memory allocation implementation is required.

One embedded / real time system can have very different RAM and timing requirements to another -

so a single RAM allocation algorithm will only ever be appropriate for a subset of applications.

To get around this problem, FreeRTOS keeps the memory allocation API in its portable layer.

The portable layer is outside of the source files that implement the core RTOS functionality,
allowing an application specific implementation appropriate for the real time system being developed to be provided.

When the RTOS kernel requires RAM, instead of calling malloc(), it instead calls pvPortMalloc().
When RAM is being freed, instead of calling free(), the RTOS kernel calls vPortFree().

Memory allocation implementations included in the RTOS source code download

The FreeRTOS download includes four sample memory allocation implementations, each of which are described in the following subsections.

The subsections also include information on when each of the provided implementations might be the most appropriate to select.

Each provided implementation is contained in a separate source file (heap_1.c, heap_2.c, heap_3.c and heap_4.c respectively)
which are located in the Source/Portable/MemMang directory of the main RTOS source code download.
Other implementations can be added as needed. Exactly one of these source files should be included in a project at a time.

heap_1.c - Heap secton name is .bss, kind is zero(Zero-initialized),  type is data(Read/write)

This is the simplest implementation of all. It does not permit memory to be freed once it has been allocated.
Despite this, heap_1.cvice versa appropriate for a large number of embedded applications.

This is because the majority of deeply embedded applications create all the tasks, queues, semaphores, etc.
required when the system boots, and then use all of these objects for the lifetime of program
(until the application is switched off again, or is rebooted). Nothing ever gets deleted.

The implementation simply subdivides a single array into smaller blocks as RAM is requested.
The total size of the array (the total size of the heap) is set by configTOTAL_HEAP_SIZE - which is defined in FreeRTOSConfig.h.

The xPortGetFreeHeapSize() API function returns the total amount of heap space that remains unallocated, allowing the configTOTAL_HEAP_SIZE setting to be optimised.

The heap_1 implementation:

• Can be used if your application never deletes a task, queue, semaphore, mutex, etc. (which actually covers the majority of applications in which FreeRTOS gets used).
• Is always deterministic (always takes the same amount of time to execute).

#define MPU_WRAPPERS_INCLUDED_FROM_API_FILE

#include "FreeRTOS.h"
#include "task.h"

#undef MPU_WRAPPERS_INCLUDED_FROM_API_FILE

/* A few bytes might be lost to byte aligning the heap start address. */
#define configADJUSTED_HEAP_SIZE    ( configTOTAL_HEAP_SIZE - portBYTE_ALIGNMENT )

/* Allocate the memory for the heap. */
static unsigned char ucHeap[ configTOTAL_HEAP_SIZE ];
static size_t xNextFreeByte = ( size_t ) ;

/*-----------------------------------------------------------*/

void *pvPortMalloc( size_t xWantedSize )
{
}
/*-----------------------------------------------------------*/

void vPortFree( void *pv )
{
    /* Memory cannot be freed using this scheme.  See heap_2.c, heap_3.c and heap_4.c for alternative implementations, 
    and the memory management pages ofhttp://www.FreeRTOS.org for more information. */

    ( void ) pv;

    /* Force an assert as it is invalid to call this function. */
    configASSERT( pv == NULL );
}
/*-----------------------------------------------------------*/

void vPortInitialiseBlocks( void )
{
    /* Only required when static memory is not cleared. */
    xNextFreeByte = ( size_t ) ;
}
/*-----------------------------------------------------------*/

size_t xPortGetFreeHeapSize( void )
{
    return ( configADJUSTED_HEAP_SIZE - xNextFreeByte );
}

heap_2.c - Heap secton name is .bss, kind is zero(Zero-initialized),  type is data(Read/write)

This scheme uses a best fit algorithm and, unlike scheme 1, allows previously allocated blocks to be freed.
It does not however combine adjacent free blocks into a single large block (it does not include a coalescence algorithm -
see heap_4.c for an implementation that does coalescence free blocks).

The total amount of available heap space is set by configTOTAL_HEAP_SIZE - which is defined in FreeRTOSConfig.h.

The xPortGetFreeHeapSize() API function returns the total amount of heap space that remains unallocated
(allowing the configTOTAL_HEAP_SIZE setting to be optimised), but does not provided information on
how the unallocated memory is fragmented into smaller blocks.

This implementation:

• Can be used even when the application repeatedly deletes tasks, queues, semaphores, mutexes, etc., with the caveat below regarding memory fragmentation.
• Should not be used if the memory being allocated and freed is of a random size.
  For example:Could possible result in memory fragmentation problems if your application queues, tasks, semaphores, mutexes, etc.
  in an unpredictable order. This would be unlikely for nearly all applications but should be kept in mind.
  • If an application dynamically creates and deletes tasks, and the size of the stack allocated to the tasks being created is always the same,
    then heap2.c can be used in most cases.
    However, if the size of the stack allocated to the tasks being created was not always the same,
    then the available free memory might become fragmented into many small blocks,
    eventually resulting in allocation failures. heap_4.c would be a better choise in this case.
  • If an application dynamically creates and deletes queues, and the queue storage area is the same in each case
    (the queue storage area is the queue item size multiplied by the length of the queue),
    then heap_2.c can be used in most cases.
    However, if the queue storage area were not the same in each case,
    then the available free memory might become fragmented into many small blocks,
    eventually resulting in allocation failures. heap_4.c would be a better choise in this case.
  • The application called pvPortMalloc() and vPortFree() directly, rather than just indirectly through other FreeRTOS API functions.
• Is not deterministic - but is much more efficient that most standard C library malloc implementations.

heap_2.c is suitable for most small real time systems that have to dynamically create tasks.

#define MPU_WRAPPERS_INCLUDED_FROM_API_FILE

#include "FreeRTOS.h"
#include "task.h"

#undef MPU_WRAPPERS_INCLUDED_FROM_API_FILE

/* A few bytes might be lost to byte aligning the heap start address. */
#define configADJUSTED_HEAP_SIZE    ( configTOTAL_HEAP_SIZE - portBYTE_ALIGNMENT )

/*
 * Initialises the heap structures before their first use.
 */
static void prvHeapInit( void );

/* Allocate the memory for the heap. */
static unsigned char ucHeap[ configTOTAL_HEAP_SIZE ];

heap_3.c - Heap secton name is HEAP, kind is uninit : __Heap_Handler  = DLMalloc

This implements a simple wrapper for the standard C library malloc() and free() functions that will, in most cases,
be supplied with your chosen compiler. The wrapper simply makes the malloc() and free() functions thread safe.

This implementation:

• Requires the linker to setup a heap, and the compiler library to provide malloc() and free() implementations.
• Is not deterministic.
• Will probably considerably increase the RTOS kernel code size.

Note that the configTOTAL_HEAP_SIZE setting in FreeRTOSConfig.h has no effect when heap_3 is used.

dlmalloc.c : malloc(), free()

Heap Size in *.icf  : define symbol __ICFEDIT_size_heap__   = 0x2000;

/*
 * Implementation of pvPortMalloc() and vPortFree() that relies on the
 * compilers own malloc() and free() implementations.
 *
 * This file can only be used if the linker is configured to to generate
 * a heap memory area.
 *
 * See heap_1.c, heap_2.c and heap_4.c for alternative implementations, and the
 * memory management pages of http://www.FreeRTOS.org for more information.
 */

#include <stdlib.h>

/* Defining MPU_WRAPPERS_INCLUDED_FROM_API_FILE prevents task.h from redefining
all the API functions to use the MPU wrappers.  That should only be done when
task.h is included from an application file. */
#define MPU_WRAPPERS_INCLUDED_FROM_API_FILE

#include "FreeRTOS.h"
#include "task.h"

#undef MPU_WRAPPERS_INCLUDED_FROM_API_FILE

/*-----------------------------------------------------------*/

void *pvPortMalloc( size_t xWantedSize )
{
void *pvReturn;

    vTaskSuspendAll();
    {
        pvReturn = malloc( xWantedSize );
        traceMALLOC( pvReturn, xWantedSize );
    }
    xTaskResumeAll();

    #if( configUSE_MALLOC_FAILED_HOOK == 1 )
    {
        if( pvReturn == NULL )
        {
            extern void vApplicationMallocFailedHook( void );
            vApplicationMallocFailedHook();
        }
    }
    #endif

    return pvReturn;
}
/*-----------------------------------------------------------*/

void vPortFree( void *pv )
{
    if( pv )
    {
        vTaskSuspendAll();
        {
            free( pv );
            traceFREE( pv,  );
        }
        xTaskResumeAll();
    }
}

heap_4.c - Heap secton name is .bss, kind is zero(Zero-initialized),  type is data(Read/write)

This scheme uses a first fit algorithm and, unlike scheme 2, does combine adjacent free memory blocks into a single large block
(it does include a coalescence algorithm).

The total amount of available heap space is set by configTOTAL_HEAP_SIZE - which is defined in FreeRTOSConfig.h.

The xPortGetFreeHeapSize() API function returns the total amount of heap space that remains unallocated
(allowing the configTOTAL_HEAP_SIZE setting to be optimised), but does not provided information on how the unallocated memory is fragmented into smaller blocks.

This implementation:

• Can be used even when the application repeatedly deletes tasks, queues, semaphores, mutexes, etc..
• Is much less likely than the heap_2 implementation to result in a heap space that is badly fragmented into multiple small blocks
  - even when the memory being allocated and freed is of random size.
• Is not deterministic - but is much more efficient that most standard C library malloc implementations.

heap_4.c is particularly useful for applications that want to use the portable layer memory allocation schemes directly in the application code
(rather than just indirectly by calling API functions that themselves call pvPortMalloc() and vPortFree()).

/*
 * A sample implementation of pvPortMalloc() and vPortFree() that combines
 * (coalescences) adjacent memory blocks as they are freed, and in so doing
 * limits memory fragmentation.
 *
 * See heap_1.c, heap_2.c and heap_3.c for alternative implementations, and the
 * memory management pages of http://www.FreeRTOS.org for more information.
 */
#include <stdlib.h>

/* Defining MPU_WRAPPERS_INCLUDED_FROM_API_FILE prevents task.h from redefining
all the API functions to use the MPU wrappers.  That should only be done when
task.h is included from an application file. */
#define MPU_WRAPPERS_INCLUDED_FROM_API_FILE

#include "FreeRTOS.h"
#include "task.h"

#undef MPU_WRAPPERS_INCLUDED_FROM_API_FILE

/* Block sizes must not get too small. */
#define heapMINIMUM_BLOCK_SIZE    ( ( size_t ) ( heapSTRUCT_SIZE * 2 ) )

/* Assumes 8bit bytes! */
#define heapBITS_PER_BYTE        ( ( size_t ) 8 )

/* A few bytes might be lost to byte aligning the heap start address. */
#define heapADJUSTED_HEAP_SIZE    ( configTOTAL_HEAP_SIZE - portBYTE_ALIGNMENT )

/* Allocate the memory for the heap. */
static unsigned char ucHeap[ configTOTAL_HEAP_SIZE ];