[PATCH v2] api: timer: require an array of timeout events in odp_timer_periodic_start()

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

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;