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 115 #include "rte_eventdev.h" 116 #include "rte_eventdev_trace_fp.h" 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 */ 315 int 316 rte_event_timer_adapter_get_info( 317 const struct rte_event_timer_adapter *adapter, 318 struct rte_event_timer_adapter_info *adapter_info); 319 320 /** 321 * Start a timer adapter. 322 * 323 * The adapter start step is the last one and consists of setting the timer 324 * adapter to start accepting the timers and schedules to event queues. 325 * 326 * On success, all basic functions exported by the API (timer arm, 327 * timer cancel and so on) can be invoked. 328 * 329 * @param adapter 330 * A pointer to the event timer adapter structure. 331 * 332 * @return 333 * - 0: Success, adapter started. 334 * - <0: Error code returned by the driver start function. 335 * - -EINVAL if adapter identifier invalid 336 * - -ENOENT if software adapter but no service core mapped 337 * - -ENOTSUP if software adapter and more than one service core mapped 338 * - -EALREADY if adapter has already been started 339 * 340 * @note 341 * The eventdev to which the event_timer_adapter is connected needs to 342 * be started before calling rte_event_timer_adapter_start(). 343 */ 344 int 345 rte_event_timer_adapter_start( 346 const struct rte_event_timer_adapter *adapter); 347 348 /** 349 * Stop an event timer adapter. 350 * 351 * The adapter can be restarted with a call to 352 * ``rte_event_timer_adapter_start()``. 353 * 354 * @param adapter 355 * A pointer to the event timer adapter structure. 356 * 357 * @return 358 * - 0: Success, adapter stopped. 359 * - <0: Error code returned by the driver stop function. 360 * - -EINVAL if adapter identifier invalid 361 */ 362 int 363 rte_event_timer_adapter_stop(const struct rte_event_timer_adapter *adapter); 364 365 /** 366 * Lookup an event timer adapter using its identifier. 367 * 368 * If an event timer adapter was created in another process with the same 369 * identifier, this function will locate its state and set up access to it 370 * so that it can be used in this process. 371 * 372 * @param adapter_id 373 * The event timer adapter identifier. 374 * 375 * @return 376 * A pointer to the event timer adapter matching the identifier on success. 377 * NULL on error with rte_errno set appropriately. 378 * Possible rte_errno values include: 379 * - ENOENT - requested entry not available to return. 380 */ 381 struct rte_event_timer_adapter * 382 rte_event_timer_adapter_lookup(uint16_t adapter_id); 383 384 /** 385 * Free an event timer adapter. 386 * 387 * Destroy an event timer adapter, freeing all resources. 388 * 389 * Before invoking this function, the application must wait for all the 390 * armed timers to expire or cancel the outstanding armed timers. 391 * 392 * @param adapter 393 * A pointer to an event timer adapter structure. 394 * 395 * @return 396 * - 0: Successfully freed the event timer adapter resources. 397 * - <0: Failed to free the event timer adapter resources. 398 * - -EAGAIN: adapter is busy; timers outstanding 399 * - -EBUSY: stop hasn't been called for this adapter yet 400 * - -EINVAL: adapter id invalid, or adapter invalid 401 */ 402 int 403 rte_event_timer_adapter_free(struct rte_event_timer_adapter *adapter); 404 405 /** 406 * Retrieve the service ID of the event timer adapter. If the adapter doesn't 407 * use an rte_service function, this function returns -ESRCH. 408 * 409 * @param adapter 410 * A pointer to an event timer adapter. 411 * 412 * @param [out] service_id 413 * A pointer to a uint32_t, to be filled in with the service id. 414 * 415 * @return 416 * - 0: Success 417 * - <0: Error code on failure 418 * - -ESRCH: the adapter does not require a service to operate 419 */ 420 int 421 rte_event_timer_adapter_service_id_get(struct rte_event_timer_adapter *adapter, 422 uint32_t *service_id); 423 424 /** 425 * Retrieve statistics for an event timer adapter instance. 426 * 427 * @param adapter 428 * A pointer to an event timer adapter structure. 429 * @param[out] stats 430 * A pointer to a structure to fill with statistics. 431 * 432 * @return 433 * - 0: Successfully retrieved. 434 * - <0: Failure; error code returned. 435 */ 436 int 437 rte_event_timer_adapter_stats_get(struct rte_event_timer_adapter *adapter, 438 struct rte_event_timer_adapter_stats *stats); 439 440 /** 441 * Reset statistics for an event timer adapter instance. 442 * 443 * @param adapter 444 * A pointer to an event timer adapter structure. 445 * 446 * @return 447 * - 0: Successfully reset; 448 * - <0: Failure; error code returned. 449 */ 450 int 451 rte_event_timer_adapter_stats_reset(struct rte_event_timer_adapter *adapter); 452 453 /** 454 * Event timer state. 455 */ 456 enum rte_event_timer_state { 457 RTE_EVENT_TIMER_NOT_ARMED = 0, 458 /**< Event timer not armed. */ 459 RTE_EVENT_TIMER_ARMED = 1, 460 /**< Event timer successfully armed. */ 461 RTE_EVENT_TIMER_CANCELED = 2, 462 /**< Event timer successfully canceled. */ 463 RTE_EVENT_TIMER_ERROR = -1, 464 /**< Generic event timer error. */ 465 RTE_EVENT_TIMER_ERROR_TOOEARLY = -2, 466 /**< Event timer timeout tick value is too small for the adapter to 467 * handle, given its configured resolution. 468 */ 469 RTE_EVENT_TIMER_ERROR_TOOLATE = -3, 470 /**< Event timer timeout tick is greater than the maximum timeout.*/ 471 }; 472 473 /** 474 * The generic *rte_event_timer* structure to hold the event timer attributes 475 * for arm and cancel operations. 476 */ 477 RTE_STD_C11 478 struct rte_event_timer { 479 struct rte_event ev; 480 /**< 481 * Expiry event attributes. On successful event timer timeout, 482 * the following attributes will be used to inject the expiry event to 483 * the eventdev: 484 * - event_queue_id: Targeted event queue id for expiry events. 485 * - event_priority: Event priority of the event expiry event in the 486 * event queue relative to other events. 487 * - sched_type: Scheduling type of the expiry event. 488 * - flow_id: Flow id of the expiry event. 489 * - op: RTE_EVENT_OP_NEW 490 * - event_type: RTE_EVENT_TYPE_TIMER 491 */ 492 uint64_t timeout_ticks; 493 /**< Expiry timer ticks expressed in number of *timer_ticks_ns* from 494 * now. 495 * @see struct rte_event_timer_adapter_info::adapter_conf::timer_tick_ns 496 */ 497 uint64_t impl_opaque[2]; 498 /**< Implementation-specific opaque data. 499 * An event timer adapter implementation use this field to hold 500 * implementation specific values to share between the arm and cancel 501 * operations. The application should not modify this field. 502 */ 503 enum rte_event_timer_state state; 504 /**< State of the event timer. */ 505 uint8_t user_meta[]; 506 /**< Memory to store user specific metadata. 507 * The event timer adapter implementation should not modify this area. 508 */ 509 } __rte_cache_aligned; 510 511 typedef uint16_t (*rte_event_timer_arm_burst_t)( 512 const struct rte_event_timer_adapter *adapter, 513 struct rte_event_timer **tims, 514 uint16_t nb_tims); 515 /**< @internal Enable event timers to enqueue timer events upon expiry */ 516 typedef uint16_t (*rte_event_timer_arm_tmo_tick_burst_t)( 517 const struct rte_event_timer_adapter *adapter, 518 struct rte_event_timer **tims, 519 uint64_t timeout_tick, 520 uint16_t nb_tims); 521 /**< @internal Enable event timers with common expiration time */ 522 typedef uint16_t (*rte_event_timer_cancel_burst_t)( 523 const struct rte_event_timer_adapter *adapter, 524 struct rte_event_timer **tims, 525 uint16_t nb_tims); 526 /**< @internal Prevent event timers from enqueuing timer events */ 527 528 /** 529 * @internal Data structure associated with each event timer adapter. 530 */ 531 struct rte_event_timer_adapter { 532 rte_event_timer_arm_burst_t arm_burst; 533 /**< Pointer to driver arm_burst function. */ 534 rte_event_timer_arm_tmo_tick_burst_t arm_tmo_tick_burst; 535 /**< Pointer to driver arm_tmo_tick_burst function. */ 536 rte_event_timer_cancel_burst_t cancel_burst; 537 /**< Pointer to driver cancel function. */ 538 struct rte_event_timer_adapter_data *data; 539 /**< Pointer to shared adapter data */ 540 const struct event_timer_adapter_ops *ops; 541 /**< Functions exported by adapter driver */ 542 543 RTE_STD_C11 544 uint8_t allocated : 1; 545 /**< Flag to indicate that this adapter has been allocated */ 546 } __rte_cache_aligned; 547 548 #define ADAPTER_VALID_OR_ERR_RET(adapter, retval) do { \ 549 if (adapter == NULL || !adapter->allocated) \ 550 return retval; \ 551 } while (0) 552 553 #define FUNC_PTR_OR_ERR_RET(func, errval) do { \ 554 if ((func) == NULL) \ 555 return errval; \ 556 } while (0) 557 558 #define FUNC_PTR_OR_NULL_RET_WITH_ERRNO(func, errval) do { \ 559 if ((func) == NULL) { \ 560 rte_errno = errval; \ 561 return NULL; \ 562 } \ 563 } while (0) 564 565 /** 566 * Arm a burst of event timers with separate expiration timeout tick for each 567 * event timer. 568 * 569 * Before calling this function, the application allocates 570 * ``struct rte_event_timer`` objects from mempool or huge page backed 571 * application buffers of desired size. On successful allocation, 572 * application updates the `struct rte_event_timer`` attributes such as 573 * expiry event attributes, timeout ticks from now. 574 * This function submits the event timer arm requests to the event timer adapter 575 * and on expiry, the events will be injected to designated event queue. 576 * Timer expiry events will be generated once or periodically until cancellation 577 * based on the adapter mode. 578 * 579 * @param adapter 580 * A pointer to an event timer adapter structure. 581 * @param evtims 582 * Pointer to an array of objects of type *rte_event_timer* structure. 583 * @param nb_evtims 584 * Number of event timers in the supplied array. 585 * 586 * @return 587 * The number of successfully armed event timers. The return value can be less 588 * than the value of the *nb_evtims* parameter. If the return value is less 589 * than *nb_evtims*, the remaining event timers at the end of *evtims* 590 * are not consumed, and the caller has to take care of them, and rte_errno 591 * is set accordingly. Possible errno values include: 592 * - EINVAL Invalid timer adapter, expiry event queue ID is invalid, or an 593 * expiry event's sched type doesn't match the capabilities of the 594 * destination event queue. 595 * - EAGAIN Specified timer adapter is not running 596 * - EALREADY A timer was encountered that was already armed 597 * 598 * @see RTE_EVENT_TIMER_ADAPTER_F_PERIODIC 599 * 600 */ 601 static inline uint16_t 602 rte_event_timer_arm_burst(const struct rte_event_timer_adapter *adapter, 603 struct rte_event_timer **evtims, 604 uint16_t nb_evtims) 605 { 606 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG 607 ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL); 608 FUNC_PTR_OR_ERR_RET(adapter->arm_burst, -EINVAL); 609 #endif 610 rte_eventdev_trace_timer_arm_burst(adapter, (void **)evtims, 611 nb_evtims); 612 return adapter->arm_burst(adapter, evtims, nb_evtims); 613 } 614 615 /** 616 * Arm a burst of event timers with same expiration timeout tick. 617 * 618 * Provides the same functionality as ``rte_event_timer_arm_burst()``, except 619 * that application can use this API when all the event timers have the 620 * same timeout expiration tick. This specialized function can provide the 621 * additional hint to the adapter implementation and optimize if possible. 622 * 623 * @param adapter 624 * A pointer to an event timer adapter structure. 625 * @param evtims 626 * Points to an array of objects of type *rte_event_timer* structure. 627 * @param timeout_ticks 628 * The number of ticks in which the timers should expire. 629 * @param nb_evtims 630 * Number of event timers in the supplied array. 631 * 632 * @return 633 * The number of successfully armed event timers. The return value can be less 634 * than the value of the *nb_evtims* parameter. If the return value is less 635 * than *nb_evtims*, the remaining event timers at the end of *evtims* 636 * are not consumed, and the caller has to take care of them, and rte_errno 637 * is set accordingly. Possible errno values include: 638 * - EINVAL Invalid timer adapter, expiry event queue ID is invalid, or an 639 * expiry event's sched type doesn't match the capabilities of the 640 * destination event queue. 641 * - EAGAIN Specified event timer adapter is not running 642 * - EALREADY A timer was encountered that was already armed 643 */ 644 static inline uint16_t 645 rte_event_timer_arm_tmo_tick_burst( 646 const struct rte_event_timer_adapter *adapter, 647 struct rte_event_timer **evtims, 648 const uint64_t timeout_ticks, 649 const uint16_t nb_evtims) 650 { 651 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG 652 ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL); 653 FUNC_PTR_OR_ERR_RET(adapter->arm_tmo_tick_burst, -EINVAL); 654 #endif 655 rte_eventdev_trace_timer_arm_tmo_tick_burst(adapter, timeout_ticks, 656 (void **)evtims, nb_evtims); 657 return adapter->arm_tmo_tick_burst(adapter, evtims, timeout_ticks, 658 nb_evtims); 659 } 660 661 /** 662 * Cancel a burst of event timers from being scheduled to the event device. 663 * 664 * @param adapter 665 * A pointer to an event timer adapter structure. 666 * @param evtims 667 * Points to an array of objects of type *rte_event_timer* structure 668 * @param nb_evtims 669 * Number of event timer instances in the supplied array. 670 * 671 * @return 672 * The number of successfully canceled event timers. The return value can be 673 * less than the value of the *nb_evtims* parameter. If the return value is 674 * less than *nb_evtims*, the remaining event timers at the end of *evtims* 675 * are not consumed, and the caller has to take care of them, and rte_errno 676 * is set accordingly. Possible errno values include: 677 * - EINVAL Invalid timer adapter identifier 678 * - EAGAIN Specified timer adapter is not running 679 * - EALREADY A timer was encountered that was already canceled 680 */ 681 static inline uint16_t 682 rte_event_timer_cancel_burst(const struct rte_event_timer_adapter *adapter, 683 struct rte_event_timer **evtims, 684 uint16_t nb_evtims) 685 { 686 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG 687 ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL); 688 FUNC_PTR_OR_ERR_RET(adapter->cancel_burst, -EINVAL); 689 #endif 690 rte_eventdev_trace_timer_cancel_burst(adapter, (void **)evtims, 691 nb_evtims); 692 return adapter->cancel_burst(adapter, evtims, nb_evtims); 693 } 694 695 /** 696 * @warning 697 * @b EXPERIMENTAL: this API may change without prior notice 698 * 699 * Get the number of ticks remaining until event timer expiry. 700 * 701 * @param adapter 702 * A pointer to an event timer adapter structure 703 * @param evtim 704 * A pointer to an rte_event_timer structure 705 * @param[out] ticks_remaining 706 * Pointer to variable into which to write the number of ticks remaining 707 * until event timer expiry 708 * 709 * @return 710 * - 0: Success 711 * - -EINVAL Invalid timer adapter identifier or the event timer is not in 712 * the armed state or ticks_remaining is NULL 713 * - -ENOTSUP The timer adapter implementation does not support this API. 714 */ 715 __rte_experimental 716 int 717 rte_event_timer_remaining_ticks_get( 718 const struct rte_event_timer_adapter *adapter, 719 const struct rte_event_timer *evtim, 720 uint64_t *ticks_remaining); 721 722 #ifdef __cplusplus 723 } 724 #endif 725 726 #endif /* __RTE_EVENT_TIMER_ADAPTER_H__ */ 727