X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=lib%2Flibrte_timer%2Frte_timer.h;h=c6b3d450df1f9b74adab5723028b8e5f81cf094a;hb=8d4659e70fc081ab220e44552af194900d720d2e;hp=a44bc90d95eda8227d67d50c94bb223c0dbdfbd7;hpb=af75078fece3615088e561357c1e97603e43a5fe;p=dpdk.git diff --git a/lib/librte_timer/rte_timer.h b/lib/librte_timer/rte_timer.h index a44bc90d95..c6b3d450df 100644 --- a/lib/librte_timer/rte_timer.h +++ b/lib/librte_timer/rte_timer.h @@ -1,36 +1,5 @@ -/*- - * BSD LICENSE - * - * Copyright(c) 2010-2012 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. - * - * version: DPDK.L.1.2.3-3 +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright(c) 2010-2014 Intel Corporation */ #ifndef _RTE_TIMER_H_ @@ -65,9 +34,12 @@ * design of this library. */ +#include #include #include -#include +#include +#include +#include #ifdef __cplusplus extern "C" { @@ -78,7 +50,7 @@ extern "C" { #define RTE_TIMER_RUNNING 2 /**< State: timer function is running. */ #define RTE_TIMER_CONFIG 3 /**< State: timer is being configured. */ -#define RTE_TIMER_NO_OWNER -1 /**< Timer has no owner. */ +#define RTE_TIMER_NO_OWNER -2 /**< Timer has no owner. */ /** * Timer type: Periodic or single (one-shot). @@ -93,6 +65,7 @@ enum rte_timer_type { * config) and an owner (the id of the lcore that owns the timer). */ union rte_timer_status { + RTE_STD_C11 struct { uint16_t state; /**< Stop, pending, running, config. */ int16_t owner; /**< The lcore that owns the timer. */ @@ -117,18 +90,20 @@ struct rte_timer; /** * Callback function type for timer expiry. */ -typedef void (rte_timer_cb_t)(struct rte_timer *, void *); +typedef void (*rte_timer_cb_t)(struct rte_timer *, void *); + +#define MAX_SKIPLIST_DEPTH 10 /** * A structure describing a timer in RTE. */ struct rte_timer { - LIST_ENTRY(rte_timer) next; /**< Next and prev in list. */ + uint64_t expire; /**< Time when timer expire. */ + struct rte_timer *sl_next[MAX_SKIPLIST_DEPTH]; volatile union rte_timer_status status; /**< Status of timer. */ uint64_t period; /**< Period of timer (0 if not periodic). */ - uint64_t expire; /**< Time when timer expire. */ - rte_timer_cb_t *f; /**< Callback function. */ + rte_timer_cb_t f; /**< Callback function. */ void *arg; /**< Argument to callback function. */ }; @@ -137,10 +112,10 @@ struct rte_timer /** * A C++ static initializer for a timer structure. */ -#define RTE_TIMER_INITIALIZER { \ - {0, 0}, \ - {{RTE_TIMER_STOP, RTE_TIMER_NO_OWNER}}, \ +#define RTE_TIMER_INITIALIZER { \ 0, \ + {NULL}, \ + {{RTE_TIMER_STOP, RTE_TIMER_NO_OWNER}}, \ 0, \ NULL, \ NULL, \ @@ -157,13 +132,64 @@ struct rte_timer } #endif +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Allocate a timer data instance in shared memory to track a set of pending + * timer lists. + * + * @param id_ptr + * Pointer to variable into which to write the identifier of the allocated + * timer data instance. + * + * @return + * - 0: Success + * - -ENOSPC: maximum number of timer data instances already allocated + */ +__rte_experimental +int rte_timer_data_alloc(uint32_t *id_ptr); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Deallocate a timer data instance. + * + * @param id + * Identifier of the timer data instance to deallocate. + * + * @return + * - 0: Success + * - -EINVAL: invalid timer data instance identifier + */ +__rte_experimental +int rte_timer_data_dealloc(uint32_t id); + /** * Initialize the timer library. * * Initializes internal variables (list, locks and so on) for the RTE * timer library. + * + * @note + * This function must be called in every process before using the library. + * + * @return + * - 0: Success + * - -ENOMEM: Unable to allocate memory needed to initialize timer + * subsystem + */ +int rte_timer_subsystem_init(void); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Free timer subsystem resources. */ -void rte_timer_subsystem_init(void); +__rte_experimental +void rte_timer_subsystem_finalize(void); /** * Initialize a timer handle. @@ -223,7 +249,6 @@ int rte_timer_reset(struct rte_timer *tim, uint64_t ticks, enum rte_timer_type type, unsigned tim_lcore, rte_timer_cb_t fct, void *arg); - /** * Loop until rte_timer_reset() succeeds. * @@ -280,7 +305,6 @@ rte_timer_reset_sync(struct rte_timer *tim, uint64_t ticks, */ int rte_timer_stop(struct rte_timer *tim); - /** * Loop until rte_timer_stop() succeeds. * @@ -307,23 +331,210 @@ void rte_timer_stop_sync(struct rte_timer *tim); */ int rte_timer_pending(struct rte_timer *tim); +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Time until the next timer on the current lcore + * This function gives the ticks until the next timer will be active. + * + * @return + * - -EINVAL: invalid timer data instance identifier + * - -ENOENT: no timer pending + * - 0: a timer is pending and will run at next rte_timer_manage() + * - >0: ticks until the next timer is ready + */ +__rte_experimental +int64_t rte_timer_next_ticks(void); + /** * Manage the timer list and execute callback functions. * - * This function must be called periodically from all cores + * This function must be called periodically from EAL lcores * main_loop(). It browses the list of pending timers and runs all * timers that are expired. * * The precision of the timer depends on the call frequency of this * function. However, the more often the function is called, the more * CPU resources it will use. + * + * @return + * - 0: Success + * - -EINVAL: timer subsystem not yet initialized */ -void rte_timer_manage(void); +int rte_timer_manage(void); /** * Dump statistics about timers. + * + * @param f + * A pointer to a file for output + * @return + * - 0: Success + * - -EINVAL: timer subsystem not yet initialized + */ +int rte_timer_dump_stats(FILE *f); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * This function is the same as rte_timer_reset(), except that it allows a + * caller to specify the rte_timer_data instance containing the list to which + * the timer should be added. + * + * @see rte_timer_reset() + * + * @param timer_data_id + * An identifier indicating which instance of timer data should be used for + * this operation. + * @param tim + * The timer handle. + * @param ticks + * The number of cycles (see rte_get_hpet_hz()) before the callback + * function is called. + * @param type + * The type can be either: + * - PERIODICAL: The timer is automatically reloaded after execution + * (returns to the PENDING state) + * - SINGLE: The timer is one-shot, that is, the timer goes to a + * STOPPED state after execution. + * @param tim_lcore + * The ID of the lcore where the timer callback function has to be + * executed. If tim_lcore is LCORE_ID_ANY, the timer library will + * launch it on a different core for each call (round-robin). + * @param fct + * The callback function of the timer. This parameter can be NULL if (and + * only if) rte_timer_alt_manage() will be used to manage this timer. + * @param arg + * The user argument of the callback function. + * @return + * - 0: Success; the timer is scheduled. + * - (-1): Timer is in the RUNNING or CONFIG state. + * - -EINVAL: invalid timer_data_id + */ +__rte_experimental +int +rte_timer_alt_reset(uint32_t timer_data_id, struct rte_timer *tim, + uint64_t ticks, enum rte_timer_type type, + unsigned int tim_lcore, rte_timer_cb_t fct, void *arg); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * This function is the same as rte_timer_stop(), except that it allows a + * caller to specify the rte_timer_data instance containing the list from which + * this timer should be removed. + * + * @see rte_timer_stop() + * + * @param timer_data_id + * An identifier indicating which instance of timer data should be used for + * this operation. + * @param tim + * The timer handle. + * @return + * - 0: Success; the timer is stopped. + * - (-1): The timer is in the RUNNING or CONFIG state. + * - -EINVAL: invalid timer_data_id + */ +__rte_experimental +int +rte_timer_alt_stop(uint32_t timer_data_id, struct rte_timer *tim); + +/** + * Callback function type for rte_timer_alt_manage(). + */ +typedef void (*rte_timer_alt_manage_cb_t)(struct rte_timer *tim); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Manage a set of timer lists and execute the specified callback function for + * all expired timers. This function is similar to rte_timer_manage(), except + * that it allows a caller to specify the timer_data instance that should + * be operated on, as well as a set of lcore IDs identifying which timer lists + * should be processed. Callback functions of individual timers are ignored. + * + * @see rte_timer_manage() + * + * @param timer_data_id + * An identifier indicating which instance of timer data should be used for + * this operation. + * @param poll_lcores + * An array of lcore ids identifying the timer lists that should be processed. + * NULL is allowed - if NULL, the timer list corresponding to the lcore + * calling this routine is processed (same as rte_timer_manage()). + * @param n_poll_lcores + * The size of the poll_lcores array. If 'poll_lcores' is NULL, this parameter + * is ignored. + * @param f + * The callback function which should be called for all expired timers. + * @return + * - 0: success + * - -EINVAL: invalid timer_data_id + */ +__rte_experimental +int +rte_timer_alt_manage(uint32_t timer_data_id, unsigned int *poll_lcores, + int n_poll_lcores, rte_timer_alt_manage_cb_t f); + +/** + * Callback function type for rte_timer_stop_all(). + */ +typedef void (*rte_timer_stop_all_cb_t)(struct rte_timer *tim, void *arg); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Walk the pending timer lists for the specified lcore IDs, and for each timer + * that is encountered, stop it and call the specified callback function to + * process it further. + * + * @param timer_data_id + * An identifier indicating which instance of timer data should be used for + * this operation. + * @param walk_lcores + * An array of lcore ids identifying the timer lists that should be processed. + * @param nb_walk_lcores + * The size of the walk_lcores array. + * @param f + * The callback function which should be called for each timers. Can be NULL. + * @param f_arg + * An arbitrary argument that will be passed to f, if it is called. + * @return + * - 0: success + * - EINVAL: invalid timer_data_id + */ +__rte_experimental +int +rte_timer_stop_all(uint32_t timer_data_id, unsigned int *walk_lcores, + int nb_walk_lcores, rte_timer_stop_all_cb_t f, void *f_arg); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * This function is the same as rte_timer_dump_stats(), except that it allows + * the caller to specify the rte_timer_data instance that should be used. + * + * @see rte_timer_dump_stats() + * + * @param timer_data_id + * An identifier indicating which instance of timer data should be used for + * this operation. + * @param f + * A pointer to a file for output + * @return + * - 0: success + * - -EINVAL: invalid timer_data_id */ -void rte_timer_dump_stats(void); +__rte_experimental +int +rte_timer_alt_dump_stats(uint32_t timer_data_id, FILE *f); #ifdef __cplusplus }