1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2014 Intel Corporation. 3 4.. _Timer_Library: 5 6Timer Library 7============= 8 9The Timer library provides a timer service to DPDK execution units to enable execution of callback functions asynchronously. 10Features of the library are: 11 12* Timers can be periodic (multi-shot) or single (one-shot). 13 14* Timers can be loaded from one core and executed on another. It has to be specified in the call to rte_timer_reset(). 15 16* Timers provide high precision (depends on the call frequency to rte_timer_manage() that checks timer expiration for the local core). 17 18* If not required in the application, timers can be disabled at compilation time by not calling the rte_timer_manage() to increase performance. 19 20The timer library uses the rte_get_timer_cycles() function that uses the High Precision Event Timer (HPET) 21or the CPUs Time Stamp Counter (TSC) to provide a reliable time reference. 22 23This library provides an interface to add, delete and restart a timer. The API is based on BSD callout() with a few differences. 24Refer to the `callout manual <http://www.daemon-systems.org/man/callout.9.html>`_. 25 26Implementation Details 27---------------------- 28 29Timers are tracked on a per-lcore basis, 30with all pending timers for a core being maintained in order of timer expiry in a skiplist data structure. 31The skiplist used has ten levels and each entry in the table appears in each level with probability ¼^level. 32This means that all entries are present in level 0, 1 in every 4 entries is present at level 1, 33one in every 16 at level 2 and so on up to level 9. 34This means that adding and removing entries from the timer list for a core can be done in log(n) time, 35up to 4^10 entries, that is, approximately 1,000,000 timers per lcore. 36 37A timer structure contains a special field called status, 38which is a union of a timer state (stopped, pending, running, config) and an owner (lcore id). 39Depending on the timer state, we know if a timer is present in a list or not: 40 41* STOPPED: no owner, not in a list 42 43* CONFIG: owned by a core, must not be modified by another core, maybe in a list or not, depending on previous state 44 45* PENDING: owned by a core, present in a list 46 47* RUNNING: owned by a core, must not be modified by another core, present in a list 48 49Resetting or stopping a timer while it is in a CONFIG or RUNNING state is not allowed. 50When modifying the state of a timer, 51a Compare And Swap instruction should be used to guarantee that the status (state+owner) is modified atomically. 52 53Inside the rte_timer_manage() function, 54the skiplist is used as a regular list by iterating along the level 0 list, which contains all timer entries, 55until an entry which has not yet expired has been encountered. 56To improve performance in the case where there are entries in the timer list but none of those timers have yet expired, 57the expiry time of the first list entry is maintained within the per-core timer list structure itself. 58On 64-bit platforms, this value can be checked without the need to take a lock on the overall structure. 59(Since expiry times are maintained as 64-bit values, 60a check on the value cannot be done on 32-bit platforms without using either a compare-and-swap (CAS) instruction or using a lock, 61so this additional check is skipped in favor of checking as normal once the lock has been taken.) 62On both 64-bit and 32-bit platforms, 63a call to rte_timer_manage() returns without taking a lock in the case where the timer list for the calling core is empty. 64 65Use Cases 66--------- 67 68The timer library is used for periodic calls, such as garbage collectors, or some state machines (ARP, bridging, and so on). 69 70References 71---------- 72 73* `callout manual <http://www.daemon-systems.org/man/callout.9.html>`_ 74 - The callout facility that provides timers with a mechanism to execute a function at a given time. 75 76* `HPET <http://en.wikipedia.org/wiki/HPET>`_ 77 - Information about the High Precision Event Timer (HPET). 78