@@ -117,8 +117,8 @@ typedef struct {
* @param name Name of the timer pool. The string will be copied.
* @param params Timer pool parameters. The content will be copied.
*
- * @return Timer pool handle if successful, otherwise ODP_TIMER_POOL_INVALID
- * and errno set
+ * @return Timer pool handle on success
+ * @retval ODP_TIMER_POOL_INVALID on failure and errno set
*/
odp_timer_pool_t
odp_timer_pool_create(const char *name,
@@ -140,14 +140,14 @@ void odp_timer_pool_start(void);
* Destroy a timer pool, freeing all resources.
* All timers must have been freed.
*
- * @param tpid Timer pool identifier
+ * @param tpid Timer pool handle
*/
void odp_timer_pool_destroy(odp_timer_pool_t tpid);
/**
* Convert timer ticks to nanoseconds
*
- * @param tpid Timer pool identifier
+ * @param tpid Timer pool handle
* @param ticks Timer ticks
*
* @return Nanoseconds
@@ -157,7 +157,7 @@ uint64_t odp_timer_tick_to_ns(odp_timer_pool_t tpid, uint64_t ticks);
/**
* Convert nanoseconds to timer ticks
*
- * @param tpid Timer pool identifier
+ * @param tpid Timer pool handle
* @param ns Nanoseconds
*
* @return Timer ticks
@@ -167,7 +167,7 @@ uint64_t odp_timer_ns_to_tick(odp_timer_pool_t tpid, uint64_t ns);
/**
* Current tick value
*
- * @param tpid Timer pool identifier
+ * @param tpid Timer pool handle
*
* @return Current time in timer ticks
*/
@@ -186,12 +186,14 @@ typedef struct {
/**
* Query timer pool configuration and current state
+ * @note This is the only timer API function which accepts invalid handles
+ * (any bit value) without causing undefined behavior.
*
- * @param tpid Timer pool identifier
+ * @param tpid Timer pool handle
* @param[out] info Pointer to information buffer
*
- * @retval 0 Success
- * @retval -1 Failure. Info could not be retrieved.
+ * @retval 0 on success
+ * @retval <0 on failure. Info could not be retrieved.
*/
int odp_timer_pool_info(odp_timer_pool_t tpid,
odp_timer_pool_info_t *info);
@@ -203,12 +205,12 @@ int odp_timer_pool_info(odp_timer_pool_t tpid,
* the timer pool. The user_ptr is copied to timeouts and can be retrieved
* using the odp_timeout_user_ptr() call.
*
- * @param tpid Timer pool identifier
+ * @param tpid Timer pool handle
* @param queue Destination queue for timeout notifications
* @param user_ptr User defined pointer or NULL to be copied to timeouts
*
- * @return Timer handle if successful, otherwise ODP_TIMER_INVALID and
- * errno set.
+ * @return Timer handle on success
+ * @retval ODP_TIMER_INVALID on failure and errno set.
*/
odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid,
odp_queue_t queue,
@@ -223,7 +225,8 @@ odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid,
* responsibility of the application to handle this timeout when it is received.
*
* @param tim Timer handle
- * @return Event handle of timeout event or ODP_EVENT_INVALID
+ * @return Event handle of timeout event
+ * @retval ODP_EVENT_INVALID on failure
*/
odp_event_t odp_timer_free(odp_timer_t tim);
@@ -233,9 +236,6 @@ odp_event_t odp_timer_free(odp_timer_t tim);
* Set (arm) the timer to expire at specific time. The timeout
* event will be enqueued when the timer expires.
*
- * Note: any invalid parameters will be treated as programming errors and will
- * cause the application to abort.
- *
* @param tim Timer
* @param abs_tck Expiration time in absolute timer ticks
* @param[in,out] tmo_ev Reference to an event variable that points to
@@ -260,9 +260,6 @@ int odp_timer_set_abs(odp_timer_t tim,
*
* Set (arm) the timer to expire at a relative future time.
*
- * Note: any invalid parameters will be treated as programming errors and will
- * cause the application to abort.
- *
* @param tim Timer
* @param rel_tck Expiration time in timer ticks relative to current time of
* the timer pool the timer belongs to
@@ -292,22 +289,16 @@ int odp_timer_set_rel(odp_timer_t tim,
* A timer that has already expired may be impossible to cancel and the timeout
* will instead be delivered to the destination queue.
*
- * Note: any invalid parameters will be treated as programming errors and will
- * cause the application to abort.
- *
* @param tim Timer
* @param[out] tmo_ev Pointer to an event variable
* @retval 0 Success, active timer cancelled, timeout returned in '*tmo_ev'
- * @retval -1 Failure, timer already expired (or inactive)
+ * @retval <0 on failure, timer already expired (or inactive)
*/
int odp_timer_cancel(odp_timer_t tim, odp_event_t *tmo_ev);
/**
* Return timeout handle that is associated with timeout event
*
- * Note: any invalid parameters will cause undefined behavior and may cause
- * the application to abort or crash.
- *
* @param ev An event of type ODP_EVENT_TIMEOUT
*
* @return timeout handle
@@ -337,9 +328,6 @@ int odp_timeout_fresh(odp_timeout_t tmo);
/**
* Return timer handle for the timeout
*
- * Note: any invalid parameters will cause undefined behavior and may cause
- * the application to abort or crash.
- *
* @param tmo Timeout handle
*
* @return Timer handle
@@ -349,9 +337,6 @@ odp_timer_t odp_timeout_timer(odp_timeout_t tmo);
/**
* Return expiration tick for the timeout
*
- * Note: any invalid parameters will cause undefined behavior and may cause
- * the application to abort or crash.
- *
* @param tmo Timeout handle
*
* @return Expiration tick
@@ -362,9 +347,6 @@ uint64_t odp_timeout_tick(odp_timeout_t tmo);
* Return user pointer for the timeout
* The user pointer was specified when the timer was allocated.
*
- * Note: any invalid parameters will cause undefined behavior and may cause
- * the application to abort or crash.
- *
* @param tmo Timeout handle
*
* @return User pointer
Updated doxygen descriptions, particularly the @return/@retval descriptions. No change of implementation necessary. Documented API calls which are guaranteed to handle invalid/stale handles. Removed unnecessary warnings of undefined behavior. Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org> --- (This document/code contribution attached is provided under the terms of agreement LES-LTM-21309) platform/linux-generic/include/api/odp_timer.h | 52 +++++++++----------------- 1 file changed, 17 insertions(+), 35 deletions(-)