<head>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<META name="description" content="FreeRTOS is a portable, open source, mini Real Time kernel. A free RTOS for small embedded systems">
<META name="keywords" content="8051, 8052, Free RTOS, royalty free, RTOS, free, RTOS free, open source, real time, embedded, FreeRTOS, source code, AVR, GNU, PIC, PIC18, development tools">
<title>FreeRTOS - A FREE Open Source RTOS for small real time embedded systems</title><link rel="stylesheet" href="doxygen.css"><style type="text/css"></style>
</head>
<font face="Arial">
<body><div align="right"><font face="arial"><small><a href="http://www.freertos.org/" target="_top">Homepage</a></small> </font></div>
</BODY>
<!-- Generated by Doxygen 1.3 -->
<h1>Customisation<br>
<small>
[<a class="el" href="a00109.html">Configuration</a>]</small></h1>
A number of configurable parameters exist that allow the FreeRTOS kernel to be tailored to your particular application.
These items are located in a file called FreeRTOSConfig.h. Each demo application included in the FreeRTOS
source code download has its own FreeRTOSConfig.h file. Here is a typical example, followed by an explanation of each
parameter:
<p>
<font face="courier"><pre>
#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_IDLE_HOOK 0
#define configUSE_TICK_HOOK 0
#define configCPU_CLOCK_HZ 58982400
#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
#define configCHECK_FOR_STACK_OVERFLOW 0
#define INCLUDE_vTaskPrioritySet 1
#define INCLUDE_uxTaskPriorityGet 1
#define INCLUDE_vTaskDelete 1
#define INCLUDE_vTaskCleanUpResources 0
#define INCLUDE_vTaskSuspend 1
#define INCLUDE_vResumeFromISR 1
#define INCLUDE_vTaskDelayUntil 1
#define INCLUDE_vTaskDelay 1
#define INCLUDE_xTaskGetSchedulerState 1
#define INCLUDE_xTaskGetCurrentTaskHandle 1
#define INCLUDE_uxTaskGetStackHighWaterMark 0
#define configUSE_CO_ROUTINES 0
#define configMAX_CO_ROUTINE_PRIORITIES 1
#define configKERNEL_INTERRUPT_PRIORITY [dependent of processor]
#define configMAX_SYSCALL_INTERRUPT_PRIORITY [dependent on processor and application]
#endif /* FREERTOS_CONFIG_H */
</pre></font>
<p>
<hr>
<h2>'config' Parameters</h2>
<h3>configUSE_PREEMPTION</h3>
Set to 1 to use the preemptive kernel, or 0 to use the cooperative kernel.
<p>
<br>
<h3>configUSE_IDLE_HOOK</h3>
Set to 1 if you wish to use an <a href="http://www.freertos.org/a00015.html#IdleHook">idle hook</a>,
or 0 to omit an idle hook.
<p>
<br>
<h3>configUSE_TICK_HOOK</h3>
Set to 1 if you wish to use an <a href="http://www.freertos.org/a00016.html#TickHook">tick hook</a>,
or 0 to omit an tick hook.
<p>
<br>
<h3>configCPU_CLOCK_HZ</h3>
Enter the frequency in Hz at which the <i>internal</i> processor core will be executing. This value is required in order
to correctly configure timer peripherals.
<p>
<br>
<h3>configTICK_RATE_HZ</h3>
The frequency of the RTOS tick interrupt.
<p>
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 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 kernel and is
higher than would normally be required.
<p>
More than one task can share the same priority. The kernel 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.
<p>
<br>
<h3>configMAX_PRIORITIES</h3>
The number of <a href="http://www.freertos.org/a00015.html#Prior">priorities</a>
available to the application tasks. Any number of tasks can share the same priority. Co-routines are prioritised separately - see configMAX_CO_ROUTINE_PRIORITIES.
<p>
Each available priority consumes RAM within the kernel so this value should not be set any higher than actually
required by your application.
<p>
<br>
<h3>configMINIMAL_STACK_SIZE</h3>
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.
<p>
<br>
<h3>configTOTAL_HEAP_SIZE</h3>
The total amount of RAM available to the kernel.
<p>
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 <a href="http://www.freertos.org/a00111.html">memory configuration</a> section for further details.
<p>
<br>
<h3>configMAX_TASK_NAME_LEN</h3>
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
<i>including</i> the NULL termination byte.
<p>
<br>
<h3>configUSE_TRACE_FACILITY</h3>
Set to 1 if you wish the trace visualisation functionality to be available, or 0 if the trace functionality is not
going to be used. If you use the trace functionality a trace buffer must also be provided.
<p>
<br>
<h3>configUSE_16_BIT_TICKS</h3>
Time is measured in 'ticks' - which is the number of times the tick interrupt has executed since the kernel was started.
The tick count is held in a variable of type portTickType.
<p>
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.
<p>
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.
<p>
<br>
<h3>configIDLE_SHOULD_YIELD</h3>
This parameter controls the behaviour of tasks at the idle priority. It only has an effect if:
<ol>
<li>The preemptive scheduler is being used.</li>
<li>The users application creates tasks that run at the idle priority.</li>
</ol>
Tasks that share the same priority will time slice. Assuming none of the tasks get preempted, it might be assumed that each
task of at a given priority will be allocated an equal amount of processing time - and if the shared priority is above the
idle priority then this is indeed the case.
<p>
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:
<div align="center"><img src="idl