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 rte_event_timer_adapter_stats_reset( 465 struct rte_event_timer_adapter *adapter); 466 467 /** 468 * Retrieve the service ID of the event timer adapter. If the adapter doesn't 469 * use an rte_service function, this function returns -ESRCH. 470 * 471 * @param adapter 472 * A pointer to an event timer adapter. 473 * 474 * @param [out] service_id 475 * A pointer to a uint32_t, to be filled in with the service id. 476 * 477 * @return 478 * - 0: Success 479 * - <0: Error code on failure, if the event dev doesn't use a rte_service 480 * function, this function returns -ESRCH. 481 */ 482 int 483 rte_event_timer_adapter_service_id_get(struct rte_event_timer_adapter *adapter, 484 uint32_t *service_id); 485 486 /** 487 * @warning 488 * @b EXPERIMENTAL: this API may change without prior notice 489 * 490 * Retrieve statistics for an event timer adapter instance. 491 * 492 * @param adapter 493 * A pointer to an event timer adapter structure. 494 * @param[out] stats 495 * A pointer to a structure to fill with statistics. 496 * 497 * @return 498 * - 0: Successfully retrieved. 499 * - <0: Failure; error code returned. 500 */ 501 int rte_event_timer_adapter_stats_get(struct rte_event_timer_adapter *adapter, 502 struct rte_event_timer_adapter_stats *stats); 503 504 /** 505 * @warning 506 * @b EXPERIMENTAL: this API may change without prior notice 507 * 508 * Reset statistics for an event timer adapter instance. 509 * 510 * @param adapter 511 * A pointer to an event timer adapter structure. 512 * 513 * @return 514 * - 0: Successfully reset; 515 * - <0: Failure; error code returned. 516 */ 517 int rte_event_timer_adapter_stats_reset( 518 struct rte_event_timer_adapter *adapter); 519 520 /** 521 * @warning 522 * @b EXPERIMENTAL: this structure may change without prior notice 523 * 524 * Event timer state. 525 */ 526 enum rte_event_timer_state { 527 RTE_EVENT_TIMER_NOT_ARMED = 0, 528 /**< Event timer not armed. */ 529 RTE_EVENT_TIMER_ARMED = 1, 530 /**< Event timer successfully armed. */ 531 RTE_EVENT_TIMER_CANCELED = 2, 532 /**< Event timer successfully canceled. */ 533 RTE_EVENT_TIMER_ERROR = -1, 534 /**< Generic event timer error. */ 535 RTE_EVENT_TIMER_ERROR_TOOEARLY = -2, 536 /**< Event timer timeout tick value is too small for the adapter to 537 * handle, given its configured resolution. 538 */ 539 RTE_EVENT_TIMER_ERROR_TOOLATE = -3, 540 /**< Event timer timeout tick is greater than the maximum timeout.*/ 541 }; 542 543 /** 544 * @warning 545 * @b EXPERIMENTAL: this structure may change without prior notice 546 * 547 * The generic *rte_event_timer* structure to hold the event timer attributes 548 * for arm and cancel operations. 549 */ 550 RTE_STD_C11 551 struct rte_event_timer { 552 struct rte_event ev; 553 /**< 554 * Expiry event attributes. On successful event timer timeout, 555 * the following attributes will be used to inject the expiry event to 556 * the eventdev: 557 * - event_queue_id: Targeted event queue id for expiry events. 558 * - event_priority: Event priority of the event expiry event in the 559 * event queue relative to other events. 560 * - sched_type: Scheduling type of the expiry event. 561 * - flow_id: Flow id of the expiry event. 562 * - op: RTE_EVENT_OP_NEW 563 * - event_type: RTE_EVENT_TYPE_TIMER 564 */ 565 volatile enum rte_event_timer_state state; 566 /**< State of the event timer. */ 567 uint64_t timeout_ticks; 568 /**< Expiry timer ticks expressed in number of *timer_ticks_ns* from 569 * now. 570 * @see struct rte_event_timer_adapter_info::adapter_conf::timer_tick_ns 571 */ 572 uint64_t impl_opaque[2]; 573 /**< Implementation-specific opaque data. 574 * An event timer adapter implementation use this field to hold 575 * implementation specific values to share between the arm and cancel 576 * operations. The application should not modify this field. 577 */ 578 uint8_t user_meta[0]; 579 /**< Memory to store user specific metadata. 580 * The event timer adapter implementation should not modify this area. 581 */ 582 } __rte_cache_aligned; 583 584 typedef uint16_t (*rte_event_timer_arm_burst_t)( 585 const struct rte_event_timer_adapter *adapter, 586 struct rte_event_timer **tims, 587 uint16_t nb_tims); 588 /**< @internal Enable event timers to enqueue timer events upon expiry */ 589 typedef uint16_t (*rte_event_timer_arm_tmo_tick_burst_t)( 590 const struct rte_event_timer_adapter *adapter, 591 struct rte_event_timer **tims, 592 uint64_t timeout_tick, 593 uint16_t nb_tims); 594 /**< @internal Enable event timers with common expiration time */ 595 typedef uint16_t (*rte_event_timer_cancel_burst_t)( 596 const struct rte_event_timer_adapter *adapter, 597 struct rte_event_timer **tims, 598 uint16_t nb_tims); 599 /**< @internal Prevent event timers from enqueuing timer events */ 600 601 /** 602 * @internal Data structure associated with each event timer adapter. 603 */ 604 struct rte_event_timer_adapter { 605 rte_event_timer_arm_burst_t arm_burst; 606 /**< Pointer to driver arm_burst function. */ 607 rte_event_timer_arm_tmo_tick_burst_t arm_tmo_tick_burst; 608 /**< Pointer to driver arm_tmo_tick_burst function. */ 609 rte_event_timer_cancel_burst_t cancel_burst; 610 /**< Pointer to driver cancel function. */ 611 struct rte_event_timer_adapter_data *data; 612 /**< Pointer to shared adapter data */ 613 const struct rte_event_timer_adapter_ops *ops; 614 /**< Functions exported by adapter driver */ 615 616 RTE_STD_C11 617 uint8_t allocated : 1; 618 /**< Flag to indicate that this adapter has been allocated */ 619 } __rte_cache_aligned; 620 621 #define ADAPTER_VALID_OR_ERR_RET(adapter, retval) do { \ 622 if (adapter == NULL || !adapter->allocated) \ 623 return retval; \ 624 } while (0) 625 626 #define FUNC_PTR_OR_ERR_RET(func, errval) do { \ 627 if ((func) == NULL) \ 628 return errval; \ 629 } while (0) 630 631 #define FUNC_PTR_OR_NULL_RET_WITH_ERRNO(func, errval) do { \ 632 if ((func) == NULL) { \ 633 rte_errno = errval; \ 634 return NULL; \ 635 } \ 636 } while (0) 637 638 /** 639 * @warning 640 * @b EXPERIMENTAL: this API may change without prior notice 641 * 642 * Arm a burst of event timers with separate expiration timeout tick for each 643 * event timer. 644 * 645 * Before calling this function, the application allocates 646 * ``struct rte_event_timer`` objects from mempool or huge page backed 647 * application buffers of desired size. On successful allocation, 648 * application updates the `struct rte_event_timer`` attributes such as 649 * expiry event attributes, timeout ticks from now. 650 * This function submits the event timer arm requests to the event timer adapter 651 * and on expiry, the events will be injected to designated event queue. 652 * 653 * @param adapter 654 * A pointer to an event timer adapter structure. 655 * @param evtims 656 * Pointer to an array of objects of type *rte_event_timer* structure. 657 * @param nb_evtims 658 * Number of event timers in the supplied array. 659 * 660 * @return 661 * The number of successfully armed event timers. The return value can be less 662 * than the value of the *nb_evtims* parameter. If the return value is less 663 * than *nb_evtims*, the remaining event timers at the end of *evtims* 664 * are not consumed, and the caller has to take care of them, and rte_errno 665 * is set accordingly. Possible errno values include: 666 * - EINVAL Invalid timer adapter, expiry event queue ID is invalid, or an 667 * expiry event's sched type doesn't match the capabilities of the 668 * destination event queue. 669 * - EAGAIN Specified timer adapter is not running 670 * - EALREADY A timer was encountered that was already armed 671 */ 672 static inline uint16_t __rte_experimental 673 rte_event_timer_arm_burst(const struct rte_event_timer_adapter *adapter, 674 struct rte_event_timer **evtims, 675 uint16_t nb_evtims) 676 { 677 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG 678 ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL); 679 FUNC_PTR_OR_ERR_RET(adapter->arm_burst, -EINVAL); 680 #endif 681 return adapter->arm_burst(adapter, evtims, nb_evtims); 682 } 683 684 /** 685 * @warning 686 * @b EXPERIMENTAL: this API may change without prior notice 687 * 688 * Arm a burst of event timers with same expiration timeout tick. 689 * 690 * Provides the same functionality as ``rte_event_timer_arm_burst()``, except 691 * that application can use this API when all the event timers have the 692 * same timeout expiration tick. This specialized function can provide the 693 * additional hint to the adapter implementation and optimize if possible. 694 * 695 * @param adapter 696 * A pointer to an event timer adapter structure. 697 * @param evtims 698 * Points to an array of objects of type *rte_event_timer* structure. 699 * @param timeout_ticks 700 * The number of ticks in which the timers should expire. 701 * @param nb_evtims 702 * Number of event timers in the supplied array. 703 * 704 * @return 705 * The number of successfully armed event timers. The return value can be less 706 * than the value of the *nb_evtims* parameter. If the return value is less 707 * than *nb_evtims*, the remaining event timers at the end of *evtims* 708 * are not consumed, and the caller has to take care of them, and rte_errno 709 * is set accordingly. Possible errno values include: 710 * - EINVAL Invalid timer adapter, expiry event queue ID is invalid, or an 711 * expiry event's sched type doesn't match the capabilities of the 712 * destination event queue. 713 * - EAGAIN Specified event timer adapter is not running 714 * - EALREADY A timer was encountered that was already armed 715 */ 716 static inline uint16_t __rte_experimental 717 rte_event_timer_arm_tmo_tick_burst( 718 const struct rte_event_timer_adapter *adapter, 719 struct rte_event_timer **evtims, 720 const uint64_t timeout_ticks, 721 const uint16_t nb_evtims) 722 { 723 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG 724 ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL); 725 FUNC_PTR_OR_ERR_RET(adapter->arm_tmo_tick_burst, -EINVAL); 726 #endif 727 return adapter->arm_tmo_tick_burst(adapter, evtims, timeout_ticks, 728 nb_evtims); 729 } 730 731 /** 732 * @warning 733 * @b EXPERIMENTAL: this API may change without prior notice 734 * 735 * Cancel a burst of event timers from being scheduled to the event device. 736 * 737 * @param adapter 738 * A pointer to an event timer adapter structure. 739 * @param evtims 740 * Points to an array of objects of type *rte_event_timer* structure 741 * @param nb_evtims 742 * Number of event timer instances in the supplied array. 743 * 744 * @return 745 * The number of successfully canceled event timers. The return value can be 746 * less than the value of the *nb_evtims* parameter. If the return value is 747 * less than *nb_evtims*, the remaining event timers at the end of *evtims* 748 * are not consumed, and the caller has to take care of them, and rte_errno 749 * is set accordingly. Possible errno values include: 750 * - EINVAL Invalid timer adapter identifier 751 * - EAGAIN Specified timer adapter is not running 752 * - EALREADY A timer was encountered that was already canceled 753 */ 754 static inline uint16_t __rte_experimental 755 rte_event_timer_cancel_burst(const struct rte_event_timer_adapter *adapter, 756 struct rte_event_timer **evtims, 757 uint16_t nb_evtims) 758 { 759 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG 760 ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL); 761 FUNC_PTR_OR_ERR_RET(adapter->cancel_burst, -EINVAL); 762 #endif 763 return adapter->cancel_burst(adapter, evtims, nb_evtims); 764 } 765 766 #endif /* __RTE_EVENT_TIMER_ADAPTER_H__ */ 767