.TH "rte_timer.h" 3 "Version 25.11.0" "DPDK" \" -*- nroff -*- .ad l .nh .SH NAME rte_timer.h .SH SYNOPSIS .br .PP \fR#include \fP .br \fR#include \fP .br \fR#include \fP .br \fR#include \fP .br .SS "Data Structures" .in +1c .ti -1c .RI "union \fBrte_timer_status\fP" .br .ti -1c .RI "struct \fBrte_timer\fP" .br .in -1c .SS "Macros" .in +1c .ti -1c .RI "#define \fBRTE_TIMER_STOP\fP 0" .br .ti -1c .RI "#define \fBRTE_TIMER_PENDING\fP 1" .br .ti -1c .RI "#define \fBRTE_TIMER_RUNNING\fP 2" .br .ti -1c .RI "#define \fBRTE_TIMER_CONFIG\fP 3" .br .ti -1c .RI "#define \fBRTE_TIMER_NO_OWNER\fP \-2" .br .ti -1c .RI "#define \fBRTE_TIMER_INITIALIZER\fP" .br .in -1c .SS "Typedefs" .in +1c .ti -1c .RI "\fBtypedef\fP void(* \fBrte_timer_cb_t\fP) (struct \fBrte_timer\fP *, void *)" .br .ti -1c .RI "\fBtypedef\fP void(* \fBrte_timer_alt_manage_cb_t\fP) (struct \fBrte_timer\fP *tim)" .br .ti -1c .RI "\fBtypedef\fP void(* \fBrte_timer_stop_all_cb_t\fP) (struct \fBrte_timer\fP *tim, void *arg)" .br .in -1c .SS "Enumerations" .in +1c .ti -1c .RI "enum \fBrte_timer_type\fP " .br .in -1c .SS "Functions" .in +1c .ti -1c .RI "int \fBrte_timer_data_alloc\fP (uint32_t *id_ptr)" .br .ti -1c .RI "int \fBrte_timer_data_dealloc\fP (uint32_t id)" .br .ti -1c .RI "int \fBrte_timer_subsystem_init\fP (void)" .br .ti -1c .RI "void \fBrte_timer_subsystem_finalize\fP (void)" .br .ti -1c .RI "void \fBrte_timer_init\fP (struct \fBrte_timer\fP *tim)" .br .ti -1c .RI "int \fBrte_timer_reset\fP (struct \fBrte_timer\fP *tim, uint64_t ticks, enum \fBrte_timer_type\fP type, unsigned tim_lcore, \fBrte_timer_cb_t\fP fct, void *arg)" .br .ti -1c .RI "void \fBrte_timer_reset_sync\fP (struct \fBrte_timer\fP *tim, uint64_t ticks, enum \fBrte_timer_type\fP type, unsigned tim_lcore, \fBrte_timer_cb_t\fP fct, void *arg)" .br .ti -1c .RI "int \fBrte_timer_stop\fP (struct \fBrte_timer\fP *tim)" .br .ti -1c .RI "void \fBrte_timer_stop_sync\fP (struct \fBrte_timer\fP *tim)" .br .ti -1c .RI "int \fBrte_timer_pending\fP (struct \fBrte_timer\fP *tim)" .br .ti -1c .RI "int64_t \fBrte_timer_next_ticks\fP (void)" .br .ti -1c .RI "int \fBrte_timer_manage\fP (void)" .br .ti -1c .RI "int \fBrte_timer_dump_stats\fP (FILE *f)" .br .ti -1c .RI "int \fBrte_timer_alt_reset\fP (uint32_t timer_data_id, struct \fBrte_timer\fP *tim, uint64_t ticks, enum \fBrte_timer_type\fP type, unsigned int tim_lcore, \fBrte_timer_cb_t\fP fct, void *arg)" .br .ti -1c .RI "int \fBrte_timer_alt_stop\fP (uint32_t timer_data_id, struct \fBrte_timer\fP *tim)" .br .ti -1c .RI "int \fBrte_timer_alt_manage\fP (uint32_t timer_data_id, unsigned int *poll_lcores, int n_poll_lcores, \fBrte_timer_alt_manage_cb_t\fP f)" .br .ti -1c .RI "int \fBrte_timer_stop_all\fP (uint32_t timer_data_id, unsigned int *walk_lcores, int nb_walk_lcores, \fBrte_timer_stop_all_cb_t\fP f, void *f_arg)" .br .ti -1c .RI "int \fBrte_timer_alt_dump_stats\fP (uint32_t timer_data_id, FILE *f)" .br .in -1c .SH "Detailed Description" .PP RTE Timer .PP This library provides a timer service to RTE Data Plane execution units that allows the execution of callback functions asynchronously\&. .PP .IP "\(bu" 2 Timers can be periodic or single (one-shot)\&. .IP "\(bu" 2 The timers can be loaded from one core and executed on another\&. This has to be specified in the call to \fBrte_timer_reset()\fP\&. .IP "\(bu" 2 High precision is possible\&. NOTE: this depends on the call frequency to \fBrte_timer_manage()\fP that check the timer expiration for the local core\&. .IP "\(bu" 2 If not used in an application, for improved performance, it can be disabled at compilation time by not calling the \fBrte_timer_manage()\fP to improve performance\&. .PP .PP The timer library uses the rte_get_hpet_cycles() function that uses the HPET, when available, to provide a reliable time reference\&. [HPET routines are provided by EAL, which falls back to using the chip TSC (time- stamp counter) as fallback when HPET is not available] .PP This library provides an interface to add, delete and restart a timer\&. The API is based on the BSD callout(9) API with a few differences\&. .PP See the RTE architecture documentation for more information about the design of this library\&. .PP Definition in file \fBrte_timer\&.h\fP\&. .SH "Macro Definition Documentation" .PP .SS "#define RTE_TIMER_STOP 0" State: timer is stopped\&. .PP Definition at line \fB47\fP of file \fBrte_timer\&.h\fP\&. .SS "#define RTE_TIMER_PENDING 1" State: timer is scheduled\&. .PP Definition at line \fB48\fP of file \fBrte_timer\&.h\fP\&. .SS "#define RTE_TIMER_RUNNING 2" State: timer function is running\&. .PP Definition at line \fB49\fP of file \fBrte_timer\&.h\fP\&. .SS "#define RTE_TIMER_CONFIG 3" State: timer is being configured\&. .PP Definition at line \fB50\fP of file \fBrte_timer\&.h\fP\&. .SS "#define RTE_TIMER_NO_OWNER \-2" Timer has no owner\&. .PP Definition at line \fB52\fP of file \fBrte_timer\&.h\fP\&. .SS "#define RTE_TIMER_INITIALIZER" \fBValue:\fP .nf { \\ \&.status = {{ \\ \&.state = RTE_TIMER_STOP, \\ \&.owner = RTE_TIMER_NO_OWNER, \\ }}, \\ } .PP .fi A static initializer for a timer structure\&. .PP Definition at line \fB125\fP of file \fBrte_timer\&.h\fP\&. .SH "Typedef Documentation" .PP .SS "\fBtypedef\fP void(* rte_timer_cb_t) (struct \fBrte_timer\fP *, void *)" Callback function type for timer expiry\&. .PP Definition at line \fB91\fP of file \fBrte_timer\&.h\fP\&. .SS "\fBtypedef\fP void(* rte_timer_alt_manage_cb_t) (struct \fBrte_timer\fP *tim)" Callback function type for \fBrte_timer_alt_manage()\fP\&. .PP Definition at line \fB436\fP of file \fBrte_timer\&.h\fP\&. .SS "\fBtypedef\fP void(* rte_timer_stop_all_cb_t) (struct \fBrte_timer\fP *tim, void *arg)" Callback function type for \fBrte_timer_stop_all()\fP\&. .PP Definition at line \fB470\fP of file \fBrte_timer\&.h\fP\&. .SH "Enumeration Type Documentation" .PP .SS "enum \fBrte_timer_type\fP" Timer type: Periodic or single (one-shot)\&. .PP Definition at line \fB57\fP of file \fBrte_timer\&.h\fP\&. .SH "Function Documentation" .PP .SS "int rte_timer_data_alloc (uint32_t * id_ptr)" Allocate a timer data instance in shared memory to track a set of pending timer lists\&. .PP \fBParameters\fP .RS 4 \fIid_ptr\fP Pointer to variable into which to write the identifier of the allocated timer data instance\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: Success .IP "\(bu" 2 -ENOSPC: maximum number of timer data instances already allocated .PP .RE .PP .SS "int rte_timer_data_dealloc (uint32_t id)" Deallocate a timer data instance\&. .PP \fBParameters\fP .RS 4 \fIid\fP Identifier of the timer data instance to deallocate\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: Success .IP "\(bu" 2 -EINVAL: invalid timer data instance identifier .PP .RE .PP .SS "int rte_timer_subsystem_init (void )" Initialize the timer library\&. .PP Initializes internal variables (list, locks and so on) for the RTE timer library\&. .PP \fBNote\fP .RS 4 This function must be called in every process before using the library\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: Success .IP "\(bu" 2 -ENOMEM: Unable to allocate memory needed to initialize timer subsystem .IP "\(bu" 2 -EALREADY: timer subsystem was already initialized\&. Not an error\&. .PP .RE .PP .SS "void rte_timer_subsystem_finalize (void )" Free timer subsystem resources\&. .SS "void rte_timer_init (struct \fBrte_timer\fP * tim)" Initialize a timer handle\&. .PP The \fBrte_timer_init()\fP function initializes the timer handle \fItim\fP for use\&. No operations can be performed on a timer before it is initialized\&. .PP \fBParameters\fP .RS 4 \fItim\fP The timer to initialize\&. .RE .PP .SS "int rte_timer_reset (struct \fBrte_timer\fP * tim, uint64_t ticks, enum \fBrte_timer_type\fP type, unsigned tim_lcore, \fBrte_timer_cb_t\fP fct, void * arg)" Reset and start the timer associated with the timer handle\&. .PP The \fBrte_timer_reset()\fP function resets and starts the timer associated with the timer handle \fItim\fP\&. When the timer expires after \fIticks\fP HPET cycles, the function specified by \fIfct\fP will be called with the argument \fIarg\fP on core \fItim_lcore\fP\&. .PP If the timer associated with the timer handle is already running (in the RUNNING state), the function will fail\&. The user has to check the return value of the function to see if there is a chance that the timer is in the RUNNING state\&. .PP If the timer is being configured on another core (the CONFIG state), it will also fail\&. .PP If the timer is pending or stopped, it will be rescheduled with the new parameters\&. .PP \fBParameters\fP .RS 4 \fItim\fP The timer handle\&. .br \fIticks\fP The number of cycles (see rte_get_hpet_hz()) before the callback function is called\&. .br \fItype\fP The type can be either: .IP "\(bu" 2 PERIODICAL: The timer is automatically reloaded after execution (returns to the PENDING state) .IP "\(bu" 2 SINGLE: The timer is one-shot, that is, the timer goes to a STOPPED state after execution\&. .PP .br \fItim_lcore\fP 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)\&. .br \fIfct\fP The callback function of the timer\&. .br \fIarg\fP The user argument of the callback function\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: Success; the timer is scheduled\&. .IP "\(bu" 2 (-1): Timer is in the RUNNING or CONFIG state\&. .PP .RE .PP .SS "void rte_timer_reset_sync (struct \fBrte_timer\fP * tim, uint64_t ticks, enum \fBrte_timer_type\fP type, unsigned tim_lcore, \fBrte_timer_cb_t\fP fct, void * arg)" Loop until \fBrte_timer_reset()\fP succeeds\&. .PP Reset and start the timer associated with the timer handle\&. Always succeed\&. See \fBrte_timer_reset()\fP for details\&. .PP \fBParameters\fP .RS 4 \fItim\fP The timer handle\&. .br \fIticks\fP The number of cycles (see rte_get_hpet_hz()) before the callback function is called\&. .br \fItype\fP The type can be either: .IP "\(bu" 2 PERIODICAL: The timer is automatically reloaded after execution (returns to the PENDING state) .IP "\(bu" 2 SINGLE: The timer is one-shot, that is, the timer goes to a STOPPED state after execution\&. .PP .br \fItim_lcore\fP 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)\&. .br \fIfct\fP The callback function of the timer\&. .br \fIarg\fP The user argument of the callback function\&. .RE .PP \fBNote\fP .RS 4 This API should not be called inside a timer's callback function to reset another timer; doing so could hang in certain scenarios\&. Instead, the \fBrte_timer_reset()\fP API can be called directly and its return code can be checked for success or failure\&. .RE .PP .SS "int rte_timer_stop (struct \fBrte_timer\fP * tim)" Stop a timer\&. .PP The \fBrte_timer_stop()\fP function stops the timer associated with the timer handle \fItim\fP\&. It may fail if the timer is currently running or being configured\&. .PP If the timer is pending or stopped (for instance, already expired), the function will succeed\&. The timer handle tim must have been initialized using \fBrte_timer_init()\fP, otherwise, undefined behavior will occur\&. .PP This function can be called safely from a timer callback\&. If it succeeds, the timer is not referenced anymore by the timer library and the timer structure can be freed (even in the callback function)\&. .PP \fBParameters\fP .RS 4 \fItim\fP The timer handle\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: Success; the timer is stopped\&. .IP "\(bu" 2 (-1): The timer is in the RUNNING or CONFIG state\&. .PP .RE .PP .SS "void rte_timer_stop_sync (struct \fBrte_timer\fP * tim)" Loop until \fBrte_timer_stop()\fP succeeds\&. .PP After a call to this function, the timer identified by \fItim\fP is stopped\&. See \fBrte_timer_stop()\fP for details\&. .PP \fBParameters\fP .RS 4 \fItim\fP The timer handle\&. .RE .PP \fBNote\fP .RS 4 This API should not be called inside a timer's callback function to stop another timer; doing so could hang in certain scenarios\&. Instead, the \fBrte_timer_stop()\fP API can be called directly and its return code can be checked for success or failure\&. .RE .PP .SS "int rte_timer_pending (struct \fBrte_timer\fP * tim)" Test if a timer is pending\&. .PP The \fBrte_timer_pending()\fP function tests the PENDING status of the timer handle \fItim\fP\&. A PENDING timer is one that has been scheduled and whose function has not yet been called\&. .PP \fBParameters\fP .RS 4 \fItim\fP The timer handle\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: The timer is not pending\&. .IP "\(bu" 2 1: The timer is pending\&. .PP .RE .PP .SS "int64_t rte_timer_next_ticks (void )" Time until the next timer on the current lcore This function gives the ticks until the next timer will be active\&. .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 -EINVAL: invalid timer data instance identifier .IP "\(bu" 2 -ENOENT: no timer pending .IP "\(bu" 2 0: a timer is pending and will run at next \fBrte_timer_manage()\fP .IP "\(bu" 2 >0: ticks until the next timer is ready .PP .RE .PP .SS "int rte_timer_manage (void )" Manage the timer list and execute callback functions\&. .PP 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\&. .PP 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\&. .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: Success .IP "\(bu" 2 -EINVAL: timer subsystem not yet initialized .PP .RE .PP .SS "int rte_timer_dump_stats (FILE * f)" Dump statistics about timers\&. .PP \fBParameters\fP .RS 4 \fIf\fP A pointer to a file for output .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: Success .IP "\(bu" 2 -EINVAL: timer subsystem not yet initialized .PP .RE .PP .SS "int rte_timer_alt_reset (uint32_t timer_data_id, struct \fBrte_timer\fP * tim, uint64_t ticks, enum \fBrte_timer_type\fP type, unsigned int tim_lcore, \fBrte_timer_cb_t\fP fct, void * arg)" This function is the same as \fBrte_timer_reset()\fP, except that it allows a caller to specify the rte_timer_data instance containing the list to which the timer should be added\&. .PP \fBSee also\fP .RS 4 \fBrte_timer_reset()\fP .RE .PP \fBParameters\fP .RS 4 \fItimer_data_id\fP An identifier indicating which instance of timer data should be used for this operation\&. .br \fItim\fP The timer handle\&. .br \fIticks\fP The number of cycles (see rte_get_hpet_hz()) before the callback function is called\&. .br \fItype\fP The type can be either: .IP "\(bu" 2 PERIODICAL: The timer is automatically reloaded after execution (returns to the PENDING state) .IP "\(bu" 2 SINGLE: The timer is one-shot, that is, the timer goes to a STOPPED state after execution\&. .PP .br \fItim_lcore\fP 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)\&. .br \fIfct\fP The callback function of the timer\&. This parameter can be NULL if (and only if) \fBrte_timer_alt_manage()\fP will be used to manage this timer\&. .br \fIarg\fP The user argument of the callback function\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: Success; the timer is scheduled\&. .IP "\(bu" 2 (-1): Timer is in the RUNNING or CONFIG state\&. .IP "\(bu" 2 -EINVAL: invalid timer_data_id .PP .RE .PP .SS "int rte_timer_alt_stop (uint32_t timer_data_id, struct \fBrte_timer\fP * tim)" This function is the same as \fBrte_timer_stop()\fP, except that it allows a caller to specify the rte_timer_data instance containing the list from which this timer should be removed\&. .PP \fBSee also\fP .RS 4 \fBrte_timer_stop()\fP .RE .PP \fBParameters\fP .RS 4 \fItimer_data_id\fP An identifier indicating which instance of timer data should be used for this operation\&. .br \fItim\fP The timer handle\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: Success; the timer is stopped\&. .IP "\(bu" 2 (-1): The timer is in the RUNNING or CONFIG state\&. .IP "\(bu" 2 -EINVAL: invalid timer_data_id .PP .RE .PP .SS "int rte_timer_alt_manage (uint32_t timer_data_id, unsigned int * poll_lcores, int n_poll_lcores, \fBrte_timer_alt_manage_cb_t\fP f)" Manage a set of timer lists and execute the specified callback function for all expired timers\&. This function is similar to \fBrte_timer_manage()\fP, 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\&. .PP \fBSee also\fP .RS 4 \fBrte_timer_manage()\fP .RE .PP \fBParameters\fP .RS 4 \fItimer_data_id\fP An identifier indicating which instance of timer data should be used for this operation\&. .br \fIpoll_lcores\fP 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 \fBrte_timer_manage()\fP)\&. .br \fIn_poll_lcores\fP The size of the poll_lcores array\&. If 'poll_lcores' is NULL, this parameter is ignored\&. .br \fIf\fP The callback function which should be called for all expired timers\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: success .IP "\(bu" 2 -EINVAL: invalid timer_data_id .PP .RE .PP .SS "int rte_timer_stop_all (uint32_t timer_data_id, unsigned int * walk_lcores, int nb_walk_lcores, \fBrte_timer_stop_all_cb_t\fP f, void * f_arg)" 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\&. .PP \fBParameters\fP .RS 4 \fItimer_data_id\fP An identifier indicating which instance of timer data should be used for this operation\&. .br \fIwalk_lcores\fP An array of lcore ids identifying the timer lists that should be processed\&. .br \fInb_walk_lcores\fP The size of the walk_lcores array\&. .br \fIf\fP The callback function which should be called for each timers\&. Can be NULL\&. .br \fIf_arg\fP An arbitrary argument that will be passed to f, if it is called\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: success .IP "\(bu" 2 EINVAL: invalid timer_data_id .PP .RE .PP .SS "int rte_timer_alt_dump_stats (uint32_t timer_data_id, FILE * f)" This function is the same as \fBrte_timer_dump_stats()\fP, except that it allows the caller to specify the rte_timer_data instance that should be used\&. .PP \fBSee also\fP .RS 4 \fBrte_timer_dump_stats()\fP .RE .PP \fBParameters\fP .RS 4 \fItimer_data_id\fP An identifier indicating which instance of timer data should be used for this operation\&. .br \fIf\fP A pointer to a file for output .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: success .IP "\(bu" 2 -EINVAL: invalid timer_data_id .PP .RE .PP .SH "Author" .PP Generated automatically by Doxygen for DPDK from the source code\&.