@@ -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
Signed-off-by: Ivan Khoronzhuk <ivan.khoronzhuk@linaro.org> --- doc/users-guide/users-guide.adoc | 49 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 5 deletions(-)