1 /* 2 * 3 * Copyright(c) 2016 Cavium, Inc. All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * * Redistributions in binary form must reproduce the above copyright 12 * notice, this list of conditions and the following disclaimer in 13 * the documentation and/or other materials provided with the 14 * distribution. 15 * * Neither the name of Cavium, Inc nor the names of its 16 * contributors may be used to endorse or promote products derived 17 * from this software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 #ifndef _RTE_EVENTDEV_PMD_H_ 33 #define _RTE_EVENTDEV_PMD_H_ 34 35 /** @file 36 * RTE Event PMD APIs 37 * 38 * @note 39 * These API are from event PMD only and user applications should not call 40 * them directly. 41 */ 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 #include <string.h> 48 49 #include <rte_common.h> 50 #include <rte_config.h> 51 #include <rte_dev.h> 52 #include <rte_log.h> 53 #include <rte_malloc.h> 54 55 #include "rte_eventdev.h" 56 57 /* Logging Macros */ 58 #define RTE_EDEV_LOG_ERR(...) \ 59 RTE_LOG(ERR, EVENTDEV, \ 60 RTE_FMT("%s() line %u: " RTE_FMT_HEAD(__VA_ARGS__,) "\n", \ 61 __func__, __LINE__, RTE_FMT_TAIL(__VA_ARGS__,))) 62 63 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG 64 #define RTE_EDEV_LOG_DEBUG(...) \ 65 RTE_LOG(DEBUG, EVENTDEV, \ 66 RTE_FMT("%s() line %u: " RTE_FMT_HEAD(__VA_ARGS__,) "\n", \ 67 __func__, __LINE__, RTE_FMT_TAIL(__VA_ARGS__,))) 68 #else 69 #define RTE_EDEV_LOG_DEBUG(...) (void)0 70 #endif 71 72 /* Macros to check for valid device */ 73 #define RTE_EVENTDEV_VALID_DEVID_OR_ERR_RET(dev_id, retval) do { \ 74 if (!rte_event_pmd_is_valid_dev((dev_id))) { \ 75 RTE_EDEV_LOG_ERR("Invalid dev_id=%d\n", dev_id); \ 76 return retval; \ 77 } \ 78 } while (0) 79 80 #define RTE_EVENTDEV_VALID_DEVID_OR_ERRNO_RET(dev_id, errno, retval) do { \ 81 if (!rte_event_pmd_is_valid_dev((dev_id))) { \ 82 RTE_EDEV_LOG_ERR("Invalid dev_id=%d\n", dev_id); \ 83 rte_errno = errno; \ 84 return retval; \ 85 } \ 86 } while (0) 87 88 #define RTE_EVENTDEV_VALID_DEVID_OR_RET(dev_id) do { \ 89 if (!rte_event_pmd_is_valid_dev((dev_id))) { \ 90 RTE_EDEV_LOG_ERR("Invalid dev_id=%d\n", dev_id); \ 91 return; \ 92 } \ 93 } while (0) 94 95 #define RTE_EVENT_ETH_RX_ADAPTER_SW_CAP \ 96 ((RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID) | \ 97 (RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ)) 98 99 /**< Ethernet Rx adapter cap to return If the packet transfers from 100 * the ethdev to eventdev use a SW service function 101 */ 102 103 #define RTE_EVENTDEV_DETACHED (0) 104 #define RTE_EVENTDEV_ATTACHED (1) 105 106 struct rte_eth_dev; 107 108 /** Global structure used for maintaining state of allocated event devices */ 109 struct rte_eventdev_global { 110 uint8_t nb_devs; /**< Number of devices found */ 111 }; 112 113 extern struct rte_eventdev_global *rte_eventdev_globals; 114 /** Pointer to global event devices data structure. */ 115 extern struct rte_eventdev *rte_eventdevs; 116 /** The pool of rte_eventdev structures. */ 117 118 /** 119 * Get the rte_eventdev structure device pointer for the named device. 120 * 121 * @param name 122 * device name to select the device structure. 123 * 124 * @return 125 * - The rte_eventdev structure pointer for the given device ID. 126 */ 127 static inline struct rte_eventdev * 128 rte_event_pmd_get_named_dev(const char *name) 129 { 130 struct rte_eventdev *dev; 131 unsigned int i; 132 133 if (name == NULL) 134 return NULL; 135 136 for (i = 0; i < RTE_EVENT_MAX_DEVS; i++) { 137 dev = &rte_eventdevs[i]; 138 if ((dev->attached == RTE_EVENTDEV_ATTACHED) && 139 (strcmp(dev->data->name, name) == 0)) 140 return dev; 141 } 142 143 return NULL; 144 } 145 146 /** 147 * Validate if the event device index is valid attached event device. 148 * 149 * @param dev_id 150 * Event device index. 151 * 152 * @return 153 * - If the device index is valid (1) or not (0). 154 */ 155 static inline unsigned 156 rte_event_pmd_is_valid_dev(uint8_t dev_id) 157 { 158 struct rte_eventdev *dev; 159 160 if (dev_id >= RTE_EVENT_MAX_DEVS) 161 return 0; 162 163 dev = &rte_eventdevs[dev_id]; 164 if (dev->attached != RTE_EVENTDEV_ATTACHED) 165 return 0; 166 else 167 return 1; 168 } 169 170 /** 171 * Definitions of all functions exported by a driver through the 172 * the generic structure of type *event_dev_ops* supplied in the 173 * *rte_eventdev* structure associated with a device. 174 */ 175 176 /** 177 * Get device information of a device. 178 * 179 * @param dev 180 * Event device pointer 181 * @param dev_info 182 * Event device information structure 183 * 184 * @return 185 * Returns 0 on success 186 */ 187 typedef void (*eventdev_info_get_t)(struct rte_eventdev *dev, 188 struct rte_event_dev_info *dev_info); 189 190 /** 191 * Configure a device. 192 * 193 * @param dev 194 * Event device pointer 195 * 196 * @return 197 * Returns 0 on success 198 */ 199 typedef int (*eventdev_configure_t)(const struct rte_eventdev *dev); 200 201 /** 202 * Start a configured device. 203 * 204 * @param dev 205 * Event device pointer 206 * 207 * @return 208 * Returns 0 on success 209 */ 210 typedef int (*eventdev_start_t)(struct rte_eventdev *dev); 211 212 /** 213 * Stop a configured device. 214 * 215 * @param dev 216 * Event device pointer 217 */ 218 typedef void (*eventdev_stop_t)(struct rte_eventdev *dev); 219 220 /** 221 * Close a configured device. 222 * 223 * @param dev 224 * Event device pointer 225 * 226 * @return 227 * - 0 on success 228 * - (-EAGAIN) if can't close as device is busy 229 */ 230 typedef int (*eventdev_close_t)(struct rte_eventdev *dev); 231 232 /** 233 * Retrieve the default event queue configuration. 234 * 235 * @param dev 236 * Event device pointer 237 * @param queue_id 238 * Event queue index 239 * @param[out] queue_conf 240 * Event queue configuration structure 241 * 242 */ 243 typedef void (*eventdev_queue_default_conf_get_t)(struct rte_eventdev *dev, 244 uint8_t queue_id, struct rte_event_queue_conf *queue_conf); 245 246 /** 247 * Setup an event queue. 248 * 249 * @param dev 250 * Event device pointer 251 * @param queue_id 252 * Event queue index 253 * @param queue_conf 254 * Event queue configuration structure 255 * 256 * @return 257 * Returns 0 on success. 258 */ 259 typedef int (*eventdev_queue_setup_t)(struct rte_eventdev *dev, 260 uint8_t queue_id, 261 const struct rte_event_queue_conf *queue_conf); 262 263 /** 264 * Release resources allocated by given event queue. 265 * 266 * @param dev 267 * Event device pointer 268 * @param queue_id 269 * Event queue index 270 * 271 */ 272 typedef void (*eventdev_queue_release_t)(struct rte_eventdev *dev, 273 uint8_t queue_id); 274 275 /** 276 * Retrieve the default event port configuration. 277 * 278 * @param dev 279 * Event device pointer 280 * @param port_id 281 * Event port index 282 * @param[out] port_conf 283 * Event port configuration structure 284 * 285 */ 286 typedef void (*eventdev_port_default_conf_get_t)(struct rte_eventdev *dev, 287 uint8_t port_id, struct rte_event_port_conf *port_conf); 288 289 /** 290 * Setup an event port. 291 * 292 * @param dev 293 * Event device pointer 294 * @param port_id 295 * Event port index 296 * @param port_conf 297 * Event port configuration structure 298 * 299 * @return 300 * Returns 0 on success. 301 */ 302 typedef int (*eventdev_port_setup_t)(struct rte_eventdev *dev, 303 uint8_t port_id, 304 const struct rte_event_port_conf *port_conf); 305 306 /** 307 * Release memory resources allocated by given event port. 308 * 309 * @param port 310 * Event port pointer 311 * 312 */ 313 typedef void (*eventdev_port_release_t)(void *port); 314 315 /** 316 * Link multiple source event queues to destination event port. 317 * 318 * @param dev 319 * Event device pointer 320 * @param port 321 * Event port pointer 322 * @param link 323 * Points to an array of *nb_links* event queues to be linked 324 * to the event port. 325 * @param priorities 326 * Points to an array of *nb_links* service priorities associated with each 327 * event queue link to event port. 328 * @param nb_links 329 * The number of links to establish 330 * 331 * @return 332 * Returns 0 on success. 333 * 334 */ 335 typedef int (*eventdev_port_link_t)(struct rte_eventdev *dev, void *port, 336 const uint8_t queues[], const uint8_t priorities[], 337 uint16_t nb_links); 338 339 /** 340 * Unlink multiple source event queues from destination event port. 341 * 342 * @param dev 343 * Event device pointer 344 * @param port 345 * Event port pointer 346 * @param queues 347 * An array of *nb_unlinks* event queues to be unlinked from the event port. 348 * @param nb_unlinks 349 * The number of unlinks to establish 350 * 351 * @return 352 * Returns 0 on success. 353 * 354 */ 355 typedef int (*eventdev_port_unlink_t)(struct rte_eventdev *dev, void *port, 356 uint8_t queues[], uint16_t nb_unlinks); 357 358 /** 359 * Converts nanoseconds to *timeout_ticks* value for rte_event_dequeue() 360 * 361 * @param dev 362 * Event device pointer 363 * @param ns 364 * Wait time in nanosecond 365 * @param[out] timeout_ticks 366 * Value for the *timeout_ticks* parameter in rte_event_dequeue() function 367 * 368 * @return 369 * Returns 0 on success. 370 * 371 */ 372 typedef int (*eventdev_dequeue_timeout_ticks_t)(struct rte_eventdev *dev, 373 uint64_t ns, uint64_t *timeout_ticks); 374 375 /** 376 * Dump internal information 377 * 378 * @param dev 379 * Event device pointer 380 * @param f 381 * A pointer to a file for output 382 * 383 */ 384 typedef void (*eventdev_dump_t)(struct rte_eventdev *dev, FILE *f); 385 386 /** 387 * Retrieve a set of statistics from device 388 * 389 * @param dev 390 * Event device pointer 391 * @param ids 392 * The stat ids to retrieve 393 * @param values 394 * The returned stat values 395 * @param n 396 * The number of id values and entries in the values array 397 * @return 398 * The number of stat values successfully filled into the values array 399 */ 400 typedef int (*eventdev_xstats_get_t)(const struct rte_eventdev *dev, 401 enum rte_event_dev_xstats_mode mode, uint8_t queue_port_id, 402 const unsigned int ids[], uint64_t values[], unsigned int n); 403 404 /** 405 * Resets the statistic values in xstats for the device, based on mode. 406 */ 407 typedef int (*eventdev_xstats_reset_t)(struct rte_eventdev *dev, 408 enum rte_event_dev_xstats_mode mode, 409 int16_t queue_port_id, 410 const uint32_t ids[], 411 uint32_t nb_ids); 412 413 /** 414 * Get names of extended stats of an event device 415 * 416 * @param dev 417 * Event device pointer 418 * @param xstats_names 419 * Array of name values to be filled in 420 * @param size 421 * Number of values in the xstats_names array 422 * @return 423 * When size >= the number of stats, return the number of stat values filled 424 * into the array. 425 * When size < the number of available stats, return the number of stats 426 * values, and do not fill in any data into xstats_names. 427 */ 428 typedef int (*eventdev_xstats_get_names_t)(const struct rte_eventdev *dev, 429 enum rte_event_dev_xstats_mode mode, uint8_t queue_port_id, 430 struct rte_event_dev_xstats_name *xstats_names, 431 unsigned int *ids, unsigned int size); 432 433 /** 434 * Get value of one stats and optionally return its id 435 * 436 * @param dev 437 * Event device pointer 438 * @param name 439 * The name of the stat to retrieve 440 * @param id 441 * Pointer to an unsigned int where we store the stat-id for future reference. 442 * This pointer may be null if the id is not required. 443 * @return 444 * The value of the stat, or (uint64_t)-1 if the stat is not found. 445 * If the stat is not found, the id value will be returned as (unsigned)-1, 446 * if id pointer is non-NULL 447 */ 448 typedef uint64_t (*eventdev_xstats_get_by_name)(const struct rte_eventdev *dev, 449 const char *name, unsigned int *id); 450 451 452 /** 453 * Retrieve the event device's ethdev Rx adapter capabilities for the 454 * specified ethernet port 455 * 456 * @param dev 457 * Event device pointer 458 * 459 * @param eth_dev 460 * Ethernet device pointer 461 * 462 * @param[out] caps 463 * A pointer to memory filled with Rx event adapter capabilities. 464 * 465 * @return 466 * - 0: Success, driver provides Rx event adapter capabilities for the 467 * ethernet device. 468 * - <0: Error code returned by the driver function. 469 * 470 */ 471 typedef int (*eventdev_eth_rx_adapter_caps_get_t) 472 (const struct rte_eventdev *dev, 473 const struct rte_eth_dev *eth_dev, 474 uint32_t *caps); 475 476 struct rte_event_eth_rx_adapter_queue_conf *queue_conf; 477 478 /** 479 * Add ethernet Rx queues to event device. This callback is invoked if 480 * the caps returned from rte_eventdev_eth_rx_adapter_caps_get(, eth_port_id) 481 * has RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT set. 482 * 483 * @param dev 484 * Event device pointer 485 * 486 * @param eth_dev 487 * Ethernet device pointer 488 * 489 * @param rx_queue_id 490 * Ethernet device receive queue index 491 * 492 * @param queue_conf 493 * Additional configuration structure 494 495 * @return 496 * - 0: Success, ethernet receive queue added successfully. 497 * - <0: Error code returned by the driver function. 498 * 499 */ 500 typedef int (*eventdev_eth_rx_adapter_queue_add_t)( 501 const struct rte_eventdev *dev, 502 const struct rte_eth_dev *eth_dev, 503 int32_t rx_queue_id, 504 const struct rte_event_eth_rx_adapter_queue_conf *queue_conf); 505 506 /** 507 * Delete ethernet Rx queues from event device. This callback is invoked if 508 * the caps returned from eventdev_eth_rx_adapter_caps_get(, eth_port_id) 509 * has RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT set. 510 * 511 * @param dev 512 * Event device pointer 513 * 514 * @param eth_dev 515 * Ethernet device pointer 516 * 517 * @param rx_queue_id 518 * Ethernet device receive queue index 519 * 520 * @return 521 * - 0: Success, ethernet receive queue deleted successfully. 522 * - <0: Error code returned by the driver function. 523 * 524 */ 525 typedef int (*eventdev_eth_rx_adapter_queue_del_t) 526 (const struct rte_eventdev *dev, 527 const struct rte_eth_dev *eth_dev, 528 int32_t rx_queue_id); 529 530 /** 531 * Start ethernet Rx adapter. This callback is invoked if 532 * the caps returned from eventdev_eth_rx_adapter_caps_get(.., eth_port_id) 533 * has RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT set and Rx queues 534 * from eth_port_id have been added to the event device. 535 * 536 * @param dev 537 * Event device pointer 538 * 539 * @param eth_dev 540 * Ethernet device pointer 541 * 542 * @return 543 * - 0: Success, ethernet Rx adapter started successfully. 544 * - <0: Error code returned by the driver function. 545 */ 546 typedef int (*eventdev_eth_rx_adapter_start_t) 547 (const struct rte_eventdev *dev, 548 const struct rte_eth_dev *eth_dev); 549 550 /** 551 * Stop ethernet Rx adapter. This callback is invoked if 552 * the caps returned from eventdev_eth_rx_adapter_caps_get(..,eth_port_id) 553 * has RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT set and Rx queues 554 * from eth_port_id have been added to the event device. 555 * 556 * @param dev 557 * Event device pointer 558 * 559 * @param eth_dev 560 * Ethernet device pointer 561 * 562 * @return 563 * - 0: Success, ethernet Rx adapter stopped successfully. 564 * - <0: Error code returned by the driver function. 565 */ 566 typedef int (*eventdev_eth_rx_adapter_stop_t) 567 (const struct rte_eventdev *dev, 568 const struct rte_eth_dev *eth_dev); 569 570 struct rte_event_eth_rx_adapter_stats *stats; 571 572 /** 573 * Retrieve ethernet Rx adapter statistics. 574 * 575 * @param dev 576 * Event device pointer 577 * 578 * @param eth_dev 579 * Ethernet device pointer 580 * 581 * @param[out] stats 582 * Pointer to stats structure 583 * 584 * @return 585 * Return 0 on success. 586 */ 587 588 typedef int (*eventdev_eth_rx_adapter_stats_get) 589 (const struct rte_eventdev *dev, 590 const struct rte_eth_dev *eth_dev, 591 struct rte_event_eth_rx_adapter_stats *stats); 592 /** 593 * Reset ethernet Rx adapter statistics. 594 * 595 * @param dev 596 * Event device pointer 597 * 598 * @param eth_dev 599 * Ethernet device pointer 600 * 601 * @return 602 * Return 0 on success. 603 */ 604 typedef int (*eventdev_eth_rx_adapter_stats_reset) 605 (const struct rte_eventdev *dev, 606 const struct rte_eth_dev *eth_dev); 607 608 /** Event device operations function pointer table */ 609 struct rte_eventdev_ops { 610 eventdev_info_get_t dev_infos_get; /**< Get device info. */ 611 eventdev_configure_t dev_configure; /**< Configure device. */ 612 eventdev_start_t dev_start; /**< Start device. */ 613 eventdev_stop_t dev_stop; /**< Stop device. */ 614 eventdev_close_t dev_close; /**< Close device. */ 615 616 eventdev_queue_default_conf_get_t queue_def_conf; 617 /**< Get default queue configuration. */ 618 eventdev_queue_setup_t queue_setup; 619 /**< Set up an event queue. */ 620 eventdev_queue_release_t queue_release; 621 /**< Release an event queue. */ 622 623 eventdev_port_default_conf_get_t port_def_conf; 624 /**< Get default port configuration. */ 625 eventdev_port_setup_t port_setup; 626 /**< Set up an event port. */ 627 eventdev_port_release_t port_release; 628 /**< Release an event port. */ 629 630 eventdev_port_link_t port_link; 631 /**< Link event queues to an event port. */ 632 eventdev_port_unlink_t port_unlink; 633 /**< Unlink event queues from an event port. */ 634 eventdev_dequeue_timeout_ticks_t timeout_ticks; 635 /**< Converts ns to *timeout_ticks* value for rte_event_dequeue() */ 636 eventdev_dump_t dump; 637 /* Dump internal information */ 638 639 eventdev_xstats_get_t xstats_get; 640 /**< Get extended device statistics. */ 641 eventdev_xstats_get_names_t xstats_get_names; 642 /**< Get names of extended stats. */ 643 eventdev_xstats_get_by_name xstats_get_by_name; 644 /**< Get one value by name. */ 645 eventdev_xstats_reset_t xstats_reset; 646 /**< Reset the statistics values in xstats. */ 647 648 eventdev_eth_rx_adapter_caps_get_t eth_rx_adapter_caps_get; 649 /**< Get ethernet Rx adapter capabilities */ 650 eventdev_eth_rx_adapter_queue_add_t eth_rx_adapter_queue_add; 651 /**< Add Rx queues to ethernet Rx adapter */ 652 eventdev_eth_rx_adapter_queue_del_t eth_rx_adapter_queue_del; 653 /**< Delete Rx queues from ethernet Rx adapter */ 654 eventdev_eth_rx_adapter_start_t eth_rx_adapter_start; 655 /**< Start ethernet Rx adapter */ 656 eventdev_eth_rx_adapter_stop_t eth_rx_adapter_stop; 657 /**< Stop ethernet Rx adapter */ 658 eventdev_eth_rx_adapter_stats_get eth_rx_adapter_stats_get; 659 /**< Get ethernet Rx stats */ 660 eventdev_eth_rx_adapter_stats_reset eth_rx_adapter_stats_reset; 661 /**< Reset ethernet Rx stats */ 662 }; 663 664 /** 665 * Allocates a new eventdev slot for an event device and returns the pointer 666 * to that slot for the driver to use. 667 * 668 * @param name 669 * Unique identifier name for each device 670 * @param socket_id 671 * Socket to allocate resources on. 672 * @return 673 * - Slot in the rte_dev_devices array for a new device; 674 */ 675 struct rte_eventdev * 676 rte_event_pmd_allocate(const char *name, int socket_id); 677 678 /** 679 * Release the specified eventdev device. 680 * 681 * @param eventdev 682 * The *eventdev* pointer is the address of the *rte_eventdev* structure. 683 * @return 684 * - 0 on success, negative on error 685 */ 686 int 687 rte_event_pmd_release(struct rte_eventdev *eventdev); 688 689 #ifdef __cplusplus 690 } 691 #endif 692 693 #endif /* _RTE_EVENTDEV_PMD_H_ */ 694