| Message ID | 1422982108-13813-17-git-send-email-ola.liljedahl@linaro.org |
|---|---|
| State | New |
| Headers | show |
On 4 February 2015 at 15:02, Savolainen, Petri (NSN - FI/Espoo) <petri.savolainen@nsn.com> wrote: > > >> -----Original Message----- >> From: lng-odp-bounces@lists.linaro.org [mailto:lng-odp- >> bounces@lists.linaro.org] On Behalf Of ext Ola Liljedahl >> Sent: Tuesday, February 03, 2015 6:48 PM >> To: lng-odp@lists.linaro.org >> Subject: [lng-odp] [PATCHv5 16/18] api: odp_timer.h: updated return >> descriptions >> >> Updated doxygen descriptions, particularly the @return/@retval >> descriptions. >> Documented API calls which are guaranteed to handle invalid/stale handles. >> Removed unnecessary warnings of undefined behavior. >> No change of implementation necessary. >> >> 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(-) >> >> 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. > > > Why? How this is different? > > I think all calls accessing the timer pool (a shared resource) have the same behavior. Those can crash on bad tpid handles, and may catch stale handles with return code or crash. OK if this is the defined behavior for all timer.h calls. "May" is not a requirement of some specific behavior. I thought I was making the world a service but I will remove the above two lines. > > > - Petri > > > >> * >> - * @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 >> -- >> 1.9.1 >> >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> http://lists.linaro.org/mailman/listinfo/lng-odp
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
Updated doxygen descriptions, particularly the @return/@retval descriptions. Documented API calls which are guaranteed to handle invalid/stale handles. Removed unnecessary warnings of undefined behavior. No change of implementation necessary. 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(-)