Configuration Manual
This chapter provides a description of the configurable elements of the Flexible Safety RTOS. Because the RTOS is provided in source form, configuration is done through a number of #define constants, which are found in os_cfg.h and should exist for each project/product that you develop. In other words, configuration is done via conditional compilation.
Instead of creating an os_cfg.h file from scratch, it is recommended that you copy and modify the template os_cfg.h file provided in the delivery that came with the Flexible Safety RTOS.
This section describes each of the #define constants in os_cfg.h.
Warning
The evaluation is provided with a precompiled library. For this reason you can’t change the configuration settings!
Miscellaneous
OS_APP_HOOKS_EN
When set to 1, this #define specifies that application defined hooks are called from internal RTOS hooks.
See also OS_CPU_HOOKS_EN. Specifically:
The internal hook … |
Calls the Application-define hook … |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
OS_ARG_CHK_EN
OS_ARG_CHK_EN indicates whether you want most of the RTOS functions to perform argument checking. When set to 1, the RTOS will ensure that pointers passed to functions are non-NULL, that arguments passed are within allowable range and more. OS_ARG_CHK_EN was added to reduce the amount of code space and processing time required by the RTOS.
Set OS_ARG_CHK_EN to 0 if you must reduce code space to a minimum. In general, you should always enable argument checking and thus set OS_ARG_CHK_EN to 1.
OS_CPU_HOOKS_EN
OS_CPU_HOOKS_EN indicates whether os_cpu_c.c declares the hook function (when set to 1) or not (when set to 0). Recall that the Flexible Safety RTOS expects the presence of eight functions that can be defined either in the port (i.e., in os_cpu_c.c) or by the application code.
These functions are:
OSInitHookBegin()OSInitHookEnd()OSTaskCreateHook()OSTaskDelHook()OSTaskIdleHook()OSTaskReturnHook()OSTaskSwHook()OSTimeTickHook()
OS_EVENT_MULTI_EN
This constant determines whether the code to support pending on multiple events will be enabled (1) or not (0). This constant thus enables code for the function OSEventPendMulti().
OS_EVENT_NAME_EN
This constant determines whether names can be assigned to either a semaphore, a mutex, a mailbox or a message queue. If OS_EVENT_NAME_EN is set to 0, this feature is disabled. You should note that need to use OSEventNameSet() to set the name of either a semaphores, a mutex, a mailbox or a message queue. You need to use OSEventNameGet() to obtain the name of either a semaphores, a mutex, a mailbox or a message queue.
OS_LOWEST_PRIO
OS_LOWEST_PRIO specifies the lowest task priority (i.e., highest number) that you intend to use in your application and is provided to reduce the amount of RAM needed by Flexible Safety RTOS. RTOS priorities can go from 0 (highest priority) to a maximum of 254 (lowest possible priority). Setting OS_LOWEST_PRIO to a value less than 254 means that your application cannot create tasks with a priority number higher than OS_LOWEST_PRIO. In fact, the RTOS reserves the priority OS_LOWEST_PRIO for itself; OS_LOWEST_PRIO is reserved for the idle task, OS_TaskIdle().
The priorities of your application tasks can thus take a value between 0 and OS_LOWEST_PRIO – 1 (inclusive). The lowest task priority specified by OS_LOWEST_PRIO is independent of OS_MAX_TASKS. For example, you can set OS_MAX_TASKS to 10 and OS_LOWEST_PRIO to 32 and have up to 10 application tasks, each of which can have a task priority value between 0 and 31 (inclusive).
Note that each task must still have a different priority value. You must always set OS_LOWEST_PRIO to a value greater than the number of application tasks in your system. For example, if you set OS_MAX_TASKS to 20 and OS_LOWEST_PRIO to 10, you can not create more than nine application tasks (0 to 8) since priority 9 is the idle task. You are simply wasting RAM.
OS_MAX_EVENTS
OS_MAX_EVENTS specifies the maximum number of event control blocks that can be allocated. An event control block is needed for every message mailbox, message queue, mutual exclusion semaphore, or semaphore object. For example, if you have 10 mailboxes, 5 queues, 4 mutexes, and 3 semaphores, you must set OS_MAX_EVENTS to at least 22. OS_MAX_EVENTS must be greater than 0.
See also OS_MBOX_EN, OS_Q_EN, OS_MUTEX_EN, and OS_SEM_EN.
OS_MAX_FLAGS
OS_MAX_FLAGS specifies the maximum number of event flags that you need in your application. OS_MAX_FLAGS must be greater than 0. To use event-flag services, you also need to set OS_FLAG_EN to 1.
OS_MAX_MEM_PART
OS_MAX_MEM_PART specifies the maximum number of memory partitions that your application can create. To use memory partitions, also need to set OS_MEM_EN to 1. If you intend to use memory partitions, OS_MAX_MEM_PART must be set to at least the number of partitions you wish to create. For example, by setting OS_MAX_MEM_PART to 3, your are allowed to create and use up to three memory partitions. Setting OS_MAX_MEM_PART to a number greater than the number of memory partitions your application uses will not cause problems but is unnecessary and a waste of RAM.
OS_MAX_QS
OS_MAX_QS specifies the maximum number of message queues that your application can create. To use message queues, you also must set OS_Q_EN to 1. If you intend to use message queues, OS_MAX_QS must be set to at least the number of queues you wish to create. For example, if you set OS_MAX_QS to 3, you are allowed to create and use up to three message queues. Setting OS_MAX_QS to greater than the number of message queues your application uses will not cause problems but is unnecessary and a waste of RAM.
OS_MAX_TASKS
OS_MAX_TASKS specifies the maximum number of application tasks that can exist in your application. Note that OS_MAX_TASKS cannot be greater than 254 because the Flexible Safety RTOS currently reserves one task for itself (see OS_N_SYS_TASKS in ucos_ii.h). If you set OS_MAX_TASKS to the exact number of tasks in your system, you need to make sure that you revise this value when you add additional tasks. Conversely, if you make OS_MAX_TASKS much higher than your current task requirements (for future expansion), you are wasting valuable RAM.
OS_SCHED_LOCK_EN
This constant enables (when set to 1) or disables (when set to 0) code generation for the two functions OSSchedLock() and OSSchedUnlock().
OS_TICKS_PER_SEC
OS_TICKS_PER_SEC specifies the rate at which you call OSTimeTick(). It is up to your initialization code to ensure that OSTimeTick() is invoked at this rate. This constant is used by OSTimeDlyHMSM().
Event Flags
OS_FLAG_EN
OS_FLAG_EN enables (when set to 1) or disables (when set to 0) code generation of all the event-flag services and data structures, which reduces the amount of code and data space needed when your application does not require the use of event flags. When OS_FLAG_EN is set to 0, you do not need to enable or disable any of the other #define constants in this section.
OS_FLAG_ACCEPT_EN
OS_FLAG_ACCEPT_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSFlagAccept().
OS_FLAG_DEL_EN
OS_FLAG_DEL_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSFlagDel().
OS_FLAG_NAME_EN
This constant determines whether names can be assigned to event flag groups. If OS_FLAG_NAME_EN is set to 0, this feature is disabled.
OS_FLAG_QUERY_EN
OS_FLAG_QUERY_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSFlagQuery().
OS_FLAG_WAIT_CLR_EN
OS_FLAG_WAIT_CLR_EN enables (when set to 1) or disables (when set to 0) the code generation used to wait for event flags to be 0 instead of 1. Generally, you want to wait for event flags to be set. However, you might also want to wait for event flags to be clear, and thus you need to enable this option.
OS_FLAGS_NBITS
OS_FLAGS_NBITS specifies the number of bits used in event flags and MUST be either 8, 16 or 32.
Message Mailboxes
OS_MBOX_EN
This constant enables (when set to 1) or disables (when set to 0) the code generation of all message-mailbox services and data structures, which reduces the amount of code space needed when your application does not require the use of message mailboxes. When OS_MBOX_EN is set to 0, you do not need to enable or disable any of the other #define constants in this section.
OS_MBOX_ACCEPT_EN
This constant enables (when set to 1) or disables (when set to 0) the code generation of the function OSMboxAccept().
OS_MBOX_DEL_EN
This constant enables (when set to 1) or disables (when set to 0) the code generation of the function OSMboxDel().
OS_MBOX_PEND_ABORT_EN
OS_MBOX_PEND_ABORT_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSMboxPendAbort().
OS_MBOX_QUERY_EN
OS_MBOX_QUERY_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSMboxQuery().
Memory Management
OS_MEM_EN
OS_MEM_EN enables (when set to 1) or disables (when set to 0) all code generation of the Flexible Safety RTOS partition-memory manager and its associated data structures. This feature reduces the amount of code and data space needed when your application does not require the use of memory partitions.
OS_MEM_NAME_EN
This constant determines whether names can be assigned to memory partitions. If OS_MEM_NAME_EN is set to 0, this feature is disabled and no RAM is used in the OS_MEM for the memory partition for storage of names.
OS_MEM_QUERY_EN
OS_MEM_QUERY_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSMemQuery().
Mutual Exclusion Semaphores
OS_MUTEX_EN
OS_MUTEX_EN enables (when set to 1) or disables (when set to 0) the code generation of all mutualexclusion-semaphore services and data structures, which reduces the amount of code and data space needed when your application does not require the use of mutexes. When OS_MUTEX_EN is set to 0, you do not need to enable or disable any of the other #define constants in this section.
OS_MUTEX_ACCEPT_EN
OS_MUTEX_ACCEPT_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSMutexAccept().
OS_MUTEX_DEL_EN
OS_MUTEX_DEL_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSMutexDel().
OS_MUTEX_QUERY_EN
OS_MUTEX_QUERY_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSMutexQuery().
Message Queues
OS_Q_EN
OS_Q_EN enables (when set to 1) or disables (when set to 0) the code generation of all message-queue services and data structures, which reduces the amount of code space needed when your application does not require the use of message queues. When OS_Q_EN is set to 0, you do not need to enable or disable any of the other #define constants in this section.
Note that if OS_Q_EN is set to 0, the #define constant OS_MAX_QS is irrelevant.
OS_Q_ACCEPT_EN
OS_Q_ACCEPT_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSQAccept().
OS_Q_DEL_EN
OS_Q_DEL_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSQDel().
OS_Q_FLUSH_EN
OS_Q_FLUSH_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSQFlush().
OS_Q_PEND_ABORT_EN
OS_Q_PEND_ABORT_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSQPendAbort().
OS_Q_QUERY_EN
OS_Q_QUERY_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSQQuery().
Semaphores
OS_SEM_EN
OS_SEM_EN enables (when set to 1) or disables (when set to 0) all code generation of the Flexible Safety RTOS semaphore manager and its associated data structures, which reduces the amount of code and data space needed when your application does not require the use of semaphores. When OS_SEM_EN is set to 0, you do not need to enable or disable any of the other #define constants in this section.
OS_SEM_ACCEPT_EN
OS_SEM_ACCEPT_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSSemAccept().
OS_SEM_DEL_EN
OS_SEM_DEL_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSSemDel().
OS_SEM_PEND_ABORT_EN
OS_SEM_PEND_ABORT_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSSemPendAbort().
OS_SEM_QUERY_EN
OS_SEM_QUERY_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSSemQuery().
OS_SEM_SET_EN
OS_SEM_SET_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSSemSet().
Task Management
OS_TASK_TMR_STK_SIZE
OS_TASK_TMR_STK_SIZE specifies the size of the Flexible Safety RTOS timer task stack. The size is specified not in bytes but in number of elements. This is because a stack is declared to be of type OS_STK. The size of the timer-task stack depends on the processor you are using, the callback functions that will be executed when each of the timer times out and the deepest anticipated interrupt-nesting level.
OS_TASK_IDLE_STK_SIZE
OS_TASK_IDLE_STK_SIZE specifies the size of the Flexible Safety RTOS idle-task stack. The size is specified not in bytes but in number of elements. This is because a stack is declared to be of type OS_STK. The size of the idle-task stack depends on the processor you are using and the deepest anticipated interrupt-nesting level. Very little is being done in the idle task, but you should allow at least enough space to store all processor registers on the stack and enough storage to handle all nested interrupts.
OS_TASK_CHANGE_PRIO_EN
OS_TASK_CHANGE_PRIO_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSTaskChangePrio(). If your application never changes task priorities after they are assigned, you can reduce the amount of code space used by the RTOS by setting OS_TASK_CHANGE_PRIO_EN to 0.
OS_TASK_DEL_EN
OS_TASK_DEL_EN enables (when set to 1) or disables (when set to 0) code generation of the function OSTaskDel(), which deletes tasks. If your application never uses this function, you can reduce the amount of code space used by the RTOS by setting OS_TASK_DEL_EN to 0.
OS_TASK_NAME_EN
This constant determines whether you can assign names to tasks. If OS_TASK_NAME_EN is set to 0, this feature is disabled and no RAM is used in the OS_TCB for the task name.
OS_TASK_SUSPEND_EN
OS_TASK_SUSPEND_EN enables (when set to 1) or disables (when set to 0) code generation of the functions OSTaskSuspend() and OSTaskResume(), which allows you to explicitly suspend and resume tasks, respectively. If your application never uses these functions, you can reduce the amount of code space used by the RTOS by setting OS_TASK_SUSPEND_EN to 0.
OS_TASK_SW_HOOK_EN
Normally, Flexible Safety RTOS requires that you have a context switch hook function called OSTaskSwHook(). When set to 0, this constant allows you to omit OSTaskSwHook() from your code. This configuration constant was added to reduce the amount of overhead during a context switch in applications that doesn’t require the context switch hook. Of course, you will also need to remove the calls to OSTaskSwHook() from OSTaskStartHighRdy(), OSCtxSw() and OSIntCtxSw() in os_cpu_a.asm.
OS_TASK_TMR_PRIO (APP_CFG.H)
OS_TASK_TMR_PRIO specifies the priority of the timer management task. You can set the priority of the timer task to anything you want. Note that timer callback functions are executed by the timer task. OS_TASK_TMR_PRIO needs to be set in your application file called app_cfg.h.
OS_TASK_QUERY_EN
OS_TASK_QUERY_EN enables (when set to 1) or disables (when set to 0) code generation of the function OSTaskQuery(). If your application never uses this function, you can reduce the amount of code space used by Flexible Safety RTOS by setting OS_TASK_QUERY_EN to 0.
Time Management
OS_TIME_DLY_HMSM_EN
OS_TIME_DLY_HMSM_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSTimeDlyHMSM(), which is used to delay a task for a specified number of hours, minutes, seconds, and milliseconds.
OS_TIME_DLY_RESUME_EN
OS_TIME_DLY_RESUME_EN enables (when set to 1) or disables (when set to 0) the code generation of the function OSTimeDlyResume().
OS_TIME_GET_SET_EN
OS_TIME_GET_SET_EN enables (when set to 1) or disables (when set to 0) the code and data generation of the functions OSTimeGet() and OSTimeSet(). If you don’t need to use the 32-bit tick counter OSTime, then you can save yourself 4 bytes of data space and code space by not having the code for these functions generated by the compiler.
OS_TIME_TICK_HOOK_EN
Normally, the RTOS requires the presence of a function called OSTimeTickHook() which is called at the very beginning of the tick ISR. When set to 0, this constant allows you to omit OSTimeTickHook() from your code. This configuration constant was added to reduce the amount of overhead during a tick ISR in applications that doesn’t require this hook.
Timer Management
Note that timer management requires semaphores and thus, you need to set OS_SEM_EN to 1.
OS_TMR_EN
Enables (when set to 1) or disables (when set to 0) the code generation of the timer management services.
OS_TMR_CFG_MAX
Determines the maximum number of timers you can have in your application. Depending on the amount of RAM available in your product, you can have hundreds or even thousands of timers (max. is 65500). 36 entries are reserved.
OS_TMR_CFG_NAME_EN
This constant determines whether names can be assigned to timers. If OS_TMR_CFG_NAME_EN is set to 0, this feature is disabled and no RAM is used in the OS_TMR for the timer name.
OS_TMR_CFG_WHEEL_SIZE
Timers are updated using a rotating wheel. This ‘wheel’ allows to reduce the number of timers that need to be updated by the timer manager task. The size of the wheel should be a fraction of the number of timers you have in your application. In other words:
OS_TMR_CFG_WHEEL_SIZE <= OS_TMR_CFG_MAX
This value should be a number between 2 and 1024. Timer management overhead is somewhat determined by the size of the wheel. A large number of entries might reduce the overhead for timer management but would require more RAM. Each entry requires a pointer and a count (16-bit value). We recommend a number that is NOT a multiple of the tick rate. If your application has many timers then it’s recommended that you have a high value. As a starting value, you could use OS_TMR_CFG_MAX / 4.
OS_TMR_CFG_TICKS_PER_SEC
This configuration constant determines the rate at which timers are updated (in Hz). Timer updates should be done at a fraction of the tick rate (i.e. OS_TICKS_PER_SEC). We recommend that you update timers at 10 Hz.
Function Summary
The following table lists each Flexible Safety RTOS API function by type (Service), indicates which variables enable the code (Set to 1), and lists other configuration constants that affect the function (Other Constants).
Of course, os_cfg.h must be included when the Flexible Safety RTOS is built, in order for the desired configuration to take effect.
Service |
Set to 1 |
Other Constants |
|---|---|---|
N/A |
||
N/A |
||
N/A |
OS_MAX_EVENTS, OS_Q_EN, OS_MAX_QS, OS_MEM_EN, OS_TASK_IDLE_STK_SIZE |
|
|
||
N/A |
||
N/A |
||
N/A |
N/A |
|
N/A |
N/A |
Service |
Set to 1 |
Other Constants |
|---|---|---|
N/A |
N/A |
|
N/A |
N/A |
Service |
Set to 1 |
Other Constants |
|---|---|---|
N/A |
||
Service |
Set to 1 |
Other Constants |
|---|---|---|
N/A |
||
N/A |
||
Service |
Set to 1 |
Other Constants |
|---|---|---|
N/A |
||
N/A |
||
Service |
Set to 1 |
Other Constants |
|---|---|---|
N/A |
||
N/A |
||
Service |
Set to 1 |
Other Constants |
|---|---|---|
N/A |
||
N/A |
||
Service |
Set to 1 |
Other Constants |
|---|---|---|
N/A |
||
N/A |
||
Service |
Set to 1 |
Other Constants |
|---|---|---|
N/A |
||
N/A |
||
N/A |
||
Service |
Set to 1 |
Other Constants |
|---|---|---|
N/A |
N/A |
|
N/A |
||
N/A |
||
N/A |
N/A |
Service |
Set to 1 |
Other Constants |
|---|---|---|
N/A |
||
N/A |
||
N/A |
||
N/A |
||
N/A |
||
N/A |
||
Service |
Set to 1 |
Other Constants |
|---|---|---|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
||
|
Service |
Set to 1 |
Other Constants |
|---|---|---|