NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | ATTRIBUTES | SEE ALSO
#include <ddi/timer/timer.h>
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
DDI
The timer is an incremental counter. There are two modes of operation available: free-running and periodic timer. In free-running mode the timer will overflow after reaching its maximum value and continue to count up from its minimum value. In periodic timer mode the timer will generate an interrupt at a constant time interval, and the client handler provided can be called at each interval expiration.
typedef struct { TimerVersion version; KnError (*start_freerun) (TimerId device_id, KnTimeVal* min_period); KnError (*start_periodic) (TimerId device_id, KnTimeVal* tick_interval, TimerTickHandler tick_handler, void* tick_cookie); void (*mask) (TimerId device_id); void (*unmask) (TimerId device_id); unsigned long (*get_counter_frequency) (TimerId device_id); unsigned long (*get_counter_period) (TimerId device_id); unsigned long (*read_counter) (TimerId device_id); void (*stop) (TimerId device_id); } TimerDevOps;
A pointer to the TimerDevOps structure is exported by the driver via the svDeviceRegister microkernel call. A driver client invokes the svDeviceLookup and svDeviceEntry microkernel calls in order to obtain a pointer to the device service routines vector. Once the pointer is obtained, the driver client is able to invoke the driver service routines (via the indirect function call) in order to start/stop the device, get counter frequency and period, and read the current counter value.
start_freerun
start_freerun starts the specified timer device in a freerun mode. In this mode, the timer continuously counts without interrupt generation. The client can then use read_counter to read the counter's current value.
Arguments:
Specifies the TIMER device identifier (returned by svDeviceEntry).
Specifies the minimum required period of the timer. This specifies the minimum interval during which no counter reload should occur.
The start_freerun function returns the following results:
TIMER is successfully started.
TIMER cannot be initialized within the given period.
TIMER is already open.
The start_freerun is not implemented for this device.
Once started, the timer device must be stopped with the stop function (see Section stop) before being started again.
start_periodic
The start_periodic function starts the specified timer device in a periodic mode, where the client provided handler is called at periodic intervals (specified in the tick_interval parameter).
Arguments:
Specifies the TIMER device identifier.
Specifies the interval between two calls of the tick_handler handler.
Specifies the routine to call when the specified interval expires.
Specifies a parameter passed back to the handler specified..
The start_periodic function returns the following results:
TIMER has been started successfully.
TIMER cannot be initialized with the given interval.
TIMER is already opened.
The start_periodic is not implemented for this device.
Once the timer has been started, it should be stopped using the stop function prior to being started again. The timer is started with the interrupt disabled. The client should explicitly enable interrupts with the unmask function.
mask
The mask function disables the timer interrupts. Once interrupts have been disabled, the client handler given in the tick_handler parameter of the start_periodic function will not be called until timer interrupts are enabled again using the unmask function.
Arguments:
Specifies the TIMER device identifier.
The mask routine may be called from interrupt level.
unmask
The unmask function enables timer interrupts allowing the provided tick_handler to be called at specified periodic intervals.
Arguments:
Specifies the TIMER device identifier.
The unmask routine may be called from interrupt level. The mask/unmask pairs must not be nested.
get_counter_frequency
The get_counter_frequency function returns the frequency in hertz of the given timer device.
Arguments:
Specifies the TIMER device identifier.
get_counter_period
The get_counter_period function returns the difference between the maximum and minimum values of the timer counter.
Arguments:
Specifies the TIMER device identifier.
read_counter
The read_counter function returns the current value of the timer counter. The read value can be used to measure the time elapsed between two calls to the read_counter function.
Arguments:
Specifies the TIMER device identifier.
The read_counter must be used after the timer has been started in free_run mode. The read values are guaranteed to be incremental if the read_counter function is executed before the min_period expires.
stop
The stop function stops the timer specified.
Arguments:
Specifies the TIMER device identifier.
Once the timer device has been stopped, the read_counter function must no longer be called.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
svDeviceRegister(9DKI), svDriverRegister(9DKI), svDeviceLookup(9DKI), svDeviceEntry(9DKI), svDeviceRelease(9DKI)
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | ATTRIBUTES | SEE ALSO