|
 |
|
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. | |
Timer.
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.
| 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.
| [in] | args | pointer to arguments passed to callback |
| enum os_timer_state_e |
Timer state.
| 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. |
{
OS_TIMER_ARMED = 10,
OS_TIMER_EXPIRED = 11,
OS_TIMER_TERMINATED = 12
};
| enum os_timer_type_e |
Types of the timer.
{
OS_TIMER_SINGLE = 1,
OS_TIMER_REPETITIVE = 2
};
| 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.
| [in] | timer | pointer to timer structure |
| [in] | type | type of timer (single/periodic) |
| [in] | timeout | timeout in tick units |
| [in] | fun | callback function |
| [in] | arg | arguments passed to callback |
| 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.
| [in] | timer | pointer to the timer structure |
| 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.