core/include/timer.h File Reference

Timer. More...

Data Structures

struct  os_timer_s
 Timer. More...

Typedefs

typedef enum os_timer_type_e os_timer_type_t
 Data type for timer type.
typedef enum os_timer_state_e os_timer_state_t
 Data type for timer state.
typedef os_result_t(* os_timer_cb )(void *args)
 Type of callback function called when timer expires.
typedef struct os_timer_s os_timer_t
 Data type of timer.

Enumerations

enum  os_timer_type_e { OS_TIMER_SINGLE = 1, OS_TIMER_REPETITIVE = 2 }
 

Types of the timer.

More...
enum  os_timer_state_e { OS_TIMER_ARMED = 10, OS_TIMER_EXPIRED = 11, OS_TIMER_TERMINATED = 12 }
 

Timer state.

More...

Functions

unsigned short os_timer_tick_cnt (void)
 The function returns tick counter.
os_result_t os_timer_create (os_timer_t *timer, os_timer_type_t type, unsigned short timeout, os_timer_cb fun, void *arg)
 Creates timer and runs it.
os_result_t os_timer_delete (os_timer_t *timer)
 Delete timer.

Detailed Description

Timer.

Author:
Piotr Romaniuk, (c) ELESOFTROM
Version:
1.1 Nov 8, 2013

Software timers implemented in the DioneOS works on the basis of hardware triggered tick interrupt. The interrupt is generated periodically by hardware counter present in microcontroller. The counter is clocked by one of the system clocks and generates interrupt when counted value exceeds limit set in initial configuration (os_timers_init() and os_timers_start()).
Recommended tick period is 1ms, but it can be altered if an user does not need so fine resolution. Small part of the timer code need to be written by an user (in timer_user.h). It is proper initialization of the hardware timer and its interrupt. It is left for the user because it depends system clock settings. The user knows its application and can tune tick interrupt to the requirement. Note that period of the tick interrupt is an unit for time dependent function.

In the system there are two types of the timers: single shot and repetitive. Former is triggered only once and after that is deleted, while the latter one is restarted each time the period elapses. The repetitive timer is active until it is deleted by user. When the timer expires the system executes callback function that has been registered during timer creation. This call is done in ISR context, so it cannot hold CPU for too long. If you need to do more it is better to signal the event to the thread that will process it. The callback mechanism is considered as low level.

The timer is indirectly used in higher level functions providing temporal control over the threads: os_sema_wait_timeouted() and os_sleep(). First function allows time limited waiting on semaphore while the last allows holding the thread execution for some time. In these functions timers are handled internally and are not visible for the user.

Remember that software timer has limited accuracy. First of all, delay is expressed in units of tick period. The second factor is asynchronous timer start caused by os_timer_create() that is asynchronous to tick interrupt moment. Because of that, real time may be shorter by less than 1 unit (it happens when timer is created just before tick interrupt). There are also other factors, but they can increase the time by small amount:
1. deferred tick interrupt due to occurrence inside critical section, where interrupts are disabled,
2. latency of the internal callback referred to tick ISR entry time,
3. higher level functions involve context switch.

Note:
Number of active timers affects time spent in tick ISR.

Typedef Documentation

typedef os_result_t(* os_timer_cb)(void *args)

Type of callback function called when timer expires.

The function will be called from ISR, with disabled interrupts. Because this call is in ISR context the function must respect general rules of code in ISR (i.e. it cannot call blocking functions). It is recommended to write short callback. If longer processing time is required it is better to signal by event to the thread and there continue processing.

Parameters:
[in]argspointer to arguments passed to callback
Returns:
should return valid result code
Note:
Although the result code is not tested in current version of the system, it should be set to valid value for future compatibility.

Enumeration Type Documentation

Timer state.

Enumerator:
OS_TIMER_ARMED 

Timer in armed state, waits for timeout.

OS_TIMER_EXPIRED 

Timer expired (not used in current implementation)

OS_TIMER_TERMINATED 

Timer has been terminated.

Types of the timer.

Enumerator:
OS_TIMER_SINGLE 

single shot timer

OS_TIMER_REPETITIVE 

repetitive timer


Function Documentation

os_result_t os_timer_create ( os_timer_t timer,
os_timer_type_t  type,
unsigned short  timeout,
os_timer_cb  fun,
void *  arg 
)

Creates timer and runs it.

The function initiates timer structure. It fills the fields defined in argument list and determines others. After that it starts the timer.

Note:
The timer expiration may be in a range (timeout-1, timeout+latency),
where latency depends on system load, processed interrupts. -1 is caused by quantum counting and not synchronized call of the timer start.
Warning:
If timer creation (i.e. os_timer_create() call) is not within critical section and timeout is short, it may expire before function returns.
Parameters:
[in]timerpointer to timer structure
[in]typetype of timer (single/periodic)
[in]timeouttimeout in tick units
[in]funcallback function
[in]argarguments passed to callback
Returns:
always returns OS_STATUS_OK
os_result_t os_timer_delete ( os_timer_t timer)

Delete timer.

The timer is detached from system list of timers. It means that it is stopped and its callback will be not called. This is done automatically when timer expires and is single shot.

Note:
It is safe to call this even if the timer is already removed from system list. Such conditions are not considered as error.
Parameters:
[in]timerpointer to the timer structure
Returns:
always returns OS_STATUS_OK
Warning:
Do not call os_timer_delete from timer callback.
unsigned short os_timer_tick_cnt ( void  )

The function returns tick counter.

The function reads and returns tick counter value. It is incremented periodically, each tick interrupt. It may be used for coarse execution measurement. Please remember that this is total time spent between two points if the thread is preempted time measurement is not stopped but is included in result.

Note:
1. the value of the counter may wrap around, hence if it is used for time testing it must be taken into account.
2. Due to wrapping around only delays shorter that 65535 tick units can be counted
Returns:
current value of the counter