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.
...
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.
...
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_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 µ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.
...
Warning, this feature is DEPRECATED and will be removed in a future release of µC/OS-III.
When set to DEF_ENABLED
, 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 this to DEF_ENABLED
is 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 DEF_ENABLED
when enabling the following services, since setting this to DEF_DISABLED
would would potentially make interrupt latency unacceptably high:
µC/OS-III Service | Enabled by |
---|---|
Event Flags | OS_CFG_FLAG_EN |
Multiple Pend | OS_CFG_PEND_MULTI_EN |
OS???Post() with broadcast | |
OS???Del() with OS_OPT_DEL_ALWAYS | |
OS???PendAbort() | OS_CFG_???_PEND_ABORT |
The compromise to make is:
OS_CFG_ISR_POST_DEFERRED_EN
set to DEF_ENABLED
Short interrupt latency, longer ISR-to-task response.
OS_CFG_ISR_POST_DEFERRED_EN
set to DEF_DISABLED
Long interrupt latency (see table above), shorter ISR-to-task response.
...
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 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.
...
When OS_CFG_TS_EN
is set to DEF_ENABLED
, it enables 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_PEND_MULTI_EN
Warning, this feature is DEPRECATED and will be removed in a future release of µC/OS-III.
When this option is set to DEF_ENABLED
, it allows the user to pend on multiple objects (message queues and semaphores only) at once.
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.
...
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 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.
...
When OS_CFG_FLAG_EN
is set to DEF_ENABLED
, it enables the event 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.
...
When OS_CFG_MEM_EN
is set to DEF_ENABLED
, it enables 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.
...
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 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.
...
If your application needs to delete mutexes with OSMutexDel
once they're created, set ()
to OS_CFG_MUTEX_DEL_EN
DEF_ENABLED
, if not, set this option to DEF_DISABLED
. Critical applications should not delete kernel objects once the kernel is started.
...
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
.
...
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.
...
When OS_CFG_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
.
...
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.
...
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
.
...
If your application needs to explicitly set the value of a semaphore with OSSemSet()
at at another time than it's creation, set OS_CFG_SEM_SET_EN
to DEF_ENABLE
, if not, set this option to DEF_DISABLED
.
...
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.
...
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.
...
OS_CFG_STAT_TASK_STK_CHK_EN
When set to DEF_ENABLED
, this 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.
...
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.
...
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
...
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 If your application does not require this feature, set this option to DEF_DISABLED
.
...
Although not specifically part of µC/OS-III, µC/Trace, a Windows-based RTOS Event Analyzer (i.e. tool) that is fully integrated in the latest version of µC/OS-III. µC/Trace functionality is enabled by setting TRACE_CFG_EN
to DEF_ENABLED
. You will need to have purchased the µC/Trace product in order to set TRACE_CFG_EN
to DEF_ENABLED
or else your compiler will complain about missing macros and functions. Consult the Micriµm website for details and availability of this highly useful tool.