RTE_EVENT_TIMER_ADAPTER_STOP(3)
π rte_event_timer_adapter.h (3) β Library Functions Manual π
okay so bestie, this is the manual page for rte_event_timer_adapter.h, and it lives in the Library Functions Manual, section 3. Buckle up, it's giving event timer adapter realness. β¨
πΈ NAME πΈ
rte_event_timer_adapter.h
β¨ SYNOPSIS β¨
#include 'rte_eventdev.h'
#include 'rte_eventdev_trace_fp.h'
π«Ά Data Structures π«Ά
struct rte_event_timer_adapter_confstruct rte_event_timer_adapter_statsstruct rte_event_timer_adapter_infostruct rte_event_timer
π Macros π
#define RTE_EVENT_TIMER_ADAPTER_F_ADJUST_RES (1ULL << 0)#define RTE_EVENT_TIMER_ADAPTER_F_SP_PUT (1ULL << 1)#define RTE_EVENT_TIMER_ADAPTER_F_PERIODIC (1ULL << 2)
π Typedefs π
typedef int(* rte_event_timer_adapter_port_conf_cb_t) (uint16_t id,
uint8_t event_dev_id, uint8_t *event_port_id, void *conf_arg)
π Enumerations π
enum rte_event_timer_adapter_clk_src { RTE_EVENT_TIMER_ADAPTER_CPU_CLK,
RTE_EVENT_TIMER_ADAPTER_EXT_CLK0, RTE_EVENT_TIMER_ADAPTER_EXT_CLK1,
RTE_EVENT_TIMER_ADAPTER_EXT_CLK2, RTE_EVENT_TIMER_ADAPTER_EXT_CLK3 }
enum rte_event_timer_state { RTE_EVENT_TIMER_NOT_ARMED = 0,
RTE_EVENT_TIMER_ARMED = 1, RTE_EVENT_TIMER_CANCELED = 2,
RTE_EVENT_TIMER_ERROR = -1, RTE_EVENT_TIMER_ERROR_TOOEARLY = -2,
RTE_EVENT_TIMER_ERROR_TOOLATE = -3 }
π Functions π
struct rte_event_timer_adapter * rte_event_timer_adapter_create (const
struct rte_event_timer_adapter_conf *conf)
struct rte_event_timer_adapter * rte_event_timer_adapter_create_ext
(const struct rte_event_timer_adapter_conf *conf,
rte_event_timer_adapter_port_conf_cb_t conf_cb, void *conf_arg)
int rte_event_timer_adapter_get_info (const struct
rte_event_timer_adapter *adapter, struct
rte_event_timer_adapter_info *adapter_info)
int rte_event_timer_adapter_start (const struct rte_event_timer_adapter
*adapter)
int rte_event_timer_adapter_stop (const struct rte_event_timer_adapter
*adapter)
struct rte_event_timer_adapter * rte_event_timer_adapter_lookup
(uint16_t adapter_id)
int rte_event_timer_adapter_free (struct rte_event_timer_adapter
*adapter)
int rte_event_timer_adapter_service_id_get (struct
rte_event_timer_adapter *adapter, uint32_t *service_id)
int rte_event_timer_adapter_stats_get (struct rte_event_timer_adapter
*adapter, struct rte_event_timer_adapter_stats *stats)
int rte_event_timer_adapter_stats_reset (struct rte_event_timer_adapter
*adapter)
static uint16_t rte_event_timer_arm_burst (const struct
rte_event_timer_adapter *adapter, struct rte_event_timer **evtims,
uint16_t nb_evtims)
static uint16_t rte_event_timer_arm_tmo_tick_burst (const struct
rte_event_timer_adapter *adapter, struct rte_event_timer **evtims,
const uint64_t timeout_ticks, const uint16_t nb_evtims)
static uint16_t rte_event_timer_cancel_burst (const struct
rte_event_timer_adapter *adapter, struct rte_event_timer **evtims,
uint16_t nb_evtims)
__rte_experimental int rte_event_timer_remaining_ticks_get (const struct
rte_event_timer_adapter *adapter, const struct rte_event_timer
*evtim, uint64_t *ticks_remaining)
π¦ Detailed Description π¦
β¨ RTE Event Timer Adapter β¨
An event timer adapter has the following abstract working model:
timer_tick_ns
+
+-------+ |
| | |
+-------+ bkt 0 +----v---+
| | | |
| +-------+ |
+---+---+ +---+---+ +---+---+---+---+
| | | | | | | | |
| bkt n | | bkt 1 |<-> t0| t1| t2| tn|
| | | | | | | | |
+---+---+ +---+---+ +---+---+---+---+
| Timer adapter |
+---+---+ +---+---+
| | | |
| bkt 4 | | bkt 2 |<--- Current bucket
| | | |
+---+---+ +---+---+
| +-------+ |
| | | |
+------+ bkt 3 +-------+
| |
+-------+
- It has a virtual monotonically increasing 64-bit timer adapter clock based on
enum rte_event_timer_adapter_clk_srcclock source. The clock source could be a CPU clock, or a platform dependent external clock. - The application creates a timer adapter instance with given the clock source, the total number of event timers, and a resolution(expressed in ns) to traverse between the buckets.
- Each timer adapter may have 0 to n buckets based on the configured max timeout(
max_tmo_ns) and resolution(timer_tick_ns). Upon starting the timer adapter, the adapter starts ticking attimer_tick_nsresolution. - The application arms an event timer that will expire
timer_tick_nsfrom now. - The application can cancel an armed timer and no timer expiry event will be generated.
- If a timer expires then the library injects the timer expiry event in the designated event queue.
- The timer expiry event will be received through
rte_event_dequeue_burst. - The application frees the timer adapter instance.
Multiple timer adapters can be created with a varying level of resolution for various expiry use cases that run in parallel.
Before using the timer adapter, the application has to create and configure an event device along with the event port. Based on the event device capability it might require creating an additional event port to be used by the timer adapter.
The application creates the event timer adapter using the rte_event_timer_adapter_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_adapter_create_ext() to have granular control over producer port creation in a case where the in-built port is absent.
After creating the timer adapter, the application has to start it using rte_event_timer_adapter_start(). The buckets are traversed from 0 to n; when the adapter ticks, the next bucket is visited. Each time, the list per bucket is processed, and timer expiry 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() addresses the former case and rte_event_timer_arm_burst() addresses 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_adapter_lookup() can be used to get the timer adapter pointer from its id and use it to invoke fastpath operations such as arm and cancel.
Some of the use cases of event timer adapter 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.
Definition in file rte_event_timer_adapter.h.
π Macro Definition Documentation π
RTE_EVENT_TIMER_ADAPTER_F_ADJUST_RES
#define RTE_EVENT_TIMER_ADAPTER_F_ADJUST_RES (1ULL << 0)
The event timer adapter implementation may have constraints on the resolution (timer_tick_ns) and maximum timer expiry timeout(max_tmo_ns) based on the given timer adapter or system. If this flag is set, the implementation adjusts the resolution and maximum timeout to the best possible configuration. On successful timer adapter creation, the application can get the configured resolution and max timeout with rte_event_timer_adapter_get_info().
See also:
struct rte_event_timer_adapter_info::min_resolution_nsstruct rte_event_timer_adapter_info::max_tmo_ns
Definition at line 134 of file rte_event_timer_adapter.h.
RTE_EVENT_TIMER_ADAPTER_F_SP_PUT
#define RTE_EVENT_TIMER_ADAPTER_F_SP_PUT (1ULL << 1)
rte_event_timer_arm_burst() API to be used in single producer mode.
See also:
struct rte_event_timer_adapter_conf::flags
Definition at line 146 of file rte_event_timer_adapter.h.
RTE_EVENT_TIMER_ADAPTER_F_PERIODIC
#define RTE_EVENT_TIMER_ADAPTER_F_PERIODIC (1ULL << 2)
Flag to configure an event timer adapter in periodic mode; non-periodic mode is the default. A timer will fire once or periodically until the timer is cancelled based on the adapter mode.
See also:
struct rte_event_timer_adapter_conf::flags
Definition at line 152 of file rte_event_timer_adapter.h.
π§ Typedef Documentation π§
rte_event_timer_adapter_port_conf_cb_t
typedef int(* rte_event_timer_adapter_port_conf_cb_t) (uint16_t id,
uint8_t event_dev_id, uint8_t *event_port_id, void *conf_arg)
Callback function type for producer port creation.
Definition at line 205 of file rte_event_timer_adapter.h.
π Enumeration Type Documentation π
rte_event_timer_adapter_clk_src
enum rte_event_timer_adapter_clk_src { RTE_EVENT_TIMER_ADAPTER_CPU_CLK,
RTE_EVENT_TIMER_ADAPTER_EXT_CLK0, RTE_EVENT_TIMER_ADAPTER_EXT_CLK1,
RTE_EVENT_TIMER_ADAPTER_EXT_CLK2, RTE_EVENT_TIMER_ADAPTER_EXT_CLK3 }
Timer adapter clock source
Enumerator
RTE_EVENT_TIMER_ADAPTER_CPU_CLKβ Use CPU clock as the clock source.RTE_EVENT_TIMER_ADAPTER_EXT_CLK0β Platform dependent external clock source 0.RTE_EVENT_TIMER_ADAPTER_EXT_CLK1β Platform dependent external clock source 1.RTE_EVENT_TIMER_ADAPTER_EXT_CLK2β Platform dependent external clock source 2.RTE_EVENT_TIMER_ADAPTER_EXT_CLK3β Platform dependent external clock source 3.
Definition at line 121 of file rte_event_timer_adapter.h.
rte_event_timer_state
enum rte_event_timer_state { RTE_EVENT_TIMER_NOT_ARMED = 0,
RTE_EVENT_TIMER_ARMED = 1, RTE_EVENT_TIMER_CANCELED = 2,
RTE_EVENT_TIMER_ERROR = -1, RTE_EVENT_TIMER_ERROR_TOOEARLY = -2,
RTE_EVENT_TIMER_ERROR_TOOLATE = -3 }
Event timer state.
Enumerator
RTE_EVENT_TIMER_NOT_ARMEDβ Event timer not armed.RTE_EVENT_TIMER_ARMEDβ Event timer successfully armed.RTE_EVENT_TIMER_CANCELEDβ Event timer successfully canceled.RTE_EVENT_TIMER_ERRORβ Generic event timer error.RTE_EVENT_TIMER_ERROR_TOOEARLYβ Event timer timeout tick value is too small for the adapter to handle, given its configured resolution.RTE_EVENT_TIMER_ERROR_TOOLATEβ Event timer timeout tick is greater than the maximum timeout.
Definition at line 455 of file rte_event_timer_adapter.h.
β Function Documentation β
rte_event_timer_adapter_create
struct rte_event_timer_adapter * rte_event_timer_adapter_create (const
struct rte_event_timer_adapter_conf *conf)
Create an event timer adapter.
This function must be invoked first before any other function in the API.
So like, when you make an adapter with this API, rte_event_dev_config::nb_event_ports gets auto-incremented (no cap, it just does it for you β¨), and the event device gets reconfigured with an extra event port while the service is initializing. And heads up: that same reconfigure logic also bumps rte_event_dev_config::nb_single_link_event_port_queues if your adapter event port config is of type RTE_EVENT_PORT_CFG_SINGLE_LINK.
Which means bestie, you don't have to do anything π
β the application no longer needs to account for rte_event_dev_config::nb_event_ports and rte_event_dev_config::nb_single_link_event_port_queues when it sets up the event device config for the Timer adapter, as long as the adapter was created with this API.
Parameters
confβ the event timer adapter configuration structure. hand it over π«Ά
Returns
A pointer to the new allocated event timer adapter on success, and NULL on error with rte_errno set appropriately. Possible rte_errno values include:
ERANGE:timer_tick_nsis not in supported range. πENOMEM: unable to allocate sufficient memory for adapter instances. πEINVAL: invalid event device identifier specified in config.ENOSPC: maximum number of adapters already created. no more room at the inn πEIO: event device reconfiguration and restart error. Lowkey important: the adapter reconfigures the event device with an additional port by default if it needs a service to manage timers. And if the device had already been started before this call, this error code means there was an error in the restart that followed an error in reconfiguration β so basically a combination of the two error codes at once. π
struct rte_event_timer_adapter * rte_event_timer_adapter_create_ext (const struct rte_event_timer_adapter_conf * conf, rte_event_timer_adapter_port_conf_cb_t conf_cb, void * conf_arg)
Create a timer adapter, but with the callback you supply π.
Use this one when you want way more granular control over the timer adapter creation. If a built-in port is absent, then the function uses the callback you provided to create and get the port id that'll be used as the producer port. custom control era β¨
Parameters
confβ the timer adapter configuration structure.conf_cbβ the port config callback function.conf_argβ opaque pointer to the argument for the callback function.
Returns
A pointer to the new allocated event timer adapter on success, NULL on error with rte_errno set appropriately. Possible rte_errno values include:
ERANGE:timer_tick_nsis not in supported range.ENOMEM: unable to allocate sufficient memory for adapter instances.EINVAL: invalid event device identifier specified in config.ENOSPC: maximum number of adapters already created.
int rte_event_timer_adapter_get_info (const struct rte_event_timer_adapter * adapter, struct rte_event_timer_adapter_info * adapter_info)
Retrieve the contextual info of an event timer adapter. the tea β, if you will π
Parameters
adapterβ a pointer to the event timer adapter structure.adapter_infoβ a pointer to a structure of typerte_event_timer_adapter_infoto be filled with the contextual information of the adapter.
Returns
0: Success, the driver updates the contextual information of the timer adapter. β<0: Error code returned by the driver info get function.-EINVAL: adapter identifier invalid.
See also
RTE_EVENT_TIMER_ADAPTER_F_ADJUST_RES, struct rte_event_timer_adapter_info
int rte_event_timer_adapter_start (const struct rte_event_timer_adapter * adapter)
Start a timer adapter. π₯
The adapter start step is the last one, bestie β it's literally where the timer adapter gets set to start accepting the timers and scheduling to event queues.
On success, all the basic functions exported by the API (timer arm, timer cancel, and so on) can be invoked. unlock the whole kit and caboodle π¦
Parameters
adapterβ a pointer to the event timer adapter structure.
Returns
0: Success, adapter started. π<0: Error code returned by the driver start function.-EINVALif adapter identifier invalid.-ENOENTif software adapter but no service core mapped. π-ENOTSUPif software adapter and more than one service core mapped.-EALREADYif adapter has already been started.
Note
The eventdev to which the event_timer_adapter is connected needs to be started before calling rte_event_timer_adapter_start(). do not skip this step, i'm so serious π«Ά
int rte_event_timer_adapter_stop (const struct rte_event_timer_adapter * adapter)
Stop an event timer adapter. hit the brakes β
And good news: the adapter can be restarted with a call to rte_event_timer_adapter_start(). it's giving reversible π
Parameters
adapterβ a pointer to the event timer adapter structure.
Returns
0: Success, adapter stopped.<0: Error code returned by the driver stop function.-EINVALif adapter identifier invalid.
struct rte_event_timer_adapter * rte_event_timer_adapter_lookup (uint16_t adapter_id)
Look up an event timer adapter using its identifier. π
If an event timer adapter was created in another process with the same identifier, this function will locate its state and set up access to it so it can be used in this process. cross-process bestie behavior β¨
Parameters
adapter_idβ the event timer adapter identifier.
Returns
A pointer to the event timer adapter matching the identifier on success. NULL on error with rte_errno set appropriately. Possible rte_errno values include:
ENOENTβ requested entry not available to return. π
int rte_event_timer_adapter_free (struct rte_event_timer_adapter * adapter)
Free an event timer adapter β destroy it, and free all the resources. π§Ή
Before invoking this function, the application must wait for all the armed timers to expire or cancel the outstanding armed timers. no cap, clean up your timers first π€
Parameters
adapterβ a pointer to an event timer adapter structure.
Returns
0: Successfully freed the event timer adapter resources. π<0: Failed to free the event timer adapter resources.-EAGAIN: adapter is busy; timers outstanding.-EBUSY: stop hasn't been called for this adapter yet.-EINVAL: adapter id invalid, or adapter invalid.
int rte_event_timer_adapter_service_id_get (struct rte_event_timer_adapter * adapter, uint32_t * service_id)
Retrieve the service ID of the event timer adapter. And plot twist: if the adapter doesn't use an rte_service function, this function returns -ESRCH. π
Parameters
adapterβ a pointer to an event timer adapter.service_idβ a pointer to auint32_t, to be filled in with the service id.
Returns
0: Success β<0: Error code on failure.-ESRCH: the adapter does not require a service to operate.
int rte_event_timer_adapter_stats_get (struct rte_event_timer_adapter * adapter, struct rte_event_timer_adapter_stats * stats)
Retrieve statistics for an event timer adapter instance. π numbers era
Parameters
adapterβ a pointer to an event timer adapter structure.statsβ a pointer to a structure to fill with statistics.
Returns
0: Successfully retrieved.<0: Failure; error code returned.
int rte_event_timer_adapter_stats_reset (struct rte_event_timer_adapter * adapter)
Reset statistics for an event timer adapter instance. π fresh start energy
Parameters
adapterβ a pointer to an event timer adapter structure.
Returns
0: Successfully reset;<0: Failure; error code returned.
uint16_t rte_event_timer_arm_burst (const struct rte_event_timer_adapter * adapter, struct rte_event_timer ** evtims, uint16_t nb_evtims) [inline], [static]
Arm a burst of event timers, with a separate expiration timeout tick for each event timer. π― the way that it's per-timer
Before calling this function, the application allocates struct rte_event_timer objects from mempool or huge page backed application buffers of desired size. On successful allocation, the application updates the struct rte_event_timer attributes such as expiry event attributes and timeout ticks from now. Then this function submits the event timer arm requests to the event timer adapter, and on expiry the events will be injected to the designated event queue. and here's the key part π β timer expiry events will be generated once, or periodically until cancellation, based on the adapter mode.
Parameters
adapterβ a pointer to an event timer adapter structure.evtimsβ pointer to an array of objects of typerte_event_timerstructure.nb_evtimsβ number of event timers in the supplied array.
Returns
The number of successfully armed event timers. The return value can be less than the value of the nb_evtims parameter. If the return value is less than nb_evtims, the remaining event timers at the end of evtims 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 adapter, expiry event queue ID is invalid, or an expiry event's sched type doesn't match the capabilities of the destination event queue.EAGAINβ specified timer adapter is not running.EALREADYβ a timer was encountered that was already armed. chill, it's already armed π
See also
RTE_EVENT_TIMER_ADAPTER_F_PERIODIC
Definition at line 598 of file rte_event_timer_adapter.h.
uint16_t rte_event_timer_arm_tmo_tick_burst (const struct rte_event_timer_adapter * adapter, struct rte_event_timer ** evtims, const uint64_t timeout_ticks, const uint16_t nb_evtims) [inline], [static]
Arm a burst of event timers that all share the same expiration timeout tick. πΈ one tick to rule them all
Provides the same functionality as rte_event_timer_arm_burst(), except that the application can use this API when all the event timers have the same timeout expiration tick. This specialized function can provide the additional hint to the adapter implementation and optimize if possible. iykyk β¨
Parameters
adapterβ a pointer to an event timer adapter structure.evtimsβ points to an array of objects of typerte_event_timerstructure.timeout_ticksβ the number of ticks in which the timers should expire.nb_evtimsβ number of event timers in the supplied array. (Yes, it'sconst uint16_there π )
Returns
The number of successfully armed event timers. The return value can be less than the value of the nb_evtims parameter. If the return value is less than nb_evtims, the remaining event timers at the end of evtims 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 adapter, expiry event queue ID is invalid, or an expiry event's sched type doesn't match the capabilities of the destination event queue.EAGAINβ specified event timer adapter is not running.EALREADYβ a timer was encountered that was already armed.
Definition at line 641 of file rte_event_timer_adapter.h. π
πΈ rte_event_timer_cancel_burst()
uint16_t rte_event_timer_cancel_burst (const struct rte_event_timer_adapter * adapter,
struct rte_event_timer ** evtims,
uint16_t nb_evtims)
[inline], [static]
Okay bestie, this one is the β¨mass-cancelβ¨ button. It cancels a whole burst of event timers so they stop being scheduled to the event device. Like, one by one is so last season β we're doing them in bulk, and we're doing it fast. π
Parameters
adapterβ a pointer to an event timer adapter structure.evtimsβ points to an array of objects of typerte_event_timerstructure.nb_evtimsβ how many event timer instances live in the array you just handed over.
Returns
The number of successfully canceled event timers π β and heads up, the return value can be less than the value of the nb_evtims parameter. If it is less than nb_evtims, then the remaining event timers at the end of evtims are not consumed, and the caller has to take care of them, and rte_errno is set accordingly. So like. Don't just walk away from them, bestie, they're your responsibility now π«Ά
Possible errno values include:
EINVALβ invalid timer adapter identifier.EAGAINβ the specified timer adapter is not running.EALREADYβ a timer was encountered that was already canceled.
β οΈ Not me repeating this but β partial returns are real and the leftover timers are yours. Check the return value, check rte_errno, be the main character who actually handles their edge cases. π
Definition at line 678 of file rte_event_timer_adapter.h.
π§ rte_event_timer_remaining_ticks_get()
__rte_experimental int rte_event_timer_remaining_ticks_get (const struct rte_event_timer_adapter * adapter,
const struct rte_event_timer * evtim,
uint64_t * ticks_remaining)
Lowkey my fave, ngl β this is the "how much longer till it pops" call. It gets the number of ticks remaining until event timer expiry. β³β¨
Parameters
adapterβ a pointer to an event timer adapter structure.evtimβ a pointer to anrte_event_timerstructure.ticks_remainingβ pointer to variable into which to write the number of ticks remaining until event timer expiry.
Returns
0: Success π-EINVALβ invalid timer adapter identifier, or the event timer is not in the armed state, orticks_remainingisNULL.-ENOTSUPβ the timer adapter implementation does not support this API.
π Yep, note the __rte_experimental tag up there β that's the "this API is still cooking, don't build your whole life on it yet" energy, fr fr.
π Author
Generated automatically by Doxygen for DPDK from the source code.
And that's a wrap on the whole page, bestie!! ππ Sourced from DPDK Version 25.11.3, page rte_event_...r_adapter.h(3). Go forth and slay those timers. βπ¦π
π¦ where this page comes from
- ubuntu resolute: dpdk-doc 25.11.3-0ubuntu0.26.04.1 Β· BSD-3-Clause
- ubuntu stonking: dpdk-doc 25.11.3-1 Β· BSD-3-Clause
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms