1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2017 Intel Corporation. 3 * All rights reserved. 4 */ 5 6 #ifndef _RTE_EVENT_ETH_RX_ADAPTER_ 7 #define _RTE_EVENT_ETH_RX_ADAPTER_ 8 9 /** 10 * @file 11 * 12 * RTE Event Ethernet Rx Adapter 13 * 14 * An eventdev-based packet processing application enqueues/dequeues mbufs 15 * to/from the event device. Packet flow from the ethernet device to the event 16 * device can be accomplished using either HW or SW mechanisms depending on the 17 * platform and the particular combination of ethernet and event devices. The 18 * event ethernet Rx adapter provides common APIs to configure the packet flow 19 * from the ethernet devices to event devices across both these transfer 20 * mechanisms. 21 * 22 * The adapter uses a EAL service core function for SW based packet transfer 23 * and uses the eventdev PMD functions to configure HW based packet transfer 24 * between the ethernet device and the event device. 25 * 26 * The ethernet Rx event adapter's functions are: 27 * - rte_event_eth_rx_adapter_create_ext() 28 * - rte_event_eth_rx_adapter_create() 29 * - rte_event_eth_rx_adapter_create_with_params() 30 * - rte_event_eth_rx_adapter_free() 31 * - rte_event_eth_rx_adapter_queue_add() 32 * - rte_event_eth_rx_adapter_queue_del() 33 * - rte_event_eth_rx_adapter_start() 34 * - rte_event_eth_rx_adapter_stop() 35 * - rte_event_eth_rx_adapter_stats_get() 36 * - rte_event_eth_rx_adapter_stats_reset() 37 * - rte_event_eth_rx_adapter_queue_conf_get() 38 * 39 * The application creates an ethernet to event adapter using 40 * rte_event_eth_rx_adapter_create_ext() or rte_event_eth_rx_adapter_create() 41 * or rte_event_eth_rx_adapter_create_with_params() functions. 42 * The adapter needs to know which ethernet rx queues to poll for mbufs as well 43 * as event device parameters such as the event queue identifier, event 44 * priority and scheduling type that the adapter should use when constructing 45 * events. The rte_event_eth_rx_adapter_queue_add() function is provided for 46 * this purpose. 47 * The servicing weight parameter in the rte_event_eth_rx_adapter_queue_conf 48 * is applicable when the Rx adapter uses a service core function and is 49 * intended to provide application control of the frequency of polling ethernet 50 * device receive queues, for example, the application may want to poll higher 51 * priority queues with a higher frequency but at the same time not starve 52 * lower priority queues completely. If this parameter is zero and the receive 53 * interrupt is enabled when configuring the device, the receive queue is 54 * interrupt driven; else, the queue is assigned a servicing weight of one. 55 * 56 * The application can start/stop the adapter using the 57 * rte_event_eth_rx_adapter_start() and the rte_event_eth_rx_adapter_stop() 58 * functions. If the adapter uses a rte_service function, then the application 59 * is also required to assign a core to the service function and control the 60 * service core using the rte_service APIs. The 61 * rte_event_eth_rx_adapter_service_id_get() function can be used to retrieve 62 * the service function ID of the adapter in this case. 63 * 64 * For SW based packet transfers, i.e., when the 65 * RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT is not set in the adapter's 66 * capabilities flags for a particular ethernet device, the service function 67 * temporarily enqueues events to an event buffer before batch enqueuing these 68 * to the event device. If the buffer fills up, the service function stops 69 * dequeuing packets from the ethernet device. The application may want to 70 * monitor the buffer fill level and instruct the service function to 71 * selectively buffer events. The application may also use some other 72 * criteria to decide which packets should enter the event device even when 73 * the event buffer fill level is low or may want to enqueue packets to an 74 * internal event port. The rte_event_eth_rx_adapter_cb_register() function 75 * allows the application to register a callback that selects which packets are 76 * enqueued to the event device by the SW adapter. The callback interface is 77 * event based so the callback can also modify the event data if it needs to. 78 */ 79 80 #ifdef __cplusplus 81 extern "C" { 82 #endif 83 84 #include <stdint.h> 85 86 #include <rte_service.h> 87 88 #include "rte_eventdev.h" 89 90 #define RTE_EVENT_ETH_RX_ADAPTER_MAX_INSTANCE 32 91 92 /* struct rte_event_eth_rx_adapter_queue_conf flags definitions */ 93 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID 0x1 94 /**< This flag indicates the flow identifier is valid 95 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags 96 */ 97 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR 0x2 98 /**< This flag indicates that mbufs arriving on the queue need to be vectorized 99 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags 100 */ 101 102 /** 103 * Adapter configuration structure that the adapter configuration callback 104 * function is expected to fill out 105 * @see rte_event_eth_rx_adapter_conf_cb 106 */ 107 struct rte_event_eth_rx_adapter_conf { 108 uint8_t event_port_id; 109 /**< Event port identifier, the adapter enqueues mbuf events to this 110 * port. 111 */ 112 uint32_t max_nb_rx; 113 /**< The adapter can return early if it has processed at least 114 * max_nb_rx mbufs. This isn't treated as a requirement; batching may 115 * cause the adapter to process more than max_nb_rx mbufs. 116 */ 117 }; 118 119 /** 120 * Function type used for adapter configuration callback. The callback is 121 * used to fill in members of the struct rte_event_eth_rx_adapter_conf, this 122 * callback is invoked when creating a SW service for packet transfer from 123 * ethdev queues to the event device. The SW service is created within the 124 * rte_event_eth_rx_adapter_queue_add() function if SW based packet transfers 125 * from ethdev queues to the event device are required. 126 * 127 * @param id 128 * Adapter identifier. 129 * 130 * @param dev_id 131 * Event device identifier. 132 * 133 * @param [out] conf 134 * Structure that needs to be populated by this callback. 135 * 136 * @param arg 137 * Argument to the callback. This is the same as the conf_arg passed to the 138 * rte_event_eth_rx_adapter_create_ext(). 139 */ 140 typedef int (*rte_event_eth_rx_adapter_conf_cb) (uint8_t id, uint8_t dev_id, 141 struct rte_event_eth_rx_adapter_conf *conf, 142 void *arg); 143 144 /** 145 * Rx queue configuration structure 146 */ 147 struct rte_event_eth_rx_adapter_queue_conf { 148 uint32_t rx_queue_flags; 149 /**< Flags for handling received packets 150 * @see RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID 151 */ 152 uint16_t servicing_weight; 153 /**< Relative polling frequency of ethernet receive queue when the 154 * adapter uses a service core function for ethernet to event device 155 * transfers. If it is set to zero, the Rx queue is interrupt driven 156 * (unless rx queue interrupts are not enabled for the ethernet 157 * device). 158 */ 159 struct rte_event ev; 160 /**< 161 * The values from the following event fields will be used when 162 * queuing mbuf events: 163 * - event_queue_id: Targeted event queue ID for received packets. 164 * - event_priority: Event priority of packets from this Rx queue in 165 * the event queue relative to other events. 166 * - sched_type: Scheduling type for packets from this Rx queue. 167 * - flow_id: If the RTE_ETH_RX_EVENT_ADAPTER_QUEUE_FLOW_ID_VALID bit 168 * is set in rx_queue_flags, this flow_id is used for all 169 * packets received from this queue. Otherwise the flow ID 170 * is set to the RSS hash of the src and dst IPv4/6 171 * addresses. 172 * 173 * The event adapter sets ev.event_type to RTE_EVENT_TYPE_ETHDEV in the 174 * enqueued event. 175 */ 176 uint16_t vector_sz; 177 /**< 178 * Indicates the maximum number for mbufs to combine and form a vector. 179 * Should be within 180 * @see rte_event_eth_rx_adapter_vector_limits::min_vector_sz 181 * @see rte_event_eth_rx_adapter_vector_limits::max_vector_sz 182 * Valid when RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR flag is set in 183 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags 184 */ 185 uint64_t vector_timeout_ns; 186 /**< 187 * Indicates the maximum number of nanoseconds to wait for receiving 188 * mbufs. Should be within vectorization limits of the 189 * adapter 190 * @see rte_event_eth_rx_adapter_vector_limits::min_vector_ns 191 * @see rte_event_eth_rx_adapter_vector_limits::max_vector_ns 192 * Valid when RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR flag is set in 193 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags 194 */ 195 struct rte_mempool *vector_mp; 196 /**< 197 * Indicates the mempool that should be used for allocating 198 * rte_event_vector container. 199 * Should be created by using `rte_event_vector_pool_create`. 200 * Valid when RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR flag is set in 201 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags. 202 */ 203 uint16_t event_buf_size; 204 /**< event buffer size for this queue */ 205 }; 206 207 /** 208 * A structure used to retrieve statistics for an eth rx adapter instance. 209 */ 210 struct rte_event_eth_rx_adapter_stats { 211 uint64_t rx_poll_count; 212 /**< Receive queue poll count */ 213 uint64_t rx_packets; 214 /**< Received packet count */ 215 uint64_t rx_enq_count; 216 /**< Eventdev enqueue count */ 217 uint64_t rx_enq_retry; 218 /**< Eventdev enqueue retry count */ 219 uint64_t rx_dropped; 220 /**< Received packet dropped count */ 221 uint64_t rx_enq_start_ts; 222 /**< Rx enqueue start timestamp */ 223 uint64_t rx_enq_block_cycles; 224 /**< Cycles for which the service is blocked by the event device, 225 * i.e, the service fails to enqueue to the event device. 226 */ 227 uint64_t rx_enq_end_ts; 228 /**< Latest timestamp at which the service is unblocked 229 * by the event device. The start, end timestamps and 230 * block cycles can be used to compute the percentage of 231 * cycles the service is blocked by the event device. 232 */ 233 uint64_t rx_intr_packets; 234 /**< Received packet count for interrupt mode Rx queues */ 235 uint64_t rx_event_buf_count; 236 /**< Rx event buffered count */ 237 uint64_t rx_event_buf_size; 238 /**< Rx event buffer size */ 239 }; 240 241 /** 242 * A structure used to retrieve eth rx adapter vector limits. 243 */ 244 struct rte_event_eth_rx_adapter_vector_limits { 245 uint16_t min_sz; 246 /**< Minimum vector limit configurable. 247 * @see rte_event_eth_rx_adapter_event_vector_config::vector_sz 248 */ 249 uint16_t max_sz; 250 /**< Maximum vector limit configurable. 251 * @see rte_event_eth_rx_adapter_event_vector_config::vector_sz 252 */ 253 uint8_t log2_sz; 254 /**< True if the size configured should be in log2. 255 * @see rte_event_eth_rx_adapter_event_vector_config::vector_sz 256 */ 257 uint64_t min_timeout_ns; 258 /**< Minimum vector timeout configurable. 259 * @see rte_event_eth_rx_adapter_event_vector_config::vector_timeout_ns 260 */ 261 uint64_t max_timeout_ns; 262 /**< Maximum vector timeout configurable. 263 * @see rte_event_eth_rx_adapter_event_vector_config::vector_timeout_ns 264 */ 265 }; 266 267 /** 268 * A structure to hold adapter config params 269 */ 270 struct rte_event_eth_rx_adapter_params { 271 uint16_t event_buf_size; 272 /**< size of event buffer for the adapter. 273 * This value is rounded up for better buffer utilization 274 * and performance. 275 */ 276 bool use_queue_event_buf; 277 /**< flag to indicate that event buffer is separate for each queue */ 278 }; 279 280 /** 281 * 282 * Callback function invoked by the SW adapter before it continues 283 * to process events. The callback is passed the size of the enqueue 284 * buffer in the SW adapter and the occupancy of the buffer. The 285 * callback can use these values to decide which events are 286 * enqueued to the event device by the SW adapter. The callback may 287 * also enqueue events internally using its own event port. The SW 288 * adapter populates the event information based on the Rx queue 289 * configuration in the adapter. The callback can modify the this event 290 * information for the events to be enqueued by the SW adapter. 291 * 292 * The callback return value is the number of events from the 293 * beginning of the event array that are to be enqueued by 294 * the SW adapter. It is the callback's responsibility to arrange 295 * these events at the beginning of the array, if these events are 296 * not contiguous in the original array. The *nb_dropped* parameter is 297 * a pointer to the number of events dropped by the callback, this 298 * number is used by the adapter to indicate the number of dropped packets 299 * as part of its statistics. 300 * 301 * @param eth_dev_id 302 * Port identifier of the Ethernet device. 303 * @param queue_id 304 * Receive queue index. 305 * @param enqueue_buf_size 306 * Total enqueue buffer size. 307 * @param enqueue_buf_count 308 * Event count in enqueue buffer. 309 * @param[in, out] ev 310 * Event array. 311 * @param nb_event 312 * Event array length. 313 * @param cb_arg 314 * Callback argument. 315 * @param[out] nb_dropped 316 * Packets dropped by callback. 317 * @return 318 * - The number of events to be enqueued by the SW adapter. 319 */ 320 typedef uint16_t (*rte_event_eth_rx_adapter_cb_fn)(uint16_t eth_dev_id, 321 uint16_t queue_id, 322 uint32_t enqueue_buf_size, 323 uint32_t enqueue_buf_count, 324 struct rte_event *ev, 325 uint16_t nb_event, 326 void *cb_arg, 327 uint16_t *nb_dropped); 328 329 /** 330 * Create a new ethernet Rx event adapter with the specified identifier. 331 * 332 * @param id 333 * The identifier of the ethernet Rx event adapter. 334 * 335 * @param dev_id 336 * The identifier of the device to configure. 337 * 338 * @param conf_cb 339 * Callback function that fills in members of a 340 * struct rte_event_eth_rx_adapter_conf struct passed into 341 * it. 342 * 343 * @param conf_arg 344 * Argument that is passed to the conf_cb function. 345 * 346 * @return 347 * - 0: Success 348 * - <0: Error code on failure 349 */ 350 int rte_event_eth_rx_adapter_create_ext(uint8_t id, uint8_t dev_id, 351 rte_event_eth_rx_adapter_conf_cb conf_cb, 352 void *conf_arg); 353 354 /** 355 * Create a new ethernet Rx event adapter with the specified identifier. 356 * This function uses an internal configuration function that creates an event 357 * port. This default function reconfigures the event device with an 358 * additional event port and setups up the event port using the port_config 359 * parameter passed into this function. In case the application needs more 360 * control in configuration of the service, it should use the 361 * rte_event_eth_rx_adapter_create_ext() version. 362 * 363 * @param id 364 * The identifier of the ethernet Rx event adapter. 365 * 366 * @param dev_id 367 * The identifier of the device to configure. 368 * 369 * @param port_config 370 * Argument of type *rte_event_port_conf* that is passed to the conf_cb 371 * function. 372 * 373 * @return 374 * - 0: Success 375 * - <0: Error code on failure 376 */ 377 int rte_event_eth_rx_adapter_create(uint8_t id, uint8_t dev_id, 378 struct rte_event_port_conf *port_config); 379 380 /** 381 * This is a variant of rte_event_eth_rx_adapter_create() with additional 382 * adapter params specified in ``struct rte_event_eth_rx_adapter_params``. 383 * 384 * @param id 385 * The identifier of the ethernet Rx event adapter. 386 * 387 * @param dev_id 388 * The identifier of the event device to configure. 389 * 390 * @param port_config 391 * Argument of type *rte_event_port_conf* that is passed to the conf_cb 392 * function. 393 * 394 * @param rxa_params 395 * Pointer to struct rte_event_eth_rx_adapter_params. 396 * In case of NULL, default values are used. 397 * 398 * @return 399 * - 0: Success 400 * - <0: Error code on failure 401 */ 402 __rte_experimental 403 int rte_event_eth_rx_adapter_create_with_params(uint8_t id, uint8_t dev_id, 404 struct rte_event_port_conf *port_config, 405 struct rte_event_eth_rx_adapter_params *rxa_params); 406 407 /** 408 * Free an event adapter 409 * 410 * @param id 411 * Adapter identifier. 412 * 413 * @return 414 * - 0: Success 415 * - <0: Error code on failure, If the adapter still has Rx queues 416 * added to it, the function returns -EBUSY. 417 */ 418 int rte_event_eth_rx_adapter_free(uint8_t id); 419 420 /** 421 * Add receive queue to an event adapter. After a queue has been 422 * added to the event adapter, the result of the application calling 423 * rte_eth_rx_burst(eth_dev_id, rx_queue_id, ..) is undefined. 424 * 425 * @param id 426 * Adapter identifier. 427 * 428 * @param eth_dev_id 429 * Port identifier of Ethernet device. 430 * 431 * @param rx_queue_id 432 * Ethernet device receive queue index. 433 * If rx_queue_id is -1, then all Rx queues configured for 434 * the device are added. If the ethdev Rx queues can only be 435 * connected to a single event queue then rx_queue_id is 436 * required to be -1. 437 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ 438 * 439 * @param conf 440 * Additional configuration structure of type *rte_event_eth_rx_adapter_conf* 441 * 442 * @return 443 * - 0: Success, Receive queue added correctly. 444 * - <0: Error code on failure. 445 * - (-EIO) device reconfiguration and restart error. The adapter reconfigures 446 * the event device with an additional port if it is required to use a service 447 * function for packet transfer from the ethernet device to the event device. 448 * If the device had been started before this call, this error code indicates 449 * an error in restart following an error in reconfiguration, i.e., a 450 * combination of the two error codes. 451 */ 452 int rte_event_eth_rx_adapter_queue_add(uint8_t id, 453 uint16_t eth_dev_id, 454 int32_t rx_queue_id, 455 const struct rte_event_eth_rx_adapter_queue_conf *conf); 456 457 /** 458 * Delete receive queue from an event adapter. 459 * 460 * @param id 461 * Adapter identifier. 462 * 463 * @param eth_dev_id 464 * Port identifier of Ethernet device. 465 * 466 * @param rx_queue_id 467 * Ethernet device receive queue index. 468 * If rx_queue_id is -1, then all Rx queues configured for 469 * the device are deleted. If the ethdev Rx queues can only be 470 * connected to a single event queue then rx_queue_id is 471 * required to be -1. 472 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ 473 * 474 * @return 475 * - 0: Success, Receive queue deleted correctly. 476 * - <0: Error code on failure. 477 */ 478 int rte_event_eth_rx_adapter_queue_del(uint8_t id, uint16_t eth_dev_id, 479 int32_t rx_queue_id); 480 481 /** 482 * Start ethernet Rx event adapter 483 * 484 * @param id 485 * Adapter identifier. 486 * 487 * @return 488 * - 0: Success, Adapter started correctly. 489 * - <0: Error code on failure. 490 * 491 * @note 492 * The eventdev to which the event_eth_rx_adapter is connected needs to 493 * be started before calling rte_event_eth_rx_adapter_start(). 494 */ 495 int rte_event_eth_rx_adapter_start(uint8_t id); 496 497 /** 498 * Stop ethernet Rx event adapter 499 * 500 * @param id 501 * Adapter identifier. 502 * 503 * @return 504 * - 0: Success, Adapter started correctly. 505 * - <0: Error code on failure. 506 */ 507 int rte_event_eth_rx_adapter_stop(uint8_t id); 508 509 /** 510 * Retrieve statistics for an adapter 511 * 512 * @param id 513 * Adapter identifier. 514 * 515 * @param [out] stats 516 * A pointer to structure used to retrieve statistics for an adapter. 517 * 518 * @return 519 * - 0: Success, retrieved successfully. 520 * - <0: Error code on failure. 521 */ 522 int rte_event_eth_rx_adapter_stats_get(uint8_t id, 523 struct rte_event_eth_rx_adapter_stats *stats); 524 525 /** 526 * Reset statistics for an adapter. 527 * 528 * @param id 529 * Adapter identifier. 530 * 531 * @return 532 * - 0: Success, statistics reset successfully. 533 * - <0: Error code on failure. 534 */ 535 int rte_event_eth_rx_adapter_stats_reset(uint8_t id); 536 537 /** 538 * Retrieve the service ID of an adapter. If the adapter doesn't use 539 * a rte_service function, this function returns -ESRCH. 540 * 541 * @param id 542 * Adapter identifier. 543 * 544 * @param [out] service_id 545 * A pointer to a uint32_t, to be filled in with the service id. 546 * 547 * @return 548 * - 0: Success 549 * - <0: Error code on failure, if the adapter doesn't use a rte_service 550 * function, this function returns -ESRCH. 551 */ 552 int rte_event_eth_rx_adapter_service_id_get(uint8_t id, uint32_t *service_id); 553 554 /** 555 * Register callback to process Rx packets, this is supported for 556 * SW based packet transfers. 557 * @see rte_event_eth_rx_cb_fn 558 * 559 * @param id 560 * Adapter identifier. 561 * @param eth_dev_id 562 * Port identifier of Ethernet device. 563 * @param cb_fn 564 * Callback function. 565 * @param cb_arg 566 * Callback arg. 567 * @return 568 * - 0: Success 569 * - <0: Error code on failure. 570 */ 571 int rte_event_eth_rx_adapter_cb_register(uint8_t id, uint16_t eth_dev_id, 572 rte_event_eth_rx_adapter_cb_fn cb_fn, 573 void *cb_arg); 574 575 /** 576 * Retrieve vector limits for a given event dev and eth dev pair. 577 * @see rte_event_eth_rx_adapter_vector_limits 578 * 579 * @param dev_id 580 * Event device identifier. 581 * @param eth_port_id 582 * Port identifier of the ethernet device. 583 * @param [out] limits 584 * A pointer to rte_event_eth_rx_adapter_vector_limits structure that has to 585 * be filled. 586 * 587 * @return 588 * - 0: Success. 589 * - <0: Error code on failure. 590 */ 591 int rte_event_eth_rx_adapter_vector_limits_get( 592 uint8_t dev_id, uint16_t eth_port_id, 593 struct rte_event_eth_rx_adapter_vector_limits *limits); 594 595 /** 596 * Retrieve Rx queue config information. 597 * 598 * @param id 599 * Adapter identifier. 600 601 * @param eth_dev_id 602 * Port identifier of Ethernet device. 603 604 * @param rx_queue_id 605 * Ethernet device receive queue index. 606 607 * @param[out] queue_conf 608 * Pointer to struct rte_event_eth_rx_adapter_queue_conf 609 610 * @return 611 * - 0: Success, Receive queue added correctly. 612 * - <0: Error code on failure. 613 */ 614 __rte_experimental 615 int rte_event_eth_rx_adapter_queue_conf_get(uint8_t id, 616 uint16_t eth_dev_id, 617 uint16_t rx_queue_id, 618 struct rte_event_eth_rx_adapter_queue_conf *queue_conf); 619 620 621 #ifdef __cplusplus 622 } 623 #endif 624 #endif /* _RTE_EVENT_ETH_RX_ADAPTER_ */ 625