-/*-
- * BSD LICENSE
- *
- * Copyright(c) 2010-2013 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.
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(c) 2010-2014 Intel Corporation
*/
#ifndef _RTE_TIMER_H_
* design of this library.
*/
+#include <stdio.h>
#include <stdint.h>
#include <stddef.h>
+#include <rte_common.h>
+#include <rte_config.h>
+#include <rte_spinlock.h>
#ifdef __cplusplus
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).
* 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. */
/**
* 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
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). */
- rte_timer_cb_t *f; /**< Callback function. */
+ rte_timer_cb_t f; /**< Callback function. */
void *arg; /**< Argument to callback function. */
};
}
#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.
enum rte_timer_type type, unsigned tim_lcore,
rte_timer_cb_t fct, void *arg);
-
/**
* Loop until rte_timer_reset() succeeds.
*
*/
int rte_timer_stop(struct rte_timer *tim);
-
/**
* Loop until rte_timer_stop() succeeds.
*
*/
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
}
git.droids-corp.org / dpdk.git / blobdiff