Project 1: RTOS Timer Management
As a member of software engineering team, you are tasked to design a timer management system for the Real Time Operating Syst em that
is being developed in house for use in an embedded communication device. The following describes the high level design document.
The figure below shows the state diagram of a timer.
Tasks can call RTOSTmrStateGet() to find out the state of a timer. Also, at any time during the countdown process, the application code
can call RTOSTmrRemainGet() to find out how much time remains before the timer reaches zero (0). The value returned is expressed in
“timer ticks.” If timers are decremented at a rate of 10 Hz then a count of 50 corresponds to 5 seconds. If the timer is in the stop state, the
time remaining will correspond to either the initial delay (one shot or periodic with initial delay), or the period if the timer is configured for
periodic without initial delay.
Project 1: RTOS Timer Management
Figure - Timer State Diagram
(1)
The “Unused” state is a timer that has not been created or has been “deleted.”
(2)
When creating a timer or calling RTOSTmrStop(), the timer is placed in the “stopped” state.
(3)
A timer is placed in running state when calling RTOSTmrStart(). The timer stays in that state unless it’s stopped, deleted, or completes its
one shot.
(4)
The “Completed” state is the state a one-shot timer is in when its delay expires.
A timer is a kernel object as defined by the RTOS_TMR data type as shown in the listing below:
typedef struct os_tmr {
INT8U RTOSTmrType; /* Should always be set to RTOS_TMR_TYPE for timers */
RTOS_TMR_CALLBACK RTOSTmrCallback; /* Function to call when timer expires */
void *RTOSTmrCallbackArg; /* Argument to callback function */
void *RTOSTmrNext; /* Double link list pointers */
void *RTOSTmrPrev;
INT32U RTOSTmrMatch; /* Timer expires when RTOSTmrTickCtr = RTOSTmrMatch*/
INT32U RTOSTmrDly; /* Delay time before periodic update starts */
INT32U RTOSTmrPeriod; /* Period to repeat timer */
INT8U *RTOSTmrName; /* Name to give the timer */
INT8U RTOSTmrOpt; /* Options (see RTOS_TMR_OPT_xxx) */
INT8U RTOSTmrState; /* Indicates the state of the timer:*/
/* RTOS_TMR_STATE_UNUSED */
/* RTOS_TMR_STATE_RUNNING */
/* RTOS_TMR_STATE_STOPPED */
} RTOS_TMR;
The structure starts with a “RTOSTmrType” field, which allows it to be recognized by OS as a timer. Other kernel objects will also have a
“Type” as the first member of the structure. If a function is passed a kernel object, OS is able to confirm that it is passed the proper data
Project 1: RTOS Timer Management
type. For example, if passing a message queue to a timer service (for example RTOSTmrStart()) then OS will be able to recognize that an
invalid object was passed, and return an error code accordingly.
Each kernel object can be given a name (RTOSTmrName) for easier recognition by debuggers. This member is simply a pointer to an ASCII
string which is assumed to be NUL terminated.
The . RTOSTmrCallback member is a pointer to a function that is called when the timer expires. If a timer is created and passed
a NULL pointer, a callback would not be called when the timer expires.
If there is a non-NULL . RTOSTmrCallback then the application code could have also specified that the callback be called with an argument
when the timer expires. This is the argument that would be passed in this call.
RTOSTmrNext and RTOSTmrPrev are pointers used to link a timer in a doubly linked list. These are described later.
The RTOSTmrDly field contains the one-shot time when the timer is configured (i.e., created) as a one-shot timer and the initial delay when
the timer is created as a periodic timer. The value is expressed in multiples of 1/RTOS_CFG_TMR_TASK_RATE_HZ of a second.
The RTOSTmrPeriod field is the timer period when the timer is created to operate in periodic mode. The value is expressed in multiples
of 1/RTOS_CFG_TMR_TASK_RATE_HZ of a second.
The RTOSTmrOpt field contains options that are passed to RTOSTmrCreate().
The RTOSTmrState field represents the current state of the timer (see the figure in Timers States).
Even if the internals of the RTOS_TMR data type are understood, the application code should never access any of the fields in this data
structure directly. Instead, you should always use the Application Programming Interfaces (APIs) provided.
Project 1: RTOS Timer Management
RTOS_TmrTask() is a task created by OS (i.e. you) and its priority is configurable by the user. RTOS_TmrTask() is typically set to a
medium priority.
RTOS_TmrTask() is a periodic task and uses the same interrupt source used to generate clock ticks. However, timers are generally
updated at a slower rate (i.e., typically 10 Hz or so) and thus, the timer tick rate is divided down in software. If the tick rate is 1000 Hz and
the desired timer rate is 10 Hz then the timer task will be signaled every 100th tick interrupt as shown in the figure below.
1) The tick ISR occurs and assumes interrupts are enabled and executes.
(2) The tick ISR signals the tick task that it is time for it to update timers.
(3) The tick ISR terminates, however there might be higher priority tasks that need to execute (assuming the timer task has a lower priority).
Therefore, OS runs the higher priority task(s).
(4) When all higher priority tasks have executed, OS switches to the timer task and determines that there are three timers that expired.
(5) The callback for the first timer is executed.
(6) The callback for the second expired timer is executed.
(7) The callback for the third expired timer is executed.
There are a few interesting things to notice:
Execution of the callback functions is performed within the context of the timer task. This means that the application code will need to
make sure there is sufficient stack space for the timer task to handle these callbacks.
The callback functions are executed one after the other based on the order they are found in the timer list.
The execution time of the timer task greatly depends on how many timers expire and how long each of the callback functions takes to
execute. Since the callbacks are provided by the application code they have a large influence on the execution time of the timer task.
The timer callback functions must never wait on events because this would delay the timer task for excessive amounts of time, if not
forever.
Callbacks should execute as quickly as possible.
Timer List - Timer Management Internals Design Options
µC/OS-III applications may require many timers. The timer manager implements a simple linear list where each timer is linked in a d oubly
linked list as shown in the figure below.
(1)
RTOSTmrListEntries contains the current number of entries in the list. This variable is updated whenever timers are added or removed
from the list.
(2)
RTOSTmrListPtr contains a pointer to a doubly linked list of timers that the timer manager will need to update.
(3)
RTOSTmrTickCtr is incremented by RTOS_TmrTask() every time the tick ISR signals the task. This counter basically keeps track of the
number of times the timer task has been signaled.
(3) RTOSTmrTickCtr
(2) RTOSTmrListPtr
(1) RTOSTmrListEntries
0
Project 1: RTOS Timer Management
Timers are inserted in the timer list by calling RTOSTmrStart() and, a timer must be created before it can be used. Newly created timers
are always inserted at the beginning of the list as shown in the figure following the code listing below and the code listing itself.
RTOS_TMR MyTmr1;
RTOS_TMR MyTmr2;
void MyTmrCallbackFnct1 (void *p_arg)
{
/* Do something when timer #1 expires */
}
void MyTmrCallbackFnct2 (void *p_arg)
{
/* Do something when timer #2 expires */
}
void MyTask (void *p_arg)
{
RTOS_ERR err;
while (DEF_ON) {
:
RTOSTmrCreate((RTOS_TMR *)MyTmr1,
(RTOS_CHAR *)“My Timer #1”,
(RTOS_TICK )1,
(RTOS_TICK )0,
(RTOS_OPT )RTOS_OPT_TMR_ONE_SHOT,
(RTOS_TMR_CALLBACK_PTR)MyTmrCallbackFnct1,
(void *)0,
(RTOS_ERR *)err);
/* Check ’err” */
Project 1: RTOS Timer Management
32
33
34
35
36
RTOSTmrStart ((RTOS_TMR *)MyTmr1,
(RTOS_ERR *)err);
/* Check “err” */
// Continues in the next code listing!
Listing - Creating and Starting a timer
Since this is the first timer inserted in the timer list, the .NextPtr and .PrevPtr both point to NULL.
Figure - Inserting a timer in the timer list
The code below shows creating and starting another timer. This is performed “before” the timer task is signaled.
1
2
3
4
5
6
7
8
9
// Continuation of code from previous code listing.
:
:
RTOSTmrCreate((RTOS_TMR *)MyTmr2,
(RTOS_CHAR *)“My Timer #2”,
(RTOS_TICK )10,
(RTOS_TICK )0,
(RTOS_OPT )RTOS_OPT_TMR_ONE_SHOT,
(RTOS_TMR_CALLBACK_PTR)MyTmrCallbackFnct2,
(void *)0,
0
RTOSTmrListEntries
RTOSTmrListPtr
RTOSTmrTickCtr
RTOSTmrNextPtr
RTOSTmrPrevPtr
RTOSTmrTickCtr 0
OS_TMR
Project 1: RTOS Timer Management
10
11
12
13
14
15
16
17
(RTOS_ERR *)err);
/* Check ’err” */
RTOSTmrStart ((RTOS_TMR *)MyTmr,
(RTOS_ERR *)err);
/* Check ’err” */
}
}
Listing - Creating and Starting a timer - continued
The “second timer” is inserted at the head of the list as shown in the figure below.