device/class/timer.h header reference
[Devices support library module]

The source code of this header can be browsed online.

Description  

The timer device API allows, reading the current counter value and the current configuration of a timer device as well as queuing delay requests. Some timer implementations may no support requests and may only provide a counter value. The counter value exposed by the API is increasing.

The timer need to be started by calling the device_start function in order to have it running when no request are queued. Depending on hardware design, some timer can't be put in stopped state or lose the current timer value when stopped.

A configuration function is provided to read the timer parameters useful to perform time unit conversion and to change the resolution. This also provides some hints about timer hardware capabilities.

See also DRIVER_CLASS_TIMER.

Timer resolution  

The resolution specifies the divider between the timer input clock and the timer counter value.

Timer frequency  

There are two common ways for the driver to find the timer input frequency. When the driver contains a clock sink endpoint, the associated frequency will be computed by the clock provider device and may be stored by the driver of the timer. In this case the configuration will be updated when the clock frequency changes.

When CONFIG_DEVICE_CLOCK token is not defined, the device_get_res_freq function can be used by the driver. This function relies on the DEV_RES_FREQ resources attached to the device. Multiple such resources are needed when the device as multiple input clocks.

Hardware implementation  

There are basically two types of timer hardware design. Those with a counter register which generate a periodic interrupts when it wraps and those with an ever increasing counter along with an hardware deadline comparator. There are also simple cycle counters with no interrupt generation capabilities.

Depending on timer hardware design, setting the timer resolution will either configure an hardware prescaler which divide the timer input clock or simply update the timer interrupt tick period. In the former case, the timer hardware generally support insertion and cancellation of requests without loss of accuracy or race condition and a tick-less approach is used by the driver. The timer resolution can then be set as low as 1 for best time granularity.

In case of a periodic interrupt based timer which increases a software counter, setting the resolution to a low value will generate many interrupts. The driver should then bound the usable resolution range. This kind of timer can also be used as a high resolution counter which is not able the handle requests. This is done by exposing the hardware counter value directly. Drivers may choose to provide both implementations using two different device numbers.

Some timers can be driven using a mixed approach when a hardware deadline comparator is available with a somewhat limited bits width. This often provides a good trade-off between resolution and periodic interrupt interval.

Members  

Types  

Functions  

Constant  

Macros  

Members detail  

#define DEV_STATIC_RES_DEV_TIMER(path_)  

This macro is declared in device/class/timer.h source file, line 533.

This macro provides a DEV_RES_DEV_PARAM resource entry which specifies a dependency on a timer device.

Preprocessor condition: defined( CONFIG_DEVICE_TIMER )

#define DEV_STATIC_RES_DEV_TIMER(path_)  

This macro is declared in device/class/timer.h source file, line 537.

Documentation from alternate declaration:

This macro provides a DEV_RES_DEV_PARAM resource entry which specifies a dependency on a timer device.

Preprocessor condition: not defined( CONFIG_DEVICE_TIMER )

#define DEV_TIMER_CANCEL(n)  

This macro is declared in device/class/timer.h source file, line 258.

See also dev_timer_cancel_t.

#define DEV_TIMER_CONFIG(n)  

This macro is declared in device/class/timer.h source file, line 299.

See also dev_timer_config_t.

#define DEV_TIMER_GET_VALUE(n)  

This macro is declared in device/class/timer.h source file, line 275.

See also dev_timer_get_value_t.

#define DEV_TIMER_REQUEST(n)  

This macro is declared in device/class/timer.h source file, line 220.

See also dev_timer_request_t.

#define DRIVER_TIMER_METHODS(prefix)  

This macro is declared in device/class/timer.h source file, line 340.

#define PRItimerDelay  

This macro is declared in device/class/timer.h source file, line 130.

#define PRItimerRes  

This macro is declared in device/class/timer.h source file, line 131.

#define PRItimerRev  

This macro is declared in device/class/timer.h source file, line 133.

#define PRItimerValue  

This macro is declared in device/class/timer.h source file, line 132.

#define __DEVICE_TIMER_H__  

This macro is declared in device/class/timer.h source file, line 102.

typedef error_t (dev_timer_cancel_t)(const struct device_timer_s *accessor, struct dev_timer_rq_s *rq)   

This typedef is declared in device/class/timer.h source file, line 272.

This typedef cancel a timeout request event.

The request is removed from the timer event queue. This typedef function returns -ETIMEDOUT if the request is not in the queue any more (deadline already reached). Requests with the drvdata field set to NULL are considered not queued.

This typedef returns 0 on success.

This declaration involves expansion of the DEV_TIMER_CANCEL macro.

const char dev_timer_capabilities_e[]  

This variable is declared in ENUM_DESCRIPTOR function like macro expansion, line 1 in device/class/timer.h source file, line 167.

Alternate declarations with same identifier: [1], [2].

enum dev_timer_capabilities_e  

This enum is declared in device/class/timer.h source file, line 170.

Alternate declarations with same identifier: [1], [2].

IdentifierDescription
DEV_TIMER_CAP_REQUESTThe timer device is able to handle requests.
DEV_TIMER_CAP_STOPPABLEThe timer device can be stopped.
DEV_TIMER_CAP_KEEPVALUEThe timer counter value is not lost and can be read when the timer is stopped. This flag is set if DEV_TIMER_CAP_STOPPABLE is cleared.
DEV_TIMER_CAP_VARFREQThe timer input frequency may be changed dynamically.
DEV_TIMER_CAP_CLKSKEWDeadline of enqueued requests are not adjusted properly when the timer input frequency changes. This implies DEV_TIMER_CAP_VARFREQ.
DEV_TIMER_CAP_HIGHRESThe timer support resolution as low as 1. If DEV_TIMER_CAP_REQUEST is set, an hardware deadline comparator is used.
DEV_TIMER_CAP_TICKLESSThe timer never generates an irq for the sole purpose of increasing a counter.

typedef uint32_t dev_timer_cfgrev_t  

This typedef is declared in device/class/timer.h source file, line 129.

Timer configuration revision number

error_t dev_timer_check_timeout(const struct device_timer_s *accessor, dev_timer_delay_t delay, const dev_timer_value_t *start)  

This function checks if the time specified by delay has elapsed since the timer had the value specified in start.

This function may return a negative error code. If the timer value can not be read, -EIO is returned. If the delay is too large to fit in the dev_timer_delay_t type, -ERANGE is returned. On success, 0 is returned if the time has not elapsed yet and 1 is returned on timeout.

This is available when CONFIG_DEVICE_TIMER is defined.

struct dev_timer_config_s  

This struct is declared in device/class/timer.h source file, line 196.

Timer configuration

See also dev_timer_config_t.

FieldDescription
struct dev_freq_s freq;timer input frequency
dev_timer_value_t max;timer maximum value
dev_timer_cfgrev_t rev;revision id associated with this configuration, increased on configuration update. Can not be even.
dev_timer_res_t res;timer resolution
enum dev_timer_capabilities_e cap:8;timer device capabilities

typedef error_t (dev_timer_config_t)(const struct device_timer_s *accessor, struct dev_timer_config_s *cfg, dev_timer_res_t res)   

This typedef is declared in device/class/timer.h source file, line 331.

This typedef reads the current timer configuration and optionally sets the resolution. The struct dev_timer_config_s object is updated with the current configuration if the cfg parameter is not NULL.

The dev_timer_config_s::freq field is set to 0 if the timer frequency is not known.

The resolution is set when the res parameter is not 0. The actual resolution can be different from the requested resolution depending on hardware design of the timer. The current and possibly new resolution is stored in the res field.

The maximum timer value reached when the timer overlaps is stored in the max field. This value is a power of two minus one.

The timer resolution can not be changed if the timer has been started by calling device_start or by queuing a request. This typedef returns -EBUSY in this case.

If the new resolution value is different from the requested one, -ERANGE is returned. This can only occur when trying to change the resolution.

This typedef returns -ENOTSUP if there is no timer matching the requested device number.

This declaration involves expansion of the DEV_TIMER_CONFIG macro.

error_t dev_timer_delay_check_s2t(int_fast8_t shift, dev_timer_delay_t delay)  

This function is declared in device/class/timer.h source file, line 433.

This function checks the range of the specified delay value for conversion by the dev_timer_delay_shift_s2t function.

This is available when CONFIG_DEVICE_TIMER is defined.

error_t dev_timer_delay_check_t2s(int_fast8_t shift, dev_timer_delay_t delay)  

This function is declared in device/class/timer.h source file, line 452.

This function checks the range of the specified delay value for conversion by the dev_timer_delay_shift_t2s function.

This is available when CONFIG_DEVICE_TIMER is defined.

dev_timer_delay_t dev_timer_delay_shift_s2t(int_fast8_t shift, dev_timer_delay_t delay)  

This function is declared in device/class/timer.h source file, line 424.

This function applies the shift amount computed by the dev_timer_shift_sec function. The conversion range can be checked by calling dev_timer_delay_check_s2t.

This is available when CONFIG_DEVICE_TIMER is defined.

dev_timer_delay_t dev_timer_delay_shift_t2s(int_fast8_t shift, dev_timer_delay_t delay)  

This function is declared in device/class/timer.h source file, line 443.

This function applies the shift amount computed by the dev_timer_shift_sec function. The conversion range can be checked by calling dev_timer_delay_check_s2t.

This is available when CONFIG_DEVICE_TIMER is defined.

typedef uint32_t dev_timer_delay_t  

This typedef is declared in device/class/timer.h source file, line 125.

Timer relative value type

error_t dev_timer_frac(const struct device_timer_s *accessor, uint64_t *num, uint64_t *denom, dev_timer_cfgrev_t *rev, bool_t reduce)  

This function multiplies the given fraction by the timer frequency / timer resolution fraction. The fraction will be simplifyed if the reduce parameter is set.

The resulting fraction can be used for conversion between timer units and second based delay.

This is available when CONFIG_DEVICE_TIMER is defined.

error_t dev_timer_get_sec(const struct device_timer_s *accessor, uint64_t *stime, dev_timer_cfgrev_t *rev, dev_timer_value_t tvalue, uint32_t r_unit)  

This function works like dev_timer_init_sec but convert from timer unit to second based unit.

This is available when CONFIG_DEVICE_TIMER is defined.

typedef error_t (dev_timer_get_value_t)(const struct device_timer_s *accessor, dev_timer_value_t *value, dev_timer_cfgrev_t rev)   

This typedef is declared in device/class/timer.h source file, line 295.

This typedef reads the current raw timer value. The timer value is increasing with time.

This typedef function may returns -EIO if the timer value can not be accessed. This can append when trying to access a processor local timer from the wrong processor.

If the rev argument is not 0 and doesn't match the internal value of the configuration revision number, -EAGAIN is returned.

This typedef may return -EBUSY if the timer hardware resource is not available. This typedef returns -ENOTSUP if there is no timer matching the requested device number.

This declaration involves expansion of the DEV_TIMER_GET_VALUE macro.

error_t dev_timer_init_sec(const struct device_timer_s *accessor, dev_timer_delay_t *delay, dev_timer_cfgrev_t *rev, dev_timer_delay_t s_delay, uint32_t r_unit)  

This function initializes a timer delay from the given delay value in seconds unit. The delay is specified in seconds when r_unit is 1, in msec when r_unit is 1000 and so on. Actual delay in timer units is computed from timer frequency and current timer resolution.

This function returns a negative error code if the timer value can not be read (-EIO) or if the timer overlap period is to short for the delay (-ERANGE).

This is available when CONFIG_DEVICE_TIMER is defined.

error_t dev_timer_init_sec_ceil(const struct device_timer_s *accessor, dev_timer_delay_t *delay, dev_timer_cfgrev_t *rev, dev_timer_delay_t s_delay, uint32_t r_unit)  

.

This is available when CONFIG_DEVICE_TIMER is defined.

See also dev_timer_init_sec.

error_t dev_timer_init_sec_round(const struct device_timer_s *accessor, dev_timer_delay_t *delay, dev_timer_cfgrev_t *rev, dev_timer_delay_t s_delay, uint32_t r_unit)  

.

This is available when CONFIG_DEVICE_TIMER is defined.

See also dev_timer_init_sec.

bool_t dev_timer_request_is_scheduled(const struct dev_timer_rq_s *rq)  

This function is declared in device/class/timer.h source file, line 457.

typedef error_t (dev_timer_request_t)(const struct device_timer_s *accessor, struct dev_timer_rq_s *rq)   

This typedef is declared in device/class/timer.h source file, line 256.

This typedef enqueues a timeout event request. The delay and kr fields of the request must have been initialized. If delay is zero, the deadline field must specify an absolute deadline timer value.

If the function returns 0, the kroutine_exec function will be called when the deadline is reached. It's ok to call any of the timer functions from the kroutine; especially the request can be enqueued again.

If the deadline has already been reached, the function does nothing and return -ETIMEDOUT.

If the revision field of the request is not 0 and doesn't match the internal value of the configuration revision number, the request is rejected and -EAGAIN is returned. This allows ensuring time converted delays of the request is consistent with the current timer configuration. Valid revision numbers are odd.

If the timer has not been started explicitly by calling the device_start function, it will run until the request queue becomes empty again.

This typedef may return -EBUSY if the timer hardware resource is not available. This typedef may return -ENOTSUP if either there is no timer matching the requested device number or the timer implementation doesn't support requests.

A new request may be submitted from the kroutine handler function. Please read Nested device request submission.

This declaration involves expansion of the DEV_TIMER_REQUEST macro.

typedef uint32_t dev_timer_res_t  

This typedef is declared in device/class/timer.h source file, line 127.

Timer device resolution type

void dev_timer_rq_done(struct dev_timer_rq_s *rq)  

This function is declared in device/class/timer.h source file, line 155.

This function invokes or schedules execution of the timer request callback associated to the request. For use in device drivers.

struct dev_timer_rq_s * dev_timer_rq_from_kr(struct kroutine_s *kr)  

This function is declared in device/class/timer.h source file, line 155.

This function retrieves a pointer to the request when in the request completion callback routine.

struct dev_timer_rq_s * dev_timer_rq_head(dev_request_pqueue_root_t *q)  

This function is declared in device/class/timer.h source file, line 165.

This function returns the first timer request in the given priority queue. A NULL pointer is returned if the queue is empty. For use in device drivers.

void dev_timer_rq_init(struct dev_timer_rq_s *rq, kroutine_exec_t *exec)  

This function is declared in device/class/timer.h source file, line 155.

This function initializes the given timer request callback. This must be used before submitting the request to a driver.

This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.

void dev_timer_rq_init_immediate(struct dev_timer_rq_s *rq, kroutine_exec_t *exec)  

This function is declared in device/class/timer.h source file, line 155.

This function initializes the given timer request callback. This must be used before submitting the request to a driver.

void dev_timer_rq_init_queue(struct dev_timer_rq_s *rq, kroutine_exec_t *exec, struct kroutine_queue_s *queue)  

This function is declared in device/class/timer.h source file, line 155.

This function initializes the given timer request callback. This must be used before submitting the request to a driver.

This is available when CONFIG_MUTEK_KROUTINE_QUEUE is defined.

void dev_timer_rq_init_seq(struct dev_timer_rq_s *rq, kroutine_exec_t *exec, struct kroutine_sequence_s *seq)  

This function is declared in device/class/timer.h source file, line 155.

This function initializes the given timer request callback. This must be used before submitting the request to a driver.

This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.

void dev_timer_rq_insert(dev_request_pqueue_root_t *q, struct dev_timer_rq_s *rq)  

This function is declared in device/class/timer.h source file, line 165.

This function insert a new timer request at the right location in the given priority queue. For use in device drivers.

struct dev_timer_rq_s * dev_timer_rq_next(dev_request_pqueue_root_t *q, struct dev_timer_rq_s *rq)  

This function is declared in device/class/timer.h source file, line 165.

This function returns the timer request after the given request in the priority queue. A NULL pointer is returned if request is the last one. For use in device drivers.

struct dev_timer_rq_s * dev_timer_rq_prev(dev_request_pqueue_root_t *q, struct dev_timer_rq_s *rq)  

This function is declared in device/class/timer.h source file, line 165.

This function returns the timer request before the given request in the priority queue. A NULL pointer is returned if request is the first one. For use in device drivers.

void dev_timer_rq_remove(dev_request_pqueue_root_t *q, struct dev_timer_rq_s *rq)  

This function is declared in device/class/timer.h source file, line 165.

This function removes the specified timer request from the priority queue. For use in device drivers.

struct dev_timer_rq_s  

This struct is declared in device/class/timer.h source file, line 140.

Timer request

See also dev_timer_request_t.

FieldDescription
union <anonymous> {
struct dev_request_s base;
typeof(struct dev_request_s::pvdata) pvdata;
typeof(struct dev_request_s::drvdata) drvdata;
};
dev_timer_value_t deadline;absolute timer deadline, used when delay is 0
dev_timer_delay_t delay;timer delay
dev_timer_cfgrev_t rev;expected configuration revision, ignored if 0

struct dev_request_s * dev_timer_rq_s_base(struct dev_timer_rq_s *x)  

struct dev_timer_rq_s * dev_timer_rq_s_cast(struct dev_request_s *x)  

error_t dev_timer_shift_sec(const struct device_timer_s *accessor, int8_t *shift_a, int8_t *shift_b, dev_timer_cfgrev_t *rev, dev_timer_delay_t s_delay, uint32_t r_unit)  

This function computes two shift amounts which can be used for fast conversion between a delay in second based unit and a delay in timer unit. Shifting will result in a delay rounded to the lower or higher power of 2.

Left shifting by the shift_a value when converting from a second based delay will yield a timer delay which can be up to 2 times longer. Left shifting by the shift_b value when converting from a second based delay will yield a timer delay which will be divided by 2 in the worst case. A negative value implies a right shift in this case. The dev_timer_delay_shift_s2t function can be used to perform those conversions.

Right shifting by the shift_b value when converting from a timer delay will yield a second based delay which can be up to 2 times longer. Right shifting by the shift_a value when converting from a timer delay will yield a second based delay which will be divided by 2 in the worst case. A negative value implies a left shift in this case. The dev_timer_delay_shift_t2s function can be used to perform those conversions.

Either the shift_a or the shift_b pointer may be NULL.

This is available when CONFIG_DEVICE_TIMER is defined.

struct dev_timer_skew_s  

This struct is declared in device/class/timer.h source file, line 212.

Timer skew structure used to measure skew between two timers

FieldDescription
int64_t d;
uint32_t num;
uint32_t denom;

typedef uint64_t dev_timer_value_t  

This typedef is declared in device/class/timer.h source file, line 123.

Timer absolute value type

error_t dev_timer_wait_deadline(const struct device_timer_s *accessor, dev_timer_value_t deadline, dev_timer_cfgrev_t rev)  

This function is declared in device/class/timer.h source file, line 508.

Synchronous timer wait function. This function uses the scheduler API to put the current context in wait state waiting for the specified deadline.

This is available when CONFIG_DEVICE_TIMER and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t dev_timer_wait_delay(const struct device_timer_s *accessor, dev_timer_delay_t delay, dev_timer_cfgrev_t rev)  

This function is declared in device/class/timer.h source file, line 529.

Synchronous timer wait function. This function uses the scheduler API to put the current context in wait state waiting for the specified delay. The function never returns -ETIMEDOUT.

This is available when CONFIG_DEVICE_TIMER and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t dev_timer_wait_rq(const struct device_timer_s *accessor, struct dev_timer_rq_s *rq)  

This function is declared in device/class/timer.h source file, line 492.

Synchronous timer wait function. This function uses the scheduler API to put the current context in wait state waiting for the given request to terminate.

This is available when CONFIG_DEVICE_TIMER and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

struct device_timer_s  

This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 21 in device/class/timer.h source file, line 339.

This struct is the device accessor object type for the timer device class. This accessor must be initialized by calling the device_get_accessor function.

See also DRIVER_CLASS_TIMER, struct device_accessor_s and Device accessor.

FieldDescription
union <anonymous> {
struct device_accessor_s base;
struct <anonymous> {
struct device_s * dev;
struct driver_timer_s * api;
uint_fast8_t number;
};
};

struct device_accessor_s * device_timer_s_base(struct device_timer_s *x)  

This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 42 in device/class/timer.h source file, line 339.

This function casts a timer device accessor to a generic device accessor

struct device_timer_s * device_timer_s_cast(struct device_accessor_s *x)  

This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 35 in device/class/timer.h source file, line 339.

This function casts a generic device accessor to a timer device accessor

struct driver_timer_s  

This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 5 in device/class/timer.h source file, line 339.

This struct is the driver API descriptor for the timer device class.

See also DRIVER_CLASS_TIMER and struct driver_class_s.

Valid XHTML 1.0 StrictGenerated by diaxen on Wed Oct 17 21:18:38 2018 using MkDoc