[PATCHv3,16/18] api: odp_timer.h: updated return descriptions

Message ID 1422897646-8064-7-git-send-email-ola.liljedahl@linaro.org
State New
Headers show

Commit Message

Ola Liljedahl Feb. 2, 2015, 5:20 p.m.
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)

 include/odp/api/timer.h | 52 ++++++++++++++++---------------------------------
 1 file changed, 17 insertions(+), 35 deletions(-)

Patch

diff --git a/include/odp/api/timer.h b/include/odp/api/timer.h
index 64ccc4b..1b813da 100644
--- a/include/odp/api/timer.h
+++ b/include/odp/api/timer.h
@@ -112,8 +112,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,
@@ -135,14 +135,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
@@ -152,7 +152,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
@@ -162,7 +162,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
  */
@@ -181,12 +181,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);
@@ -198,12 +200,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,
@@ -218,7 +220,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);
 
@@ -228,9 +231,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
@@ -255,9 +255,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
@@ -287,22 +284,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
@@ -332,9 +323,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
@@ -344,9 +332,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
@@ -357,9 +342,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