api: timer: add max_timeouts periodic capability

With a periodic timer, allow an implementation to use more timeouts in
addition to the timeout allocated by application and provided in
odp_timer_periodic_start(). Add a parameter to periodic capability,
which indicates how many timeouts an application should reserve per
timer.

Signed-off-by: Jere Leppänen <[email protected]>

include/odp/api/spec/timer.h

@@ -357,14 +357,12 @@ int odp_timer_periodic_start(odp_timer_t timer, const odp_timer_periodic_start_t
  * Application must not use the event anymore after this. A greater than zero return value
  * 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 last event from a cancelled timer. After receiving it application may free the timer.
  *
  * @param timer    Periodic timer
  * @param tmo_ev   Timeout event that was received from the periodic timer
  *
- * @retval 2  Success, the last event from a cancelled timer. The call did not consume
- *            the event.
+ * @retval 2  Success, the last event from a cancelled timer. The call consumed the event.
  * @retval 1  Success, an event from a cancelled timer. The call consumed the event.
  * @retval 0  Success, the call consumed the event.
  * @retval <0 Failure, the call did not consume the event.

include/odp/api/spec/timer_types.h

@@ -116,6 +116,17 @@ typedef struct {
 	/** Timeout resolution in nanoseconds */
 	uint64_t res_ns;
 
+	/**
+	 * Maximum number of timeouts
+	 *
+	 * An implementation may use more timeouts in addition to the timeout allocated by
+	 * application and provided in odp_timer_periodic_start(). This parameter is the maximum
+	 * number of timeouts per timer that the implementation may use, including the timeout
+	 * provided in odp_timer_periodic_start(). Therefore, the returned value is always at
+	 * least 1. The input value is ignored.
+	 */
+	uint32_t max_timeouts;
+
 } odp_timer_periodic_capability_t;
 
 /**
@@ -503,8 +514,13 @@ typedef struct odp_timer_periodic_start_t {
 
 	/** Timeout event
 	 *
-	 *  This event is enqueued to the destination queue when the timer expires. The event type
-	 *  must be ODP_EVENT_TIMEOUT.
+	 *  This event, or a copy of it, is enqueued to the destination queue when the timer
+	 *  expires. The event type must be ODP_EVENT_TIMEOUT.
+	 *
+	 *  If the queued event is a copy, it is allocated from the same pool as the original event,
+	 *  and has the same user pointer value and user area contents. Application must ensure that
+	 *  there are enough timeouts in the pool.
+	 *  @see odp_timer_periodic_capability_t::max_timeouts
 	 */
 	odp_event_t tmo_ev;