diff --git a/include/odp/api/spec/timer.h b/include/odp/api/spec/timer.h index c42c5cf5ef..33ee252ae4 100644 --- a/include/odp/api/spec/timer.h +++ b/include/odp/api/spec/timer.h @@ -310,6 +310,23 @@ int odp_timer_start(odp_timer_t timer, const odp_timer_start_t *start_param); */ int odp_timer_restart(odp_timer_t timer, const odp_timer_start_t *start_param); +/** + * Return the number of timeout events + * + * Returns in start_param.num_tmo_ev the number of events that the application must allocate and + * provide in odp_timer_periodic_start(). Application must set the values of first_tick and + * freq_multiplier in start_param before calling this function, the rest of the parameters are + * ignored. On return, the value of num_tmo_ev is set and the other parameters are not modified. + * The value of num_tmo_ev is less than or equal to periodic.max_tmo_events in timer capability. + * + * @param timer_pool Timer pool + * @param start_param Periodic timer start parameters + * + * @retval 0 Success. + * @retval <0 Failure. + */ +int odp_timer_periodic_events(odp_timer_pool_t timer_pool, odp_timer_periodic_start_t *start_param); + /** * Start a periodic timer * @@ -319,6 +336,10 @@ int odp_timer_restart(odp_timer_t timer, const odp_timer_start_t *start_param); * call, the timer remains active until it is cancelled and all its timeout events have been * acknowledged. * + * Before calling this function, odp_timer_periodic_events() must be called to set the value of + * num_tmo_ev in start_param. The application must then allocate as many timeout events in an array, + * and set tmo_ev to point to the array. + * * Timer expiration frequency (period) is defined as a multiple of the timer pool base frequency * (odp_timer_pool_param_t::base_freq_hz). The timeout event type must be ODP_EVENT_TIMEOUT * (odp_timeout_t). @@ -358,7 +379,7 @@ int odp_timer_periodic_start(odp_timer_t timer, const odp_timer_periodic_start_t * indicates timeout events from a cancelled timer. These events may not arrive at the * requested interval, but are used to finalize the timer cancel request. Return value of 2 marks * the last event from a cancelled timer. After receiving it application may free the timer and - * the timeout event. + * the array of timeout events. * * @param timer Periodic timer * @param tmo_ev Timeout event that was received from the periodic timer diff --git a/include/odp/api/spec/timer_types.h b/include/odp/api/spec/timer_types.h index 0fd5d4f70d..c25f6d6f6e 100644 --- a/include/odp/api/spec/timer_types.h +++ b/include/odp/api/spec/timer_types.h @@ -213,6 +213,13 @@ typedef struct { /** Maximum supported base frequency value */ odp_fract_u64_t max_base_freq_hz; + /** Maximum number of timeout events that may be needed + * + * The number of timeout events per timer, as returned by + * odp_timer_periodic_events(), is less than or equal to this value. + */ + uint32_t max_tmo_events; + } periodic; } odp_timer_capability_t; @@ -501,12 +508,20 @@ typedef struct odp_timer_periodic_start_t { */ uint64_t freq_multiplier; - /** Timeout event + /** Number of timeout events * - * This event is enqueued to the destination queue when the timer expires. The event type - * must be ODP_EVENT_TIMEOUT. + * Number of timeout events in the tmo_ev array. This value is set by calling + * odp_timer_periodic_events(). */ - odp_event_t tmo_ev; + uint32_t num_tmo_ev; + + /** Array of timeout events + * + * One of these events is enqueued to the destination queue when the timer expires. The + * event type of the events must be ODP_EVENT_TIMEOUT. The application may free these + * events after receiving a return value of 2 (last event) from odp_timer_periodic_ack(). + */ + odp_event_t *tmo_ev; } odp_timer_periodic_start_t;