Signed-off-by: Ivan Khoronzhuk <ivan.khoronz...@linaro.org> --- doc/users-guide/users-guide.adoc | 49 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 5 deletions(-)
diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index ea5e6aa..108b1c8 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -334,11 +334,50 @@ The +odp_time_t+ opaque type represents local or global timestamps. === Timer Timers are how ODP applications measure and respond to the passage of time. -Timers are drawn from specialized pools called timer pools that have their -own abstract type (+odp_timer_pool_t+). Applications may have many timers -active at the same time and can set them to use either relative or absolute -time. When timers expire they create events of type +odp_timeout_t+, which -serve as notifications of timer expiration. +The timer API is supposed to be used when time synchronization with events is +needed and has different nature than time API has. Timers are drawn from +specialized pools called timer pools that have their own abstract type +(+odp_timer_pool_t+). Applications may have many timers active at the same +time and can set them to use either relative or absolute time. When timers +expire they create events of type +odp_timeout_t+, which serve as notifications +of timer expiration. The event is placed on a queue pointed while timer +allocation. + +Each timer pool can be set with it's own resolution in ns and number of +supported timers. So, timer pool can be considered as time source with +it's own resolution and defined number of timers. All timers in timer pool +are handed with same time source with same resolution. If user needs two types +of timers with different requirements for resolution then better to create +two pools with it's own resolution, it can decrease load on hardware. + +An expiration time for the timer is set in it's own ticks, so nanoseconds have +to be converted first with conversation function +odp_timer_ns_to_tick()+, to +convert it back to ns use +odp_timer_tick_to_ns()+. Both functions require +to pass a timer pool used, as it can be sourced with it's own time source that +can have specific resolution. + +To set a timer to deliver a timeout event the two functions can be used: ++odp_timer_set_abs()+ and +odp_timer_set_rel()+. Both of them require an +event to be passed and a time interval in ticks of corresponding timer pool. +The expiration time for a timer can be set based on current tick value for +a timer pool taken with +odp_timer_current_tick()+, to set a timer +(absolute time) with a user-provided timeout event, the +odp_timer_set_abs()+ +can be used. An event is the event converted from timeout allocated from timeout +pool with +odp_timeout_alloc()+. The event is returned to timer queue when set +time interval has expired and can be also converted to timeout with ++odp_timeout_from_event()+, if it's needed. To free timeout the ++odp_timeout_free()+ can be used, if it's presented as event it can be freed +as event with +odp_event_free()+. + +In general, timer pool characterizes time source, and timer is characterized +with timer pool, user pointer and destination queue for delivering. The timeout +is characterized with timer, timer pool and time of expiration and is placed to +queue set while timer allocation. The timeout can be delivered only to the +destination queue of concrete timer. To get timer generated the timeout the ++odp_timeout_timer()+ can be used. + +When timer is freed it's returned to timer pool and is ready to be allocated +once again. A timer can be canceled with odp_timer_cancel. === Synchronizer Multiple threads operating in parallel typically require various -- 1.9.1 _______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org https://lists.linaro.org/mailman/listinfo/lng-odp