db98dec46b856df2b00ea5d9ae6a61a9cec9691b
[dpdk.git] / lib / librte_eventdev / rte_event_timer_adapter.h
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 #ifdef __cplusplus
111 extern "C" {
112 #endif
113
114 #include <rte_spinlock.h>
115 #include <rte_memory.h>
116
117 #include "rte_eventdev.h"
118
119 /**
120  * @warning
121  * @b EXPERIMENTAL: this enum may change without prior notice
122  *
123  * Timer adapter clock source
124  */
125 enum rte_event_timer_adapter_clk_src {
126         RTE_EVENT_TIMER_ADAPTER_CPU_CLK,
127         /**< Use CPU clock as the clock source. */
128         RTE_EVENT_TIMER_ADAPTER_EXT_CLK0,
129         /**< Platform dependent external clock source 0. */
130         RTE_EVENT_TIMER_ADAPTER_EXT_CLK1,
131         /**< Platform dependent external clock source 1. */
132         RTE_EVENT_TIMER_ADAPTER_EXT_CLK2,
133         /**< Platform dependent external clock source 2. */
134         RTE_EVENT_TIMER_ADAPTER_EXT_CLK3,
135         /**< Platform dependent external clock source 3. */
136 };
137
138 #define RTE_EVENT_TIMER_ADAPTER_F_ADJUST_RES    (1ULL << 0)
139 /**< The event timer adapter implementation may have constraints on the
140  * resolution (timer_tick_ns) and maximum timer expiry timeout(max_tmo_ns)
141  * based on the given timer adapter or system. If this flag is set, the
142  * implementation adjusts the resolution and maximum timeout to the best
143  * possible configuration. On successful timer adapter creation, the
144  * application can get the configured resolution and max timeout with
145  * ``rte_event_timer_adapter_get_info()``.
146  *
147  * @see struct rte_event_timer_adapter_info::min_resolution_ns
148  * @see struct rte_event_timer_adapter_info::max_tmo_ns
149  */
150 #define RTE_EVENT_TIMER_ADAPTER_F_SP_PUT        (1ULL << 1)
151 /**< ``rte_event_timer_arm_burst()`` API to be used in single producer mode.
152  *
153  * @see struct rte_event_timer_adapter_conf::flags
154  */
155
156 /**
157  * @warning
158  * @b EXPERIMENTAL: this structure may change without prior notice
159  *
160  * Timer adapter configuration structure
161  */
162 struct rte_event_timer_adapter_conf {
163         uint8_t event_dev_id;
164         /**< Event device identifier */
165         uint16_t timer_adapter_id;
166         /**< Event timer adapter identifier */
167         uint32_t socket_id;
168         /**< Identifier of socket from which to allocate memory for adapter */
169         enum rte_event_timer_adapter_clk_src clk_src;
170         /**< Clock source for timer adapter */
171         uint64_t timer_tick_ns;
172         /**< Timer adapter resolution in ns */
173         uint64_t max_tmo_ns;
174         /**< Maximum timer timeout(expiry) in ns */
175         uint64_t nb_timers;
176         /**< Total number of timers per adapter */
177         uint64_t flags;
178         /**< Timer adapter config flags (RTE_EVENT_TIMER_ADAPTER_F_*) */
179 };
180
181 /**
182  * @warning
183  * @b EXPERIMENTAL: this structure may change without prior notice
184  *
185  * Event timer adapter stats structure
186  */
187 struct rte_event_timer_adapter_stats {
188         uint64_t evtim_exp_count;
189         /**< Number of event timers that have expired. */
190         uint64_t ev_enq_count;
191         /**< Eventdev enqueue count */
192         uint64_t ev_inv_count;
193         /**< Invalid expiry event count */
194         uint64_t evtim_retry_count;
195         /**< Event timer retry count */
196         uint64_t adapter_tick_count;
197         /**< Tick count for the adapter, at its resolution */
198 };
199
200 struct rte_event_timer_adapter;
201
202 /**
203  * @warning
204  * @b EXPERIMENTAL: this API may change without prior notice
205  *
206  * Callback function type for producer port creation.
207  */
208 typedef int (*rte_event_timer_adapter_port_conf_cb_t)(uint16_t id,
209                                                       uint8_t event_dev_id,
210                                                       uint8_t *event_port_id,
211                                                       void *conf_arg);
212
213 /**
214  * @warning
215  * @b EXPERIMENTAL: this API may change without prior notice
216  *
217  * Create an event timer adapter.
218  *
219  * This function must be invoked first before any other function in the API.
220  *
221  * @param conf
222  *   The event timer adapter configuration structure.
223  *
224  * @return
225  *   A pointer to the new allocated event timer adapter on success.
226  *   NULL on error with rte_errno set appropriately.
227  *   Possible rte_errno values include:
228  *   - ERANGE: timer_tick_ns is not in supported range.
229  *   - ENOMEM: unable to allocate sufficient memory for adapter instances
230  *   - EINVAL: invalid event device identifier specified in config
231  *   - ENOSPC: maximum number of adapters already created
232  *   - EIO: event device reconfiguration and restart error.  The adapter
233  *   reconfigures the event device with an additional port by default if it is
234  *   required to use a service to manage timers. If the device had been started
235  *   before this call, this error code indicates an error in restart following
236  *   an error in reconfiguration, i.e., a combination of the two error codes.
237  */
238 struct rte_event_timer_adapter * __rte_experimental
239 rte_event_timer_adapter_create(const struct rte_event_timer_adapter_conf *conf);
240
241 /**
242  * @warning
243  * @b EXPERIMENTAL: this API may change without prior notice
244  *
245  * Create a timer adapter with the supplied callback.
246  *
247  * This function can be used to have a more granular control over the timer
248  * adapter creation.  If a built-in port is absent, then the function uses the
249  * callback provided to create and get the port id to be used as a producer
250  * port.
251  *
252  * @param conf
253  *   The timer adapter configuration structure
254  * @param conf_cb
255  *   The port config callback function.
256  * @param conf_arg
257  *   Opaque pointer to the argument for the callback function
258  *
259  * @return
260  *   A pointer to the new allocated event timer adapter on success.
261  *   NULL on error with rte_errno set appropriately.
262  *   Possible rte_errno values include:
263  *   - ERANGE: timer_tick_ns is not in supported range.
264  *   - ENOMEM: unable to allocate sufficient memory for adapter instances
265  *   - EINVAL: invalid event device identifier specified in config
266  *   - ENOSPC: maximum number of adapters already created
267  */
268 struct rte_event_timer_adapter * __rte_experimental
269 rte_event_timer_adapter_create_ext(
270                 const struct rte_event_timer_adapter_conf *conf,
271                 rte_event_timer_adapter_port_conf_cb_t conf_cb,
272                 void *conf_arg);
273
274 /**
275  * @warning
276  * @b EXPERIMENTAL: this structure may change without prior notice
277  *
278  * Timer adapter info structure.
279  */
280 struct rte_event_timer_adapter_info {
281         uint64_t min_resolution_ns;
282         /**< Minimum timer adapter resolution in ns */
283         uint64_t max_tmo_ns;
284         /**< Maximum timer timeout(expire) in ns */
285         struct rte_event_timer_adapter_conf conf;
286         /**< Configured timer adapter attributes */
287         uint32_t caps;
288         /**< Event timer adapter capabilities */
289         int16_t event_dev_port_id;
290         /**< Event device port ID, if applicable */
291 };
292
293 /**
294  * @warning
295  * @b EXPERIMENTAL: this API may change without prior notice
296  *
297  * Retrieve the contextual information of an event timer adapter.
298  *
299  * @param adapter
300  *   A pointer to the event timer adapter structure.
301  *
302  * @param[out] adapter_info
303  *   A pointer to a structure of type *rte_event_timer_adapter_info* to be
304  *   filled with the contextual information of the adapter.
305  *
306  * @return
307  *   - 0: Success, driver updates the contextual information of the
308  *   timer adapter
309  *   - <0: Error code returned by the driver info get function.
310  *   - -EINVAL: adapter identifier invalid
311  *
312  * @see RTE_EVENT_TIMER_ADAPTER_F_ADJUST_RES,
313  *   struct rte_event_timer_adapter_info
314  *
315  */
316 int __rte_experimental
317 rte_event_timer_adapter_get_info(
318                 const struct rte_event_timer_adapter *adapter,
319                 struct rte_event_timer_adapter_info *adapter_info);
320
321 /**
322  * @warning
323  * @b EXPERIMENTAL: this API may change without prior notice
324  *
325  * Start a timer adapter.
326  *
327  * The adapter start step is the last one and consists of setting the timer
328  * adapter to start accepting the timers and schedules to event queues.
329  *
330  * On success, all basic functions exported by the API (timer arm,
331  * timer cancel and so on) can be invoked.
332  *
333  * @param adapter
334  *   A pointer to the event timer adapter structure.
335  *
336  * @return
337  *   - 0: Success, adapter started.
338  *   - <0: Error code returned by the driver start function.
339  *   - -EINVAL if adapter identifier invalid
340  *   - -ENOENT if software adapter but no service core mapped
341  *   - -ENOTSUP if software adapter and more than one service core mapped
342  */
343 int __rte_experimental
344 rte_event_timer_adapter_start(
345                 const struct rte_event_timer_adapter *adapter);
346
347 /**
348  * @warning
349  * @b EXPERIMENTAL: this API may change without prior notice
350  *
351  * Stop an event timer adapter.
352  *
353  * The adapter can be restarted with a call to
354  * ``rte_event_timer_adapter_start()``.
355  *
356  * @param adapter
357  *   A pointer to the event timer adapter structure.
358  *
359  * @return
360  *   - 0: Success, adapter stopped.
361  *   - <0: Error code returned by the driver stop function.
362  *   - -EINVAL if adapter identifier invalid
363  */
364 int __rte_experimental
365 rte_event_timer_adapter_stop(const struct rte_event_timer_adapter *adapter);
366
367 /**
368  * @warning
369  * @b EXPERIMENTAL: this API may change without prior notice
370  *
371  * Lookup an event timer adapter using its identifier.
372  *
373  * If an event timer adapter was created in another process with the same
374  * identifier, this function will locate its state and set up access to it
375  * so that it can be used in this process.
376  *
377  * @param adapter_id
378  *  The event timer adapter identifier.
379  *
380  * @return
381  *  A pointer to the event timer adapter matching the identifier on success.
382  *  NULL on error with rte_errno set appropriately.
383  *  Possible rte_errno values include:
384  *   - ENOENT - requested entry not available to return.
385  */
386 struct rte_event_timer_adapter * __rte_experimental
387 rte_event_timer_adapter_lookup(uint16_t adapter_id);
388
389 /**
390  * @warning
391  * @b EXPERIMENTAL: this API may change without prior notice
392  *
393  * Free an event timer adapter.
394  *
395  * Destroy an event timer adapter, freeing all resources.
396  *
397  * Before invoking this function, the application must wait for all the
398  * armed timers to expire or cancel the outstanding armed timers.
399  *
400  * @param adapter
401  *   A pointer to an event timer adapter structure.
402  *
403  * @return
404  *   - 0: Successfully freed the event timer adapter resources.
405  *   - <0: Failed to free the event timer adapter resources.
406  *   - -EAGAIN:  adapter is busy; timers outstanding
407  *   - -EBUSY: stop hasn't been called for this adapter yet
408  *   - -EINVAL: adapter id invalid, or adapter invalid
409  */
410 int __rte_experimental
411 rte_event_timer_adapter_free(struct rte_event_timer_adapter *adapter);
412
413 /**
414  * Retrieve the service ID of the event timer adapter. If the adapter doesn't
415  * use an rte_service function, this function returns -ESRCH.
416  *
417  * @param adapter
418  *   A pointer to an event timer adapter.
419  *
420  * @param [out] service_id
421  *   A pointer to a uint32_t, to be filled in with the service id.
422  *
423  * @return
424  *   - 0: Success
425  *   - <0: Error code on failure
426  *   - -ESRCH: the adapter does not require a service to operate
427  */
428 int __rte_experimental
429 rte_event_timer_adapter_service_id_get(struct rte_event_timer_adapter *adapter,
430                                        uint32_t *service_id);
431
432 /**
433  * @warning
434  * @b EXPERIMENTAL: this API may change without prior notice
435  *
436  * Retrieve statistics for an event timer adapter instance.
437  *
438  * @param adapter
439  *   A pointer to an event timer adapter structure.
440  * @param[out] stats
441  *   A pointer to a structure to fill with statistics.
442  *
443  * @return
444  *   - 0: Successfully retrieved.
445  *   - <0: Failure; error code returned.
446  */
447 int __rte_experimental
448 rte_event_timer_adapter_stats_get(struct rte_event_timer_adapter *adapter,
449                 struct rte_event_timer_adapter_stats *stats);
450
451 /**
452  * @warning
453  * @b EXPERIMENTAL: this API may change without prior notice
454  *
455  * Reset statistics for an event timer adapter instance.
456  *
457  * @param adapter
458  *   A pointer to an event timer adapter structure.
459  *
460  * @return
461  *   - 0: Successfully reset;
462  *   - <0: Failure; error code returned.
463  */
464 int __rte_experimental
465 rte_event_timer_adapter_stats_reset(struct rte_event_timer_adapter *adapter);
466
467 /**
468  * @warning
469  * @b EXPERIMENTAL: this structure may change without prior notice
470  *
471  * Event timer state.
472  */
473 enum rte_event_timer_state {
474         RTE_EVENT_TIMER_NOT_ARMED       = 0,
475         /**< Event timer not armed. */
476         RTE_EVENT_TIMER_ARMED           = 1,
477         /**< Event timer successfully armed. */
478         RTE_EVENT_TIMER_CANCELED        = 2,
479         /**< Event timer successfully canceled. */
480         RTE_EVENT_TIMER_ERROR           = -1,
481         /**< Generic event timer error. */
482         RTE_EVENT_TIMER_ERROR_TOOEARLY  = -2,
483         /**< Event timer timeout tick value is too small for the adapter to
484          * handle, given its configured resolution.
485          */
486         RTE_EVENT_TIMER_ERROR_TOOLATE   = -3,
487         /**< Event timer timeout tick is greater than the maximum timeout.*/
488 };
489
490 /**
491  * @warning
492  * @b EXPERIMENTAL: this structure may change without prior notice
493  *
494  * The generic *rte_event_timer* structure to hold the event timer attributes
495  * for arm and cancel operations.
496  */
497 RTE_STD_C11
498 struct rte_event_timer {
499         struct rte_event ev;
500         /**<
501          * Expiry event attributes.  On successful event timer timeout,
502          * the following attributes will be used to inject the expiry event to
503          * the eventdev:
504          *  - event_queue_id: Targeted event queue id for expiry events.
505          *  - event_priority: Event priority of the event expiry event in the
506          *  event queue relative to other events.
507          *  - sched_type: Scheduling type of the expiry event.
508          *  - flow_id: Flow id of the expiry event.
509          *  - op: RTE_EVENT_OP_NEW
510          *  - event_type: RTE_EVENT_TYPE_TIMER
511          */
512         volatile enum rte_event_timer_state state;
513         /**< State of the event timer. */
514         uint64_t timeout_ticks;
515         /**< Expiry timer ticks expressed in number of *timer_ticks_ns* from
516          * now.
517          * @see struct rte_event_timer_adapter_info::adapter_conf::timer_tick_ns
518          */
519         uint64_t impl_opaque[2];
520         /**< Implementation-specific opaque data.
521          * An event timer adapter implementation use this field to hold
522          * implementation specific values to share between the arm and cancel
523          * operations.  The application should not modify this field.
524          */
525         uint8_t user_meta[0];
526         /**< Memory to store user specific metadata.
527          * The event timer adapter implementation should not modify this area.
528          */
529 } __rte_cache_aligned;
530
531 typedef uint16_t (*rte_event_timer_arm_burst_t)(
532                 const struct rte_event_timer_adapter *adapter,
533                 struct rte_event_timer **tims,
534                 uint16_t nb_tims);
535 /**< @internal Enable event timers to enqueue timer events upon expiry */
536 typedef uint16_t (*rte_event_timer_arm_tmo_tick_burst_t)(
537                 const struct rte_event_timer_adapter *adapter,
538                 struct rte_event_timer **tims,
539                 uint64_t timeout_tick,
540                 uint16_t nb_tims);
541 /**< @internal Enable event timers with common expiration time */
542 typedef uint16_t (*rte_event_timer_cancel_burst_t)(
543                 const struct rte_event_timer_adapter *adapter,
544                 struct rte_event_timer **tims,
545                 uint16_t nb_tims);
546 /**< @internal Prevent event timers from enqueuing timer events */
547
548 /**
549  * @internal Data structure associated with each event timer adapter.
550  */
551 struct rte_event_timer_adapter {
552         rte_event_timer_arm_burst_t arm_burst;
553         /**< Pointer to driver arm_burst function. */
554         rte_event_timer_arm_tmo_tick_burst_t arm_tmo_tick_burst;
555         /**< Pointer to driver arm_tmo_tick_burst function. */
556         rte_event_timer_cancel_burst_t cancel_burst;
557         /**< Pointer to driver cancel function. */
558         struct rte_event_timer_adapter_data *data;
559         /**< Pointer to shared adapter data */
560         const struct rte_event_timer_adapter_ops *ops;
561         /**< Functions exported by adapter driver */
562
563         RTE_STD_C11
564         uint8_t allocated : 1;
565         /**< Flag to indicate that this adapter has been allocated */
566 } __rte_cache_aligned;
567
568 #define ADAPTER_VALID_OR_ERR_RET(adapter, retval) do {          \
569         if (adapter == NULL || !adapter->allocated)             \
570                 return retval;                                  \
571 } while (0)
572
573 #define FUNC_PTR_OR_ERR_RET(func, errval) do {                  \
574         if ((func) == NULL)                                     \
575                 return errval;                                  \
576 } while (0)
577
578 #define FUNC_PTR_OR_NULL_RET_WITH_ERRNO(func, errval) do {      \
579         if ((func) == NULL) {                                   \
580                 rte_errno = errval;                             \
581                 return NULL;                                    \
582         }                                                       \
583 } while (0)
584
585 /**
586  * @warning
587  * @b EXPERIMENTAL: this API may change without prior notice
588  *
589  * Arm a burst of event timers with separate expiration timeout tick for each
590  * event timer.
591  *
592  * Before calling this function, the application allocates
593  * ``struct rte_event_timer`` objects from mempool or huge page backed
594  * application buffers of desired size. On successful allocation,
595  * application updates the `struct rte_event_timer`` attributes such as
596  * expiry event attributes, timeout ticks from now.
597  * This function submits the event timer arm requests to the event timer adapter
598  * and on expiry, the events will be injected to designated event queue.
599  *
600  * @param adapter
601  *   A pointer to an event timer adapter structure.
602  * @param evtims
603  *   Pointer to an array of objects of type *rte_event_timer* structure.
604  * @param nb_evtims
605  *   Number of event timers in the supplied array.
606  *
607  * @return
608  *   The number of successfully armed event timers. The return value can be less
609  *   than the value of the *nb_evtims* parameter. If the return value is less
610  *   than *nb_evtims*, the remaining event timers at the end of *evtims*
611  *   are not consumed, and the caller has to take care of them, and rte_errno
612  *   is set accordingly. Possible errno values include:
613  *   - EINVAL Invalid timer adapter, expiry event queue ID is invalid, or an
614  *   expiry event's sched type doesn't match the capabilities of the
615  *   destination event queue.
616  *   - EAGAIN Specified timer adapter is not running
617  *   - EALREADY A timer was encountered that was already armed
618  */
619 static inline uint16_t __rte_experimental
620 rte_event_timer_arm_burst(const struct rte_event_timer_adapter *adapter,
621                           struct rte_event_timer **evtims,
622                           uint16_t nb_evtims)
623 {
624 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
625         ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL);
626         FUNC_PTR_OR_ERR_RET(adapter->arm_burst, -EINVAL);
627 #endif
628         return adapter->arm_burst(adapter, evtims, nb_evtims);
629 }
630
631 /**
632  * @warning
633  * @b EXPERIMENTAL: this API may change without prior notice
634  *
635  * Arm a burst of event timers with same expiration timeout tick.
636  *
637  * Provides the same functionality as ``rte_event_timer_arm_burst()``, except
638  * that application can use this API when all the event timers have the
639  * same timeout expiration tick. This specialized function can provide the
640  * additional hint to the adapter implementation and optimize if possible.
641  *
642  * @param adapter
643  *   A pointer to an event timer adapter structure.
644  * @param evtims
645  *   Points to an array of objects of type *rte_event_timer* structure.
646  * @param timeout_ticks
647  *   The number of ticks in which the timers should expire.
648  * @param nb_evtims
649  *   Number of event timers in the supplied array.
650  *
651  * @return
652  *   The number of successfully armed event timers. The return value can be less
653  *   than the value of the *nb_evtims* parameter. If the return value is less
654  *   than *nb_evtims*, the remaining event timers at the end of *evtims*
655  *   are not consumed, and the caller has to take care of them, and rte_errno
656  *   is set accordingly. Possible errno values include:
657  *   - EINVAL Invalid timer adapter, expiry event queue ID is invalid, or an
658  *   expiry event's sched type doesn't match the capabilities of the
659  *   destination event queue.
660  *   - EAGAIN Specified event timer adapter is not running
661  *   - EALREADY A timer was encountered that was already armed
662  */
663 static inline uint16_t __rte_experimental
664 rte_event_timer_arm_tmo_tick_burst(
665                         const struct rte_event_timer_adapter *adapter,
666                         struct rte_event_timer **evtims,
667                         const uint64_t timeout_ticks,
668                         const uint16_t nb_evtims)
669 {
670 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
671         ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL);
672         FUNC_PTR_OR_ERR_RET(adapter->arm_tmo_tick_burst, -EINVAL);
673 #endif
674         return adapter->arm_tmo_tick_burst(adapter, evtims, timeout_ticks,
675                                            nb_evtims);
676 }
677
678 /**
679  * @warning
680  * @b EXPERIMENTAL: this API may change without prior notice
681  *
682  * Cancel a burst of event timers from being scheduled to the event device.
683  *
684  * @param adapter
685  *   A pointer to an event timer adapter structure.
686  * @param evtims
687  *   Points to an array of objects of type *rte_event_timer* structure
688  * @param nb_evtims
689  *   Number of event timer instances in the supplied array.
690  *
691  * @return
692  *   The number of successfully canceled event timers. The return value can be
693  *   less than the value of the *nb_evtims* parameter. If the return value is
694  *   less than *nb_evtims*, the remaining event timers at the end of *evtims*
695  *   are not consumed, and the caller has to take care of them, and rte_errno
696  *   is set accordingly. Possible errno values include:
697  *   - EINVAL Invalid timer adapter identifier
698  *   - EAGAIN Specified timer adapter is not running
699  *   - EALREADY  A timer was encountered that was already canceled
700  */
701 static inline uint16_t __rte_experimental
702 rte_event_timer_cancel_burst(const struct rte_event_timer_adapter *adapter,
703                              struct rte_event_timer **evtims,
704                              uint16_t nb_evtims)
705 {
706 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
707         ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL);
708         FUNC_PTR_OR_ERR_RET(adapter->cancel_burst, -EINVAL);
709 #endif
710         return adapter->cancel_burst(adapter, evtims, nb_evtims);
711 }
712
713 #endif /* __RTE_EVENT_TIMER_ADAPTER_H__ */