Table of Contents |
---|
Compile-time configuration allows users to determine which features to enable and those features that are not needed. With compile-time configuration, the code and data sizes of µC/OS-III (i.e., its footprint) can be reduced by enabling only the desired functionality.
...
The compile-time configuration #defines
are listed below in alphabetic order and are not necessarily found in this order in as per the sections and order found in os_cfg.h
.
Miscellaneous Options
OS_CFG_APP_HOOKS_EN
When set to
...
DEF_ENABLED
, this
...
option specifies that application-defined hooks can be called from µC/OS-III’s hooks. This allows the application code to extend the functionality of µC/OS-III. Specifically:
The µC/OS-III |
---|
Hook | Calls the Application- |
---|
defined Hook | |
---|---|
OSIdleTaskHook() | OS_AppIdleTaskHookPtr |
OSInitHook() | None |
OSStatTaskHook() | OS_AppStatTaskHookPtr |
OSTaskCreateHook() | OS_AppTaskCreateHookPtr |
OSTaskDelHook() | OS_AppTaskDelHookPtr |
OSTaskReturnHook() | OS_AppTaskReturnHookPtr |
OSTaskSwHook() | OS_AppTaskSwHookPtr |
OSTimeTickHook() | OS_AppTimeTickHookPtr |
Application hook functions could be declared as shown in the code below.
...
It’s also up to a user to set the value of the pointers so that they point to the appropriate functions as shown below. The pointers do not have to be set in main()
but, you can set them after calling OSInit()
.
Note that not every hook function need to be defined, only the ones the user wants to place in the application code.
Also, if you don't intend to extend µC/OS-III’s hook through these application hooks, you can set OS_CFG_APP_HOOKS_EN
to 0 to save RAM (i.e., the pointers).
OS_CFG_ARG_CHK_EN
OS_CFG_ARG_CHK_EN
determines whether the user wants most of µC/OS-III functions to perform argument checking. When set to 1, µC/OS-III ensures that pointers passed to functions are non-NULL
, that arguments passed are within allowable range, that options are valid, and more. When set to 0, OS_CFG_ARG_CHK_EN
those arguments are not checked and the amount of code space and processing time required by µC/OS-III is reduced. You would set OS_CFG_ARG_CHK_EN
to 0 if you are certain that the arguments are correct.
µC/OS-III performs argument checking in over 40 functions. Therefore, you can save a few hundred bytes of code space by disabling this check. However, you should always enable argument checking until you are certain the code can be trusted.
OS_CFG_CALLED_FROM_ISR_CHK_EN
OS_CFG_CALLED_FROM_ISR_CHK_EN
determines whether most of µC/OS-III functions are to confirm that the function is not called from an ISR. In other words, most of the functions from µC/OS-III should be called by task-level code except “post” type functions (which can also be called from ISRs). By setting this #define
to 1 µC/OS-III is told to make sure that functions that are only supposed to be called by tasks are not called by ISRs. It’s highly recommended to set this #define
to 1 until you are absolutely certain that the code is behaving correctly and that task-level functions are always called from tasks. You can set this #define
to 0 to save code space and, of course, processing time.
µC/OS-III performs this check in approximately 50 functions. Therefore, you can save a few hundred bytes of code space by disabling this check.
OS_CFG_DBG_EN
When set to 1
, this #define
adds ROM constants located in os_dbg.c
to help support kernel aware debuggers. Specifically, a number of named ROM variables can be queried by a debugger to find out about compiled-in options. For example, a debugger can find out the size of an OS_TCB
, µC/OS-III’s version number, the size of an event flag group (OS_FLAG_GRP
), and much more.
OS_CFG_FLAG_EN
OS_CFG_FLAG_EN
enables (when set to 1
) or disables (when set to 0
) code generation of event flag services and data structures. This reduces the amount of code and data space needed when an application does not require event flags. When OS_CFG_FLAG_EN
is set to 0, it is not necessary to enable or disable any of the other OS_CFG_FLAG_xxx #define
constants in this section.
OS_CFG_FLAG_DEL_EN
OS_CFG_FLAG_DEL_EN
enables (when set to 1
) or disables (when set to 0
) code generation of the function OSFlagDel()
.
OS_CFG_FLAG_MODE_CLR_EN
OS_CFG_FLAG_MODE_CLR_EN
enables (when set to 1
) or disables (when set to 0
) code generation used to wait for event flags to be 0 instead of 1. Generally, you would wait for event flags to be set. However, the user may also want to wait for event flags to be clear and in this case, enable this option.
OS_CFG_FLAG_PEND_ABORT_EN
OS_CFG_FLAG_PEND_ABORT_EN
enables (when set to 1
) or disables (when set to 0
) code generation of the function OSFlagPendAbort()
.
OS_CFG_ISR_POST_DEFERRED_EN
When set to 1
, OS_CFG_ISR_POST_DEFERRED_EN
reduces interrupt latency since interrupts are not disabled during most critical sections of code within µC/OS-III. Instead, the scheduler is locked during the processing of these critical sections. The advantage of setting OS_CFG_ISR_POST_DEFERRED_EN
to 1 is that interrupt latency is lower, however, ISR to task response is slightly higher. It is recommended to set OS_CFG_ISR_POST_DEFERRED_EN
to 1 when enabling the following services, since setting this #define
to 0
would potentially make interrupt latency unacceptably high:
µC/OS-III Services | Enabled by … |
---|---|
Event Flags |
|
Multiple Pend |
|
| |
| |
|
The compromise to make is:
OS_CFG_ISR_POST_DEFERRED_EN
set to 1
Short interrupt latency, longer ISR-to-task response.
OS_CFG_ISR_POST_DEFERRED_EN
set to 0
Long interrupt latency (see table above), shorter ISR-to-task response.
OS_CFG_MEM_EN
OS_CFG_MEM_EN
enables (when set to 1
) or disables (when set to 0
) code generation of the µC/OS-III partition memory manager and its associated data structures. This feature allows users to reduce the amount of code and data space needed when an application does not require the use of memory partitions.
OS_CFG_MUTEX_EN
...
Code Block |
---|
void App_OS_TaskCreateHook (OS_TCB *p_tcb)
{
/* Your code here */
}
void App_OS_TaskDelHook (OS_TCB *p_tcb)
{
/* Your code here */
}
void App_OS_TaskReturnHook (OS_TCB *p_tcb)
{
/* Your code here */
}
void App_OS_IdleTaskHook (void)
{
/* Your code here */
}
void App_OS_StatTaskHook (void)
{
/* Your code here */
}
void App_OS_TaskSwHook (void)
{
/* Your code here */
}
void App_OS_TimeTickHook (void)
{
/* Your code here */
} |
It’s also up to a user to set the value of the pointers so that they point to the appropriate functions as shown below. The pointers do not have to be set in main()
but, you can set them after calling OSInit()
.
Code Block |
---|
void main (void)
{
OS_ERR err;
OSInit(&err);
:
:
OS_AppTaskCreateHookPtr = (OS_APP_HOOK_TCB )App_OS_TaskCreateHook;
OS_AppTaskDelHookPtr = (OS_APP_HOOK_TCB )App_OS_TaskDelHook;
OS_AppTaskReturnHookPtr = (OS_APP_HOOK_TCB )App_OS_TaskReturnHook;
OS_AppIdleTaskHookPtr = (OS_APP_HOOK_VOID)App_OS_IdleTaskHook;
OS_AppStatTaskHookPtr = (OS_APP_HOOK_VOID)App_OS_StatTaskHook;
OS_AppTaskSwHookPtr = (OS_APP_HOOK_VOID)App_OS_TaskSwHook;
OS_AppTimeTickHookPtr = (OS_APP_HOOK_VOID)App_OS_TimeTickHook;
:
:
OSStart(&err);
} |
Note that not every hook function need to be defined, only the ones the user wants to place in the application code.
Also, if you don't intend to extend µC/OS-III’s hook through these application hooks, you can set OS_CFG_APP_HOOKS_EN
to DEF_DISABLED
to save RAM (i.e., the pointers).
OS_CFG_ARG_CHK_EN
OS_CFG_ARG_CHK_EN
determines whether the user wants most of µC/OS-III functions to perform argument checking. When set to DEF_ENABLED
, µC/OS-III ensures that pointers passed to functions are non-NULL
, that arguments passed are within allowable range, that options are valid, and more. When set to DEF_DISABLED
, those arguments are not checked and the amount of code space and processing time required by µC/OS-III is reduced. You would set OS_CFG_ARG_CHK_EN
to DEF_DISABLED
if you are certain that the arguments will always be correct.
µC/OS-III performs argument checking in close to 50 functions. Therefore, you can save a few hundred bytes of code space by disabling this check. However, you should always enable argument checking until you are certain the code can be trusted.
OS_CFG_CALLED_FROM_ISR_CHK_EN
OS_CFG_CALLED_FROM_ISR_CHK_EN
determines whether most of µC/OS-III functions are to confirm that the function is not called from an ISR. In other words, most of the functions from µC/OS-III should be called by task-level code except “post” type functions (which can also be called from ISRs). By setting this DEF_ENABLED
, µC/OS-III is told to make sure that functions that are only supposed to be called by tasks are not called by ISRs. It’s highly recommended to set this to DEF_ENABLED
until you are absolutely sure that the code is behaving correctly and that task-level functions are always called from tasks. You can set this to DEF_DISABLED
to save code space and, of course, processing time.
µC/OS-III performs this check in approximately 50 functions. Therefore, you can save a few hundred bytes of code space by disabling this check.
OS_CFG_DBG_EN
When set to DEF_ENABLED
, this configuration adds ROM constants located in os_dbg.c
to help support kernel aware debuggers. Specifically, a number of named ROM variables can be queried by a debugger to find out about compiled-in options. For example, a debugger can find out the size of a OS_TCB
, µC/OS-III’s version number, the size of an event flag group (OS_FLAG_GRP
), and much more.
OS_CFG_DYN_TICK_EN
When set to DEF_ENABLED
, µC/OS-III will use a dynamic ticking mechanism instead of the traditional continuous tick. This allows µC/OS-III to sleep until a task needs to be awakened, instead of waking up every 1/OS_CFG_TICK_RATE_HZ
seconds to find no that no tasks need to be awakened. This can be used to save power since the scheduler is run only when strictly necessary.
Note that the use of this feature requires a proper Board Support Package (BSP) that implements the API described in Board Support Package.
OS_CFG_INVALID_OS_CALLS_CHK_EN
When set to DEF_ENABLED
, µC/OS-III will validate the call and check that the kernel is indeed running before performing the function. You would set OS_CFG_INVALID_OS_CALLS_CHK_EN
to DEF_DISABLED
if you are sure that the OS functions will be called only once OSStart()
has been called.
µC/OS-III performs this check in more than 40 functions. Therefore, you can save a few hundred bytes of code space by disabling this check.
OS_CFG_OBJ_TYPE_CHK_EN
OS_CFG_OBJ_TYPE_CHK_EN
determines whether most of µC/OS-III functions should check to see if the function is manipulating the proper object. In other words, if attempting to post to a semaphore, is the user in fact passing a semaphore object or another object by mistake? It is recommended to set OS_CFG_OBJ_TYPE_CHK_EN
to DEF_ENABLED
until absolutely certain that the code is behaving correctly and the user code is always pointing to the proper objects. You would set this to DEF_DISABLED
to save code space as well as data space.
µC/OS-III object type checking is done nearly 40 times, and it is possible to save a few hundred bytes of code space and processing time by disabling this check.
OS_CFG_TS_EN
When OS_CFG_TS_EN
is set to DEF_ENABLED
, it enables the timestamp facilities provided by µC/CPU. This allows the user and the kernel to measure the time between various events. For example, the time spent by a task pending on an object, the maximum interrupt disable time (if CPU_CFG_INT_DIS_MEAS_EN
is set to DEF_ENABLED
), the time the scheduler is locked, etc. This option is mostly useful in profiling and performance measurement contexts. To save space and processing time, set this option to DEF_DISABLED
.
Note that to use the timestamp facilities the µC/CPU Board Support Package should implement the functions described in cpu_bsp.c and cpu_bsp.h.
OS_CFG_PRIO_MAX
OS_CFG_PRIO_MAX
specifies the maximum number of priorities available in the application. Specifying OS_CFG_PRIO_MAX
to just the number of priorities the user intends to use, reduces the amount of RAM needed by µC/OS-III.
In µC/OS-III, task priorities can range from 0 (highest priority) to a maximum of 255 (lowest possible priority) when the data type OS_PRIO
is defined as a CPU_INT08U
. However, in µC/OS-III, there is no practical limit to the number of available priorities. Specifically, if defining OS_PRIO
as a CPU_INT16U
, there can be up to 65536 priority levels. It is recommended to leave OS_PRIO
defined as a CPU_INT08U
and use only 256 different priority levels (i.e., 0..255), which is generally sufficient for every application. You should always set the value of OS_CFG_PRIO_MAX
to even multiples of 8 (8
, 16
, 32
, 64
, 128
, 256
, etc.). The higher the number of different priorities, the more RAM µC/OS-III will consume.
An application cannot create tasks with a priority number higher than or equal to OS_CFG_PRIO_MAX
. In fact, µC/OS-III reserves priority OS_CFG_PRIO_MAX-2
and OS_CFG_PRIO_MAX-1
for itself; OS_CFG_PRIO_MAX-1
is reserved for the Idle Task OS_IdleTask()
, if used. Additionally, do not use priority 0 for an application since it is reserved by µC/OS-III’s ISR handler task. The priorities of the application tasks can therefore take a value between 2 and OS_CFG_PRIO_MAX–3
(inclusive).
To ensure proper operation of µC/OS-III and it's services, care should be taken when setting the priorities of other system task such as the Tick Task, the Statistics Task and the Timer Task in os_cfg_app.h
.
To summarize, there are two priority levels to avoid in an application:
Priority | Reserved by µC/OS-III for |
---|---|
0 | The ISR Handler Task (OS_IntQTask() ), if used |
1 | Reserved |
OS_CFG_PRIO_MAX-2 | Reserved |
OS_CFG_PRIO_MAX-1 | The Idle Task (OS_IdleTask() ), if used |
OS_CFG_SCHED_LOCK_TIME_MEAS_EN
When set to DEF_ENABLED
, OS_CFG_SCHED_LOCK_TIME_MEAS_EN
allows µC/OS-III to use the timestamp facilities (provided OS_CFG_TS_EN
is also set to DEF_ENABLED
) to measure the peak amount of time that the scheduler is locked. Use this feature to profile the application, the deployed application should set this to DEF_DISABLED
.
OS_CFG_SCHED_ROUND_ROBIN_EN
Set OS_CFG_SCHED_ROUND_ROBIN_EN
to DEF_ENABLED
to use the Round Robin Scheduler. This is only useful when there is multiple tasks sharing the same priority, if this is not your case, set this option to DEF_DISABLED
. See Round-Robin Scheduling for more information.
OS_CFG_STK_SIZE_MIN
OS_CFG_STK_SIZE_MIN
specifies the minimum stack size (in CPU_STK
elements) for each task. This is used by µC/OS-III to verify that sufficient stack space is provided for each task when the task is created. Suppose the full context of a processor consists of 16 registers of 32 bits. Also, suppose CPU_STK
is declared as being of type CPU_INT32U
, at a bare minimum, OS_CFG_STK_SIZE_MIN
should be set to 16. However, it would be quite unwise to not accommodate for storage of local variables, function call returns, and possibly nested ISRs. Refer to the “port” of the processor used to see how to set this minimum. Again, this is a safeguard to make sure task stacks have sufficient space.
Event Flag Configuration
OS_CFG_FLAG_EN
When OS_CFG_FLAG_EN
is set to DEF_ENABLED
, it enables the event flag services and data structures. If event flags are not needed, set this to DEF_DISABLED
. It reduces the amount of code and data space needed by µC/OS-III. Note than when OS_CFG_FLAG_EN
is set to DEF_DISABLED
, it is not necessary to enable or disable any of the other OS_CFG_FLAG_xxx
options in this section.
OS_CFG_FLAG_DEL_EN
If your application needs to delete event flags with
once they're created, set OSFlagDel()
OS_CFG_FLAG_DEL_EN
to DEF_ENABLED
, if not, set this option to DEF_DISABLED
. Critical applications should not delete kernel objects once the kernel is started.
OS_CFG_FLAG_MODE_CLR_EN
If your application requires to wait until a event is cleared, set OS_CFG_FLAG_MODE_CLR_EN
to DEF_ENABLED
, if not set this to DEF_DISABLED
. Generally, you would wait for event flags to be set. However, the user may also want to wait for event flags to be clear and in this case, enable this option.
OS_CFG_FLAG_PEND_ABORT_EN
When OS_CFG_FLAG_PEND_ABORT_EN is set to DEF_ENABLED
, it enables the generation of the function OSFlagPendAbort()
. If your application does not require fault-aborts on event flags, set this option to DEF_DISABLED
.
Memory Management Configuration
OS_CFG_MEM_EN
When OS_CFG_MEM_EN
is set to DEF_ENABLED
, it enables the µC/OS-III partition memory manager. If your application does not require the partitionned memory manager, set this to DEF_DISABLE
to reduce µC/OS-III's code and data space usage.
Mutal Exclusion Semaphore Configuration
OS_CFG_MUTEX_EN
When OS_CFG_MUTEX_EN
is set to
, it enables the mutual exclusion semaphore services and data structures. If your application does not require mutexes, set this option to DEF_ENABLED
DEF_DISABLED
to reduce the amount of code and data space needed by µC/OS-III. When OS_CFG_MUTEX_EN
is set to DEF_DISABLED
, there is no need to enable or disable any of the
...
other OS_CFG_MUTEX_XXX
...
options in this section.
OS_CFG_MUTEX_DEL_EN
If your application needs to delete mutexes with OSMutexDel
once they're created, set ()
OS_CFG_MUTEX_DEL_EN
...
to DEF_ENABLED
, if not, set this option to DEF_DISABLED
. Critical applications should not delete kernel objects once the kernel is started.
OS_CFG_MUTEX_PEND_ABORT_EN
When OS_CFG_MUTEX_PEND_ABORT_EN
...
is set to DEF_ENABLED
, it enables the generation of the
...
function OSMutexPendAbort()
. If your application does not require fault-aborts on mutexes, set this option to DEF_DISABLED
.
Message Queue Configuration
OS_CFG_
...
Q_
...
EN
When OS_CFG_
...
Q_EN
is set to
, it enables the message queue services and data structures. If your application does not require mutexes, set this option to DEF_ENABLED
DEF_DISABLED
to reduce the amount of code and data space needed by µC/OS-III. When OS_CFG_Q_EN
is set to DEF_DISABLED
, there is no need to enable or disable any of the other OS_CFG_Q_XXX
options in this section.
OS_CFG_
...
Q_
...
DEL_EN
This constant determines whether the code to support pending on multiple events (i.e., semaphores or message queues) will be enabled (1
) or not (0
).
...
If your application needs to delete message queues with OSQDel
once they're created, set ()
OS_CFG_Q_DEL_EN
to DEF_ENABLED
, if not, set this option to DEF_DISABLED
. Critical applications should not delete kernel objects once the kernel is started.
OS_CFG_
...
Q_FLUSH_EN
When OS_CFG
...
In µC/OS-III, task priorities can range from 0 (highest priority) to a maximum of 255 (lowest possible priority) when the data type OS_PRIO
is defined as a CPU_INT08U
. However, in
µC/OS-III, there is no practical limit to the number of available priorities. Specifically, if defining OS_PRIO
as a CPU_INT16U
, there can be up to 65536 priority levels. It is recommended to leave OS_PRIO
defined as a CPU_INT08U
and use only 256 different priority levels (i.e., 0..255), which is generally sufficient for every application. You should always set the value of OS_CFG_PRIO_MAX
to even multiples of 8 (8
, 16
, 32
, 64
, 128
, 256
, etc.). The higher the number of different priorities, the more RAM µC/OS-III will consume.
An application cannot create tasks with a priority number higher than or equal to OS_CFG_PRIO_MAX
. In fact, µC/OS-III reserves priority OS_CFG_PRIO_MAX-2
and OS_CFG_PRIO_MAX-1
for itself; OS_CFG_PRIO_MAX-1
is reserved for the idle task OS_IdleTask()
. Additionally, do not use priority 0 for an application since it is reserved by µC/OS-III’s ISR handler task. The priorities of the application tasks can therefore take a value between 2 and OS_CFG_PRIO_MAX–3
(inclusive).
To summarize, there are two priority levels to avoid in an application:
Priority | Reserved by µC/OS-III for … |
---|---|
0 | The ISR Handler Task ( |
1 | Reserved |
| Reserved |
| The idle task ( |
OS_CFG_Q_EN
OS_CFG_Q_EN
enables (when set to 1
) or disables (when set to 0
) code generation of message queue services and data structures. This reduces the amount of code space needed when an application does not require the use of message queues. When OS_CFG_Q_EN
is set to 0, you do not need to enable or disable any of the other OS_CFG_Q_XXX #define
constants in this section.
OS_CFG_Q_DEL_EN
OS_CFG_Q_DEL_EN
enables (when set to 1
) or disables (when set to 0
) code generation of the function OSQDel()
.
OS_CFG_Q_FLUSH_EN
OS_CFG_Q_FLUSH_EN
enables (when set to 1) or disables (when set to 0) code generation of the function OSQFlush()
.
OS_CFG_Q_PEND_ABORT_EN
OS_CFG_Q_PEND_ABORT_EN
enables (when set to 1
) or disables (when set to 0
) code generation of the function OSQPendAbort()
.
OS_CFG_SCHED_LOCK_TIME_MEAS_EN
This constant enables (when set to 1
) or disables (when set to 0
) code generation to measure the amount of time the scheduler is locked. This is useful when determining task latency.
OS_CFG_SCHED_ROUND_ROBIN_EN
This constant enables (when set to 1
) or disables (when set to 0
) code generation for the round-robin feature of µC/OS-III.
OS_CFG_SEM_EN
OS_CFG_SEM_EN
enables (when set to 1
) or disables (when set to 0
) code generation of the semaphore manager and associated data structures. This reduces the amount of code and data space needed when an application does not require the use of semaphores. When OS_CFG_SEM_EN
is set to 0, it is not necessary to enable or disable any of the other OS_CFG_SEM_XXX #define
constants in this section.
OS_CFG_SEM_DEL_EN
OS_CFG_SEM_DEL_EN
enables (when set to 1
) or disables (when set to 0
) code generation of the function OSSemDel()
.
OS_CFG_SEM_PEND_ABORT_EN
OS_CFG_SEM_PEND_ABORT_EN
enables (when set to 1
) or disables (when set to 0
) code generation of the function OSSemPendAbort()
.
OS_CFG_SEM_SET_EN
OS_CFG_SEM_SET_EN
enables (when set to 1
) or disables (when set to 0
) code generation of the function OSSemSet()
.
OS_CFG_STAT_TASK_EN
OS_CFG_STAT_TASK_EN
specifies whether or not to enable µC/OS-III’s statistic task, as well as its initialization function. When set to 1
, the statistic task OS_StatTask()
and statistic task initialization function are enabled. OS_StatTask()
computes the CPU usage of an application, stack usage of each task, the CPU usage of each task at run time and more.
When enabled, OS_StatTask()
executes at a rate of OS_CFG_STAT_TASK_RATE_HZ
(see os_cfg_app.h
), and computes the value of OSStatTaskCPUUsage
, which is a variable that contains the percentage of CPU used by the application. OS_StatTask()
calls OSStatTaskHook()
every time it executes so that the user can add their own statistics as needed. See os_stat.c
for details on the statistic task. The priority of OS_StatTask()
is configurable by the application code (see os_cfg_app.h
).
OS_StatTask()
also computes stack usage of each task created when the #define
OS_CFG_STAT_TASK_STK_CHK_EN
is set to 1
. In this case, OS_StatTask()
calls OSTaskStkChk()
for each task and the result is placed in the task’s TCB. The .StkFree
and .StkUsed
field of the task’s TCB represents the amount of free space (in bytes) and amount of used space, respectively.
When OS_CFG_STAT_TASK_EN
is set to 0
, all variables used by the statistic task are not declared (see os.h
). This, of course, reduces the amount of RAM needed by µC/OS-III when not enabling the statistic task. When setting OS_CFG_STAT_TASK_EN
to 1
, statistics will be determined at a rate of OS_CFG_STAT_TASK_RATE_HZ
(see os_cfg_app.h
).
OS_CFG_STAT_TASK_STK_CHK_EN
This constant allows the statistic task to call OSTaskStkChk()
for each task created. For this to happen, OS_CFG_STAT_TASK_EN
needs to be set to 1
(i.e., the statistic task needs to be enabled). However, you can call OSStatStkChk()
from one of the tasks to obtain this information about the task(s).
OS_CFG_STK_SIZE_MIN
This #define
specifies the minimum stack size (in CPU_STK
elements) for each task. This is used by µC/OS-III to verify that sufficient stack space is provided for when each task is created. Suppose the full context of a processor consists of 16 registers of 32 bits. Also, suppose CPU_STK
is declared as being of type CPU_INT32U
, at a bare minimum, set OS_CFG_STK_SIZE_MIN
to 16. However, it would be quite unwise to not accommodate for storage of local variables, function call returns, and possibly nested ISRs. Refer to the “port” of the processor used to see how to set this minimum. Again, this is a safeguard to make sure task stacks have sufficient stack space.
OS_CFG_TASK_CHANGE_PRIO_EN
OS_CFG_TASK_CHANGE_PRIO_EN
enables (when set to 1
) or disables (when set to 0
) code generation of the function OSTaskChangePrio()
.
OS_CFG_TASK_DEL_EN
OS_CFG_TASK_DEL_EN
enables (when set to 1
) or disables (when set to 0
) code generation of the function OSTaskDel()
.
OS_CFG_TASK_Q_EN
OS_CFG_TASK_Q_EN
enables (when set to 1
) or disables (when set to 0
) code generation of the OSTaskQXXX()
functions used to send and receive messages directly to/from tasks and ISRs. Sending messages directly to a task is more efficient than sending messages using a message queue because there is no pend list associated with messages sent to a task.
OS_CFG_TASK_Q_PEND_ABORT_EN
OS_CFG_TASK_Q_PEND_ABORT_EN
enables (when set to 1
) or disables (when set to 0
) code generation of code for the function OSTaskQPendAbort()
.
OS_CFG_TASK_PROFILE_EN
This constant allows variables to be allocated in each task’s OS_TCB
to hold performance data about each task. If OS_CFG_TASK_PROFILE_EN
is set to 1
, each task will have a variable to keep track of the number of times a task is switched to, the task execution time, the percent CPU usage of the task relative to the other tasks and more. The information made available with this feature is highly useful when debugging, but requires extra RAM.
OS_CFG_TASK_REG_TBL_SIZE
This constant allows each task to have task context variables. Use task variables to store such elements as “errno
”, task identifiers and other task-specific values. The number of variables that a task contains is set by this constant. Each variable is identified by a unique identifier from 0 to OS_CFG_TASK_REG_TBL_SIZE-1
. Also, each variable is declared as having an OS_REG
data type (see os_type.h
). If OS_REG
is a CPU_INT32U
, all variables in this table are of this type.
OS_CFG_TASK_SEM_PEND_ABORT_EN
OS_CFG_TASK_SEM_PEND_ABORT_EN
enables (when set to 1
) or disables (when set to 0
) code generation of code for the function OSTaskSemPendAbort()
.
OS_CFG_TASK_SUSPEND_EN
OS_CFG_TASK_SUSPEND_EN
enables (when set to 1
) or disables (when set to 0
) code generation of the functions OSTaskSuspend()
and OSTaskResume()
, which allows the application to explicitly suspend and resume tasks, respectively. Suspending and resuming a task is useful when debugging, especially if calling these functions via a terminal interface at run time.
OS_CFG_TIME_DLY_HMSM_EN
_Q_FLUSH_EN
is set to
, it allows your application to flush, or clear, a message queue with DEF_ENABLED
OSQFlush()
. If this feature is not needed, set this option to DEF_DISABLED
.
OS_CFG_Q_PEND_ABORT_EN
When OS_CFG_Q_PEND_ABORT_EN
is set to DEF_ENABLED
, it enables the generation of the function OSQPendAbort()
. If your application does not require fault-aborts on message queues, set this option to DEF_DISABLED
.
Semaphore Configuration
OS_CFG_SEM_EN
When OS_CFG_SEM_EN
is set to
, it enables the semaphore services and data structures. If your application does not require semaphores, set this option to DEF_ENABLED
DEF_DISABLED
to reduce the amount of code and data space needed by µC/OS-III. When OS_CFG_SEM_EN
is set to DEF_DISABLED
, there is no need to enable or disable any of the other OS_CFG_SEM_XXX
options in this section.
OS_CFG_SEM_DEL_EN
If your application needs to delete semaphores with OSSemDel
once they're created, set ()
OS_CFG_SEM_DEL_EN
to DEF_ENABLED
, if not, set this option to DEF_DISABLED
. Critical applications should not delete kernel objects once the kernel is started.
OS_CFG_SEM_PEND_ABORT_EN
When OS_CFG_SEM_PEND_ABORT_EN
is set to DEF_ENABLED
, it enables the generation of the function OSSemPendAbort()
. If your application does not require fault-aborts on semaphores queues, set this option to DEF_DISABLED
.
OS_CFG_SEM_SET_EN
If your application needs to explicitly set the value of a semaphore with OSSemSet()
at another time than it's creation, set OS_CFG_SEM_SET_EN
to DEF_ENABLE
, if not, set this option to DEF_DISABLED
.
Monitor Configuration
OS_CFG_MON_EN
When OS_CFG_MON_EN
is set to
, it enables the monitor services and data structures. If your application does not require monitors, set this option to DEF_ENABLED
DEF_DISABLED
to reduce the amount of code and data space needed by µC/OS-III.
OS_CFG_MON_DEL_EN
If your application needs to delete a monitor with OSMonDel
once they're created, set ()
OS_CFG_MON_DEL_EN
to DEF_ENABLED
, if not, set this option to DEF_DISABLED
. Critical applications should not delete kernel objects once the kernel is started.
Task Management Options
OS_CFG_STAT_TASK_EN
OS_CFG_STAT_TASK_EN
specifies whether or not to enable µC/OS-III’s statistic task, as well as its initialization function. When set to DEF_ENABLED
, the statistic task OS_StatTask()
and the statistic task initialization function are enabled. OS_StatTask()
computes the CPU usage of an application, the stack usage of each task, the CPU usage of each task at run time and more.
When enabled, OS_StatTask()
executes at a rate of OS_CFG_STAT_TASK_RATE_HZ
(see os_cfg_app.h
), and computes the value of OSStatTaskCPUUsage
, which is a variable that contains the percentage of CPU used by the application. OS_StatTask()
calls OSStatTaskHook()
every time it executes so that the user can add his own statistics as needed. See os_stat.c
for details on the statistic task. The priority of OS_StatTask()
is configurable by the application code (see os_cfg_app.h
).
OS_StatTask()
computes stack usage of each task created when the option OS_CFG_STAT_TASK_STK_CHK_EN
is set to DEF_ENABLED
. In this case, OS_StatTask()
calls OSTaskStkChk()
for each task and the result is placed in the task’s TCB. The .StkFree
and .StkUsed
fields of the task’s TCB represent the amount of free space (in CPU_STK
elements) and amount of used space (in CPU_STK
elements), respectively.
When OS_CFG_STAT_TASK_EN
is set to DEF_DISABLED
, all variables used by the statistic task are not declared (see os.h
). This, of course, reduces the amount of RAM needed by µC/OS-III when not enabling the statistic task.
OS_CFG_STAT_TASK_STK_CHK_EN
When set to DEF_ENABLED
, this option allows the statistic task to call OSTaskStkChk()
for each task created. Note that for this to happen, OS_CFG_STAT_TASK_EN
must also be set to DEF_ENABLED
. However, you can call OSStatStkChk()
from one of the tasks to obtain this information about the tasks.
OS_CFG_TASK_CHANGE_PRIO_EN
If your application needs to dynamically change a task's priority using OSTaskChangePrio()
, set OS_CFG_TASK_CHANGE_PRIO_EN
to DEF_ENABLED
. If not, set this option to DEF_DISABLED
. Note that the new priority has to be available and not currently in-use by a kernel task.
OS_CFG_TASK_DEL_EN
If your application needs to delete tasks using OSTaskDel()
, set OS_CFG_TASK_DEL_EN
to DEF_ENABLED
. If not, set this option to DEF_DISABLED
. Note that critical applications should not delete tasks once the kernel is started.
OS_CFG_TASK_IDLE_EN
Setting OS_CFG_TASK_IDLE_EN
to DEF_ENABLED
allows µC/OS-III to create it's Idle Task at priority OS_CFG_PRIO_MAX-1
. However, to save data space, it is possible to remove the Idle Task. To do so, set this option to DEF_DISABLED
. Doing so will move the functionality of the Idle Task within the OSSched()
function. The same counters will be incremented and the same hooks will be called under the same circumstances.
OS_CFG_TASK_PROFILE_EN
To enable the performance profiling tools within µC/OS-III, set OS_CFG_TASK_PROFILE_EN
to DEF_ENABLED
. Doing so allows variables to be allocated in each task’s OS_TCB
to hold performance data about each task. When enabled, each task will have variables to keep track of the number of times a task is switched in, the task execution time, the CPU usage percentage of the task relative to the other tasks and more. The information made available with this feature is highly useful when debugging, but requires extra RAM. To save data and code space, set this option to DEF_DISABLED
after your are certain that you application is profiled and works correctly.
OS_CFG_TASK_Q_EN
When OS_CFG_TASK_Q_EN
is set to DEF_ENABLED
, it allows the generation of the OSTaskQ???()
functions used to send and receive messages directly to and from tasks and ISRs. Sending messages directly to a task is more efficient than sending messages using a traditional message queue because there is no pend list associated with messages sent to a task. If your application does not require task-level message queues, set this option to DEF_DISABLED
. Note that if this option is set to DEF_DISABLED
, the OS_CFG_TASK_Q_PEND_ABORT_EN
configuration option is ignored.
OS_CFG_TASK_Q_PEND_ABORT_EN
When OS_CFG_TASK_Q_PEND_ABORT_EN
is set to DEF_ENABLED
, it enables the generation of the function OSTaskQPendAbort()
. If your application does not require fault-aborts on task-level message queues, set this option to DEF_DISABLED
.
OS_CFG_TASK_REG_TBL_SIZE
This constant allows each task to have task context variables. Use task variables to store such elements as “errno
”, task identifiers and other task-specific values. The number of variables that a task contains is set by OS_CFG_TASK_REG_TBL_SIZE
. Each variable is identified by a unique identifier from 0
to OS_CFG_TASK_REG_TBL_SIZE-1
. Also, each variable is declared as having an OS_REG
data type (see os_type.h
). If OS_REG
is a CPU_INT32U
, all variables in this table are of this type. To disable the usage of task context variables, set this option to 0u
.
OS_CFG_TASK_STK_REDZONE_EN
While debugging, it is useful to determine if a task overflowed it's stack space. To do so, set OS_CFG_TASK_STK_REDZONE_EN
to DEF_ENABLED
. Then, every time a task is switched in after an interrupt, it's stack is checked. If the monitored zone located at the end of a task's stack is corrupted, a software exception is thrown. To disable this feature, set this option to DEF_DISABLED
. Note that the effectively usable stack space is the task stack size minus OS_CFG_TASK_STK_REDZONE_DEPTH
.
OS_CFG_TASK_STK_REDZONE_DEPTH
The default monitored zone, located at the end of a task's stack, is 8
CPU_STK
elements long. To change the size of the monitored zone, change this option accordingly. If OS_CFG_TASK_STK_REDZONE_EN
is set to DEF_DISABLED
, this value is ignored.
OS_CFG_TASK_SEM_PEND_ABORT_EN
When OS_CFG_TASK_SEM_PEND_ABORT_EN
is set to DEF_ENABLED
, it enables the generation of the function OSTaskSemPendAbort()
. If your application does not require fault-aborts on task-level semaphores, set this option to DEF_DISABLED
.
OS_CFG_TASK_SUSPEND_EN
If your application requires the ability to explicitly suspend and resume the execution of tasks, set OS_CFG_TASK_SUSPEND_EN
to DEF_ENABLED
. Doing so, allows the generation of the OSTaskSuspend()
and OSTaskResume()
functions used to suspend and resume tasks, respectively. Note that other effects are additive with the suspension. For example, if a suspended task is pending on a semaphore that becomes available, the task will not run until it's explicitly resumed with OSTaskResume()
. Also, the suspension of a task can be nested. To resume a task, you must call OSTaskResume()
the same number of times OSTaskSuspend()
was called. If your application does not require this feature, set this option to DEF_DISABLED
.
OS_CFG_TASK_TICK_EN
To keep the traditional behavior, set OS_CFG_TASK_TICK_EN
to DEF_ENABLED
. If your application does not require any form of timeouts or time keeping, either with timeouts on kernel objects or delayed execution times, you may set OS_CFG_TASK_TICK_EN
to DEF_DISABLED
. Doing so, removes all time keeping facilities from µC/OS-III. Removing the Tisk Task from µC/OS-III allows the user to save code and data space. However, the users looses the ability to use timeouts and delays.
Task Local Storage Configuration
OS_CFG_TLS_TBL_SIZE
If your application requires task local storage, set OS_CFG_TLS_TBL_SIZE
to a non-null value. This value will determine the size of the Task Local Storage Table (TLS_Tbl
, member of OS_TCB
) present in each task. To disable TLS, set this option to 0u
.
Time Management Options
OS_CFG_TIME_DLY_HMSM_EN
If your application requires the ability to delay a task for a specified number of hours, minutes, seconds and milliseconds, set OS_CFG_TIME_DLY_HMSM_EN
...
to DEF_ENABLED
. This will allow the generation of the
...
OSTimeDlyHMSM()
...
function. Otherwise, set this option to DEF_DISABLED
.
OS_CFG_TIME_DLY_RESUME_EN
When OS_CFG_TIME_DLY_RESUME_EN
...
is set to DEF_ENABLED
, it allows applications to resume a previously delayed task, using the function OSTimeDlyResume()
, without waiting for the entire delay. If you do not require this feature, set this option to DEF_DISABLED
.
Timer Management Options
OS_CFG_
...
TMR_EN
When OS_CFG_
...
TMR_EN
is set to DEF_ENABLED
, it enables the timer management services. If your application does no require programmable timers, set this option to DEF_DISABLED
to reduce µC/OS-III's required code and data space.
OS_CFG_TMR_DEL_EN
Enables (when set to 1
) or disables (when set to 0
) the code generation of timer management services.
OS_CFG_TMR_DEL_EN
OS_CFG_TMR_DEL_EN
enables (when set to 1
) or disables (when set to 0
) the code generation of the function OSTmrDel()
.
TRACE_CFG_EN
...
If your application needs to delete timers with OSTmrDel
once they're created, set ()
OS_CFG_TMR_DEL_EN
to DEF_ENABLED
, if not, set this option to DEF_DISABLED
. Critical applications should not delete kernel objects once the kernel is started.
Trace Options
OS_CFG_TRACE_EN
µC/OS-III has built-in trace points throughout the code to record all the kernel events and interrupts in real-time. These trace calls are disabled by default and enabled when this constant is set to DEF_ENABLED
. If you do not require this feature, set this option to DEF_DISABLED
to not only reduce the required code and data space but also to eliminate the inherent overhead.
OS_CFG_TRACE_API_ENTER_EN
When this constant is set to DEF_ENABLED
the beginning of each API call in µC/OS-III will be recorded as part of the trace (it applies to SEGGER's SystemView only).
OS_CFG_TRACE_API_EXIT_EN
When this constant is set to DEF_ENABLED
the end of each API call in µC/OS-III will be recorded as part of the trace (it applies to SEGGER's SystemView only).