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 #include <stdint.h> 80 81 #include <rte_compat.h> 82 #include <rte_mbuf.h> 83 84 #include "rte_eventdev.h" 85 86 #ifdef __cplusplus 87 extern "C" { 88 #endif 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 int 496 rte_event_eth_tx_adapter_instance_get(uint16_t eth_dev_id, 497 uint16_t tx_queue_id, 498 uint8_t *txa_inst_id); 499 /** 500 * Enables the adapter to start enqueueing of packets to the 501 * Tx queue. 502 * 503 * This function is provided so that the application can 504 * resume enqueueing packets that reference packets for 505 * <eth_dev_id, tx_queue_id> after calling 506 * rte_event_eth_tx_adapter_queue_stop(). 507 * @see rte_event_eth_tx_adapter_queue_stop 508 * 509 * Use case: 510 * -------- 511 * The queue start/stop APIs help avoid some unexpected behavior with 512 * application stopping ethdev Tx queues and adapter being unaware of it. 513 * With these APIs, the application can call stop API to notify adapter 514 * that corresponding ethdev Tx queue is stopped and any in-flight 515 * packets are freed by adapter dataplane code. Adapter queue stop API 516 * is called before stopping the ethdev Tx queue. When ethdev Tx queue 517 * is enabled, application can notify adapter to resume processing of 518 * the packets for that queue by calling the start API. The ethdev Tx 519 * queue is started before calling adapter start API. 520 * 521 * @param eth_dev_id 522 * Port identifier of Ethernet device. 523 * @param tx_queue_id 524 * Ethernet device transmit queue index. 525 * @return 526 * - 0: Success 527 * - <0: Error code on failure 528 */ 529 int 530 rte_event_eth_tx_adapter_queue_start(uint16_t eth_dev_id, uint16_t tx_queue_id); 531 532 /** 533 * Stops the adapter runtime function from enqueueing any packets 534 * to the associated Tx queue. This API also frees any packets that may 535 * have been buffered for this queue. All inflight packets destined to the 536 * queue are freed by the adapter runtime until the queue is started again. 537 * @see rte_event_eth_tx_adapter_queue_start 538 * 539 * @param eth_dev_id 540 * Port identifier of Ethernet device. 541 * @param tx_queue_id 542 * Ethernet device transmit queue index. 543 * @return 544 * - 0: Success 545 * - <0: Error code on failure 546 */ 547 int 548 rte_event_eth_tx_adapter_queue_stop(uint16_t eth_dev_id, uint16_t tx_queue_id); 549 550 /** 551 * Initialize the adapter runtime configuration parameters with default values 552 * 553 * @param txa_params 554 * A pointer to structure of type struct rte_event_eth_tx_adapter_runtime_params 555 * 556 * @return 557 * - 0: Success 558 * - <0: Error code on failure 559 */ 560 __rte_experimental 561 int 562 rte_event_eth_tx_adapter_runtime_params_init( 563 struct rte_event_eth_tx_adapter_runtime_params *txa_params); 564 565 /** 566 * Set the runtime configuration parameters for adapter. 567 * 568 * @param id 569 * Adapter identifier 570 * @param params 571 * A pointer to structure of type struct rte_event_eth_tx_adapter_runtime_params 572 * with configuration parameter values. The reserved fields of this structure 573 * must be initialized to zero and the valid fields need to be set appropriately. 574 * This structure can be initialized using 575 * rte_event_eth_tx_adapter_runtime_params_init() API to default values or 576 * application may reset this structure and update required fields. 577 * 578 * @return 579 * - 0: Success 580 * - <0: Error code on failure 581 */ 582 __rte_experimental 583 int 584 rte_event_eth_tx_adapter_runtime_params_set(uint8_t id, 585 struct rte_event_eth_tx_adapter_runtime_params *params); 586 587 /** 588 * Get the runtime configuration parameters of adapter. 589 * 590 * @param id 591 * Adapter identifier 592 * @param[out] params 593 * A pointer to structure of type struct rte_event_eth_tx_adapter_runtime_params 594 * containing valid Tx adapter parameters when return value is 0. 595 * 596 * @return 597 * - 0: Success 598 * - <0: Error code on failure 599 */ 600 __rte_experimental 601 int 602 rte_event_eth_tx_adapter_runtime_params_get(uint8_t id, 603 struct rte_event_eth_tx_adapter_runtime_params *params); 604 605 #ifdef __cplusplus 606 } 607 #endif 608 #endif /* _RTE_EVENT_ETH_TX_ADAPTER_ */ 609