1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2018 Intel Corporation. 3 */ 4 5 #ifndef _RTE_EVENT_ETH_TX_ADAPTER_ 6 #define _RTE_EVENT_ETH_TX_ADAPTER_ 7 8 /** 9 * @file 10 * 11 * RTE Event Ethernet Tx Adapter 12 * 13 * The event ethernet Tx adapter provides configuration and data path APIs 14 * for the ethernet transmit stage of an event driven packet processing 15 * application. These APIs abstract the implementation of the transmit stage 16 * and allow the application to use eventdev PMD support or a common 17 * implementation. 18 * 19 * In the common implementation, the application enqueues mbufs to the adapter 20 * which runs as a rte_service function. The service function dequeues events 21 * from its event port and transmits the mbufs referenced by these events. 22 * 23 * The ethernet Tx event adapter APIs are: 24 * 25 * - rte_event_eth_tx_adapter_create() 26 * - rte_event_eth_tx_adapter_create_ext() 27 * - rte_event_eth_tx_adapter_free() 28 * - rte_event_eth_tx_adapter_start() 29 * - rte_event_eth_tx_adapter_stop() 30 * - rte_event_eth_tx_adapter_queue_add() 31 * - rte_event_eth_tx_adapter_queue_del() 32 * - rte_event_eth_tx_adapter_stats_get() 33 * - rte_event_eth_tx_adapter_stats_reset() 34 * - rte_event_eth_tx_adapter_enqueue() 35 * - rte_event_eth_tx_adapter_event_port_get() 36 * - rte_event_eth_tx_adapter_service_id_get() 37 * - rte_event_eth_tx_adapter_instance_get() 38 * - rte_event_eth_tx_adapter_queue_start() 39 * - rte_event_eth_tx_adapter_queue_stop() 40 * - rte_event_eth_tx_adapter_runtime_params_get() 41 * - rte_event_eth_tx_adapter_runtime_params_init() 42 * - rte_event_eth_tx_adapter_runtime_params_set() 43 * 44 * The application creates the adapter using 45 * rte_event_eth_tx_adapter_create() or rte_event_eth_tx_adapter_create_ext(). 46 * 47 * The adapter will use the common implementation when the eventdev PMD 48 * does not have the #RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT capability. 49 * The common implementation uses an event port that is created using the port 50 * configuration parameter passed to rte_event_eth_tx_adapter_create(). The 51 * application can get the port identifier using 52 * rte_event_eth_tx_adapter_event_port_get() and must link an event queue to 53 * this port. 54 * 55 * If the eventdev PMD has the #RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT 56 * flags set, Tx adapter events should be enqueued using the 57 * rte_event_eth_tx_adapter_enqueue() function, else the application should 58 * use rte_event_enqueue_burst(). 59 * 60 * Transmit queues can be added and deleted from the adapter using 61 * rte_event_eth_tx_adapter_queue_add()/del() APIs respectively. 62 * 63 * The application can start and stop the adapter using the 64 * rte_event_eth_tx_adapter_start/stop() calls. 65 * 66 * The common adapter implementation uses an EAL service function as described 67 * before and its execution is controlled using the rte_service APIs. The 68 * rte_event_eth_tx_adapter_service_id_get() 69 * function can be used to retrieve the adapter's service function ID. 70 * 71 * The ethernet port and transmit queue index to transmit the mbuf on are 72 * specified using the mbuf port struct rte_mbuf::hash::txadapter:txq. 73 * The application should use the rte_event_eth_tx_adapter_txq_set() 74 * and rte_event_eth_tx_adapter_txq_get() functions to access the transmit 75 * queue index, using these macros will help with minimizing application 76 * impact due to a change in how the transmit queue index is specified. 77 */ 78 79 #ifdef __cplusplus 80 extern "C" { 81 #endif 82 83 #include <stdint.h> 84 85 #include <rte_compat.h> 86 #include <rte_mbuf.h> 87 88 #include "rte_eventdev.h" 89 90 /** 91 * Adapter configuration structure 92 * 93 * @see rte_event_eth_tx_adapter_create_ext 94 * @see rte_event_eth_tx_adapter_conf_cb 95 */ 96 struct rte_event_eth_tx_adapter_conf { 97 uint8_t event_port_id; 98 /**< Event port identifier, the adapter service function dequeues mbuf 99 * events from this port. 100 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT 101 */ 102 uint32_t max_nb_tx; 103 /**< The adapter can return early if it has processed at least 104 * max_nb_tx mbufs. This isn't treated as a requirement; batching may 105 * cause the adapter to process more than max_nb_tx mbufs. 106 */ 107 }; 108 109 /** 110 * Adapter runtime configuration parameters 111 */ 112 struct rte_event_eth_tx_adapter_runtime_params { 113 uint32_t max_nb_tx; 114 /**< The adapter can return early if it has processed at least 115 * max_nb_tx mbufs. This isn't treated as a requirement; batching may 116 * cause the adapter to process more than max_nb_tx mbufs. 117 * 118 * rte_event_eth_tx_adapter_create() configures the 119 * adapter with default value of max_nb_tx. 120 * rte_event_eth_tx_adapter_create_ext() configures the adapter with 121 * user provided value of max_nb_tx through 122 * rte_event_eth_tx_adapter_conf::max_nb_tx parameter. 123 * rte_event_eth_tx_adapter_runtime_params_set() allows to re-configure 124 * max_nb_tx during runtime (after adding at least one queue) 125 * 126 * This is valid for the devices without 127 * RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT capability. 128 */ 129 uint16_t flush_threshold; 130 /**< the number of service function iteration count to 131 * flush buffered packets. 132 * 133 * This is valid for the devices without 134 * RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT capability. 135 */ 136 uint16_t rsvd[29]; 137 /**< Reserved fields for future expansion */ 138 }; 139 140 /** 141 * Function type used for adapter configuration callback. The callback is 142 * used to fill in members of the struct rte_event_eth_tx_adapter_conf, this 143 * callback is invoked when creating a RTE service function based 144 * adapter implementation. 145 * 146 * @param id 147 * Adapter identifier. 148 * @param dev_id 149 * Event device identifier. 150 * @param [out] conf 151 * Structure that needs to be populated by this callback. 152 * @param arg 153 * Argument to the callback. This is the same as the conf_arg passed to the 154 * rte_event_eth_tx_adapter_create_ext(). 155 * 156 * @return 157 * - 0: Success 158 * - <0: Error code on failure 159 */ 160 typedef int (*rte_event_eth_tx_adapter_conf_cb) (uint8_t id, uint8_t dev_id, 161 struct rte_event_eth_tx_adapter_conf *conf, 162 void *arg); 163 164 /** 165 * A structure used to retrieve statistics for an ethernet Tx adapter instance. 166 */ 167 struct rte_event_eth_tx_adapter_stats { 168 uint64_t tx_retry; 169 /**< Number of transmit retries */ 170 uint64_t tx_packets; 171 /**< Number of packets transmitted */ 172 uint64_t tx_dropped; 173 /**< Number of packets dropped */ 174 }; 175 176 /** 177 * Create a new ethernet Tx adapter with the specified identifier. 178 * 179 * When this API is used for creating adapter instance, 180 * ``rte_event_dev_config::nb_event_ports`` is automatically incremented, 181 * and event device is reconfigured with additional event port during service 182 * initialization. This event device reconfigure logic also increments the 183 * ``rte_event_dev_config::nb_single_link_event_port_queues`` 184 * parameter if the adapter event port config is of type 185 * ``RTE_EVENT_PORT_CFG_SINGLE_LINK``. 186 * 187 * Application no longer needs to account for the 188 * ``rte_event_dev_config::nb_event_ports`` and 189 * ``rte_event_dev_config::nb_single_link_event_port_queues`` 190 * parameters required for eth Tx adapter in event device configure when 191 * the adapter is created with this API. 192 * 193 * @param id 194 * The identifier of the ethernet Tx adapter. 195 * @param dev_id 196 * The event device identifier. 197 * @param port_config 198 * Event port configuration, the adapter uses this configuration to 199 * create an event port if needed. 200 * @return 201 * - 0: Success 202 * - <0: Error code on failure 203 */ 204 int 205 rte_event_eth_tx_adapter_create(uint8_t id, uint8_t dev_id, 206 struct rte_event_port_conf *port_config); 207 208 /** 209 * Create a new ethernet Tx adapter with the specified identifier. 210 * 211 * @param id 212 * The identifier of the ethernet Tx adapter. 213 * @param dev_id 214 * The event device identifier. 215 * @param conf_cb 216 * Callback function that initializes members of the 217 * struct rte_event_eth_tx_adapter_conf struct passed into 218 * it. 219 * @param conf_arg 220 * Argument that is passed to the conf_cb function. 221 * @return 222 * - 0: Success 223 * - <0: Error code on failure 224 */ 225 int 226 rte_event_eth_tx_adapter_create_ext(uint8_t id, uint8_t dev_id, 227 rte_event_eth_tx_adapter_conf_cb conf_cb, 228 void *conf_arg); 229 230 /** 231 * Free an ethernet Tx adapter 232 * 233 * @param id 234 * Adapter identifier. 235 * @return 236 * - 0: Success 237 * - <0: Error code on failure, If the adapter still has Tx queues 238 * added to it, the function returns -EBUSY. 239 */ 240 int 241 rte_event_eth_tx_adapter_free(uint8_t id); 242 243 /** 244 * Start ethernet Tx adapter 245 * 246 * @param id 247 * Adapter identifier. 248 * @return 249 * - 0: Success, Adapter started correctly. 250 * - <0: Error code on failure. 251 */ 252 int 253 rte_event_eth_tx_adapter_start(uint8_t id); 254 255 /** 256 * Stop ethernet Tx adapter 257 * 258 * @param id 259 * Adapter identifier. 260 * @return 261 * - 0: Success. 262 * - <0: Error code on failure. 263 */ 264 int 265 rte_event_eth_tx_adapter_stop(uint8_t id); 266 267 /** 268 * Add a Tx queue to the adapter. 269 * A queue value of -1 is used to indicate all 270 * queues within the device. 271 * 272 * @param id 273 * Adapter identifier. 274 * @param eth_dev_id 275 * Ethernet Port Identifier. 276 * @param queue 277 * Tx queue index. 278 * @return 279 * - 0: Success, Queues added successfully. 280 * - <0: Error code on failure. 281 */ 282 int 283 rte_event_eth_tx_adapter_queue_add(uint8_t id, 284 uint16_t eth_dev_id, 285 int32_t queue); 286 287 /** 288 * Delete a Tx queue from the adapter. 289 * A queue value of -1 is used to indicate all 290 * queues within the device, that have been added to this 291 * adapter. 292 * 293 * @param id 294 * Adapter identifier. 295 * @param eth_dev_id 296 * Ethernet Port Identifier. 297 * @param queue 298 * Tx queue index. 299 * @return 300 * - 0: Success, Queues deleted successfully. 301 * - <0: Error code on failure. 302 */ 303 int 304 rte_event_eth_tx_adapter_queue_del(uint8_t id, 305 uint16_t eth_dev_id, 306 int32_t queue); 307 308 /** 309 * Set Tx queue in the mbuf. This queue is used by the adapter 310 * to transmit the mbuf. 311 * 312 * @param pkt 313 * Pointer to the mbuf. 314 * @param queue 315 * Tx queue index. 316 */ 317 static __rte_always_inline void 318 rte_event_eth_tx_adapter_txq_set(struct rte_mbuf *pkt, uint16_t queue) 319 { 320 pkt->hash.txadapter.txq = queue; 321 } 322 323 /** 324 * Retrieve Tx queue from the mbuf. 325 * 326 * @param pkt 327 * Pointer to the mbuf. 328 * @return 329 * Tx queue identifier. 330 * 331 * @see rte_event_eth_tx_adapter_txq_set() 332 */ 333 static __rte_always_inline uint16_t 334 rte_event_eth_tx_adapter_txq_get(struct rte_mbuf *pkt) 335 { 336 return pkt->hash.txadapter.txq; 337 } 338 339 /** 340 * Retrieve the adapter event port. The adapter creates an event port if 341 * the #RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT is not set in the 342 * ethernet Tx capabilities of the event device. 343 * 344 * @param id 345 * Adapter Identifier. 346 * @param[out] event_port_id 347 * Event port pointer. 348 * @return 349 * - 0: Success. 350 * - <0: Error code on failure. 351 */ 352 int 353 rte_event_eth_tx_adapter_event_port_get(uint8_t id, uint8_t *event_port_id); 354 355 #define RTE_EVENT_ETH_TX_ADAPTER_ENQUEUE_SAME_DEST 0x1 356 /**< This flag is used when all the packets enqueued in the tx adapter are 357 * destined for the same Ethernet port & Tx queue. 358 */ 359 360 /** 361 * Enqueue a burst of events objects or an event object supplied in *rte_event* 362 * structure on an event device designated by its *dev_id* through the event 363 * port specified by *port_id*. This function is supported if the eventdev PMD 364 * has the #RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT capability flag set. 365 * 366 * The *nb_events* parameter is the number of event objects to enqueue which are 367 * supplied in the *ev* array of *rte_event* structure. 368 * 369 * The rte_event_eth_tx_adapter_enqueue() function returns the number of 370 * events objects it actually enqueued. A return value equal to *nb_events* 371 * means that all event objects have been enqueued. 372 * 373 * @param dev_id 374 * The identifier of the device. 375 * @param port_id 376 * The identifier of the event port. 377 * @param ev 378 * Points to an array of *nb_events* objects of type *rte_event* structure 379 * which contain the event object enqueue operations to be processed. 380 * @param nb_events 381 * The number of event objects to enqueue, typically number of 382 * rte_event_port_attr_get(...RTE_EVENT_PORT_ATTR_ENQ_DEPTH...) 383 * available for this port. 384 * @param flags 385 * RTE_EVENT_ETH_TX_ADAPTER_ENQUEUE_ flags. 386 * #RTE_EVENT_ETH_TX_ADAPTER_ENQUEUE_SAME_DEST signifies that all the packets 387 * which are enqueued are destined for the same Ethernet port & Tx queue. 388 * 389 * @return 390 * The number of event objects actually enqueued on the event device. The 391 * return value can be less than the value of the *nb_events* parameter when 392 * the event devices queue is full or if invalid parameters are specified in a 393 * *rte_event*. If the return value is less than *nb_events*, the remaining 394 * events at the end of ev[] are not consumed and the caller has to take care 395 * of them, and rte_errno is set accordingly. Possible errno values include: 396 * - EINVAL The port ID is invalid, device ID is invalid, an event's queue 397 * ID is invalid, or an event's sched type doesn't match the 398 * capabilities of the destination queue. 399 * - ENOSPC The event port was backpressured and unable to enqueue 400 * one or more events. This error code is only applicable to 401 * closed systems. 402 */ 403 static inline uint16_t 404 rte_event_eth_tx_adapter_enqueue(uint8_t dev_id, 405 uint8_t port_id, 406 struct rte_event ev[], 407 uint16_t nb_events, 408 const uint8_t flags) 409 { 410 const struct rte_event_fp_ops *fp_ops; 411 void *port; 412 413 fp_ops = &rte_event_fp_ops[dev_id]; 414 port = fp_ops->data[port_id]; 415 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG 416 if (dev_id >= RTE_EVENT_MAX_DEVS || 417 port_id >= RTE_EVENT_MAX_PORTS_PER_DEV) { 418 rte_errno = EINVAL; 419 return 0; 420 } 421 422 if (port == NULL) { 423 rte_errno = EINVAL; 424 return 0; 425 } 426 #endif 427 rte_eventdev_trace_eth_tx_adapter_enqueue(dev_id, port_id, ev, 428 nb_events, flags); 429 if (flags) 430 return fp_ops->txa_enqueue_same_dest(port, ev, nb_events); 431 else 432 return fp_ops->txa_enqueue(port, ev, nb_events); 433 } 434 435 /** 436 * Retrieve statistics for an adapter 437 * 438 * @param id 439 * Adapter identifier. 440 * @param [out] stats 441 * A pointer to structure used to retrieve statistics for an adapter. 442 * @return 443 * - 0: Success, statistics retrieved successfully. 444 * - <0: Error code on failure. 445 */ 446 int 447 rte_event_eth_tx_adapter_stats_get(uint8_t id, 448 struct rte_event_eth_tx_adapter_stats *stats); 449 450 /** 451 * Reset statistics for an adapter. 452 * 453 * @param id 454 * Adapter identifier. 455 * @return 456 * - 0: Success, statistics reset successfully. 457 * - <0: Error code on failure. 458 */ 459 int 460 rte_event_eth_tx_adapter_stats_reset(uint8_t id); 461 462 /** 463 * Retrieve the service ID of an adapter. If the adapter doesn't use 464 * a rte_service function, this function returns -ESRCH. 465 * 466 * @param id 467 * Adapter identifier. 468 * @param [out] service_id 469 * A pointer to a uint32_t, to be filled in with the service id. 470 * @return 471 * - 0: Success 472 * - <0: Error code on failure, if the adapter doesn't use a rte_service 473 * function, this function returns -ESRCH. 474 */ 475 int 476 rte_event_eth_tx_adapter_service_id_get(uint8_t id, uint32_t *service_id); 477 478 /** 479 * Get TX adapter instance id for TX queue 480 * 481 * @param eth_dev_id 482 * Port identifier of Ethernet device 483 * 484 * @param tx_queue_id 485 * Etherdev device TX queue index 486 * 487 * @param[out] txa_inst_id 488 * Pointer to TX adapter instance identifier 489 * Contains valid Tx adapter instance id when return value is 0 490 * 491 * @return 492 * - 0: Success 493 * - <0: Error code on failure 494 */ 495 __rte_experimental 496 int 497 rte_event_eth_tx_adapter_instance_get(uint16_t eth_dev_id, 498 uint16_t tx_queue_id, 499 uint8_t *txa_inst_id); 500 /** 501 * Enables the adapter to start enqueueing of packets to the 502 * Tx queue. 503 * 504 * This function is provided so that the application can 505 * resume enqueueing packets that reference packets for 506 * <eth_dev_id, tx_queue_id> after calling 507 * rte_event_eth_tx_adapter_queue_stop(). 508 * @see rte_event_eth_tx_adapter_queue_stop 509 * 510 * Use case: 511 * -------- 512 * The queue start/stop APIs help avoid some unexpected behavior with 513 * application stopping ethdev Tx queues and adapter being unaware of it. 514 * With these APIs, the application can call stop API to notify adapter 515 * that corresponding ethdev Tx queue is stopped and any in-flight 516 * packets are freed by adapter dataplane code. Adapter queue stop API 517 * is called before stopping the ethdev Tx queue. When ethdev Tx queue 518 * is enabled, application can notify adapter to resume processing of 519 * the packets for that queue by calling the start API. The ethdev Tx 520 * queue is started before calling adapter start API. 521 * 522 * @param eth_dev_id 523 * Port identifier of Ethernet device. 524 * @param tx_queue_id 525 * Ethernet device transmit queue index. 526 * @return 527 * - 0: Success 528 * - <0: Error code on failure 529 */ 530 __rte_experimental 531 int 532 rte_event_eth_tx_adapter_queue_start(uint16_t eth_dev_id, uint16_t tx_queue_id); 533 534 /** 535 * Stops the adapter runtime function from enqueueing any packets 536 * to the associated Tx queue. This API also frees any packets that may 537 * have been buffered for this queue. All inflight packets destined to the 538 * queue are freed by the adapter runtime until the queue is started again. 539 * @see rte_event_eth_tx_adapter_queue_start 540 * 541 * @param eth_dev_id 542 * Port identifier of Ethernet device. 543 * @param tx_queue_id 544 * Ethernet device transmit queue index. 545 * @return 546 * - 0: Success 547 * - <0: Error code on failure 548 */ 549 __rte_experimental 550 int 551 rte_event_eth_tx_adapter_queue_stop(uint16_t eth_dev_id, uint16_t tx_queue_id); 552 553 /** 554 * Initialize the adapter runtime configuration parameters with default values 555 * 556 * @param txa_params 557 * A pointer to structure of type struct rte_event_eth_tx_adapter_runtime_params 558 * 559 * @return 560 * - 0: Success 561 * - <0: Error code on failure 562 */ 563 __rte_experimental 564 int 565 rte_event_eth_tx_adapter_runtime_params_init( 566 struct rte_event_eth_tx_adapter_runtime_params *txa_params); 567 568 /** 569 * Set the runtime configuration parameters for adapter. 570 * 571 * @param id 572 * Adapter identifier 573 * @param params 574 * A pointer to structure of type struct rte_event_eth_tx_adapter_runtime_params 575 * with configuration parameter values. The reserved fields of this structure 576 * must be initialized to zero and the valid fields need to be set appropriately. 577 * This structure can be initialized using 578 * rte_event_eth_tx_adapter_runtime_params_init() API to default values or 579 * application may reset this structure and update required fields. 580 * 581 * @return 582 * - 0: Success 583 * - <0: Error code on failure 584 */ 585 __rte_experimental 586 int 587 rte_event_eth_tx_adapter_runtime_params_set(uint8_t id, 588 struct rte_event_eth_tx_adapter_runtime_params *params); 589 590 /** 591 * Get the runtime configuration parameters of adapter. 592 * 593 * @param id 594 * Adapter identifier 595 * @param[out] params 596 * A pointer to structure of type struct rte_event_eth_tx_adapter_runtime_params 597 * containing valid Tx adapter parameters when return value is 0. 598 * 599 * @return 600 * - 0: Success 601 * - <0: Error code on failure 602 */ 603 __rte_experimental 604 int 605 rte_event_eth_tx_adapter_runtime_params_get(uint8_t id, 606 struct rte_event_eth_tx_adapter_runtime_params *params); 607 608 #ifdef __cplusplus 609 } 610 #endif 611 #endif /* _RTE_EVENT_ETH_TX_ADAPTER_ */ 612