Collaboration diagram for Timer services.:
Detailed Description
The RTAI/fusion timer facility behaves slightly differently depending on the underlying system timer mode, i.e. periodic or aperiodic. In periodic mode, the hardware timer ticks periodically without any external programming (aside of the initial one which sets its period). In such a case, a BSD timer wheel (see "Redesigning the BSD Callout and Timer Facilities" by Adam M. Costello and George Varghese) is used to its full addressing capabilities.
If the underlying timer source is aperiodic, we need to reprogram the next shot after each tick at hardware level, and we do not need any periodic source. In such a case, the timer manager only uses a single slot (#0) from the wheel as a plain linked list, which is ordered by increasing timeout values of the running timers.
Depending on the above mode, the timer object stores time values either as count of periodic ticks, or as count of CPU ticks.
The current implementation assumes that the maximum number of outstanding timers in aperiodic mode is low (< 16?). Would this assumption prove false, we would need to go for an AVL of some sort, likely a RB tree. The periodic mode is already based on a timer wheel, so there should not be any problem here, unless your application is some ugly monster from the dark ages...
Function Documentation
void xntimer_destroy |
( |
xntimer_t * |
timer |
) |
|
|
|
Release a timer object.
Destroys a timer. After it has been destroyed, all resources associated with the timer have been released. The timer is automatically deactivated before deletion if active on entry.
- Parameters:
-
| timer | The address of a valid timer descriptor. |
Environments:
This service can be called from:
- Kernel module initialization/cleanup code
- Interrupt service routine
- Kernel-based task
- User-space task
Rescheduling: never. |
void xntimer_do_timers |
( |
void |
|
) |
|
|
|
Process a timer tick.
For internal use only.
This routine informs all active timers that the clock has been updated by processing the timer wheel. Elapsed timer actions will be fired.
Environments:
This service can be called from:
- Interrupt service routine, nklock locked, interrupts off
Rescheduling: never.
- Note:
- Only active timers are inserted into the timer wheel.
|
void xntimer_freeze |
( |
void |
|
) |
|
|
|
Freeze all timers.
For internal use only.
This routine deactivates all active timers atomically.
Environments:
This service can be called from:
- Interrupt service routine, nklock unlocked
Rescheduling: never.
- Note:
- Always make sure the nklock is free when stopping the underlying timing source by calling xnarch_stop_timer(), otherwise, deadlock situations would arise on some architectures.
|
xnticks_t xntimer_get_date |
( |
xntimer_t * |
timer |
) |
|
|
|
Return the absolute expiration date.
Return the next expiration date of a timer in absolute clock ticks (see note).
- Parameters:
-
| timer | The address of a valid timer descriptor. |
- Returns:
- The expiration date converted to the current time unit. The special value XN_INFINITE is returned if timer is currently inactive.
Environments:
This service can be called from:
- Kernel module initialization/cleanup code
- Interrupt service routine
- Kernel-based task
- User-space task
Rescheduling: never.
- Note:
- This service is sensitive to the current operation mode of the system timer, as defined by the xnpod_start_timer() service. In periodic mode, clock ticks are expressed as periodic jiffies. In oneshot mode, clock ticks are expressed as nanoseconds.
|
xnticks_t xntimer_get_timeout |
( |
xntimer_t * |
timer |
) |
|
|
|
Return the relative expiration date.
Return the next expiration date of a timer in relative clock ticks (see note).
- Parameters:
-
| timer | The address of a valid timer descriptor. |
- Returns:
- The expiration date converted to the current time unit. The special value XN_INFINITE is returned if timer is currently inactive. In oneshot mode, it might happen that the timer has already expired when this service is run (even if the associated handler has not been fired yet); in such a case, 1 is returned.
Environments:
This service can be called from:
- Kernel module initialization/cleanup code
- Interrupt service routine
- Kernel-based task
- User-space task
Rescheduling: never.
- Note:
- This service is sensitive to the current operation mode of the system timer, as defined by the xnpod_start_timer() service. In periodic mode, clock ticks are expressed as periodic jiffies. In oneshot mode, clock ticks are expressed as nanoseconds.
|
void xntimer_init |
( |
xntimer_t * |
timer, |
|
|
void(*)(void *cookie) |
handler, |
|
|
void * |
cookie |
|
) |
|
|
|
Initialize a timer object.
Creates a timer. When created, a timer is left disarmed; it must be started using xntimer_start() in order to be activated.
- Parameters:
-
| timer | The address of a timer descriptor the nucleus will use to store the object-specific data. This descriptor must always be valid while the object is active therefore it must be allocated in permanent memory. |
| handler | The routine to call upon expiration of the timer. |
| cookie | A user-defined opaque cookie the nucleus will pass unmodified to the handler as its unique argument. |
There is no limitation on the number of timers which can be created/active concurrently.
Environments:
This service can be called from:
- Kernel module initialization/cleanup code
- Interrupt service routine
- Kernel-based task
- User-space task
Rescheduling: never. |
int xntimer_start |
( |
xntimer_t * |
timer, |
|
|
xnticks_t |
value, |
|
|
xnticks_t |
interval |
|
) |
|
|
|
Arm a timer.
Activates a timer so that the associated timeout handler will be fired after each expiration time. A timer can be either periodic or single-shot, depending on the reload value passed to this routine. The given timer must have been previously initialized by a call to xntimer_init().
- Parameters:
-
| timer | The address of a valid timer descriptor. |
| value | The relative date of the initial timer shot, expressed in clock ticks (see note). |
| interval | The reload value of the timer. It is a periodic interval value to be used for reprogramming the next timer shot, expressed in clock ticks (see note). If interval is equal to XN_INFINITE, the timer will not be reloaded after it has expired. |
- Returns:
- 0 is always returned.
Environments:
This service can be called from:
- Kernel module initialization/cleanup code
- Interrupt service routine
- Kernel-based task
- User-space task
Rescheduling: never.
- Note:
- This service is sensitive to the current operation mode of the system timer, as defined by the xnpod_start_timer() service. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.
|
Generated on Wed Jun 22 22:54:04 2005 for RTAI Fusion API by
1.4.1