Branch data Line data Source code
1 : : /* SPDX-License-Identifier: BSD-3-Clause
2 : : * Copyright(c) 2017 Cavium, Inc.
3 : : * Copyright(c) 2017-2018 Intel Corporation.
4 : : * All rights reserved.
5 : : */
6 : :
7 : : #ifndef __RTE_EVENT_TIMER_ADAPTER_H__
8 : : #define __RTE_EVENT_TIMER_ADAPTER_H__
9 : :
10 : : /**
11 : : * @file
12 : : *
13 : : * RTE Event Timer Adapter
14 : : *
15 : : * An event timer adapter has the following abstract working model:
16 : : *
17 : : * timer_tick_ns
18 : : * +
19 : : * +-------+ |
20 : : * | | |
21 : : * +-------+ bkt 0 +----v---+
22 : : * | | | |
23 : : * | +-------+ |
24 : : * +---+---+ +---+---+ +---+---+---+---+
25 : : * | | | | | | | | |
26 : : * | bkt n | | bkt 1 |<-> t0| t1| t2| tn|
27 : : * | | | | | | | | |
28 : : * +---+---+ +---+---+ +---+---+---+---+
29 : : * | Timer adapter |
30 : : * +---+---+ +---+---+
31 : : * | | | |
32 : : * | bkt 4 | | bkt 2 |<--- Current bucket
33 : : * | | | |
34 : : * +---+---+ +---+---+
35 : : * | +-------+ |
36 : : * | | | |
37 : : * +------+ bkt 3 +-------+
38 : : * | |
39 : : * +-------+
40 : : *
41 : : * - It has a virtual monotonically increasing 64-bit timer adapter clock based
42 : : * on *enum rte_event_timer_adapter_clk_src* clock source. The clock source
43 : : * could be a CPU clock, or a platform dependent external clock.
44 : : *
45 : : * - The application creates a timer adapter instance with given the clock
46 : : * source, the total number of event timers, and a resolution(expressed in ns)
47 : : * to traverse between the buckets.
48 : : *
49 : : * - Each timer adapter may have 0 to n buckets based on the configured
50 : : * max timeout(max_tmo_ns) and resolution(timer_tick_ns). Upon starting the
51 : : * timer adapter, the adapter starts ticking at *timer_tick_ns* resolution.
52 : : *
53 : : * - The application arms an event timer that will expire *timer_tick_ns*
54 : : * from now.
55 : : *
56 : : * - The application can cancel an armed timer and no timer expiry event will be
57 : : * generated.
58 : : *
59 : : * - If a timer expires then the library injects the timer expiry event in
60 : : * the designated event queue.
61 : : *
62 : : * - The timer expiry event will be received through *rte_event_dequeue_burst*.
63 : : *
64 : : * - The application frees the timer adapter instance.
65 : : *
66 : : * Multiple timer adapters can be created with a varying level of resolution
67 : : * for various expiry use cases that run in parallel.
68 : : *
69 : : * Before using the timer adapter, the application has to create and configure
70 : : * an event device along with the event port. Based on the event device
71 : : * capability it might require creating an additional event port to be used
72 : : * by the timer adapter.
73 : : *
74 : : * The application creates the event timer adapter using the
75 : : * ``rte_event_timer_adapter_create()``. The event device id is passed to this
76 : : * function, inside this function the event device capability is checked,
77 : : * and if an in-built port is absent the application uses the default
78 : : * function to create a new producer port.
79 : : *
80 : : * The application may also use the function
81 : : * ``rte_event_timer_adapter_create_ext()`` to have granular control over
82 : : * producer port creation in a case where the in-built port is absent.
83 : : *
84 : : * After creating the timer adapter, the application has to start it
85 : : * using ``rte_event_timer_adapter_start()``. The buckets are traversed from
86 : : * 0 to n; when the adapter ticks, the next bucket is visited. Each time,
87 : : * the list per bucket is processed, and timer expiry events are sent to the
88 : : * designated event queue.
89 : : *
90 : : * The application can arm one or more event timers using the
91 : : * ``rte_event_timer_arm_burst()``. The *timeout_ticks* represents the number
92 : : * of *timer_tick_ns* after which the timer has to expire. The timeout at
93 : : * which the timers expire can be grouped or be independent of each
94 : : * event timer instance. ``rte_event_timer_arm_tmo_tick_burst()`` addresses the
95 : : * former case and ``rte_event_timer_arm_burst()`` addresses the latter case.
96 : : *
97 : : * The application can cancel the timers from expiring using the
98 : : * ``rte_event_timer_cancel_burst()``.
99 : : *
100 : : * On the secondary process, ``rte_event_timer_adapter_lookup()`` can be used
101 : : * to get the timer adapter pointer from its id and use it to invoke fastpath
102 : : * operations such as arm and cancel.
103 : : *
104 : : * Some of the use cases of event timer adapter are Beacon Timers,
105 : : * Generic SW Timeout, Wireless MAC Scheduling, 3G Frame Protocols,
106 : : * Packet Scheduling, Protocol Retransmission Timers, Supervision Timers.
107 : : * All these use cases require high resolution and low time drift.
108 : : */
109 : :
110 : :
111 : : #include "rte_eventdev.h"
112 : : #include "rte_eventdev_trace_fp.h"
113 : :
114 : : #ifdef __cplusplus
115 : : extern "C" {
116 : : #endif
117 : :
118 : : /**
119 : : * Timer adapter clock source
120 : : */
121 : : enum rte_event_timer_adapter_clk_src {
122 : : RTE_EVENT_TIMER_ADAPTER_CPU_CLK,
123 : : /**< Use CPU clock as the clock source. */
124 : : RTE_EVENT_TIMER_ADAPTER_EXT_CLK0,
125 : : /**< Platform dependent external clock source 0. */
126 : : RTE_EVENT_TIMER_ADAPTER_EXT_CLK1,
127 : : /**< Platform dependent external clock source 1. */
128 : : RTE_EVENT_TIMER_ADAPTER_EXT_CLK2,
129 : : /**< Platform dependent external clock source 2. */
130 : : RTE_EVENT_TIMER_ADAPTER_EXT_CLK3,
131 : : /**< Platform dependent external clock source 3. */
132 : : };
133 : :
134 : : #define RTE_EVENT_TIMER_ADAPTER_F_ADJUST_RES (1ULL << 0)
135 : : /**< The event timer adapter implementation may have constraints on the
136 : : * resolution (timer_tick_ns) and maximum timer expiry timeout(max_tmo_ns)
137 : : * based on the given timer adapter or system. If this flag is set, the
138 : : * implementation adjusts the resolution and maximum timeout to the best
139 : : * possible configuration. On successful timer adapter creation, the
140 : : * application can get the configured resolution and max timeout with
141 : : * ``rte_event_timer_adapter_get_info()``.
142 : : *
143 : : * @see struct rte_event_timer_adapter_info::min_resolution_ns
144 : : * @see struct rte_event_timer_adapter_info::max_tmo_ns
145 : : */
146 : : #define RTE_EVENT_TIMER_ADAPTER_F_SP_PUT (1ULL << 1)
147 : : /**< ``rte_event_timer_arm_burst()`` API to be used in single producer mode.
148 : : *
149 : : * @see struct rte_event_timer_adapter_conf::flags
150 : : */
151 : :
152 : : #define RTE_EVENT_TIMER_ADAPTER_F_PERIODIC (1ULL << 2)
153 : : /**< Flag to configure an event timer adapter in periodic mode; non-periodic
154 : : * mode is the default. A timer will fire once or periodically until the timer
155 : : * is cancelled based on the adapter mode.
156 : : *
157 : : * @see struct rte_event_timer_adapter_conf::flags
158 : : */
159 : :
160 : : /**
161 : : * Timer adapter configuration structure
162 : : */
163 : : struct rte_event_timer_adapter_conf {
164 : : uint8_t event_dev_id;
165 : : /**< Event device identifier */
166 : : uint16_t timer_adapter_id;
167 : : /**< Event timer adapter identifier */
168 : : uint32_t socket_id;
169 : : /**< Identifier of socket from which to allocate memory for adapter */
170 : : enum rte_event_timer_adapter_clk_src clk_src;
171 : : /**< Clock source for timer adapter */
172 : : uint64_t timer_tick_ns;
173 : : /**< Timer adapter resolution in ns */
174 : : uint64_t max_tmo_ns;
175 : : /**< Maximum timer timeout(expiry) in ns */
176 : : uint64_t nb_timers;
177 : : /**< Total number of timers per adapter */
178 : : uint64_t flags;
179 : : /**< Timer adapter config flags (RTE_EVENT_TIMER_ADAPTER_F_*) */
180 : : };
181 : :
182 : : /**
183 : : * Event timer adapter stats structure
184 : : */
185 : : struct rte_event_timer_adapter_stats {
186 : : uint64_t evtim_exp_count;
187 : : /**< Number of event timers that have expired. */
188 : : uint64_t ev_enq_count;
189 : : /**< Eventdev enqueue count */
190 : : uint64_t ev_inv_count;
191 : : /**< Invalid expiry event count */
192 : : uint64_t evtim_retry_count;
193 : : /**< Event timer retry count */
194 : : uint64_t adapter_tick_count;
195 : : /**< Tick count for the adapter, at its resolution */
196 : : uint64_t evtim_drop_count;
197 : : /**< event timer expiries dropped */
198 : : };
199 : :
200 : : struct rte_event_timer_adapter;
201 : :
202 : : /**
203 : : * Callback function type for producer port creation.
204 : : */
205 : : typedef int (*rte_event_timer_adapter_port_conf_cb_t)(uint16_t id,
206 : : uint8_t event_dev_id,
207 : : uint8_t *event_port_id,
208 : : void *conf_arg);
209 : :
210 : : /**
211 : : * Create an event timer adapter.
212 : : *
213 : : * This function must be invoked first before any other function in the API.
214 : : *
215 : : * When this API is used for creating adapter instance,
216 : : * ``rte_event_dev_config::nb_event_ports`` is automatically incremented,
217 : : * and the event device is reconfigured with additional event port during
218 : : * service initialization. This event device reconfigure logic also increments
219 : : * the ``rte_event_dev_config::nb_single_link_event_port_queues``
220 : : * parameter if the adapter event port config is of type
221 : : * ``RTE_EVENT_PORT_CFG_SINGLE_LINK``.
222 : : *
223 : : * Application no longer needs to account for
224 : : * ``rte_event_dev_config::nb_event_ports`` and
225 : : * ``rte_event_dev_config::nb_single_link_event_port_queues``
226 : : * parameters required for Timer adapter in event device configuration
227 : : * when the adapter is created with this API.
228 : : *
229 : : * @param conf
230 : : * The event timer adapter configuration structure.
231 : : *
232 : : * @return
233 : : * A pointer to the new allocated event timer adapter on success.
234 : : * NULL on error with rte_errno set appropriately.
235 : : * Possible rte_errno values include:
236 : : * - ERANGE: timer_tick_ns is not in supported range.
237 : : * - ENOMEM: unable to allocate sufficient memory for adapter instances
238 : : * - EINVAL: invalid event device identifier specified in config
239 : : * - ENOSPC: maximum number of adapters already created
240 : : * - EIO: event device reconfiguration and restart error. The adapter
241 : : * reconfigures the event device with an additional port by default if it is
242 : : * required to use a service to manage timers. If the device had been started
243 : : * before this call, this error code indicates an error in restart following
244 : : * an error in reconfiguration, i.e., a combination of the two error codes.
245 : : */
246 : : struct rte_event_timer_adapter *
247 : : rte_event_timer_adapter_create(const struct rte_event_timer_adapter_conf *conf);
248 : :
249 : : /**
250 : : * Create a timer adapter with the supplied callback.
251 : : *
252 : : * This function can be used to have a more granular control over the timer
253 : : * adapter creation. If a built-in port is absent, then the function uses the
254 : : * callback provided to create and get the port id to be used as a producer
255 : : * port.
256 : : *
257 : : * @param conf
258 : : * The timer adapter configuration structure
259 : : * @param conf_cb
260 : : * The port config callback function.
261 : : * @param conf_arg
262 : : * Opaque pointer to the argument for the callback function
263 : : *
264 : : * @return
265 : : * A pointer to the new allocated event timer adapter on success.
266 : : * NULL on error with rte_errno set appropriately.
267 : : * Possible rte_errno values include:
268 : : * - ERANGE: timer_tick_ns is not in supported range.
269 : : * - ENOMEM: unable to allocate sufficient memory for adapter instances
270 : : * - EINVAL: invalid event device identifier specified in config
271 : : * - ENOSPC: maximum number of adapters already created
272 : : */
273 : : struct rte_event_timer_adapter *
274 : : rte_event_timer_adapter_create_ext(
275 : : const struct rte_event_timer_adapter_conf *conf,
276 : : rte_event_timer_adapter_port_conf_cb_t conf_cb,
277 : : void *conf_arg);
278 : :
279 : : /**
280 : : * Timer adapter info structure.
281 : : */
282 : : struct rte_event_timer_adapter_info {
283 : : uint64_t min_resolution_ns;
284 : : /**< Minimum timer adapter resolution in ns */
285 : : uint64_t max_tmo_ns;
286 : : /**< Maximum timer timeout(expire) in ns */
287 : : struct rte_event_timer_adapter_conf conf;
288 : : /**< Configured timer adapter attributes */
289 : : uint32_t caps;
290 : : /**< Event timer adapter capabilities */
291 : : int16_t event_dev_port_id;
292 : : /**< Event device port ID, if applicable */
293 : : };
294 : :
295 : : /**
296 : : * Retrieve the contextual information of an event timer adapter.
297 : : *
298 : : * @param adapter
299 : : * A pointer to the event timer adapter structure.
300 : : *
301 : : * @param[out] adapter_info
302 : : * A pointer to a structure of type *rte_event_timer_adapter_info* to be
303 : : * filled with the contextual information of the adapter.
304 : : *
305 : : * @return
306 : : * - 0: Success, driver updates the contextual information of the
307 : : * timer adapter
308 : : * - <0: Error code returned by the driver info get function.
309 : : * - -EINVAL: adapter identifier invalid
310 : : *
311 : : * @see RTE_EVENT_TIMER_ADAPTER_F_ADJUST_RES,
312 : : * struct rte_event_timer_adapter_info
313 : : */
314 : : int
315 : : rte_event_timer_adapter_get_info(
316 : : const struct rte_event_timer_adapter *adapter,
317 : : struct rte_event_timer_adapter_info *adapter_info);
318 : :
319 : : /**
320 : : * Start a timer adapter.
321 : : *
322 : : * The adapter start step is the last one and consists of setting the timer
323 : : * adapter to start accepting the timers and schedules to event queues.
324 : : *
325 : : * On success, all basic functions exported by the API (timer arm,
326 : : * timer cancel and so on) can be invoked.
327 : : *
328 : : * @param adapter
329 : : * A pointer to the event timer adapter structure.
330 : : *
331 : : * @return
332 : : * - 0: Success, adapter started.
333 : : * - <0: Error code returned by the driver start function.
334 : : * - -EINVAL if adapter identifier invalid
335 : : * - -ENOENT if software adapter but no service core mapped
336 : : * - -ENOTSUP if software adapter and more than one service core mapped
337 : : * - -EALREADY if adapter has already been started
338 : : *
339 : : * @note
340 : : * The eventdev to which the event_timer_adapter is connected needs to
341 : : * be started before calling rte_event_timer_adapter_start().
342 : : */
343 : : int
344 : : rte_event_timer_adapter_start(
345 : : const struct rte_event_timer_adapter *adapter);
346 : :
347 : : /**
348 : : * Stop an event timer adapter.
349 : : *
350 : : * The adapter can be restarted with a call to
351 : : * ``rte_event_timer_adapter_start()``.
352 : : *
353 : : * @param adapter
354 : : * A pointer to the event timer adapter structure.
355 : : *
356 : : * @return
357 : : * - 0: Success, adapter stopped.
358 : : * - <0: Error code returned by the driver stop function.
359 : : * - -EINVAL if adapter identifier invalid
360 : : */
361 : : int
362 : : rte_event_timer_adapter_stop(const struct rte_event_timer_adapter *adapter);
363 : :
364 : : /**
365 : : * Lookup an event timer adapter using its identifier.
366 : : *
367 : : * If an event timer adapter was created in another process with the same
368 : : * identifier, this function will locate its state and set up access to it
369 : : * so that it can be used in this process.
370 : : *
371 : : * @param adapter_id
372 : : * The event timer adapter identifier.
373 : : *
374 : : * @return
375 : : * A pointer to the event timer adapter matching the identifier on success.
376 : : * NULL on error with rte_errno set appropriately.
377 : : * Possible rte_errno values include:
378 : : * - ENOENT - requested entry not available to return.
379 : : */
380 : : struct rte_event_timer_adapter *
381 : : rte_event_timer_adapter_lookup(uint16_t adapter_id);
382 : :
383 : : /**
384 : : * Free an event timer adapter.
385 : : *
386 : : * Destroy an event timer adapter, freeing all resources.
387 : : *
388 : : * Before invoking this function, the application must wait for all the
389 : : * armed timers to expire or cancel the outstanding armed timers.
390 : : *
391 : : * @param adapter
392 : : * A pointer to an event timer adapter structure.
393 : : *
394 : : * @return
395 : : * - 0: Successfully freed the event timer adapter resources.
396 : : * - <0: Failed to free the event timer adapter resources.
397 : : * - -EAGAIN: adapter is busy; timers outstanding
398 : : * - -EBUSY: stop hasn't been called for this adapter yet
399 : : * - -EINVAL: adapter id invalid, or adapter invalid
400 : : */
401 : : int
402 : : rte_event_timer_adapter_free(struct rte_event_timer_adapter *adapter);
403 : :
404 : : /**
405 : : * Retrieve the service ID of the event timer adapter. If the adapter doesn't
406 : : * use an rte_service function, this function returns -ESRCH.
407 : : *
408 : : * @param adapter
409 : : * A pointer to an event timer adapter.
410 : : *
411 : : * @param [out] service_id
412 : : * A pointer to a uint32_t, to be filled in with the service id.
413 : : *
414 : : * @return
415 : : * - 0: Success
416 : : * - <0: Error code on failure
417 : : * - -ESRCH: the adapter does not require a service to operate
418 : : */
419 : : int
420 : : rte_event_timer_adapter_service_id_get(struct rte_event_timer_adapter *adapter,
421 : : uint32_t *service_id);
422 : :
423 : : /**
424 : : * Retrieve statistics for an event timer adapter instance.
425 : : *
426 : : * @param adapter
427 : : * A pointer to an event timer adapter structure.
428 : : * @param[out] stats
429 : : * A pointer to a structure to fill with statistics.
430 : : *
431 : : * @return
432 : : * - 0: Successfully retrieved.
433 : : * - <0: Failure; error code returned.
434 : : */
435 : : int
436 : : rte_event_timer_adapter_stats_get(struct rte_event_timer_adapter *adapter,
437 : : struct rte_event_timer_adapter_stats *stats);
438 : :
439 : : /**
440 : : * Reset statistics for an event timer adapter instance.
441 : : *
442 : : * @param adapter
443 : : * A pointer to an event timer adapter structure.
444 : : *
445 : : * @return
446 : : * - 0: Successfully reset;
447 : : * - <0: Failure; error code returned.
448 : : */
449 : : int
450 : : rte_event_timer_adapter_stats_reset(struct rte_event_timer_adapter *adapter);
451 : :
452 : : /**
453 : : * Event timer state.
454 : : */
455 : : enum rte_event_timer_state {
456 : : RTE_EVENT_TIMER_NOT_ARMED = 0,
457 : : /**< Event timer not armed. */
458 : : RTE_EVENT_TIMER_ARMED = 1,
459 : : /**< Event timer successfully armed. */
460 : : RTE_EVENT_TIMER_CANCELED = 2,
461 : : /**< Event timer successfully canceled. */
462 : : RTE_EVENT_TIMER_ERROR = -1,
463 : : /**< Generic event timer error. */
464 : : RTE_EVENT_TIMER_ERROR_TOOEARLY = -2,
465 : : /**< Event timer timeout tick value is too small for the adapter to
466 : : * handle, given its configured resolution.
467 : : */
468 : : RTE_EVENT_TIMER_ERROR_TOOLATE = -3,
469 : : /**< Event timer timeout tick is greater than the maximum timeout.*/
470 : : };
471 : :
472 : : /**
473 : : * The generic *rte_event_timer* structure to hold the event timer attributes
474 : : * for arm and cancel operations.
475 : : */
476 : : struct __rte_cache_aligned rte_event_timer {
477 : : struct rte_event ev;
478 : : /**<
479 : : * Expiry event attributes. On successful event timer timeout,
480 : : * the following attributes will be used to inject the expiry event to
481 : : * the eventdev:
482 : : * - event_queue_id: Targeted event queue id for expiry events.
483 : : * - event_priority: Event priority of the event expiry event in the
484 : : * event queue relative to other events.
485 : : * - sched_type: Scheduling type of the expiry event.
486 : : * - flow_id: Flow id of the expiry event.
487 : : * - op: RTE_EVENT_OP_NEW
488 : : * - event_type: RTE_EVENT_TYPE_TIMER
489 : : */
490 : : uint64_t timeout_ticks;
491 : : /**< Expiry timer ticks expressed in number of *timer_ticks_ns* from
492 : : * now.
493 : : * @see struct rte_event_timer_adapter_info::adapter_conf::timer_tick_ns
494 : : */
495 : : uint64_t impl_opaque[2];
496 : : /**< Implementation-specific opaque data.
497 : : * An event timer adapter implementation use this field to hold
498 : : * implementation specific values to share between the arm and cancel
499 : : * operations. The application should not modify this field.
500 : : */
501 : : RTE_ATOMIC(enum rte_event_timer_state) state;
502 : : /**< State of the event timer. */
503 : : uint8_t user_meta[];
504 : : /**< Memory to store user specific metadata.
505 : : * The event timer adapter implementation should not modify this area.
506 : : */
507 : : };
508 : :
509 : : typedef uint16_t (*rte_event_timer_arm_burst_t)(
510 : : const struct rte_event_timer_adapter *adapter,
511 : : struct rte_event_timer **tims,
512 : : uint16_t nb_tims);
513 : : /**< @internal Enable event timers to enqueue timer events upon expiry */
514 : : typedef uint16_t (*rte_event_timer_arm_tmo_tick_burst_t)(
515 : : const struct rte_event_timer_adapter *adapter,
516 : : struct rte_event_timer **tims,
517 : : uint64_t timeout_tick,
518 : : uint16_t nb_tims);
519 : : /**< @internal Enable event timers with common expiration time */
520 : : typedef uint16_t (*rte_event_timer_cancel_burst_t)(
521 : : const struct rte_event_timer_adapter *adapter,
522 : : struct rte_event_timer **tims,
523 : : uint16_t nb_tims);
524 : : /**< @internal Prevent event timers from enqueuing timer events */
525 : :
526 : : /**
527 : : * @internal Data structure associated with each event timer adapter.
528 : : */
529 : : struct __rte_cache_aligned rte_event_timer_adapter {
530 : : rte_event_timer_arm_burst_t arm_burst;
531 : : /**< Pointer to driver arm_burst function. */
532 : : rte_event_timer_arm_tmo_tick_burst_t arm_tmo_tick_burst;
533 : : /**< Pointer to driver arm_tmo_tick_burst function. */
534 : : rte_event_timer_cancel_burst_t cancel_burst;
535 : : /**< Pointer to driver cancel function. */
536 : : struct rte_event_timer_adapter_data *data;
537 : : /**< Pointer to shared adapter data */
538 : : const struct event_timer_adapter_ops *ops;
539 : : /**< Functions exported by adapter driver */
540 : :
541 : : uint8_t allocated : 1;
542 : : /**< Flag to indicate that this adapter has been allocated */
543 : : };
544 : :
545 : : #define ADAPTER_VALID_OR_ERR_RET(adapter, retval) do { \
546 : : if (adapter == NULL || !adapter->allocated) \
547 : : return retval; \
548 : : } while (0)
549 : :
550 : : #define FUNC_PTR_OR_ERR_RET(func, errval) do { \
551 : : if ((func) == NULL) \
552 : : return errval; \
553 : : } while (0)
554 : :
555 : : #define FUNC_PTR_OR_NULL_RET_WITH_ERRNO(func, errval) do { \
556 : : if ((func) == NULL) { \
557 : : rte_errno = errval; \
558 : : return NULL; \
559 : : } \
560 : : } while (0)
561 : :
562 : : /**
563 : : * Arm a burst of event timers with separate expiration timeout tick for each
564 : : * event timer.
565 : : *
566 : : * Before calling this function, the application allocates
567 : : * ``struct rte_event_timer`` objects from mempool or huge page backed
568 : : * application buffers of desired size. On successful allocation,
569 : : * application updates the `struct rte_event_timer`` attributes such as
570 : : * expiry event attributes, timeout ticks from now.
571 : : * This function submits the event timer arm requests to the event timer adapter
572 : : * and on expiry, the events will be injected to designated event queue.
573 : : * Timer expiry events will be generated once or periodically until cancellation
574 : : * based on the adapter mode.
575 : : *
576 : : * @param adapter
577 : : * A pointer to an event timer adapter structure.
578 : : * @param evtims
579 : : * Pointer to an array of objects of type *rte_event_timer* structure.
580 : : * @param nb_evtims
581 : : * Number of event timers in the supplied array.
582 : : *
583 : : * @return
584 : : * The number of successfully armed event timers. The return value can be less
585 : : * than the value of the *nb_evtims* parameter. If the return value is less
586 : : * than *nb_evtims*, the remaining event timers at the end of *evtims*
587 : : * are not consumed, and the caller has to take care of them, and rte_errno
588 : : * is set accordingly. Possible errno values include:
589 : : * - EINVAL Invalid timer adapter, expiry event queue ID is invalid, or an
590 : : * expiry event's sched type doesn't match the capabilities of the
591 : : * destination event queue.
592 : : * - EAGAIN Specified timer adapter is not running
593 : : * - EALREADY A timer was encountered that was already armed
594 : : *
595 : : * @see RTE_EVENT_TIMER_ADAPTER_F_PERIODIC
596 : : */
597 : : static inline uint16_t
598 : : rte_event_timer_arm_burst(const struct rte_event_timer_adapter *adapter,
599 : : struct rte_event_timer **evtims,
600 : : uint16_t nb_evtims)
601 : : {
602 : : #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
603 : : ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL);
604 : : FUNC_PTR_OR_ERR_RET(adapter->arm_burst, -EINVAL);
605 : : #endif
606 : : rte_eventdev_trace_timer_arm_burst(adapter, (void **)evtims,
607 : : nb_evtims);
608 : 0 : return adapter->arm_burst(adapter, evtims, nb_evtims);
609 : : }
610 : :
611 : : /**
612 : : * Arm a burst of event timers with same expiration timeout tick.
613 : : *
614 : : * Provides the same functionality as ``rte_event_timer_arm_burst()``, except
615 : : * that application can use this API when all the event timers have the
616 : : * same timeout expiration tick. This specialized function can provide the
617 : : * additional hint to the adapter implementation and optimize if possible.
618 : : *
619 : : * @param adapter
620 : : * A pointer to an event timer adapter structure.
621 : : * @param evtims
622 : : * Points to an array of objects of type *rte_event_timer* structure.
623 : : * @param timeout_ticks
624 : : * The number of ticks in which the timers should expire.
625 : : * @param nb_evtims
626 : : * Number of event timers in the supplied array.
627 : : *
628 : : * @return
629 : : * The number of successfully armed event timers. The return value can be less
630 : : * than the value of the *nb_evtims* parameter. If the return value is less
631 : : * than *nb_evtims*, the remaining event timers at the end of *evtims*
632 : : * are not consumed, and the caller has to take care of them, and rte_errno
633 : : * is set accordingly. Possible errno values include:
634 : : * - EINVAL Invalid timer adapter, expiry event queue ID is invalid, or an
635 : : * expiry event's sched type doesn't match the capabilities of the
636 : : * destination event queue.
637 : : * - EAGAIN Specified event timer adapter is not running
638 : : * - EALREADY A timer was encountered that was already armed
639 : : */
640 : : static inline uint16_t
641 : : rte_event_timer_arm_tmo_tick_burst(
642 : : const struct rte_event_timer_adapter *adapter,
643 : : struct rte_event_timer **evtims,
644 : : const uint64_t timeout_ticks,
645 : : const uint16_t nb_evtims)
646 : : {
647 : : #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
648 : : ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL);
649 : : FUNC_PTR_OR_ERR_RET(adapter->arm_tmo_tick_burst, -EINVAL);
650 : : #endif
651 : : rte_eventdev_trace_timer_arm_tmo_tick_burst(adapter, timeout_ticks,
652 : : (void **)evtims, nb_evtims);
653 : 0 : return adapter->arm_tmo_tick_burst(adapter, evtims, timeout_ticks,
654 : : nb_evtims);
655 : : }
656 : :
657 : : /**
658 : : * Cancel a burst of event timers from being scheduled to the event device.
659 : : *
660 : : * @param adapter
661 : : * A pointer to an event timer adapter structure.
662 : : * @param evtims
663 : : * Points to an array of objects of type *rte_event_timer* structure
664 : : * @param nb_evtims
665 : : * Number of event timer instances in the supplied array.
666 : : *
667 : : * @return
668 : : * The number of successfully canceled event timers. The return value can be
669 : : * less than the value of the *nb_evtims* parameter. If the return value is
670 : : * less than *nb_evtims*, the remaining event timers at the end of *evtims*
671 : : * are not consumed, and the caller has to take care of them, and rte_errno
672 : : * is set accordingly. Possible errno values include:
673 : : * - EINVAL Invalid timer adapter identifier
674 : : * - EAGAIN Specified timer adapter is not running
675 : : * - EALREADY A timer was encountered that was already canceled
676 : : */
677 : : static inline uint16_t
678 : : rte_event_timer_cancel_burst(const struct rte_event_timer_adapter *adapter,
679 : : struct rte_event_timer **evtims,
680 : : uint16_t nb_evtims)
681 : : {
682 : : #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
683 : : ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL);
684 : : FUNC_PTR_OR_ERR_RET(adapter->cancel_burst, -EINVAL);
685 : : #endif
686 : : rte_eventdev_trace_timer_cancel_burst(adapter, (void **)evtims,
687 : : nb_evtims);
688 : 0 : return adapter->cancel_burst(adapter, evtims, nb_evtims);
689 : : }
690 : :
691 : : /**
692 : : * Get the number of ticks remaining until event timer expiry.
693 : : *
694 : : * @param adapter
695 : : * A pointer to an event timer adapter structure
696 : : * @param evtim
697 : : * A pointer to an rte_event_timer structure
698 : : * @param[out] ticks_remaining
699 : : * Pointer to variable into which to write the number of ticks remaining
700 : : * until event timer expiry
701 : : *
702 : : * @return
703 : : * - 0: Success
704 : : * - -EINVAL Invalid timer adapter identifier or the event timer is not in
705 : : * the armed state or ticks_remaining is NULL
706 : : * - -ENOTSUP The timer adapter implementation does not support this API.
707 : : */
708 : : __rte_experimental
709 : : int
710 : : rte_event_timer_remaining_ticks_get(
711 : : const struct rte_event_timer_adapter *adapter,
712 : : const struct rte_event_timer *evtim,
713 : : uint64_t *ticks_remaining);
714 : :
715 : : #ifdef __cplusplus
716 : : }
717 : : #endif
718 : :
719 : : #endif /* __RTE_EVENT_TIMER_ADAPTER_H__ */
|
