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