--- /dev/null
+.. BSD LICENSE
+ Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in
+ the documentation and/or other materials provided with the
+ distribution.
+ * Neither the name of Intel Corporation nor the names of its
+ contributors may be used to endorse or promote products derived
+ from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+.. _Timer_Library:
+
+Timer Library
+=============
+
+The Timer library provides a timer service to DPDK execution units to enable execution of callback functions asynchronously.
+Features of the library are:
+
+* Timers can be periodic (multi-shot) or single (one-shot).
+
+* Timers can be loaded from one core and executed on another. It has to be specified in the call to rte_timer_reset().
+
+* Timers provide high precision (depends on the call frequency to rte_timer_manage() that checks timer expiration for the local core).
+
+* If not required in the application, timers can be disabled at compilation time by not calling the rte_timer_manage() to increase performance.
+
+The timer library uses the rte_get_timer_cycles() function that uses the High Precision Event Timer (HPET)
+or the CPUs Time Stamp Counter (TSC) to provide a reliable time reference.
+
+This library provides an interface to add, delete and restart a timer. The API is based on BSD callout() with a few differences.
+Refer to the `callout manual <http://www.daemon-systems.org/man/callout.9.html>`_.
+
+Implementation Details
+----------------------
+
+Timers are tracked on a per-lcore basis,
+with all pending timers for a core being maintained in order of timer expiry in a skiplist data structure.
+The skiplist used has ten levels and each entry in the table appears in each level with probability ΒΌ^level.
+This means that all entries are present in level 0, 1 in every 4 entries is present at level 1,
+one in every 16 at level 2 and so on up to level 9.
+This means that adding and removing entries from the timer list for a core can be done in log(n) time,
+up to 4^10 entries, that is, approximately 1,000,000 timers per lcore.
+
+A timer structure contains a special field called status,
+which is a union of a timer state (stopped, pending, running, config) and an owner (lcore id).
+Depending on the timer state, we know if a timer is present in a list or not:
+
+* STOPPED: no owner, not in a list
+
+* CONFIG: owned by a core, must not be modified by another core, maybe in a list or not, depending on previous state
+
+* PENDING: owned by a core, present in a list
+
+* RUNNING: owned by a core, must not be modified by another core, present in a list
+
+Resetting or stopping a timer while it is in a CONFIG or RUNNING state is not allowed.
+When modifying the state of a timer,
+a Compare And Swap instruction should be used to guarantee that the status (state+owner) is modified atomically.
+
+Inside the rte_timer_manage() function,
+the skiplist is used as a regular list by iterating along the level 0 list, which contains all timer entries,
+until an entry which has not yet expired has been encountered.
+To improve performance in the case where there are entries in the timer list but none of those timers have yet expired,
+the expiry time of the first list entry is maintained within the per-core timer list structure itself.
+On 64-bit platforms, this value can be checked without the need to take a lock on the overall structure.
+(Since expiry times are maintained as 64-bit values,
+a check on the value cannot be done on 32-bit platforms without using either a compare-and-swap (CAS) instruction or using a lock,
+so this additional check is skipped in favor of checking as normal once the lock has been taken.)
+On both 64-bit and 32-bit platforms,
+a call to rte_timer_manage() returns without taking a lock in the case where the timer list for the calling core is empty.
+
+Use Cases
+---------
+
+The timer library is used for periodic calls, such as garbage collectors, or some state machines (ARP, bridging, and so on).
+
+References
+----------
+
+* `callout manual <http://www.daemon-systems.org/man/callout.9.html>`_
+ - The callout facility that provides timers with a mechanism to execute a function at a given time.
+
+* `HPET <http://en.wikipedia.org/wiki/HPET>`_
+ - Information about the High Precision Event Timer (HPET).
Code Review / deb_dpdk.git / blobdiff