EM-ODP  3.7.0
Event Machine on ODP
Event timer

Event Machine timer. More...

Data Structures

struct  em_fract_u64_t
 
struct  em_timer_res_param_t
 
struct  em_timer_ring_param_t
 
struct  em_timer_attr_t
 
struct  em_tmo_stats_t
 
struct  em_timer_capability_t
 
struct  em_tmo_args_t
 

Macros

#define EM_TIMER_API_VERSION_MAJOR   EM_API_VERSION_MAJOR
 
#define EM_TIMER_API_VERSION_MINOR   EM_API_VERSION_MINOR
 

Typedefs

typedef enum em_tmo_state_t em_tmo_state_t
 
typedef enum em_tmo_type_t em_tmo_type_t
 
typedef uint64_t em_timer_tick_t
 
typedef struct em_fract_u64_t em_fract_u64_t
 
typedef struct em_timer_res_param_t em_timer_res_param_t
 
typedef struct em_timer_ring_param_t em_timer_ring_param_t
 
typedef struct em_timer_attr_t em_timer_attr_t
 
typedef struct em_tmo_stats_t em_tmo_stats_t
 
typedef struct em_timer_capability_t em_timer_capability_t
 
typedef struct em_tmo_args_t em_tmo_args_t
 
typedef struct em_timer_timeout_tem_tmo_t
 

Enumerations

enum  em_tmo_state_t { EM_TMO_STATE_UNKNOWN = 0, EM_TMO_STATE_IDLE = 1, EM_TMO_STATE_ACTIVE = 2, EM_TMO_STATE_INACTIVE = 3 }
 
enum  em_tmo_type_t { EM_TMO_TYPE_NONE = 0, EM_TMO_TYPE_ONESHOT = 1, EM_TMO_TYPE_PERIODIC = 2 }
 
enum  em_timer_flag_t { EM_TIMER_FLAG_NONE = 0, EM_TIMER_FLAG_PRIVATE = 1, EM_TIMER_FLAG_RING = 2 }
 
enum  em_tmo_flag_t { EM_TMO_FLAG_ONESHOT = 1, EM_TMO_FLAG_PERIODIC = 2, EM_TMO_FLAG_NOSKIP = 4 }
 
enum  em_timer_clksrc_t {
  EM_TIMER_CLKSRC_0, EM_TIMER_CLKSRC_1, EM_TIMER_CLKSRC_2, EM_TIMER_CLKSRC_3,
  EM_TIMER_CLKSRC_4, EM_TIMER_CLKSRC_5, EM_TIMER_NUM_CLKSRC
}
 

Functions

void em_timer_attr_init (em_timer_attr_t *tmr_attr)
 
em_status_t em_timer_ring_attr_init (em_timer_attr_t *ring_attr, em_timer_clksrc_t clk_src, uint64_t base_hz, uint64_t max_mul, uint64_t res_ns)
 
em_status_t em_timer_capability (em_timer_capability_t *capa, em_timer_clksrc_t clk_src)
 
em_status_t em_timer_res_capability (em_timer_res_param_t *res, em_timer_clksrc_t clk_src)
 
em_status_t em_timer_ring_capability (em_timer_ring_param_t *ring)
 Check periodic ring timer capability. More...
 
em_timer_t em_timer_create (const em_timer_attr_t *tmr_attr)
 
em_timer_t em_timer_ring_create (const em_timer_attr_t *ring_attr)
 
em_status_t em_timer_delete (em_timer_t tmr)
 
em_timer_tick_t em_timer_current_tick (em_timer_t tmr)
 
em_tmo_t em_tmo_create (em_timer_t tmr, em_tmo_flag_t flags, em_queue_t queue)
 
em_tmo_t em_tmo_create_arg (em_timer_t tmr, em_tmo_flag_t flags, em_queue_t queue, em_tmo_args_t *args)
 
em_status_t em_tmo_delete (em_tmo_t tmo, em_event_t *cur_event)
 
em_status_t em_tmo_set_abs (em_tmo_t tmo, em_timer_tick_t ticks_abs, em_event_t tmo_ev)
 
em_status_t em_tmo_set_rel (em_tmo_t tmo, em_timer_tick_t ticks_rel, em_event_t tmo_ev)
 
em_status_t em_tmo_set_periodic (em_tmo_t tmo, em_timer_tick_t start_abs, em_timer_tick_t period, em_event_t tmo_ev)
 
em_status_t em_tmo_set_periodic_ring (em_tmo_t tmo, em_timer_tick_t start_abs, uint64_t multiplier, em_event_t tmo_ev)
 
em_status_t em_tmo_cancel (em_tmo_t tmo, em_event_t *cur_event)
 
em_status_t em_tmo_ack (em_tmo_t tmo, em_event_t next_tmo_ev)
 
int em_timer_get_all (em_timer_t *tmr_list, int max)
 
em_status_t em_timer_get_attr (em_timer_t tmr, em_timer_attr_t *tmr_attr)
 
uint64_t em_timer_get_freq (em_timer_t tmr)
 
uint64_t em_timer_tick_to_ns (em_timer_t tmr, em_timer_tick_t ticks)
 
em_timer_tick_t em_timer_ns_to_tick (em_timer_t tmr, uint64_t ns)
 
em_tmo_state_t em_tmo_get_state (em_tmo_t tmo)
 
em_status_t em_tmo_get_stats (em_tmo_t tmo, em_tmo_stats_t *stat)
 
em_tmo_type_t em_tmo_get_type (em_event_t event, em_tmo_t *tmo, bool reset)
 
void * em_tmo_get_userptr (em_event_t event, em_tmo_t *tmo)
 
em_timer_t em_tmo_get_timer (em_tmo_t tmo)
 
uint64_t em_timer_to_u64 (em_timer_t timer)
 
uint64_t em_tmo_to_u64 (em_tmo_t tmo)
 

Detailed Description

Event Machine timer.

Deprecated:
Do not use or include this file include/add-ons/event_machine_timer.h anymore. EM timer is moved under EM API.

The timer API can be used to request an event to be sent to a specified queue at a specified time once (one-shot) or at regular intervals (periodic). A timer needs to be created first - it represents a collection of timeouts with certain attributes (e.g. timeout resolution and maximum period). A timer can be mapped to a HW resource on an SoC, thus the number of timers, capabilities and time bases are system specific. Typically only a few timers are supported. The application can specify required capabilities when a timer is created. The creation will fail if the implementation cannot fulfill the required values. Timers are typically created once at system startup.

A timer is a shared resource with proper synchronization for concurrent multi-thread use. It is possible to exclude all multi-thread protections if a timer is used exclusively by a single thread (for potential performance gains). This is done by setting EM_TIMER_FLAG_PRIVATE when creating a timer. Setting this flag means that the application must ensure that only a single thread is using the timer (this also includes the receiver of periodic timeouts due to the ack-functionality). This private-mode is not necessarily implemented on all systems, in which case the flag is ignored as it will not cause any functional difference.

Timeouts (tmo) can be created once a timer exists. Creating a timeout allocates the resources needed to serve the timeout, but does not arm it. This makes it possible to pre-create timeout(s) and set the expiry later at runtime. This can improve performance but also minimizes the possibility that the runtime call setting the expiry would fail, as resources have already been reserved beforehand.

A pending timeout can be cancelled. Note that there is no way to cancel an expired timeout for which the event has already been sent but not yet received by the application. Canceling in this case will return an error to enable the application to detect the situation. For a periodic timer, a cancel will stop further timeouts, but may not be able to prevent the latest event from being received. An active timeout cannot be altered without canceling it first.

A timeout can be re-used after it has been received or successfully cancelled. Timeouts need to be deleted after use. Deletion frees the resources reserved during creation.

The timeout value is an abstract system and timer dependent tick count. It is assumed that the tick count increases with a static frequency. The frequency can be inquired at runtime for time calculations, e.g. tick frequency divided by 1000 gives ticks for 1ms. Tick frequency is at least equal to the resolution, but can also be higher (implementation can quantize ticks to any underlying implementation). Supported resolution can also be inquired. A clock source can be specified when creating a timer. It defines the time base of the timer for systems with multiple sources implemented (optional). EM_TIMER_CLKSRC_DEFAULT is a portable value that implements a basic monotonic time, that will not wrap back to zero in any reasonable uptime.

The major event types EM_EVENT_TYPE_SW, EM_EVENT_TYPE_PACKET and EM_EVENT_TYPE_TIMER can be used as a timeout indication. The type EM_EVENT_TYPE_TIMER is alternative to EM_EVENT_TYPE_SW and works the same way. Additionally for ring timer only, the type EM_EVENT_TYPE_TIMER_IND is used. This is a special indication event without visible payload.

A periodic timer requires the application to acknowledge each received timeout event after it has been processed. The acknowledgment activates the next timeout and compensates for the processing delay to keep the original interval. This creates a flow control mechanism and also protects the event handling from races if the same event is reused every time, the next timeout will not be sent before the previous has been acknowledged. The event to be received for each periodic timeout can also be different as the next event is given by the application with the acknowledge. The target queue cannot be modified after the timeout has been created.

If the acknowledgment of a periodic timeout is done too late (after the next period has already passed), the default action is to skip the missed timeout slot(s) and arm for the next valid slot. If the application never wants to skip a missed timeout it can set the flag EM_TMO_FLAG_NOSKIP when creating a timeout. This causes each acknowledgment to schedule an immediate timeout event until all the missed time slots have been served. This keeps the number of timeouts as expected but may cause an event storm if a long processing delay has occurred.

The timeout handle is needed when acknowledging a periodic timeout event. Because any event can be used for the timeout, the application must itself provide a way to derive the timeout handle from the received timeout event. A typical way is to include the tmo handle within the timeout event. Application also needs to have a mechanism to detect which event is a periodic timeout to be able to call acknowledge.

If the timeout tick value given to timeout start points to the past or is too close to current time then error code EM_ERR_TOONEAR is returned. In this case EM will not call error handler to let application decide whether it is an error or if it will try again with updated target time.

There is an alternative periodic ring timer. As it uses different abstraction it is created and started via separate ring specific APIs. It has three main differencies to the regular periodic timeouts:

  1. Only a pre-defined read-only event type can be used and is provided by the timer (EM_EVENT_TYPE_TIMER_IND).
  2. Flow control is not supported. Some implementations may have it, but the specification does not quarantee any so the user needs to be prepared to see the same event enqueued multiple times if handling of the received timeouts is not fast enough
  1. A limited set of period times are supported per timer (base rate or an integer multiple of it only)

Ring timers can be abstracted as a clock face ticking the pointer forward. One cycle around is the base rate (minimum rate). The same timeout can be inserted into multiple locations evenly spread within the clock face thus multiplying the base rate. The starting offset can be adjusted only up to one timeout period. Depending on platform, this mode may provide better integration with HW and thus have less runtime overhead. However, as it exposes a potential queue overflow and a race hazard (race avoidable by using atomic queue as target), the regular periodic timer is recommended as a default.

Example usage

// This would typically be done at application init.
// Accept all defaults but change the name
strncpy(attr.name, "myTimer", EM_TIMER_NAME_LEN);
em_timer_t tmr = em_timer_create(&attr);
if(tmr == EM_TIMER_UNDEF) {
// handle error here or via error handler
}
// At runtime - create a timeout resource.
// Can be done in advance to save time if the target queue is known.
em_tmo_t tmo = em_tmo_create(tmr, EM_TIMER_FLAG_ONESHOT, target_queue);
if(tmo == EM_TMO_UNDEF) {
// no such timer or out of resources
// handle error here or via error handler
}
// Get the timer tick frequency
uint64_t hz = em_timer_get_freq(tmr);
// Activate a 10ms timeout from now.
// Very unlikely to fail with valid arguments.
if (em_tmo_set_rel(tmo, hz / 100, my_tmo_event) != EM_OK) {
// handle error here or via error handler
}

Macro Definition Documentation

◆ EM_TIMER_API_VERSION_MAJOR

#define EM_TIMER_API_VERSION_MAJOR   EM_API_VERSION_MAJOR

Deprecated Major EM Timer API version. Marks possibly backwards incompatible changes. EM timer is now part of EM API. Use EM_API_VERSION_MAJOR instead.

Definition at line 196 of file api/event_machine_timer.h.

◆ EM_TIMER_API_VERSION_MINOR

#define EM_TIMER_API_VERSION_MINOR   EM_API_VERSION_MINOR

Deprecated Minor EM Timer API version. Marks possibly backwards incompatible changes. EM Timer is now part of EM API. Use EM_API_VERSION_MINOR instead.

Definition at line 201 of file api/event_machine_timer.h.

Typedef Documentation

◆ em_fract_u64_t

Fractional 64-bit unsigned value for timer frequency.

◆ em_timer_attr_t

Structure used to create a timer or inquire its configuration later.

This needs to be initialized with em_timer_attr_init(), which fills default values to each field. After that the values can be modified as needed. Values are considered a requirement, e.g. setting 'resparam.res_ns' to 1000(ns) requires at least 1us resolution. The timer creation will fail if the implementation cannot support such resolution (like only goes down to 1500ns). The implementation is free to provide better than requested, but not worse.

To know the implementation specific limits use em_timer_capability and em_timer_res_capability.

When creating the alternative periodic ring timer, this needs to be initialized with em_timer_ring_attr_init instead. EM_TIMER_FLAG_RING will be set by em_timer_ring_attr_init so it does not need to be manually set.

See also
em_timer_attr_init, em_timer_ring_attr_init, em_timer_capability

◆ em_timer_capability_t

Timer capability info

◆ em_timer_res_param_t

Type for timer resolution parameters

This structure is used to group timer resolution parameters that may affect each other. All time values are ns.

Note
This is used both as capability and configuration. When used as configuration either res_ns or res_hz must be 0 (for em_timer_create).
See also
em_timer_capability, em_timer_create

◆ em_timer_ring_param_t

Timer ring timing parameters.

◆ em_timer_tick_t

typedef uint64_t em_timer_tick_t

The timer tick has HW and timer specific meaning, but the type is always a 64-bit integer and is normally assumed to be monotonic and not to wrap around. Exceptions with exotic extra timers should be clearly documented.

Definition at line 261 of file api/event_machine_timer.h.

◆ em_tmo_args_t

typedef struct em_tmo_args_t em_tmo_args_t

tmo optional extra arguments

◆ em_tmo_state_t

Visible state of a timeout

◆ em_tmo_stats_t

Timeout statistics counters

Some fields relate to periodic timeout only (0 on one-shots) and vice versa. New fields may be added later at the end.

◆ em_tmo_t

em_tmo_t (timeout handle) needs to be defined by the EM implementation

System specific type for a timeout handle.

Definition at line 70 of file event_machine_timer_hw_specific.h.

◆ em_tmo_type_t

Type returned by em_tmo_get_type()

Enumeration Type Documentation

◆ em_timer_clksrc_t

System specific enum type for timer clock source. This is system specific, but all implementations must define EM_TIMER_CLKSRC_DEFAULT.

Examples
timer_test_ring.c.

Definition at line 95 of file event_machine_timer_hw_specific.h.

◆ em_timer_flag_t

System specific type for timer flags. This is system specific, but all implementations must define EM_TIMER_FLAG_DEFAULT and EM_TIMER_FLAG_PRIVATE, of which the latter is used to skip API synchronization for single threaded apps. Flags can be combined by bitwise OR.

Enumerator
EM_TIMER_FLAG_NONE 

default

EM_TIMER_FLAG_PRIVATE 

single thread use. Not multithread safe, but potentially faster

EM_TIMER_FLAG_RING 

is periodic ring. This does not need to be manually set, init does

Definition at line 57 of file event_machine_timer_hw_specific.h.

◆ em_tmo_flag_t

System specific enum type for timeout flags. This is system specific, but all implementations must define EM_TMO_FLAG_ONESHOT, EM_TMO_FLAG_PERIODIC and EM_TMO_FLAG_NOSKIP. Flags can be combined by bitwise OR.

Enumerator
EM_TMO_FLAG_ONESHOT 

to select one-shot

EM_TMO_FLAG_PERIODIC 

to select periodic

EM_TMO_FLAG_NOSKIP 

see periodic ack

Definition at line 80 of file event_machine_timer_hw_specific.h.

◆ em_tmo_state_t

Visible state of a timeout

Enumerator
EM_TMO_STATE_IDLE 

just created or canceled

EM_TMO_STATE_ACTIVE 

armed

EM_TMO_STATE_INACTIVE 

oneshot expired

Definition at line 240 of file api/event_machine_timer.h.

◆ em_tmo_type_t

Type returned by em_tmo_get_type()

Enumerator
EM_TMO_TYPE_NONE 

unknown or not timer-related event

EM_TMO_TYPE_ONESHOT 

event is oneshot timeout indication

EM_TMO_TYPE_PERIODIC 

event is periodic timeout indication

Definition at line 250 of file api/event_machine_timer.h.

Function Documentation

◆ em_timer_attr_init()

void em_timer_attr_init ( em_timer_attr_t tmr_attr)

Initialize em_timer_attr_t

Initializes em_timer_attr_t to system specific default values. After initialization user can adjust the values as needed before calling em_timer_create. em_timer_capability() and/or em_timer_res_capability() can optionally be used to find valid values.

Always initialize em_timer_attr_t with em_timer_attr_init before any use.

This function will not trigger errorhandler calls internally.

Example for all defaults

em_timer_attr_t tmr_attr;
em_timer_attr_init(&tmr_attr);
em_timer_t tmr = em_timer_create(&tmr_attr);
Parameters
tmr_attrPointer to em_timer_attr_t to be initialized
See also
em_timer_capability, em_timer_create
Examples
timer_hello.c, timer_test.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 378 of file event_machine_timer.c.

◆ em_timer_capability()

em_status_t em_timer_capability ( em_timer_capability_t capa,
em_timer_clksrc_t  clk_src 
)

Inquire timer capabilities

Returns timer capabilities for the given clock source, which is also written to both 'capa->max_res.clk_src' and 'capa->max_tmo.clk_src'. For resolution both 'res_ns' and 'res_hz' are filled.

This function will not trigger errorhandler calls internally.

Parameters
capapointer to em_timer_capability_t to be updated (does not need to be initialized)
clk_srcClock source to use for timer (EM_TIMER_CLKSRC_DEFAULT for system specific default)
Returns
EM_OK if the given clk_src is supported (capa updated)
See also
em_timer_capability_t, em_timer_res_capability
Examples
timer_test_periodic.c, and timer_test_ring.c.

Definition at line 502 of file event_machine_timer.c.

◆ em_timer_create()

em_timer_t em_timer_create ( const em_timer_attr_t tmr_attr)

Create and start a timer resource

Required attributes are given via tmr_attr. The given structure must be initialized with em_timer_attr_init before setting any field.

Timer resolution can be given as time 'res_ns' or frequency 'res_hz'. User must choose which one to use by setting the other one to 0.

To use all defaults initialize tmr_attr with em_timer_attr_init() and pass it as is to em_timer_create().

Note
NULL is no longer supported, must give pointer to initialized em_timer_attr_t
Parameters
tmr_attrTimer parameters to use, pointer to initialized em_timer_attr_t
Returns
Timer handle on success or EM_TIMER_UNDEF on error
See also
em_timer_attr_init, em_timer_capability
Examples
timer_hello.c, timer_test.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 616 of file event_machine_timer.c.

◆ em_timer_current_tick()

em_timer_tick_t em_timer_current_tick ( em_timer_t  tmr)

Returns current tick value of the given timer

This can be used for calculating absolute timeouts.

Parameters
tmrTimer handle
Returns
Current time in timer specific ticks or 0 on non-existing timer
Examples
timer_hello.c, timer_test.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 1045 of file event_machine_timer.c.

◆ em_timer_delete()

em_status_t em_timer_delete ( em_timer_t  tmr)

Stop and delete a timer

Delete a timer, frees all resources. All timeouts for this timer must have been deleted first.

Parameters
tmrTimer handle
Returns
EM_OK on success
Examples
timer_hello.c, timer_test.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 980 of file event_machine_timer.c.

◆ em_timer_get_all()

int em_timer_get_all ( em_timer_t *  tmr_list,
int  max 
)

Get a list of currently active timers.

The timer handles returned via 'tmr_list' can be used for further timer queries or to destroy existing timers.

The return value always reflects the actual number of timers in the EM instance but the output parameter 'tmr_list' is only written up to the given 'max' length.

Note that the return value (number of timers) can be greater than the given 'max'. It is the user's responsibility to check the return value against the given 'max'.

To only get the current number of active timers, without any timer handles output, use the following: num_timers = em_timer_get_all(NULL, 0);

Parameters
[out]tmr_listPointer to an array of timer handles. Use NULL if only interested in the return value.
maxMax number of handles that can be written into tmr_list 'max' is ignored if 'tmr_list' is NULL.
Returns
The number of active timers
Examples
timer_hello.c, timer_test.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 1754 of file event_machine_timer.c.

◆ em_timer_get_attr()

em_status_t em_timer_get_attr ( em_timer_t  tmr,
em_timer_attr_t tmr_attr 
)

Get timer attributes

Returns the actual capabilities of the given timer.

Parameters
tmrTimer handle
[out]tmr_attrPointer to em_timer_attr_t to fill
Returns
EM_OK on success
Examples
timer_hello.c, timer_test.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 1778 of file event_machine_timer.c.

◆ em_timer_get_freq()

uint64_t em_timer_get_freq ( em_timer_t  tmr)

Returns the timer frequency, i.e. ticks per second for the given timer.

Can be used to convert real time to timer specific tick.

Parameters
tmrTimer handle
Returns
ticks per second (Hz), or 0 for non-existing timer
Examples
timer_hello.c, timer_test.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 1823 of file event_machine_timer.c.

◆ em_timer_ns_to_tick()

em_timer_tick_t em_timer_ns_to_tick ( em_timer_t  tmr,
uint64_t  ns 
)

Convert ns to timer tick

Parameters
tmrValid timer handle
nsns value to convert
Returns
converted amount in timer ticks
Examples
timer_test_periodic.c.

Definition at line 1850 of file event_machine_timer.c.

◆ em_timer_res_capability()

em_status_t em_timer_res_capability ( em_timer_res_param_t res,
em_timer_clksrc_t  clk_src 
)

Inquire timer capabilities for a specific resolution or maximum timeout

Returns timer capabilities by given resolution or maximum timeout. Set one of resolution (res.res_ns) or maximum timeout (res.max_tmo) to required value and the other to zero and this will fill the other fields with valid limits. Error is returned if the given value is not supported. The given clk_src is used to set the values and also written to 'res->clk_src'. Both 'res_ns' and 'res_hz' are filled, so if this is passed to em_timer_create, one of those must be set to 0.

Example for external clock maximum resolution

em_timer_attr_t *tmr_attr;
em_timer_attr_init(&tmr_attr);
// external clock not supported
}
tmr_attr.resparam = capa.max_res;
tmr_attr.resparam.res_hz = 0;
tmr = em_timer_create(&tmr_attr);

This function will not trigger errorhandler calls internally.

Parameters
resPointer to em_timer_res_param_t with one field set
clk_srcClock source to use for timer (EM_TIMER_CLKSRC_DEFAULT for system specific default)
Returns
EM_OK if the input value is supported (res updated)
See also
em_timer_capability
Examples
timer_test.c, and timer_test_periodic.c.

Definition at line 544 of file event_machine_timer.c.

◆ em_timer_ring_attr_init()

em_status_t em_timer_ring_attr_init ( em_timer_attr_t ring_attr,
em_timer_clksrc_t  clk_src,
uint64_t  base_hz,
uint64_t  max_mul,
uint64_t  res_ns 
)

Initialize em_timer_ring_attr_t

Initializes em_timer_ring_attr_t according to given values. After successful return the attributes can be given to em_timer_ring_create. Note, that if the implementation cannot use exact given combination it may update the ring_attr values, but always to meet or exceed given value. User can read the new values to determine if they were modified. Error is returned if given values cannot be met.

Before creating the ring timer other values like num_tmo and name can be adjusted as needed. Also if non-integer frequency is needed the base_hz fractional part can be adjusted before timer_ring_create.

This function will not trigger errorhandler calls.

Parameters
[out]ring_attrPointer to em_timer_attr_t to be initialized
clk_srcClock source to use (system specific or portable EM_TIMER_CLKSRC_DEFAULT)
base_hzBase rate of the ring (minimum rate i.e. longest period)
max_mulMaximum multiplier (maximum rate = base_hz * max_mul)
res_nsRequired resolution of the timing or 0 to accept default
Returns
EM_OK if the given clk_src and other values are supported
See also
em_timer_ring_capability, em_timer_ring_create
Examples
timer_test_ring.c.

Definition at line 444 of file event_machine_timer.c.

◆ em_timer_ring_capability()

em_status_t em_timer_ring_capability ( em_timer_ring_param_t ring)

Check periodic ring timer capability.

Returns ring timer capability from given input values. On input parameter ring must be initialized with the required values. res_ns can be 0, which gets replaced by the system default. During the call values are updated. If this returns EM_OK then the combination of given values are all supported (or exceeded e.g. better resolution), otherwise values are updated with the closest supported.

As em_timer_ring_attr_init only takes integer base_hz, this can also be used to verify valid values for modified fractional frequencies to avoid errorhandler call from timer_ring_create().

This function will not trigger errorhandler calls.

Parameters
ring[in,out] timer ring parameters to check
Return values
EM_OKParameter combination is supported
EM_ERR_NOT_SUPPORTEDParameters not supported, values updated to closest
(othererror) Unsupported arguments
Examples
timer_test_ring.c.

Definition at line 577 of file event_machine_timer.c.

◆ em_timer_ring_create()

em_timer_t em_timer_ring_create ( const em_timer_attr_t ring_attr)

Create and start a timer ring (alternative periodic timer)

Required attributes are given via ring_attr, which must have been initialized with em_timer_ring_attr_init and optionally adjusted for the required timing constraints.

A periodic ring timer is different and will only send EM_EVENT_TYPE_TIMER_IND events, which are automatically provided and cannot be modified. These events can be allocated only via timer APIs.

Example for 1ms ... 125us periodic ring timer (base 1000 hz, multiplier up to 8):

em_timer_ring_attr_t attr;
// given values not supported
}
em_timer_t tmr = em_timer_ring_create(&attr);
if (tmr == EM_TIMER_UNDEF) {
// handle error here or via error handler
}
Parameters
ring_attrTimer ring parameters to use
Returns
Timer handle on success or EM_TIMER_UNDEF on error
See also
em_timer_ring_attr_init
Examples
timer_test_ring.c.

Definition at line 770 of file event_machine_timer.c.

◆ em_timer_tick_to_ns()

uint64_t em_timer_tick_to_ns ( em_timer_t  tmr,
em_timer_tick_t  ticks 
)

Convert timer tick to ns

Parameters
tmrValid timer handle
ticksTimer specific ticks to convert
Returns
converted amount in ns

Definition at line 1837 of file event_machine_timer.c.

◆ em_timer_to_u64()

uint64_t em_timer_to_u64 ( em_timer_t  timer)

Convert a timer handle to an unsigned integer

Parameters
timertimer handle to be converted
Returns
uint64_t value that can be used to print/display the handle
Note
This routine is intended to be used for diagnostic purposes to enable applications to e.g. generate a printable value that represents an em_timer_t handle.

Definition at line 1968 of file event_machine_timer.c.

◆ em_tmo_ack()

em_status_t em_tmo_ack ( em_tmo_t  tmo,
em_event_t  next_tmo_ev 
)

Acknowledge a periodic timeout

All received periodic timeout events must be acknowledged with em_tmo_ack(). No further timeout event(s) will be sent before the user has acknowledged the previous one unless a ring timer is used.

Timeout acknowledgment is usually done at the end of the EO-receive function to prevent race conditions (e.g. if the same event is re-used for the next timeout period also). The implementation will adjust for the processing delay so that the time slot will not drift over time.

If em_tmo_ack() is called too late, e.g. the next period(s) is already passed, the implementation by default will skip all the missed time slots and arm for the next future one keeping the original start offset. Application can alter this behaviour with the flag EM_TMO_FLAG_NOSKIP when creating a timeout. Then no past timeout is skipped and each late acknowledgment will immediately trigger sending the next timeout event until current time has been reached. Note that using EM_TMO_FLAG_NOSKIP may result in an event storm if a large number of timeouts have been unacknowledged for a longer time (limited by application response latency). Timing problems will not call errorhandler.

If the timer has been canceled, but the cancel happened too late for the current period the timeout will be delivered. If application then calls em_tmo_ack it returns EM_ERR_CANCELED and does not call errorhandler. This is to signal it was the last timeout coming for that tmo.

Application may re-use the same received timeout event or provide a new one for the next timeout. With ring timer the received event must be returned.

The given event should not be touched after calling this function until it has been received again or after the timeout is successfully cancelled and event returned.

Periodic timeout will stop if em_tmo_ack() returns an error other than timing related. The implementation will call errorhandler in this case unless timer was canceled, so the exception can be handled also there.

em_tmo_ack() can only be used with periodic timeouts.

Parameters
tmoTimeout handle
next_tmo_evNext timeout event handle (can be the received one)
Return values
EM_OKsuccess (event taken)
EM_ERR_CANCELEDtimer has been cancelled, no more coming, not taken
(other_codes)failure, event not taken
Examples
timer_hello.c, timer_test.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 1638 of file event_machine_timer.c.

◆ em_tmo_cancel()

em_status_t em_tmo_cancel ( em_tmo_t  tmo,
em_event_t *  cur_event 
)

Cancel a timeout

Cancels a timeout preventing future expiration. Returns the timeout event in case the timeout was not expired. A timeout that has already expired or just about to cannot be cancelled and the timeout event will be delivered to the destination queue. In this case cancel will return an error as it was too late to cancel. Errorhandler is not called if failure is due to expired timeout only.

Periodic timeout: cancel may fail if attempted too close to the next period. This can be considered normal and indicates that one more timeout will be received. In this case errorhandler is not called, error status EM_ERR_TOONEAR returned and no event returned. When em_tmo_ack is then called on the canceled timeout event receive it will return EM_ERR_CANCELED to indicate this is the last event coming for this timeout.

Parameters
tmoTimeout handle
[out]cur_eventEvent handle pointer to return the pending timeout event or EM_EVENT_UNDEF if cancel fails (e.g. called too late)
Return values
EM_OKsuccess, event returned
EM_ERR_TOONEARalready expired (too late to cancel). Errorhandler not called
(other_codes)failure
See also
em_tmo_set_abs, em_tmo_set_rel, em_tmo_set_periodic, em_tmo_set_periodic_ring
Examples
timer_test.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 1563 of file event_machine_timer.c.

◆ em_tmo_create()

em_tmo_t em_tmo_create ( em_timer_t  tmr,
em_tmo_flag_t  flags,
em_queue_t  queue 
)

Allocate a new timeout

Create a new timeout. Allocates the necessary internal resources from the given timer and prepares for em_tmo_set_abs/rel/periodic().

Scheduled queues are always supported. LOCAL or OUTPUT queues can not be used as timeout targets. Support for unscheduled queues is implementation specific.

Flags are used to select functionality:

  • EM_TMO_FLAG_ONESHOT creates a one-shot timeout and
  • EM_TMO_FLAG_PERIODIC creates a periodic timeout. The flag EM_TMO_FLAG_NOSKIP can, in the periodic case, be 'OR':d into the flags to make the timeout acknowledgment never skip a missed timeout (the default is to skip missed time slots).

If used timer is timer ring the NOSKIP flag is ignored.

Parameters
tmrTimer handle
flagsFunctionality flags
queueTarget queue where the timeout event should be delivered
Returns
Timeout handle on success or EM_TMO_UNDEF on failure
Examples
timer_hello.c, timer_test.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 1056 of file event_machine_timer.c.

◆ em_tmo_create_arg()

em_tmo_t em_tmo_create_arg ( em_timer_t  tmr,
em_tmo_flag_t  flags,
em_queue_t  queue,
em_tmo_args_t args 
)

Allocate a new timeout with extra arguments

Like em_tmo_create but with additional argument. This can be used with any timer type, but e.g. the userptr argument is only used with ring timers using events of type EM_EVENT_TYPE_TIMER_IND that can carry userptr.

Parameters
tmrTimer handle
flagsFunctionality flags
queueTarget queue where the timeout event should be delivered
argsOptional pointer holding extra arguments e.g. userptr for ring timers. NULL ok.
Returns
Timeout handle on success or EM_TMO_UNDEF on failure
See also
em_tmo_create
Examples
timer_test_ring.c.

Definition at line 1061 of file event_machine_timer.c.

◆ em_tmo_delete()

em_status_t em_tmo_delete ( em_tmo_t  tmo,
em_event_t *  cur_event 
)

Free a timeout

Free (destroy) a timeout. The user provided timeout event for an active timeout will be returned via cur_event and the timeout is cancelled. The timeout event for an expired, but not yet received timeout will not be returned. It is the responsibility of the application to handle that case (event will still be received).

After and during this call the tmo handle is not valid anymore and must not be used. With periodic timeout means em_tmo_ack must also not be called when tmo is deleted.

Parameters
tmoTimeout handle
[out]cur_eventCurrent event for an active timeout
Returns
EM_OK on success
Examples
timer_hello.c, timer_test.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 1161 of file event_machine_timer.c.

◆ em_tmo_get_state()

em_tmo_state_t em_tmo_get_state ( em_tmo_t  tmo)

Returns the current state of the given timeout.

Note that the returned state may change at any time if the timeout expires or is manipulated by other threads.

Parameters
tmoTimeout handle
Returns
current timeout state (EM_TMO_STATE_UNKNOWN on error)
See also
em_tmo_state_t
Examples
timer_test_ring.c.

Definition at line 1863 of file event_machine_timer.c.

◆ em_tmo_get_stats()

em_status_t em_tmo_get_stats ( em_tmo_t  tmo,
em_tmo_stats_t stat 
)

Returns the statistic counters for a timeout.

Returns a snapshot of the current counters of the given timeout. Statistics can be accessed while the timeout is valid, i.e. tmo created but not deleted.

Counter support is optional. If counters are not supported the function returns EM_ERR_NOT_IMPLEMENTED. A quick way to detect whether counters are supported is to call the function with stat=NULL and check the return value.

Parameters
tmoTimeout handle
[out]statPointer to em_tmo_stats_t to receive the values (NULL ok)
Returns
EM_OK on success
Examples
timer_test_periodic.c.

Definition at line 1877 of file event_machine_timer.c.

◆ em_tmo_get_timer()

em_timer_t em_tmo_get_timer ( em_tmo_t  tmo)

Returns the associated timer handle from a timeout handle

Associated timer handle is returned from a valid timeout. Can be used to for instance read the current timer tick without having the timer handle:

Parameters
tmovalid timeout handle
Returns
associated timer handle or EM_TIMER_UNDEF if tmo is not valid

Definition at line 1954 of file event_machine_timer.c.

◆ em_tmo_get_type()

em_tmo_type_t em_tmo_get_type ( em_event_t  event,
em_tmo_t tmo,
bool  reset 
)

Ask if given event is currently used as timeout indication.

This can be used with any valid event handle to ask if it is used as a timeout indication event. Events are updated for tmo type when going through timer API.

Note
As a received event is owned by the application and not necessarily passing through timer API anymore this type will not reset until event is freed, re-used as another timeout or explicitly reset by setting the reset argument to true. This reset should be done if re-using the received tmo event for something else than timeout to avoid expired value being returned in case someone later calls tmo_get_type.

Successful timeout cancel (event returned) will reset the event type to EM_TMO_TYPE_NONE.

Note
The reset argument is ignored if the given event is of type EM_EVENT_TYPE_TIMER_IND.

The related tmo handle can also be retrieved via parameter tmo. This can be useful to call em_tmo_ack() for periodic timeouts:

if (em_tmo_get_type(event, &tmo, false) == EM_TMO_TYPE_PERIODIC)
retval = em_tmo_ack(tmo, event);
Parameters
eventevent handle to check
[out]tmopointer to em_tmo_t to receive related tmo handle (NULL ok)
resetset true to reset tmo type to EM_TMO_TYPE_NONE for non-timer re-use
Returns
type of timeout use or EM_TMO_TYPE_NONE if event is not related to a timeout
See also
em_tmo_type_t
Examples
timer_test_periodic.c, and timer_test_ring.c.

Definition at line 1900 of file event_machine_timer.c.

◆ em_tmo_get_userptr()

void* em_tmo_get_userptr ( em_event_t  event,
em_tmo_t tmo 
)

Returns the optional user pointer for a periodic ring timeout

Can only be used with an event received as a timeout for a periodic ring, i.e. EM_EVENT_TYPE_TIMER_IND only. Other event types will return NULL.

Parameters
eventEvent received as timeout
[out]tmoOptionally returns associated tmo handle. NULL ok.
Returns
A pointer given when creating the associated tmo or NULL if the event is not ring timeout
Examples
timer_test_ring.c.

Definition at line 1933 of file event_machine_timer.c.

◆ em_tmo_set_abs()

em_status_t em_tmo_set_abs ( em_tmo_t  tmo,
em_timer_tick_t  ticks_abs,
em_event_t  tmo_ev 
)

Activate a oneshot timeout with absolute time.

Activates oneshot timeout to expire at specific absolute time. The given timeout event will be sent to the queue given to em_tmo_create() when the timeout expires.

It is not possible to send timeouts with an event group, but the application can assign the event group when receiving the timeout event, see em_event_group_assign().

The timeout event should not be accessed after it has been given to the timer, similar to sending an event.

Even if not guaranteed, the implementation should make sure that this call can fail only in exceptional situations (em_tmo_create() should pre- allocate needed resources).

Allowed minimum and maximum timeout can be inquired with em_timer_res_capability.

An active timeout can not be modified. The timeout needs to be canceled and then set again with new arguments.

An inactive timeout can be re-used by calling em_tmo_set_abs/rel() again after the previous timeout was received or was cancelled successfully.

This function is for activating oneshot timeouts only. To activate a periodic timer use em_tmo_set_periodic() instead.

Parameters
tmoTimeout handle
ticks_absExpiration time in absolute timer specific ticks
tmo_evTimeout event
Return values
EM_OKsuccess (event taken)
EM_ERR_TOONEARfailure, tick value is in past or too close to current time. Errorhandler not called, event not taken
(other_codes)failure, event not taken
See also
em_timer_res_capability
Examples
timer_hello.c.

Definition at line 1255 of file event_machine_timer.c.

◆ em_tmo_set_periodic()

em_status_t em_tmo_set_periodic ( em_tmo_t  tmo,
em_timer_tick_t  start_abs,
em_timer_tick_t  period,
em_event_t  tmo_ev 
)

Activate a periodic timeout

Used to activate periodic timeouts. The first period can be different from the repetitive period by providing an absolute start time e.g. the first period starts from that moment. Use 0 as start time if the period can start from the moment of the call (relative).

The timeout event will be sent to the queue given to em_tmo_create() when the first timeout expires. Receiver then need to call em_tmo_ack() to allow sending next event.

This function can only be used with periodic timeouts (created with flag EM_TMO_FLAG_PERIODIC).

Parameters
tmoTimeout handle
start_absAbsolute start time (or 0 for period starting at call time)
periodPeriod in timer specific ticks
tmo_evTimeout event handle
Return values
EM_OKsuccess (event taken)
EM_ERR_TOONEARfailure, tick value is in past or too close to current time. Errorhandler not called, event not taken
(other_codes)failure, event not taken
See also
em_tmo_ack
Examples
timer_hello.c, timer_test.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 1402 of file event_machine_timer.c.

◆ em_tmo_set_periodic_ring()

em_status_t em_tmo_set_periodic_ring ( em_tmo_t  tmo,
em_timer_tick_t  start_abs,
uint64_t  multiplier,
em_event_t  tmo_ev 
)

Activate a periodic timeout on a periodic ring timer

Use start_abs value 0 to start the timer relative to current time. To adjust the offset of timeouts an absolute tick can also be given, but the maximum distance from current time can only be up to one period. Periodic rate of the timeout event is base_hz (given when creating the timer) multiplied by the given multiplier. For example 1000Hz base_hz with multiplier of 8 will give 125us period.

Timeout event of type EM_EVENT_TYPE_TIMER_IND is automatically allocated if not provided and will be sent to the queue given to em_tmo_create() when the timeout expires. User then needs to call em_timer_ack like with normal periodic timeout. With ring timer however there is no guaranteed flow control, new events may be sent even before user has called ack. This means the same event may be in the input queue multiple times if the application can not keep up the period rate. If the destination queue is not atomic the same event can then also be concurrently received by multiple cores. This is a race hazard to prepare for. Additionally the used event can not change via em_tmo_ack, the received event must always be returned.

The last argument tmo_ev is normally EM_EVENT_UNDEF for a new timeout start. Then the implementation will use pre-allocated event. Exception is re-use of canceled ring timeout event (when ack returns EM_ERR_CANCELED the event stays with user and can be re-used). Such event can be recycled here to avoid extra free and alloc.

This function can only be used with periodic timeouts with a ring timer. The timeout indication event is read-only and can be accessed only via accessor APIs.

Parameters
tmoTimeout handle
start_absAbsolute start time (or 0 for period starting at call time)
multiplierRate multiplier (period rate = multiplier * timer base_hz)
tmo_evEvent of type EM_EVENT_TYPE_TIMER_IND to re-use. Normally EM_EVENT_UNDEF.
Return values
EM_OKsuccess
EM_ERR_TOONEARfailure, start tick value is past or too close to current time or multiplier is too high
EM_ERR_TOOFARfailure, start tick value exceeds one period
(other_codes)failure
See also
em_tmo_get_user_ptr, em_tmo_get_type, em_timer_create_ring
Examples
timer_test_ring.c.

Definition at line 1487 of file event_machine_timer.c.

◆ em_tmo_set_rel()

em_status_t em_tmo_set_rel ( em_tmo_t  tmo,
em_timer_tick_t  ticks_rel,
em_event_t  tmo_ev 
)

Activate a timeout with relative time.

Similar to em_tmo_set_abs(), but instead of an absolute time uses timeout value relative to the moment of the call.

This function is for activating oneshot timeouts only. To activate a periodic timer use em_tmo_set_periodic() instead.

Parameters
tmoTimeout handle
ticks_relExpiration time in relative timer specific ticks
tmo_evTimeout event handle
Return values
EM_OKsuccess (event taken)
EM_ERR_TOONEARfailure, tick value is too low. Errorhandler not called, event not taken
(other_codes)failure, event not taken
Deprecated:
Do not use for periodic timeouts
See also
em_tmo_set_abs, em_tmo_set_periodic
Examples
timer_hello.c, and timer_test.c.

Definition at line 1330 of file event_machine_timer.c.

◆ em_tmo_to_u64()

uint64_t em_tmo_to_u64 ( em_tmo_t  tmo)

Convert a timeout handle to an unsigned integer

Parameters
tmotimeout handle to be converted
Returns
uint64_t value that can be used to print/display the handle
Note
This routine is intended to be used for diagnostic purposes to enable applications to e.g. generate a printable value that represents an em_tmo_t handle.

Definition at line 1973 of file event_machine_timer.c.

em_timer_current_tick
em_timer_tick_t em_timer_current_tick(em_timer_t tmr)
Definition: event_machine_timer.c:1045
EM_OK
#define EM_OK
Definition: event_machine_types.h:329
em_timer_attr_t::resparam
em_timer_res_param_t resparam
Definition: api/event_machine_timer.h:339
em_tmo_set_rel
em_status_t em_tmo_set_rel(em_tmo_t tmo, em_timer_tick_t ticks_rel, em_event_t tmo_ev)
Definition: event_machine_timer.c:1330
em_timer_capability_t::max_res
em_timer_res_param_t max_res
Definition: api/event_machine_timer.h:386
em_tmo_ack
em_status_t em_tmo_ack(em_tmo_t tmo, em_event_t next_tmo_ev)
Definition: event_machine_timer.c:1638
em_timer_capability_t
Definition: api/event_machine_timer.h:380
em_timer_tick_t
uint64_t em_timer_tick_t
Definition: api/event_machine_timer.h:261
em_timer_capability
em_status_t em_timer_capability(em_timer_capability_t *capa, em_timer_clksrc_t clk_src)
Definition: event_machine_timer.c:502
em_timer_attr_t::name
char name[EM_TIMER_NAME_LEN]
Definition: api/event_machine_timer.h:345
em_timer_ring_create
em_timer_t em_timer_ring_create(const em_timer_attr_t *ring_attr)
Definition: event_machine_timer.c:770
em_tmo_create
em_tmo_t em_tmo_create(em_timer_t tmr, em_tmo_flag_t flags, em_queue_t queue)
Definition: event_machine_timer.c:1056
em_timer_timeout_t
Definition: em_timer_types.h:76
em_timer_attr_t
Definition: api/event_machine_timer.h:335
EM_TIMER_CLKSRC_DEFAULT
#define EM_TIMER_CLKSRC_DEFAULT
Definition: event_machine_timer_hw_specific.h:106
EM_TMO_TYPE_PERIODIC
@ EM_TMO_TYPE_PERIODIC
Definition: api/event_machine_timer.h:253
em_timer_attr_init
void em_timer_attr_init(em_timer_attr_t *tmr_attr)
Definition: event_machine_timer.c:378
em_tmo_get_type
em_tmo_type_t em_tmo_get_type(em_event_t event, em_tmo_t *tmo, bool reset)
Definition: event_machine_timer.c:1900
EM_TMO_UNDEF
#define EM_TMO_UNDEF
Definition: event_machine_timer_hw_specific.h:125
EM_TIMER_UNDEF
#define EM_TIMER_UNDEF
Definition: event_machine_timer_hw_specific.h:120
em_tmo_get_timer
em_timer_t em_tmo_get_timer(em_tmo_t tmo)
Definition: event_machine_timer.c:1954
em_timer_ring_attr_init
em_status_t em_timer_ring_attr_init(em_timer_attr_t *ring_attr, em_timer_clksrc_t clk_src, uint64_t base_hz, uint64_t max_mul, uint64_t res_ns)
Definition: event_machine_timer.c:444
em_timer_get_freq
uint64_t em_timer_get_freq(em_timer_t tmr)
Definition: event_machine_timer.c:1823
EM_TIMER_CLKSRC_EXT
#define EM_TIMER_CLKSRC_EXT
Definition: event_machine_timer_hw_specific.h:115
em_timer_create
em_timer_t em_timer_create(const em_timer_attr_t *tmr_attr)
Definition: event_machine_timer.c:616
em_timer_res_param_t::res_hz
uint64_t res_hz
Definition: api/event_machine_timer.h:295