|
|||||||
 
|
|
FreeRTOS Sponsors
|
|
| Get seen by 1000s of embedded engineers a month | |
|
|
|
|
|
|
|
|
|
Customisation
[Configuration]
FreeRTOS is customised using a configuration file called FreeRTOSConfig.h. Every
FreeRTOS application must have a FreeRTOSConfig.h header file in its pre-processor
include path. FreeRTOSConfig.h tailors the RTOS kernel to the application being
built. It is therefore specific to the application, not the RTOS, and should be
located in an application directory, not in one of the RTOS kernel source code
directories.
Each demo application included in the RTOS source code download has its own FreeRTOSConfig.h file. Some of the demos are quite old and do not contain all the available configuration options. Configuration options that are omitted are set to a default value within an RTOS source file.
Here is a typical FreeRTOSConfig.h definition, followed by an explanation of each parameter:
#ifndef FREERTOS_CONFIG_H
#define FREERTOS_CONFIG_H
/* Here is a good place to include header files that are required across
your application. */
#include "something.h"
#define configUSE_PREEMPTION 1
#define configUSE_PORT_OPTIMISED_TASK_SELECTION 0
#define configUSE_TICKLESS_IDLE 0
#define configCPU_CLOCK_HZ 60000000
#define configTICK_RATE_HZ 250
#define configMAX_PRIORITIES 5
#define configMINIMAL_STACK_SIZE 128
#define configTOTAL_HEAP_SIZE 10240
#define configMAX_TASK_NAME_LEN 16
#define configUSE_TRACE_FACILITY 0
#define configUSE_16_BIT_TICKS 0
#define configIDLE_SHOULD_YIELD 1
#define configUSE_MUTEXES 0
#define configUSE_RECURSIVE_MUTEXES 0
#define configUSE_COUNTING_SEMAPHORES 0
#define configUSE_ALTERNATIVE_API 0 /* Deprecated! */
#define configQUEUE_REGISTRY_SIZE 10
#define configUSE_QUEUE_SETS 0
/* Hook function related definitions. */
#define configUSE_IDLE_HOOK 0
#define configUSE_TICK_HOOK 0
#define configCHECK_FOR_STACK_OVERFLOW 0
#define configUSE_MALLOC_FAILED_HOOK 0
/* Run time stats gathering related definitions. */
#define configGENERATE_RUN_TIME_STATS 0
/* Co-routine related definitions. */
#define configUSE_CO_ROUTINES 0
#define configMAX_CO_ROUTINE_PRIORITIES 1
/* Software timer related definitions. */
#define configUSE_TIMERS 1
#define configTIMER_TASK_PRIORITY 3
#define configTIMER_QUEUE_LENGTH 10
#define configTIMER_TASK_STACK_DEPTH configMINIMAL_STACK_SIZE
/* Interrupt nesting behaviour configuration. */
#define configKERNEL_INTERRUPT_PRIORITY [dependent of processor]
#define configMAX_SYSCALL_INTERRUPT_PRIORITY [dependent on processor and application]
/* Define to trap errors during development. */
#define configASSERT( ( x ) ) if( ( x ) == 0 ) vCallAssert( __FILE__, __LINE__ )
/* Optional functions - most linkers will remove unused functions anyway. */
#define INCLUDE_vTaskPrioritySet 1
#define INCLUDE_uxTaskPriorityGet 1
#define INCLUDE_vTaskDelete 1
#define INCLUDE_vTaskSuspend 1
#define INCLUDE_xResumeFromISR 1
#define INCLUDE_vTaskDelayUntil 1
#define INCLUDE_vTaskDelay 1
#define INCLUDE_xTaskGetSchedulerState 1
#define INCLUDE_xTaskGetCurrentTaskHandle 1
#define INCLUDE_uxTaskGetStackHighWaterMark 0
#define INCLUDE_xTaskGetIdleTaskHandle 0
#define INCLUDE_xTimerGetTimerDaemonTaskHandle 0
#define INCLUDE_pcTaskGetTaskName 0
#define INCLUDE_eTaskGetState 0
/* A header file that defines trace macro can be included here. */
#endif /* FREERTOS_CONFIG_H */
'config' Parameters
configUSE_PREEMPTION
Set to 1 to use the preemptive RTOS scheduler, or 0 to use the cooperative RTOS scheduler.
configUSE_PORT_OPTIMISED_TASK_SELECTION
Some FreeRTOS ports have two methods of selecting the next task to execute - a generic method, and a method that is specific to that port.The Generic method:
-
Is used when configUSE_PORT_OPTIMISED_TASK_SELECTION is set to 0, or when
a port specific method is not implemented.
-
Can be used with all FreeRTOS ports.
-
Is completely written in C, making it less efficient than a port specific
method.
-
Does not impose a limit on the maximum number of available priorities.
A port specific method:
-
Is not available for all ports.
-
Is used when configUSE_PORT_OPTIMISED_TASK_SELECTION is set to 1.
-
Relies on one or more architecture specific assembly instructions
(typically a Count Leading Zeros [CLZ] of equivalent instruction) so can
only be used with the architecture for which it was specifically written.
-
Is more efficient than the generic method.
- Typically imposes a limit of 32 on the maximum number of available priorities.
configUSE_TICKLESS_IDLE
Set configUSE_TICKLESS_IDLE to 1 to use the low power tickless mode, or 0 to keep the tick interrupt running at all times.
configUSE_IDLE_HOOK
Set to 1 if you wish to use an idle hook, or 0 to omit an idle hook.
configUSE_MALLOC_FAILED_HOOK
The kernel uses a call to pvPortMalloc() to allocate memory from the heap each time a task, queue or semaphore is created. The official FreeRTOS download includes four sample memory allocation schemes for this purpose. The schemes are implemented in the heap_1.c, heap_2.c, heap_3.c and heap_4.c source files respectively. configUSE_MALLOC_FAILED_HOOK is only relevant when one of these three sample schemes is being used.The malloc() failed hook function is a hook (or callback) function that, if defined and configured, will be called if pvPortMalloc() ever returns NULL. NULL will be returned only if there is insufficient FreeRTOS heap memory remaining for the requested allocation to succeed.
If configUSE_MALLOC_FAILED_HOOK is set to 1 then the application must define a malloc() failed hook function. If configUSE_MALLOC_FAILED_HOOK is set to 0 then the malloc() failed hook function will not be called, even if one is defined. Malloc() failed hook functions must have the name and prototype shown below.
void vApplicationMallocFailedHook( void );
configUSE_TICK_HOOK
Set to 1 if you wish to use an tick hook, or 0 to omit an tick hook.
configCPU_CLOCK_HZ
Enter the frequency in Hz at which the internal clock that driver the peripheral used to generate the tick interrupt will be executing - this is normally the same clock that drives the internal CPU clock. This value is required in order to correctly configure timer peripherals.
configTICK_RATE_HZ
The frequency of the RTOS tick interrupt.The tick interrupt is used to measure time. Therefore a higher tick frequency means time can be measured to a higher resolution. However, a high tick frequency also means that the RTOS kernel will use more CPU time so be less efficient. The RTOS demo applications all use a tick rate of 1000Hz. This is used to test the RTOS kernel and is higher than would normally be required.
More than one task can share the same priority. The RTOS scheduler will share processor time between tasks of the same priority by switching between the tasks during each RTOS tick. A high tick rate frequency will therefore also have the effect of reducing the 'time slice' given to each task.
configMAX_PRIORITIES
The number of priorities available to the application tasks. Any number of tasks can share the same priority. Co-routines are prioritised separately - see configMAX_CO_ROUTINE_PRIORITIES.Each available priority consumes RAM within the RTOS kernel so this value should not be set any higher than actually required by your application.
configMINIMAL_STACK_SIZE
The size of the stack used by the idle task. Generally this should not be reduced from the value set in the FreeRTOSConfig.h file provided with the demo application for the port you are using.
configTOTAL_HEAP_SIZE
The total amount of RAM available to the RTOS kernel.This value will only be used if your application makes use of one of the sample memory allocation schemes provided in the FreeRTOS source code download. See the memory configuration section for further details.
configMAX_TASK_NAME_LEN
The maximum permissible length of the descriptive name given to a task when the task is created. The length is specified in the number of characters including the NULL termination byte.
configUSE_TRACE_FACILITY
Set to 1 if you wish to include additional structure members and functions to assist with execution visualisation and tracing.
configUSE_16_BIT_TICKS
Time is measured in 'ticks' - which is the number of times the tick interrupt has executed since the RTOS kernel was started. The tick count is held in a variable of type portTickType.Defining configUSE_16_BIT_TICKS as 1 causes portTickType to be defined (typedef'ed) as an unsigned 16bit type. Defining configUSE_16_BIT_TICKS as 0 causes portTickType to be defined (typedef'ed) as an unsigned 32bit type.
Using a 16 bit type will greatly improve performance on 8 and 16 bit architectures, but limits the maximum specifiable time period to 65535 'ticks'. Therefore, assuming a tick frequency of 250Hz, the maximum time a task can delay or block when a 16bit counter is used is 262 seconds, compared to 17179869 seconds when using a 32bit counter.
configIDLE_SHOULD_YIELD
This parameter controls the behaviour of tasks at the idle priority. It only has an effect if:- The preemptive scheduler is being used.
- The users application creates tasks that run at the idle priority.
When tasks share the idle priority the behaviour can be slightly different. When configIDLE_SHOULD_YIELD is set to 1 the idle task will yield immediately should any other task at the idle priority be ready to run. This ensures the minimum amount of time is spent in the idle task when application tasks are available for scheduling. This behaviour can however have undesirable effects (depending on the needs of your application) as depicted below:
This diagram shows the execution pattern of four tasks at the idle priority. Tasks A, B and C are application tasks. Task I is the idle task. A context switch occurs with regular period at times T0, T1, ..., T6. When the idle task yields task A starts to execute - but the idle task has already taken up some of the current time slice. This results in task I and task A effectively sharing a time slice. The application tasks B and C therefore get more processing time than the application task A.
This situation can be avoided by:
- If appropriate, using an idle hook in place of separate tasks at the idle priority.
- Creating all application tasks at a priority greater than the idle priority.
- Setting configIDLE_SHOULD_YIELD to 0.
configUSE_MUTEXES
Set to 1 to include mutex functionality in the build, or 0 to omit mutex functionality from the build. Readers should familiarise themselves with the differences between mutexes and binary semaphores in relation to the FreeRTOS functionality.
configUSE_RECURSIVE_MUTEXES
Set to 1 to include recursive mutex functionality in the build, or 0 to omit recursive mutex functionality from the build.
configUSE_COUNTING_SEMAPHORES
Set to 1 to include counting semaphore functionality in the build, or 0 to omit counting semaphore functionality from the build.
configUSE_ALTERNATIVE_API
Set to 1 to include the 'alternative' queue functions in the build, or 0 to omit the 'alternative' queue functions from the build. The alternative API is described within the queue.h header file. The alternative API is deprecated and should not be used in new designs.
configCHECK_FOR_STACK_OVERFLOW
The stack overflow detection page describes the use of this parameter.
configQUEUE_REGISTRY_SIZE
The queue registry has two purposes, both of which are associated with RTOS kernel aware debugging:- It allows a textual name to be associated with a queue for easy queue identification within a debugging GUI.
- It contains the information required by a debugger to locate each registered queue and semaphore.
configQUEUE_REGISTRY_SIZE defines the maximum number of queues and semaphores that can be registered. Only those queues and semaphores that you want to view using a RTOS kernel aware debugger need be registered. See the API reference documentation for vQueueAddToRegistry() and vQueueUnregisterQueue() for more information.
configUSE_QUEUE_SETS
Set to 1 to include queue set functionality (the ability to block, or pend, on multiple queues and semaphores), or 0 to omit queue set functionality.
configGENERATE_RUN_TIME_STATS
The Run Time Stats page describes the use of this parameter.
configUSE_CO_ROUTINES
Set to 1 to include co-routine functionality in the build, or 0 to omit co-routine functionality from the build. To include co-routines croutine.c must be included in the project.
configMAX_CO_ROUTINE_PRIORITIES
The number of priorities available to the application co-routines. Any number of co-routines can share the same priority. Tasks are prioritised separately - see configMAX_PRIORITIES.
configUSE_TIMERS
Set to 1 to include software timer functionality, or 0 to omit software timer functionality. See the FreeRTOS software timers page for a full description.
configTIMER_TASK_PRIORITY
Sets the priority of the software timer service/daemon task. See the FreeRTOS software timers page for a full description.
configTIMER_QUEUE_LENGTH
Sets the length of the software timer command queue. See the FreeRTOS software timers page for a full description.
configTIMER_TASK_STACK_DEPTH
Sets the stack depth allocated to the software timer service/daemon task. See the FreeRTOS software timers page for a full description.
configKERNEL_INTERRUPT_PRIORITY and configMAX_SYSCALL_INTERRUPT_PRIORITY
Ports that contain a configKERNEL_INTERRUPT_PRIORITY setting include ARM Cortex-M3, PIC24, dsPIC, PIC32, SuperH and RX600.
Ports that contain a configMAX_SYSCALL_INTERRUPT_PRIORITY setting include PIC32, RX600 and ARM Cortex-M ports.
ARM Cortex-M3 and ARM Cortex-M4 users please take heed of the special note at the end of this section!
configKERNEL_INTERRUPT_PRIORITY should be set to the lowest priority.
Note in the following discussion that only API functions that end in "FromISR" can be called from within an interrupt service routine.
For ports that only implement configKERNEL_INTERRUPT_PRIORITY
configKERNEL_INTERRUPT_PRIORITY sets the interrupt priority used by the RTOS kernel itself. Interrupts that call API functions must also execute at this
priority. Interrupts that do not call API functions can execute at higher priorities and therefore never have their execution delayed by the RTOS kernel
activity (within the limits of the hardware itself).
For ports that implement both configKERNEL_INTERRUPT_PRIORITY and configMAX_SYSCALL_INTERRUPT_PRIORITY:
configKERNEL_INTERRUPT_PRIORITY sets the interrupt priority used by the RTOS kernel itself. configMAX_SYSCALL_INTERRUPT_PRIORITY sets the highest
interrupt priority from which interrupt safe FreeRTOS API functions can be called.
A full interrupt nesting model is achieved by setting configMAX_SYSCALL_INTERRUPT_PRIORITY above (that is, at a higher priority level) than configKERNEL_INTERRUPT_PRIORITY. This means the FreeRTOS kernel does not completely disable interrupts, even inside critical sections. Further, this is achieved without the disadvantages of a segmented kernel architecture. Note however, certain microcontroller architectures will (in hardware) disable interrupts when a new interrupt is accepted - meaning interrupts are unavoidably disabled for the short period between the hardware accepting the interrupt, and the FreeRTOS code re-enabling interrupts.
Interrupts that do not call API functions can execute at priorities above configMAX_SYSCALL_INTERRUPT_PRIORITY and therefore never be delayed by the RTOS kernel execution.
For example, imagine a hypothetical microcontroller that has 8 interrupt priority levels - 0 being the lowest and 7 being the highest (see the special note for ARM Cortex-M3 users at the end of this section). The picture below describes what can and cannot be done at each priority level should the two configuration constants be set to 4 and 0 as shown:
Example interrupt priority configuration
These configuration parameters allow very flexible interrupt handling:
-
Interrupt handling 'tasks' can be written and prioritised as per any other task in the system. These are tasks that are woken
by an interrupt. The interrupt service routine (ISR) itself should be written to be as short as it possibly can be - it just grabs the data then wakes the
high priority handler task. The ISR then returns directly into the woken handler task - so interrupt processing is contiguous in time just as if it were all
done in the ISR itself. The benefit of this is that all interrupts remain enabled while the handler task executes.
-
Ports that implement configMAX_SYSCALL_INTERRUPT_PRIORITY take this further - permitting a fully nested model where interrupts between
the RTOS kernel interrupt priority and configMAX_SYSCALL_INTERRUPT_PRIORITY can nest and make applicable API calls. Interrupts with priority
above configMAX_SYSCALL_INTERRUPT_PRIORITY are never delayed by the RTOS kernel activity.
- ISR's running above the maximum syscall priority are never masked out by the RTOS kernel itself, so their responsiveness is not effected by the RTOS kernel functionality. This is ideal for interrupts that require very high temporal accuracy - for example interrupts that perform motor commutation. However, such ISR's cannot use the FreeRTOS API functions.
A special note for ARM Cortex-M3 and ARM Cortex-M4 users: Please read the page dedicated to interrupt priority settings on ARM Cortex-M devices. As a minimum, remember that ARM Cortex-M3 cores use numerically low priority numbers to represent HIGH priority interrupts, which can seem counter-intuitive and is easy to forget! If you wish to assign an interrupt a low priority do NOT assign it a priority of 0 (or other low numeric value) as this can result in the interrupt actually having the highest priority in the system - and therefore potentially make your system crash if this priority is above configMAX_SYSCALL_INTERRUPT_PRIORITY.
The lowest priority on a ARM Cortex-M3 core is in fact 255 - however different ARM Cortex-M3 vendors implement a different number of priority bits and supply library functions that expect priorities to be specified in different ways. For example, on the STM32 the lowest priority you can specify in an ST driver library call is in fact 15 - and the highest priority you can specify is 0.
configASSERT
Calls to configASSERT( x ) exist at key points in the FreeRTOS kernel code. If the parameter ( x ) is found to be equal to zero in a call to configASSERT( x ) then an error has occurred. The error will most likely be caused by an invalid parameter being passed into a FreeRTOS API function. Defining configASSERT() can therefore assist in debugging run time errors. However, defining configASSERT() will also increase the application code size and slow down its execution.configASSERT() is equivalent to the standard C assert() macro. It is used in place of the standard C assert() macro because not all the compilers that can be used to build FreeRTOS provide an assert.h header file.
INCLUDE Parameters
The macros starting 'INCLUDE' allow those components of the real time kernel not utilized by your application to be excluded from your build. This ensures the RTOS does not use any more ROM or RAM than necessary for your particular embedded application.
Each macro takes the form ...
To exclude vTaskDelete() from your build use:
Any and all data, files, source code, html content and documentation included in the FreeRTOSTM distribution or available on this site are the exclusive property of Real Time Engineers Ltd..
See the files license.txt (included in the distribution) and this copyright notice for more information. FreeRTOSTM and FreeRTOS.orgTM are trade marks of Real Time Engineers Ltd.