Some of the NPU class of networking hardwares has timer hardware where the user
can arm and cancel the event timer. On the expiry of the timeout time, the
hardware will post the notification as an event to eventdev HW, Instead of
calling a callback like CPU based timer scheme. It enables, high resolution
(1us or so) timer management using internal or external clock domains, and
offloading the timer housing keeping work from the worker lcores.
This RFC attempts to abstract such NPU class of timer Hardware and introduce
event timer wheel subsystem inside the eventdev as they are tightly coupled.
This RFC introduces the functionality to create an event timer wheel. This
allows an application to arm event timers, which shall enqueue an event to a
specified event queue on expiry of a given interval.
The event timer wheel uses an ops table to which the various event devices
(e.g Cavium Octeontx, NXP dpaa2 and SW) register timer subsystem implementation
specific ops to use.
The RFC extends DPDK event based programming model where event can be of type
timer, and expiry event will be notified through CPU over eventdev ports.
Some of the use cases of event timer wheel are Beacon Timers,
Generic SW Timeout, Wireless MAC Scheduling, 3G Frame Protocols,
Packet Scheduling, Protocol Retransmission Timers, Supervision Timers.
All these use cases require high resolution and low time drift.
Signed-off-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
Signed-off-by: Pavan Nikhilesh <pbhagavatula@caviumnetworks.com>
---
doc/api/doxy-api-index.md | 3 +-
lib/librte_eventdev/Makefile | 1 +
lib/librte_eventdev/rte_event_timer_wheel.h | 493 ++++++++++++++++++++++++++++
lib/librte_eventdev/rte_eventdev.h | 4 +-
4 files changed, 498 insertions(+), 3 deletions(-)
create mode 100644 lib/librte_eventdev/rte_event_timer_wheel.h
@@ -55,7 +55,8 @@ The public API headers are grouped by topics:
[KNI] (@ref rte_kni.h),
[ixgbe] (@ref rte_pmd_ixgbe.h),
[i40e] (@ref rte_pmd_i40e.h),
- [crypto_scheduler] (@ref rte_cryptodev_scheduler.h)
+ [crypto_scheduler] (@ref rte_cryptodev_scheduler.h),
+ [event_timerwheel] (@ref rte_event_timer_wheel.h)
- **memory**:
[memseg] (@ref rte_memory.h),
@@ -50,6 +50,7 @@ SYMLINK-y-include += rte_eventdev_pmd.h
SYMLINK-y-include += rte_eventdev_pmd_pci.h
SYMLINK-y-include += rte_eventdev_pmd_vdev.h
SYMLINK-y-include += rte_event_ring.h
+SYMLINK-y-include += rte_event_timer_wheel.h
# versioning export map
EXPORT_MAP := rte_eventdev_version.map
new file mode 100644
@@ -0,0 +1,493 @@
+/*
+ * BSD LICENSE
+ *
+ * Copyright 2017 Cavium, Inc.
+ *
+ * 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 Cavium, Inc 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.
+ */
+
+#ifndef _RTE_EVENT_TIMER_WHEEL_H_
+#define _RTE_EVENT_TIMER_WHEEL_H_
+
+/**
+ * @file
+ *
+ * RTE event timer wheel
+ *
+ * The abstract working model of an event timer wheel is as follows:
+ *
+ * timer_tick_ns
+ * +
+ * +-------+ |
+ * | | |
+ * +-------+ bkt 0 +----v---+
+ * | | | |
+ * | +-------+ |
+ * +---+---+ +---+---+ +---+---+---+---+
+ * | | | | | | | | |
+ * | bkt n | | bkt 1 |<-> t0| t1| t2| tn|
+ * | | | | | | | | |
+ * +---+---+ +---+---+ +---+---+---+---+
+ * | Timer wheel |
+ * +---+---+ +---+---+
+ * | | | |
+ * | bkt 4 | | bkt 2 |<--- Current bucket
+ * | | | |
+ * +---+---+ +---+---+
+ * | +-------+ |
+ * | | | |
+ * +------+ bkt 3 +-------+
+ * | |
+ * +-------+
+ *
+ * - It has a virtual monotonically increasing 64-bit timer wheel clock based on
+ * *enum rte_event_timer_wheel_clk_src* clock source. The clock source could
+ * be a CPU clock, or a platform depended external clock.
+ *
+ * - Application creates a timer wheel instance with given clock source,
+ * the total number of event timers, resolution(expressed in ns) to traverse
+ * between the buckets.
+ *
+ * - Each timer wheel may have 0 to n buckets based on the configured
+ * max timeout(max_tmo_ns) and resolution(timer_tick_ns). On timer wheel
+ * start, the timer starts ticking at *timer_tick_ns* resolution.
+ *
+ * - Application arms an event timer to be expired at the number of
+ * *timer_tick_ns* from now.
+ *
+ * - Application can cancel the existing armed timer if required.
+ *
+ * - If not canceled by the application and the timer expires then the library
+ * injects the timer expiry event to the designated event queue.
+ *
+ * - The timer expiry event will be received through *rte_event_dequeue_burst*
+ *
+ * - Application frees the created timer wheel instance.
+ *
+ * Multiple timer wheels can be created with a varying level of resolution
+ * for various expiry use cases that run in parallel.
+ *
+ * Before using the timer wheel, the application has to create and configure
+ * an event device along with the event ports. Based on the event device
+ * capability it might require creating an additional event port to be used
+ * by the timer wheel.
+ *
+ * The application creates the event timer wheel using the
+ * ``rte_event_timer_wheel_create()``. The event device id is passed to this
+ * function, inside this function the event device capability is checked,
+ * and if an in-built port is absent the application uses the <default>
+ * function to create a new producer port.
+ *
+ * The application may also use the function
+ * ``rte_event_timer_wheel_create_ext()`` to have granular control over producer
+ * port creation in a case where the in-built port is absent.
+ *
+ * After creating the timer wheel, the application has to start it
+ * using ``rte_event_timer_wheel_start()``. The buckets are traversed from
+ * 0 to n, the list per each bucket is processed, and the expired timer events
+ * are sent to the designated event queue.
+ *
+ * The application can arm one or more event timers using the
+ * ``rte_event_timer_arm_burst()``. The *timeout_ticks* represents the number
+ * of *timer_tick_ns* after which the timer has to expire. The timeout at
+ * which the timers expire can be grouped or be independent of each
+ * event timer instance. ``rte_event_timer_arm_tmo_tick_burst()`` address the
+ * former case and ``rte_event_timer_arm_burst()`` address the latter case.
+ *
+ * The application can cancel the timers from expiring using the
+ * ``rte_event_timer_cancel_burst()``.
+ *
+ * On the secondary process, ``rte_event_timer_wheel_lookup()`` can be used to
+ * get the timer wheel pointer from its id and use it to invoke fastpath
+ * operations such as arm and cancel.
+ *
+ * Some of the use cases of event timer wheel are Beacon Timers,
+ * Generic SW Timeout, Wireless MAC Scheduling, 3G Frame Protocols,
+ * Packet Scheduling, Protocol Retransmission Timers, Supervision Timers.
+ * All these use cases require high resolution and low time drift.
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <rte_eventdev.h>
+
+/**
+ * Timer wheel clock source.
+ */
+enum rte_event_timer_wheel_clk_src {
+ RTE_EVENT_TIMER_WHEEL_CPU_CLK,
+ /**< Use CPU clock as the clock source. */
+ RTE_EVENT_TIMER_WHEEL_EXT_CLK0,
+ /**< Platform dependent external clock source 0. */
+ RTE_EVENT_TIMER_WHEEL_EXT_CLK1,
+ /**< Platform dependent external clock source 1. */
+ RTE_EVENT_TIMER_WHEEL_EXT_CLK2,
+ /**< Platform dependent external clock source 2. */
+ RTE_EVENT_TIMER_WHEEL_EXT_CLK3,
+ /**< Platform dependent external clock source 3. */
+};
+
+#define RTE_EVENT_TIMER_WHEEL_F_ADJUST_RES (1ULL << 0)
+/**< The event timer wheel implementation may have constraints on the wheel
+ * resolution(timer_tick_ns) and maximum timer expiry timeout(max_tmo_ns)
+ * based on the given event timer wheel or system.
+ * If this flag is set, implementation adjusts the wheel resolution and
+ * maximum timeout to the best possible configuration.
+ * On successful timer wheel creation, the application can get the configured
+ * resolution and max timeout with ``rte_event_timer_wheel_get_info()``.
+ *
+ * @see struct rte_event_timer_wheel_conf::timer_wheel_flags
+ */
+#define RTE_EVENT_TIMER_WHEEL_F_SP_PUT (1ULL << 1)
+/**< ``rte_event_timer_arm_burst()`` API to be used in single producer mode.
+ *
+ * @see struct rte_event_timer_wheel_conf::timer_wheel_flags
+ */
+
+/**
+ * Timer wheel configuration structure.
+ */
+struct rte_event_timer_wheel_conf {
+ uint8_t event_dev_id;
+ /**< Event device identifier.*/
+ uint16_t timer_wheel_id;
+ /**< The event timer wheel identifier */
+ enum rte_event_timer_wheel_clk_src clk_src;
+ /**< Clock source for timer wheel. */
+ uint64_t timer_tick_ns;
+ /**< Timer wheel resolution in ns i.e interval between buckets.*/
+ uint64_t max_tmo_ns;
+ /**< Maximum timer timeout(expiry) in ns.*/
+ uint64_t nb_timers;
+ /**< Total number of timers per wheel.*/
+ uint32_t timer_wheel_flags;
+ /**< Timer wheel config flags(RTE_EVENT_TIMER_WHEEL_F_*).*/
+};
+
+struct rte_event_timer_wheel;
+
+/**
+ * Create an event timer wheel.
+ *
+ * This function must be invoked first before any other function in the API.
+ *
+ * @param conf
+ * The event timer wheel configuration structure.
+ *
+ * @return
+ * The pointer to the new allocated event timer wheel, on success.
+ * NULL on error with rte_errno set appropriately.
+ * Possible rte_errno values include:
+ * - ERANGE - timer_tick_ns is not in supported range.
+ */
+struct rte_event_timer_wheel *
+rte_event_timer_wheel_create(const struct rte_event_timer_wheel_conf *conf);
+
+/**
+ * Callback function type for producer port creation.
+ */
+typedef void (*rte_event_timer_wheel_port_conf_cb)(uint16_t id,
+ uint8_t event_dev_id, uint8_t *event_port_id,
+ void *conf_arg);
+
+/**
+ * Create an timer wheel with supplied callback.
+ *
+ * This function can be used to have a more granular control over the timer
+ * wheel creation, If an inbuilt port is absent then the function uses the
+ * callback provided to create and get the port id to be used as producer port.
+ *
+ *
+ * @param[out] wheel
+ * A pointer to the event timer wheel structure pointer.
+ * @param conf
+ * The timer wheel configuration structure.
+ * @param conf_cb
+ * The port config callback function.
+ * @param conf_arg
+ * Opaque pointer to the callback function.
+ *
+ * @return
+ * The pointer to the new allocated event timer wheel, on success.
+ * NULL on error with rte_errno set appropriately.
+ * Possible rte_errno values include:
+ * - ERANGE - timer_tick_ns is not in supported range.
+ */
+struct rte_event_timer_wheel *
+rte_event_timer_wheel_create_ext(const struct rte_event_timer_wheel_conf *conf,
+ rte_event_timer_wheel_port_conf_cb conf_cb, void *conf_arg);
+
+/**
+ * Timer wheel info structure.
+ */
+struct rte_event_timer_wheel_info {
+ uint64_t min_resoultion_ns;
+ /**< Minimum timer wheel resolution in ns.*/
+ uint64_t max_tmo_ns;
+ /**< Maximum timer timeout(expiry) in ns. */
+ struct rte_event_timer_wheel_conf wheel_conf;
+ /**< Configured timer wheel attributes. */
+};
+
+/**
+ * Retrieve the contextual information of an event timer wheel.
+ *
+ * @param wheel
+ * A pointer to the event timer wheel structure.
+ *
+ * @param[out] wheel_info
+ * A pointer to a structure of type *rte_event_timer_wheel_info* to be
+ * filled with the contextual information of the wheel.
+ *
+ * @return
+ * - 0: Success, driver updates the contextual information of the
+ * timer wheel
+ * - <0: Error code returned by the driver info get function.
+ *
+ * @see RTE_EVENT_TIMER_WHEEL_F_ADJUST_RES, struct rte_event_timer_wheel_info
+ *
+ */
+int
+rte_event_timer_wheel_get_info(const struct rte_event_timer_wheel *wheel,
+ struct rte_event_timer_wheel_info *wheel_info);
+
+/**
+ * Start an timer wheel.
+ *
+ * The wheel start step is the last one and consists of setting the timer
+ * wheel to start accepting the timers and schedules to event queues.
+ *
+ * On success, all basic functions exported by the API (timer arm,
+ * timer cancel and so on) can be invoked.
+ *
+ * @param wheel
+ * A pointer to the event timer wheel structure.
+ *
+ * @return
+ * - 0: Success, wheel started.
+ * - <0: Error code returned by the driver start function.
+ */
+int
+rte_event_timer_wheel_start(const struct rte_event_timer_wheel *wheel);
+
+/**
+ * Stop an event timer wheel.
+ *
+ * The wheel can be restarted with a call to ``rte_event_timer_wheel_start()``.
+ *
+ * @param wheel
+ * A pointer to the event timer wheel structure.
+ *
+ * @return
+ * - 0: Success, wheel stop.
+ * - <0: Error code returned by the driver stop function.
+ */
+int
+rte_event_timer_wheel_stop(const struct rte_event_timer_wheel *wheel);
+
+/**
+ * Free an event timer wheel.
+ *
+ * Destroy an event timer wheel, freeing all resources.
+ *
+ * Before invoking this function, the application must wait for all the armed
+ * timers to expire or cancel the outstanding armed timers.
+ *
+ * @param wheel
+ * A pointer to the event timer wheel structure.
+ *
+ * @return
+ * - 0 on successfully freed the event timer wheel resources.
+ * - <0 on failure to free an event timer wheel.
+ * - -EAGAIN if wheel is busy
+ */
+int
+rte_event_timer_wheel_free(const struct rte_event_timer_wheel *wheel);
+
+/**
+ * Search an event timer wheel from its id.
+ *
+ * @param timer_wheel_id
+ * The event timer wheel identifier.
+ *
+ * @return
+ * The pointer to the event timer wheel matching the id, or NULL if not found.
+ * NULL on error with rte_errno set appropriately.
+ * Possible rte_errno values include:
+ * - ENOENT - required entry not available to return.
+ */
+struct rte_event_timer_wheel *
+rte_event_timer_wheel_lookup(uint16_t timer_wheel_id);
+
+/**
+ * Event timer state.
+ */
+enum rte_event_timer_state {
+ RTE_EVENT_TIMER_NOT_ARMED = 0,
+ /**< Event timer is in not armed state.*/
+ RTE_EVENT_TIMER_SUCCESS_ARM = 1,
+ /**< Event timer successfully armed.*/
+ RTE_EVENT_TIMER_SUCCESS_CANCEL = 2,
+ /**< Event timer successfully canceled.*/
+ RTE_EVENT_TIMER_ERROR = -1,
+ /**< Generic event timer error.*/
+ RTE_EVENT_TIMER_ERROR_TOOEARLY = -2,
+ /**< Event timer timeout tick is too less to add to the wheel.*/
+ RTE_EVENT_TIMER_ERROR_TOOLATE = -3,
+ /**< Event timer timeout tick is greater than the maximum timeout.*/
+};
+
+/**
+ * The generic *rte_event_timer* structure to hold the event timer attributes
+ * for arm and cancel operations.
+ */
+RTE_STD_C11
+struct rte_event_timer {
+ struct rte_event ev;
+ /**<
+ * Expiry event attributes. On successful event timer timeout,following
+ * attributes will be used to inject the expiry event to eventdev.
+ * - event_queue_id: Targeted event queue id for expiry events.
+ * - event_priority: Event priority of the event expiry event in the
+ * event queue relative to other events.
+ * - sched_type: Scheduling type of the expiry event.
+ * - flow_id: Flow id of the expiry event.
+ * - op: RTE_EVENT_OP_NEW
+ * - event_type: RTE_EVENT_TYPE_TIMER
+ */
+ enum rte_event_timer_state state;
+ /**< State of the event timer.*/
+ uint64_t timeout_ticks;
+ /**< Expiry timer ticks expressed in number of *timer_ticks_ns* from
+ * now.
+ * @see struct rte_event_timer_wheel_info::wheel_conf::timer_tick_ns
+ */
+ uint64_t impl_opaque[2];
+ /**< Implementation specific opaque data.
+ * An event timer wheel implementation may use this field to hold
+ * implementation specific value to share between the arm and cancel
+ * operation. The application should not modify this field.
+ */
+ uint8_t user_meta[];
+ /**< Memory to store user specific metadata.
+ * The event timer wheel implementation should not modify this area.
+ */
+} __rte_cache_aligned;
+
+/**
+ * Arm a burst of event timers with separate expiration timeout tick for each
+ * event timer.
+ *
+ * Before calling this function, the application allocates
+ * ``struct rte_event_timer`` objects from mempool or huge page backed
+ * application buffers of interested size. On successful allocation,
+ * application updates the `struct rte_event_timer`` attributes such as
+ * expiry event attributes, timeout ticks from now.
+ * This function submits the event timer arm requests to the event timer wheel
+ * and on expiry, the events will be injected to designated event queue.
+ *
+ * @param wheel
+ * A pointer to the event timer wheel structure.
+ * @param tim
+ * Points to an array of objects of type *rte_event_timer* structure.
+ * @param nb_timers
+ * Number of event timers in the supplied array.
+ *
+ * @return
+ * The number of successfully armed event timers. The return value can be less
+ * than the value of the *nb_timers* parameter. If the return value is less
+ * than *nb_events*, the remaining event timers at the end of *tim*
+ * are not consumed, and the caller has to take care of them, and rte_errno
+ * is set accordingly. Possible errno values include:
+ * - -EINVAL Invalid timer wheel pointer, expiry event queue ID is invalid,
+ * or an expiry event's sched type doesn't match the capabilities of the
+ * destination event queue.
+ */
+int
+rte_event_timer_arm_burst(const struct rte_event_timer_wheel *wheel,
+ struct rte_event_timer **tim, const uint16_t nb_timers);
+
+/**
+ * Arm a burst of event timers with same expiration timeout tick.
+ *
+ * Provides the same functionality as ``rte_event_timer_arm_burst()``, expect
+ * that application can use this API when the all the event timers have the
+ * same timeout expiration tick. This specialized function can provide the
+ * additional hint to the wheel implementation and optimize if possible.
+ *
+ * @param wheel
+ * A pointer to the event timer wheel structure.
+ * @param tim
+ * Points to an array of objects of type *rte_event_timer* structure.
+ * @param nb_timers
+ * Number of event timers in the supplied array.
+ *
+ * @return
+ * The number of successfully armed event timers. The return value can be less
+ * than the value of the *nb_timers* parameter. If the return value is less
+ * than *nb_events*, the remaining event timers at the end of *tim*
+ * are not consumed, and the caller has to take care of them, and rte_errno
+ * is set accordingly. Possible errno values include:
+ * - -EINVAL Invalid timer wheel pointer, expiry event queue ID is invalid,
+ * or an expiry event's sched type doesn't match the capabilities of the
+ * destination event queue.
+ */
+int
+rte_event_timer_arm_tmo_tick_burst(const struct rte_event_timer_wheel *wheel,
+ struct rte_event_timer **tim, const uint64_t timeout_tick,
+ const uint16_t nb_timers);
+
+
+/**
+ * Cancel a burst of event timer from being scheduled to the event device.
+ *
+ * @param wheel
+ * A pointer to the event timer wheel structure.
+ * @param tim
+ * Points to an array of objects of type *rte_event_timer* structure
+ * @param nb_timers
+ * Number of event timer instances in the supplied array.
+ *
+ * @return
+ * The number of successfully canceled event timers. The return value can be
+ * less than the value of the *nb_timers* parameter. If the return value is
+ * less than *nb_events*, the remaining event timers at the end of *tim*
+ * are not consumed, and the caller has to take care of them, and rte_errno
+ * is set accordingly. Possible errno values include:
+ * - -EINVAL Invalid timer wheel pointer
+ */
+int
+rte_event_timer_cancel_burst(const struct rte_event_timer_wheel *wheel,
+ struct rte_event_timer **tim, const uint16_t nb_timers);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _RTE_EVENT_TIMER_WHEEL_H_ */
@@ -865,8 +865,8 @@ rte_event_dev_close(uint8_t dev_id);
/**< The event generated from ethdev subsystem */
#define RTE_EVENT_TYPE_CRYPTODEV 0x1
/**< The event generated from crypodev subsystem */
-#define RTE_EVENT_TYPE_TIMERDEV 0x2
-/**< The event generated from timerdev subsystem */
+#define RTE_EVENT_TYPE_TIMER 0x2
+/**< The event generated from event timer wheel */
#define RTE_EVENT_TYPE_CPU 0x3
/**< The event generated from cpu for pipelining.
* Application may use *sub_event_type* to further classify the event