diff options
Diffstat (limited to 'include/odp/api/spec/timer.h')
| -rw-r--r-- | include/odp/api/spec/timer.h | 611 |
1 files changed, 424 insertions, 187 deletions
diff --git a/include/odp/api/spec/timer.h b/include/odp/api/spec/timer.h index 75f9db98e..9766eafa3 100644 --- a/include/odp/api/spec/timer.h +++ b/include/odp/api/spec/timer.h @@ -1,127 +1,137 @@ -/* Copyright (c) 2013, Linaro Limited - * All rights reserved. - * - * SPDX-License-Identifier: BSD-3-Clause +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2013-2018 Linaro Limited + * Copyright (c) 2019-2023 Nokia */ - /** * @file * * ODP timer service */ -#ifndef ODP_API_TIMER_H_ -#define ODP_API_TIMER_H_ +#ifndef ODP_API_SPEC_TIMER_H_ +#define ODP_API_SPEC_TIMER_H_ #include <odp/visibility_begin.h> #ifdef __cplusplus extern "C" { #endif -/** @defgroup odp_timer ODP TIMER - * @{ - */ - -/** - * @typedef odp_timer_pool_t - * ODP timer pool handle - */ - -/** - * @def ODP_TIMER_POOL_INVALID - * Invalid timer pool handle - */ - -/** - * Clock sources for timers in timer pool. - */ -typedef enum { - /** Use CPU clock as clock source for timers */ - ODP_CLOCK_CPU, - /** Use external clock as clock source for timers */ - ODP_CLOCK_EXT - /* Platform dependent which other clock sources exist */ -} odp_timer_clk_src_t; - -/** - * @typedef odp_timer_t - * ODP timer handle - */ - -/** - * @def ODP_TIMER_INVALID - * Invalid timer handle - */ +#include <odp/api/timer_types.h> +#include <odp/api/event_types.h> +#include <odp/api/pool_types.h> +#include <odp/api/queue_types.h> -/** - * @typedef odp_timeout_t - * ODP timeout handle +/** @addtogroup odp_timer + * @{ */ /** - * @def ODP_TIMEOUT_INVALID - * Invalid timeout handle + * Query timer capabilities per clock source + * + * Outputs timer capabilities on success. Returns -1 if the clock source + * is not supported. + * + * @param clk_src Clock source for timers + * @param[out] capa Pointer to capability structure for output + * + * @retval 0 on success + * @retval -1 when the clock source is not supported + * @retval <-1 on other failures */ +int odp_timer_capability(odp_timer_clk_src_t clk_src, odp_timer_capability_t *capa); /** - * Return values of timer set calls. - */ -typedef enum { -/** - * Timer set operation succeeded + * Timer resolution capability + * + * This function fills in capability limits for timer pool resolution and + * min/max timeout values, based on either resolution or maximum timeout. + * Set the required value to a resolution field (res_ns or res_hz) or to the + * maximum timeout field (max_tmo), and set other fields to zero. A successful + * call fills in the other fields. The call returns a failure, if the user + * defined value exceeds capability limits. Outputted values are minimums for + * 'res_ns' and 'min_tmo', and maximums for 'res_hz' and 'max_tmo'. + * + * @param clk_src Clock source for timers + * @param[in,out] res_capa Resolution capability pointer for input/output. + * Set either a resolution or max timeout field, + * a successful call fills in other fields. + * + * @retval 0 on success + * @retval <0 on failure */ - ODP_TIMER_SUCCESS = 0, -/** - * Timer set operation failed, expiration too early. - * Either retry with a later expiration time or process the timeout - * immediately. */ - ODP_TIMER_TOOEARLY = -1, +int odp_timer_res_capability(odp_timer_clk_src_t clk_src, + odp_timer_res_capability_t *res_capa); /** - * Timer set operation failed, expiration too late. - * Truncate the expiration time against the maximum timeout for the - * timer pool. */ - ODP_TIMER_TOOLATE = -2, -/** - * Timer set operation failed because no timeout event specified and no - * timeout event present in the timer (timer inactive/expired). + * Periodic timer capability + * + * Checks periodic timer capability to support the requested base frequency and other parameters. + * Application sets 'capa' with the requested timer pool base frequency, the maximum + * frequency multiplier and the minimum timeout resolution. If there is no requirement for timeout + * resolution, it is set to zero. + * + * When the call returns success, 'capa' fields are overwritten in following ways. On return value + * of 1, timer supports the requested base frequency exactly, and meets or exceeds other requested + * values. The base frequency value is not modified, but other 'capa' fields are updated with + * resulting maximum capabilities. + * + * When the call returns 0, the requested base frequency is not supported exactly, but timer + * capabilities meet or exceed all other requested values. In this case, the call overwrites + * 'base_freq_hz' with the closest supported frequency and updates other 'capa' fields accordingly. + * + * Failure is returned when the requirements are not supported or the call fails otherwise. + * + * @param clk_src Clock source for timer pool + * @param[in,out] capa Pointer to periodic timer capability for input/output. + * + * @retval 1 Success. Capability matches base frequency, and meets or exceeds other requested + * values. + * @retval 0 Success. Capability does not match base frequency exactly, but meets or exceeds + * other requested values. + * @retval <0 Failure */ - ODP_TIMER_NOEVENT = -3 -} odp_timer_set_t; +int odp_timer_periodic_capability(odp_timer_clk_src_t clk_src, + odp_timer_periodic_capability_t *capa); /** - * @def ODP_TIMER_POOL_NAME_LEN - * Maximum timer pool name length in chars including null char - */ - -/** Timer pool parameters - * Timer pool parameters are used when creating and querying timer pools. + * Initialize timer pool parameters + * + * Initialize an odp_timer_pool_param_t to its default values for all fields. + * + * @param[out] param Pointer to the odp_timer_pool_param_t structure to be initialized */ -typedef struct { - uint64_t res_ns; /**< Timeout resolution in nanoseconds */ - uint64_t min_tmo; /**< Minimum relative timeout in nanoseconds */ - uint64_t max_tmo; /**< Maximum relative timeout in nanoseconds */ - uint32_t num_timers; /**< (Minimum) number of supported timers */ - int priv; /**< Shared (false) or private (true) timer pool */ - odp_timer_clk_src_t clk_src; /**< Clock source for timers */ -} odp_timer_pool_param_t; +void odp_timer_pool_param_init(odp_timer_pool_param_t *param); /** * Create a timer pool * - * The use of pool name is optional. Unique names are not required. + * Creates a timer pool according to the parameters. Use 'timer_type' parameter to select if timers + * are single shot or periodic. All timers in the pool are of the same type. The selected timer + * type defines which other parameters are used or ignored. + * + * The use of pool name is optional. Unique names are not required. Use odp_timer_pool_param_init() + * to initialize timer pool parameters into their default values. + * + * After creation a timer pool can be either started (see odp_timer_pool_start_multi()) or + * destroyed. The returned pool handle cannot be used with any other APIs, except + * odp_timer_pool_to_u64(), before the pool is successfully started. + * + * Periodic timer expiration frequency is a multiple of the timer pool base frequency + * (odp_timer_pool_param_t::base_freq_hz). Depending on implementation, the base frequency may need + * to be selected carefully with respect to the timer pool source clock frequency. Use + * odp_timer_periodic_capability() to check which base frequencies and multipliers are supported. + * + * The call returns failure when requested parameter values are not supported. * * @param name Name of the timer pool or NULL. Maximum string length is - * ODP_TIMER_POOL_NAME_LEN. + * ODP_TIMER_POOL_NAME_LEN, including the null character. * @param params Timer pool parameters. The content will be copied. * * @return Timer pool handle on success - * @retval ODP_TIMER_POOL_INVALID on failure and errno set + * @retval ODP_TIMER_POOL_INVALID on failure */ -odp_timer_pool_t -odp_timer_pool_create(const char *name, - const odp_timer_pool_param_t *params); +odp_timer_pool_t odp_timer_pool_create(const char *name, const odp_timer_pool_param_t *params); /** * Start a timer pool @@ -130,171 +140,308 @@ odp_timer_pool_create(const char *name, * The purpose of this call is to coordinate the creation of multiple timer * pools that may use the same underlying HW resources. * This function may be called multiple times. + * + * @deprecated Use odp_timer_pool_start_multi() instead */ void odp_timer_pool_start(void); /** + * Start timer pools + * + * Start given timer pools. After a pool has been successfully started the pool handle can be used + * with other APIs. Each timer pool can be started only once. + * + * Returns 'num' when all given timer pools have been successfully started. If the return value + * N < 'num', only the first N pools started successfully and at least some of the remaining ones + * failed to start. In case of a negative return value, none of the pools were started. The + * unstarted timer pools cannot be used anymore (can only be destroyed). + * + * @param timer_pool Array of timer pool handles + * @param num Number of pools to start + * + * @retval num on success + * @retval <num on failure + */ +int odp_timer_pool_start_multi(odp_timer_pool_t timer_pool[], int num); + +/** * Destroy a timer pool * * Destroy a timer pool, freeing all resources. * All timers must have been freed. * - * @param tpid Timer pool identifier + * @param timer_pool Timer pool */ -void odp_timer_pool_destroy(odp_timer_pool_t tpid); +void odp_timer_pool_destroy(odp_timer_pool_t timer_pool); /** * Convert timer ticks to nanoseconds * - * @param tpid Timer pool identifier - * @param ticks Timer ticks + * @param timer_pool Timer pool + * @param ticks Timer ticks * * @return Nanoseconds */ -uint64_t odp_timer_tick_to_ns(odp_timer_pool_t tpid, uint64_t ticks); +uint64_t odp_timer_tick_to_ns(odp_timer_pool_t timer_pool, uint64_t ticks); /** * Convert nanoseconds to timer ticks * - * @param tpid Timer pool identifier - * @param ns Nanoseconds + * @param timer_pool Timer pool + * @param ns Nanoseconds * * @return Timer ticks */ -uint64_t odp_timer_ns_to_tick(odp_timer_pool_t tpid, uint64_t ns); +uint64_t odp_timer_ns_to_tick(odp_timer_pool_t timer_pool, uint64_t ns); /** * Current tick value * - * @param tpid Timer pool identifier + * Returns the current tick value of the timer pool. Timer tick is an implementation defined unit + * of time. Ticks and related nanosecond values are timer pool specific. Those may not start from + * zero, but are guaranteed not to wrap around in at least 10 years from the ODP instance startup. + * + * Timer tick value increments with a constant, timer pool specific frequency. Tick frequency may + * be equal or higher than the requested timer pool resolution. The frequency can be checked with + * odp_timer_pool_info(). Tick value increments with implementation specific step sizes. + * + * Use odp_timer_sample_ticks() to determine offset between tick values of two or more timer pools. + * + * @param timer_pool Timer pool * * @return Current time in timer ticks + * + * @see odp_timer_tick_info_t */ -uint64_t odp_timer_current_tick(odp_timer_pool_t tpid); +uint64_t odp_timer_current_tick(odp_timer_pool_t timer_pool); /** - * ODP timer pool information and configuration + * Sample tick values of timer pools + * + * Reads timer pool tick values simultaneously (or closely back-to-back) from all requested timer + * pools, and outputs those on success. Optionally, outputs corresponding source clock (HW) counter + * values, which are implementation specific and may be used for debugging. When a timer pool does + * not support reading of the source clock value, zero is written instead. Values are written into + * the output arrays in the same order which timer pools were defined. Nothing is written on + * failure. + * + * @param timer_pool Timer pools to sample + * @param[out] tick Tick value array for output (one element per timer pool) + * @param[out] clk_count Source clock counter value array for output (one element per + * timer pool), or NULL when counter values are not requested. + * @param num Number of timer pools to sample + * + * @retval 0 All requested timer pools sampled successfully + * @retval -1 Failure */ - -typedef struct { - odp_timer_pool_param_t param; /**< Parameters specified at creation */ - uint32_t cur_timers; /**< Number of currently allocated timers */ - uint32_t hwm_timers; /**< High watermark of allocated timers */ - const char *name; /**< Name of timer pool */ -} odp_timer_pool_info_t; +int odp_timer_sample_ticks(odp_timer_pool_t timer_pool[], uint64_t tick[], uint64_t clk_count[], + int num); /** * Query timer pool configuration and current state * - * @param tpid Timer pool identifier - * @param[out] info Pointer to information buffer + * @param timer_pool Timer pool + * @param[out] info Pointer to information buffer * * @retval 0 on success * @retval <0 on failure. Info could not be retrieved. */ -int odp_timer_pool_info(odp_timer_pool_t tpid, +int odp_timer_pool_info(odp_timer_pool_t timer_pool, odp_timer_pool_info_t *info); /** * Allocate a timer * - * Create a timer (allocating all necessary resources e.g. timeout event) from - * the timer pool. The user_ptr is copied to timeouts and can be retrieved - * using the odp_timeout_user_ptr() call. + * Allocates a timer from the timer pool. Depending on timer type, the allocated timer is started + * with either odp_timer_start() or odp_timer_periodic_start() call. A timer may be reused multiple + * times before freeing it back into the timer pool. + * + * When timer expires, the timeout event defined in timer start parameters (see + * odp_timer_start_t::tmo_ev or odp_timer_periodic_start_t::tmo_ev) is sent into the provided + * destination queue. * - * @param tpid Timer pool identifier - * @param queue Destination queue for timeout notifications - * @param user_ptr User defined pointer or NULL to be copied to timeouts + * The provided user pointer value is copied into timeout events when the event type is + * ODP_EVENT_TIMEOUT. The value can be retrieved from an event with odp_timeout_user_ptr() call. + * + * @param timer_pool Timer pool + * @param queue Destination queue for timeout events + * @param user_ptr User defined pointer value or NULL * * @return Timer handle on success - * @retval ODP_TIMER_INVALID on failure and errno set. + * @retval ODP_TIMER_INVALID on failure */ -odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid, - odp_queue_t queue, - void *user_ptr); +odp_timer_t odp_timer_alloc(odp_timer_pool_t timer_pool, odp_queue_t queue, const void *user_ptr); /** * Free a timer * - * Free (destroy) a timer, reclaiming associated resources. - * The timeout event for an active timer will be returned. - * The timeout event for an expired timer will not be returned. It is the - * responsibility of the application to handle this timeout when it is received. + * Frees a previously allocated timer. The timer must be inactive when calling this function. + * In other words, the application must cancel an active single shot timer (odp_timer_cancel()) + * successfully or wait it to expire before freeing it. Similarly for an active periodic timer, the + * application must cancel it (odp_timer_periodic_cancel()) and receive the last event from + * the timer (odp_timer_periodic_ack()) before freeing it. + * + * The call returns failure only on non-recoverable errors. Application must not use the timer + * handle anymore after the call, regardless of the return value. * - * @param tim Timer handle - * @return Event handle of timeout event - * @retval ODP_EVENT_INVALID on failure + * @param timer Timer + * + * @retval 0 on success + * @retval <0 on failure */ -odp_event_t odp_timer_free(odp_timer_t tim); +int odp_timer_free(odp_timer_t timer); /** - * Set a timer (absolute time) with a user-provided timeout event + * Start a timer * - * Set (arm) the timer to expire at specific time. The timeout - * event will be enqueued when the timer expires. + * Starts a timer with an expiration time and a timeout event. The timer must not be active when + * calling this function. After a successful call, the timer remains active until it expires or + * is cancelled successfully. An active timer can be restarted with odp_timer_restart(). * - * @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 - * timeout event or NULL to reuse the existing timeout event. Any existing - * timeout event that is replaced by a successful set operation will be - * returned here. + * The timeout event is sent to the destination queue when the timer expires. The expiration time + * may be passed as absolute timer ticks or ticks relative to the current time. Use 'tick_type' + * parameter to select between the tick types. Current time of the timer pool can be read with + * odp_timer_current_tick(). * - * @retval ODP_TIMER_SUCCESS Operation succeeded - * @retval ODP_TIMER_TOOEARLY Operation failed because expiration tick too - * early - * @retval ODP_TIMER_TOOLATE Operation failed because expiration tick too - * late - * @retval ODP_TIMER_NOEVENT Operation failed because timeout event not - * specified in odp_timer_set call and not present in timer + * The timer is not started when a failure is returned. + * + * @param timer Timer to be started + * @param start_param Timer start parameters + * + * @retval ODP_TIMER_SUCCESS Success + * @retval ODP_TIMER_TOO_NEAR Failure. The expiration time passed already, or is too near to + * the current time. + * @retval ODP_TIMER_TOO_FAR Failure. The expiration time is too far from the current time. + * @retval ODP_TIMER_FAIL Other failure. */ -int odp_timer_set_abs(odp_timer_t tim, - uint64_t abs_tck, - odp_event_t *tmo_ev); +int odp_timer_start(odp_timer_t timer, const odp_timer_start_t *start_param); /** - * Set a timer with a relative expiration time and user-provided event. + * Restart a timer + * + * A successful restart call updates the expiration time of an active timer. The timeout event + * is not changed. + * + * The timer is not modified when a failure is returned. The call returns #ODP_TIMER_FAIL if + * the timer has expired already, or is so close to expire that it cannot be restarted anymore. + * A failure is returned also when the new expiration time is too near to the current time + * (#ODP_TIMER_TOO_NEAR) or too far from the current time (#ODP_TIMER_TOO_FAR). * - * Set (arm) the timer to expire at a relative future time. + * The new expiration time is passed the same way as with odp_timer_start() call. * - * @param tim Timer - * @param rel_tck Expiration time in timer ticks relative to current time of - * the timer pool the timer belongs to - * @param[in,out] tmo_ev Reference to an event variable that points to - * timeout event or NULL to reuse the existing timeout event. Any existing - * timeout event that is replaced by a successful set operation will be - * returned here. + * @param timer Timer to be restarted + * @param start_param Timer start parameters. Value of 'tmo_ev' parameter is ignored. * - * @retval ODP_TIMER_SUCCESS Operation succeeded - * @retval ODP_TIMER_TOOEARLY Operation failed because expiration tick too - * early - * @retval ODP_TIMER_TOOLATE Operation failed because expiration tick too - * late - * @retval ODP_TIMER_NOEVENT Operation failed because timeout event not - * specified in call and not present in timer + * @retval ODP_TIMER_SUCCESS Success + * @retval ODP_TIMER_TOO_NEAR Failure. The new expiration time passed already, or is too near to + * the current time. + * @retval ODP_TIMER_TOO_FAR Failure. The new expiration time is too far from the current time. + * @retval ODP_TIMER_FAIL Failure. The timer expired already, or other failure. */ -int odp_timer_set_rel(odp_timer_t tim, - uint64_t rel_tck, - odp_event_t *tmo_ev); +int odp_timer_restart(odp_timer_t timer, const odp_timer_start_t *start_param); + +/** + * Start a periodic timer + * + * Starts a timer that delivers timeout events periodically to the destination queue starting + * from the first expiration time provided. The timer must have been allocated from a pool of + * periodic timers. The timer must not be active when calling this function. After a successful + * call, the timer remains active until it is cancelled and all its timeout events have been + * acknowledged. + * + * 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). + * + * Periodic timers cannot be restarted. If the period needs to be changed, the timer is first + * cancelled and then started again with new parameters. + * + * Application must acknowledge each timeout event with odp_timer_periodic_ack() call. The call + * should be made as soon as possible after receiving the event. + * + * The timer is not started when a failure is returned. + * + * @param timer Periodic timer to be started + * @param start_param Periodic timer start parameters + * + * @retval ODP_TIMER_SUCCESS Success + * @retval ODP_TIMER_TOO_NEAR Failure. The first expiration time passed already, or is too near to + * the current time. + * @retval ODP_TIMER_TOO_FAR Failure. The first expiration time is too far from the current time. + * @retval ODP_TIMER_FAIL Other failure. + * + * @see odp_timer_periodic_cancel() + */ +int odp_timer_periodic_start(odp_timer_t timer, const odp_timer_periodic_start_t *start_param); + +/** + * Acknowledge timeout from a periodic timer + * + * This call is valid only for periodic timers. Each timeout event from a periodic timer must be + * acknowledged with this call. Acknowledgment should be done as soon as possible after receiving + * the event. A late call may affect accuracy of the following period(s). However, a missing + * acknowledgment may not stop timeout event delivery to the destination queue, and thus the same + * event may appear in the destination queue multiple times (when application falls behind). + * + * Normally, the acknowledgment call returns zero on success and consumes the timeout event. + * 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. + * + * @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 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. + */ +int odp_timer_periodic_ack(odp_timer_t timer, odp_event_t tmo_ev); + +/** + * Cancel a periodic timer + * + * Cancel a previously started periodic timer. A successful operation stops timer expiration. + * The timer delivers remaining timeout event(s) into the destination queue. Note that these events + * may not arrive at the requested interval. Return value of odp_timer_periodic_ack() call + * will indicate the last timeout event from the timer. Application may free the timer and + * the timeout event only after receiving the last event. + * + * @param timer Timer + * + * @retval 0 Periodic timer expiration stopped. The timeout event will be received through + * the destination queue. + * @retval <0 Timer cancel failed. + */ +int odp_timer_periodic_cancel(odp_timer_t timer); /** * Cancel a timer * - * Cancel a timer, preventing future expiration and delivery. Return any - * present timeout event. + * Cancels a previously started single shot timer. A successful operation (#ODP_TIMER_SUCCESS) + * prevents timer expiration and returns the timeout event back to application. Application may + * use or free the event normally. + * + * When the timer is close to expire or has expired already, the call may not be able cancel it + * anymore. In this case, the call returns #ODP_TIMER_TOO_NEAR and the timeout is delivered to + * the destination queue. * - * A timer that has already expired may be impossible to cancel and the timeout - * will instead be delivered to the destination queue. + * @param timer Timer + * @param[out] tmo_ev Pointer to an event handle for output. Event handle is written only + * on success. * - * @param tim Timer - * @param[out] tmo_ev Pointer to an event variable - * @retval 0 Success, active timer cancelled, timeout returned in '*tmo_ev' - * @retval <0 on failure (timer inactive or already expired) + * @retval ODP_TIMER_SUCCESS Timer was cancelled successfully. Timeout event returned in 'tmo_ev'. + * @retval ODP_TIMER_TOO_NEAR Timer cannot be cancelled. Timer has expired already, or cannot be + * cancelled due to close expiration time. + * @retval ODP_TIMER_FAIL Other failure. */ -int odp_timer_cancel(odp_timer_t tim, odp_event_t *tmo_ev); +int odp_timer_cancel(odp_timer_t timer, odp_event_t *tmo_ev); /** - * Return timeout handle that is associated with timeout event + * Get timeout handle from a ODP_EVENT_TIMEOUT type event * * @param ev An event of type ODP_EVENT_TIMEOUT * @@ -303,6 +450,17 @@ int odp_timer_cancel(odp_timer_t tim, odp_event_t *tmo_ev); odp_timeout_t odp_timeout_from_event(odp_event_t ev); /** + * Convert multiple timeout events to timeout handles + * + * All events must be of type ODP_EVENT_TIMEOUT. + * + * @param[out] tmo Timeout handle array for output + * @param ev Array of event handles to convert + * @param num Number of timeouts and events + */ +void odp_timeout_from_event_multi(odp_timeout_t tmo[], const odp_event_t ev[], int num); + +/** * Convert timeout handle to event handle * * @param tmo Timeout handle @@ -313,14 +471,17 @@ odp_event_t odp_timeout_to_event(odp_timeout_t tmo); /** * Check for fresh timeout + * * If the corresponding timer has been reset or cancelled since this timeout * was enqueued, the timeout is stale (not fresh). * * @param tmo Timeout handle * @retval 1 Timeout is fresh * @retval 0 Timeout is stale + * + * @deprecated The function will be removed in a future API version. */ -int odp_timeout_fresh(odp_timeout_t tmo); +int ODP_DEPRECATE(odp_timeout_fresh)(odp_timeout_t tmo); /** * Return timer handle for the timeout @@ -332,7 +493,15 @@ int odp_timeout_fresh(odp_timeout_t tmo); odp_timer_t odp_timeout_timer(odp_timeout_t tmo); /** - * Return expiration tick for the timeout + * Timeout expiration tick + * + * Returns the absolute expiration time (in timer ticks) that was used to set + * (or reset) the timer. For timers set with absolute expiration time this + * equals the provided tick value. + * + * For periodic timers, returns the expiration time of the period, or zero. + * When periodic timer implementation cannot return expiration time, it returns zero + * for all timeouts from the timer pool. * * @param tmo Timeout handle * @@ -342,6 +511,7 @@ 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. * * @param tmo Timeout handle @@ -351,6 +521,19 @@ uint64_t odp_timeout_tick(odp_timeout_t tmo); void *odp_timeout_user_ptr(odp_timeout_t tmo); /** + * Timeout user area + * + * Returns pointer to the user area associated with the timeout. Size of the area is fixed + * and defined in timeout pool parameters. + * + * @param tmo Timeout handle + * + * @return Pointer to the user area of the timeout + * @retval NULL The timeout does not have user area + */ +void *odp_timeout_user_area(odp_timeout_t tmo); + +/** * Timeout alloc * * Allocates timeout from pool. Pool must be created with ODP_POOL_TIMEOUT type. @@ -363,6 +546,20 @@ void *odp_timeout_user_ptr(odp_timeout_t tmo); odp_timeout_t odp_timeout_alloc(odp_pool_t pool); /** + * Allocate multiple timeouts + * + * Otherwise like odp_timeout_alloc(), but allocates multiple timeouts from a pool. + * + * @param pool Pool handle + * @param[out] tmo Array of timeout handles for output + * @param num Number of timeouts to allocate + * + * @return Number of timeouts actually allocated (0 ... num) + * @retval <0 on failure + */ +int odp_timeout_alloc_multi(odp_pool_t pool, odp_timeout_t tmo[], int num); + +/** * Timeout free * * Frees the timeout back to the pool it was allocated from. @@ -372,43 +569,83 @@ odp_timeout_t odp_timeout_alloc(odp_pool_t pool); void odp_timeout_free(odp_timeout_t tmo); /** + * Free multiple timeouts + * + * Otherwise like odp_timeout_free(), but frees multiple timeouts to their originating pools. + * + * @param tmo Array of timeout handles + * @param num Number of timeouts to free + */ +void odp_timeout_free_multi(odp_timeout_t tmo[], int num); + +/** + * Print timer pool debug information + * + * Prints implementation specific debug information about + * the timer pool to the ODP log. + * + * @param timer_pool Timer pool handle + */ +void odp_timer_pool_print(odp_timer_pool_t timer_pool); + +/** + * Print timer debug information + * + * Prints implementation specific debug information about + * the timer to the ODP log. + * + * @param timer Timer handle + */ +void odp_timer_print(odp_timer_t timer); + +/** + * Print timeout debug information + * + * Prints implementation specific debug information about + * the timeout to the ODP log. + * + * @param tmo Timeout handle + */ +void odp_timeout_print(odp_timeout_t tmo); + +/** * Get printable value for an odp_timer_pool_t * - * @param hdl odp_timer_pool_t handle to be printed - * @return uint64_t value that can be used to print/display this - * handle + * @param timer_pool odp_timer_pool_t handle to be printed + * + * @return uint64_t value that can be used to print/display this handle * * @note This routine is intended to be used for diagnostic purposes * to enable applications to generate a printable value that represents * an odp_timer_pool_t handle. */ -uint64_t odp_timer_pool_to_u64(odp_timer_pool_t hdl); +uint64_t odp_timer_pool_to_u64(odp_timer_pool_t timer_pool); /** * Get printable value for an odp_timer_t * - * @param hdl odp_timer_t handle to be printed - * @return uint64_t value that can be used to print/display this - * handle + * @param timer odp_timer_t handle to be printed + * + * @return uint64_t value that can be used to print/display this handle * * @note This routine is intended to be used for diagnostic purposes * to enable applications to generate a printable value that represents * an odp_timer_t handle. */ -uint64_t odp_timer_to_u64(odp_timer_t hdl); +uint64_t odp_timer_to_u64(odp_timer_t timer); /** * Get printable value for an odp_timeout_t * - * @param hdl odp_timeout_t handle to be printed - * @return uint64_t value that can be used to print/display this - * handle + * @param tmo odp_timeout_t handle to be printed + * + * @return uint64_t value that can be used to print/display this handle * * @note This routine is intended to be used for diagnostic purposes * to enable applications to generate a printable value that represents * an odp_timeout_t handle. */ -uint64_t odp_timeout_to_u64(odp_timeout_t hdl); +uint64_t odp_timeout_to_u64(odp_timeout_t tmo); /** * @} |