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 * 41 * The application creates the adapter using 42 * rte_event_eth_tx_adapter_create() or rte_event_eth_tx_adapter_create_ext(). 43 * 44 * The adapter will use the common implementation when the eventdev PMD 45 * does not have the #RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT capability. 46 * The common implementation uses an event port that is created using the port 47 * configuration parameter passed to rte_event_eth_tx_adapter_create(). The 48 * application can get the port identifier using 49 * rte_event_eth_tx_adapter_event_port_get() and must link an event queue to 50 * this port. 51 * 52 * If the eventdev PMD has the #RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT 53 * flags set, Tx adapter events should be enqueued using the 54 * rte_event_eth_tx_adapter_enqueue() function, else the application should 55 * use rte_event_enqueue_burst(). 56 * 57 * Transmit queues can be added and deleted from the adapter using 58 * rte_event_eth_tx_adapter_queue_add()/del() APIs respectively. 59 * 60 * The application can start and stop the adapter using the 61 * rte_event_eth_tx_adapter_start/stop() calls. 62 * 63 * The common adapter implementation uses an EAL service function as described 64 * before and its execution is controlled using the rte_service APIs. The 65 * rte_event_eth_tx_adapter_service_id_get() 66 * function can be used to retrieve the adapter's service function ID. 67 * 68 * The ethernet port and transmit queue index to transmit the mbuf on are 69 * specified using the mbuf port struct rte_mbuf::hash::txadapter:txq. 70 * The application should use the rte_event_eth_tx_adapter_txq_set() 71 * and rte_event_eth_tx_adapter_txq_get() functions to access the transmit 72 * queue index, using these macros will help with minimizing application 73 * impact due to a change in how the transmit queue index is specified. 74 */ 75 76 #ifdef __cplusplus 77 extern "C" { 78 #endif 79 80 #include <stdint.h> 81 82 #include <rte_mbuf.h> 83 84 #include "rte_eventdev.h" 85 86 /** 87 * Adapter configuration structure 88 * 89 * @see rte_event_eth_tx_adapter_create_ext 90 * @see rte_event_eth_tx_adapter_conf_cb 91 */ 92 struct rte_event_eth_tx_adapter_conf { 93 uint8_t event_port_id; 94 /**< Event port identifier, the adapter service function dequeues mbuf 95 * events from this port. 96 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT 97 */ 98 uint32_t max_nb_tx; 99 /**< The adapter can return early if it has processed at least 100 * max_nb_tx mbufs. This isn't treated as a requirement; batching may 101 * cause the adapter to process more than max_nb_tx mbufs. 102 */ 103 }; 104 105 /** 106 * Function type used for adapter configuration callback. The callback is 107 * used to fill in members of the struct rte_event_eth_tx_adapter_conf, this 108 * callback is invoked when creating a RTE service function based 109 * adapter implementation. 110 * 111 * @param id 112 * Adapter identifier. 113 * @param dev_id 114 * Event device identifier. 115 * @param [out] conf 116 * Structure that needs to be populated by this callback. 117 * @param arg 118 * Argument to the callback. This is the same as the conf_arg passed to the 119 * rte_event_eth_tx_adapter_create_ext(). 120 * 121 * @return 122 * - 0: Success 123 * - <0: Error code on failure 124 */ 125 typedef int (*rte_event_eth_tx_adapter_conf_cb) (uint8_t id, uint8_t dev_id, 126 struct rte_event_eth_tx_adapter_conf *conf, 127 void *arg); 128 129 /** 130 * A structure used to retrieve statistics for an ethernet Tx adapter instance. 131 */ 132 struct rte_event_eth_tx_adapter_stats { 133 uint64_t tx_retry; 134 /**< Number of transmit retries */ 135 uint64_t tx_packets; 136 /**< Number of packets transmitted */ 137 uint64_t tx_dropped; 138 /**< Number of packets dropped */ 139 }; 140 141 /** 142 * Create a new ethernet Tx adapter with the specified identifier. 143 * 144 * @param id 145 * The identifier of the ethernet Tx adapter. 146 * @param dev_id 147 * The event device identifier. 148 * @param port_config 149 * Event port configuration, the adapter uses this configuration to 150 * create an event port if needed. 151 * @return 152 * - 0: Success 153 * - <0: Error code on failure 154 */ 155 int 156 rte_event_eth_tx_adapter_create(uint8_t id, uint8_t dev_id, 157 struct rte_event_port_conf *port_config); 158 159 /** 160 * Create a new ethernet Tx adapter with the specified identifier. 161 * 162 * @param id 163 * The identifier of the ethernet Tx adapter. 164 * @param dev_id 165 * The event device identifier. 166 * @param conf_cb 167 * Callback function that initializes members of the 168 * struct rte_event_eth_tx_adapter_conf struct passed into 169 * it. 170 * @param conf_arg 171 * Argument that is passed to the conf_cb function. 172 * @return 173 * - 0: Success 174 * - <0: Error code on failure 175 */ 176 int 177 rte_event_eth_tx_adapter_create_ext(uint8_t id, uint8_t dev_id, 178 rte_event_eth_tx_adapter_conf_cb conf_cb, 179 void *conf_arg); 180 181 /** 182 * Free an ethernet Tx adapter 183 * 184 * @param id 185 * Adapter identifier. 186 * @return 187 * - 0: Success 188 * - <0: Error code on failure, If the adapter still has Tx queues 189 * added to it, the function returns -EBUSY. 190 */ 191 int 192 rte_event_eth_tx_adapter_free(uint8_t id); 193 194 /** 195 * Start ethernet Tx adapter 196 * 197 * @param id 198 * Adapter identifier. 199 * @return 200 * - 0: Success, Adapter started correctly. 201 * - <0: Error code on failure. 202 */ 203 int 204 rte_event_eth_tx_adapter_start(uint8_t id); 205 206 /** 207 * Stop ethernet Tx adapter 208 * 209 * @param id 210 * Adapter identifier. 211 * @return 212 * - 0: Success. 213 * - <0: Error code on failure. 214 */ 215 int 216 rte_event_eth_tx_adapter_stop(uint8_t id); 217 218 /** 219 * Add a Tx queue to the adapter. 220 * A queue value of -1 is used to indicate all 221 * queues within the device. 222 * 223 * @param id 224 * Adapter identifier. 225 * @param eth_dev_id 226 * Ethernet Port Identifier. 227 * @param queue 228 * Tx queue index. 229 * @return 230 * - 0: Success, Queues added successfully. 231 * - <0: Error code on failure. 232 */ 233 int 234 rte_event_eth_tx_adapter_queue_add(uint8_t id, 235 uint16_t eth_dev_id, 236 int32_t queue); 237 238 /** 239 * Delete a Tx queue from the adapter. 240 * A queue value of -1 is used to indicate all 241 * queues within the device, that have been added to this 242 * adapter. 243 * 244 * @param id 245 * Adapter identifier. 246 * @param eth_dev_id 247 * Ethernet Port Identifier. 248 * @param queue 249 * Tx queue index. 250 * @return 251 * - 0: Success, Queues deleted successfully. 252 * - <0: Error code on failure. 253 */ 254 int 255 rte_event_eth_tx_adapter_queue_del(uint8_t id, 256 uint16_t eth_dev_id, 257 int32_t queue); 258 259 /** 260 * Set Tx queue in the mbuf. This queue is used by the adapter 261 * to transmit the mbuf. 262 * 263 * @param pkt 264 * Pointer to the mbuf. 265 * @param queue 266 * Tx queue index. 267 */ 268 static __rte_always_inline void 269 rte_event_eth_tx_adapter_txq_set(struct rte_mbuf *pkt, uint16_t queue) 270 { 271 pkt->hash.txadapter.txq = queue; 272 } 273 274 /** 275 * Retrieve Tx queue from the mbuf. 276 * 277 * @param pkt 278 * Pointer to the mbuf. 279 * @return 280 * Tx queue identifier. 281 * 282 * @see rte_event_eth_tx_adapter_txq_set() 283 */ 284 static __rte_always_inline uint16_t 285 rte_event_eth_tx_adapter_txq_get(struct rte_mbuf *pkt) 286 { 287 return pkt->hash.txadapter.txq; 288 } 289 290 /** 291 * Retrieve the adapter event port. The adapter creates an event port if 292 * the #RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT is not set in the 293 * ethernet Tx capabilities of the event device. 294 * 295 * @param id 296 * Adapter Identifier. 297 * @param[out] event_port_id 298 * Event port pointer. 299 * @return 300 * - 0: Success. 301 * - <0: Error code on failure. 302 */ 303 int 304 rte_event_eth_tx_adapter_event_port_get(uint8_t id, uint8_t *event_port_id); 305 306 #define RTE_EVENT_ETH_TX_ADAPTER_ENQUEUE_SAME_DEST 0x1 307 /**< This flag is used when all the packets enqueued in the tx adapter are 308 * destined for the same Ethernet port & Tx queue. 309 */ 310 311 /** 312 * Enqueue a burst of events objects or an event object supplied in *rte_event* 313 * structure on an event device designated by its *dev_id* through the event 314 * port specified by *port_id*. This function is supported if the eventdev PMD 315 * has the #RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT capability flag set. 316 * 317 * The *nb_events* parameter is the number of event objects to enqueue which are 318 * supplied in the *ev* array of *rte_event* structure. 319 * 320 * The rte_event_eth_tx_adapter_enqueue() function returns the number of 321 * events objects it actually enqueued. A return value equal to *nb_events* 322 * means that all event objects have been enqueued. 323 * 324 * @param dev_id 325 * The identifier of the device. 326 * @param port_id 327 * The identifier of the event port. 328 * @param ev 329 * Points to an array of *nb_events* objects of type *rte_event* structure 330 * which contain the event object enqueue operations to be processed. 331 * @param nb_events 332 * The number of event objects to enqueue, typically number of 333 * rte_event_port_attr_get(...RTE_EVENT_PORT_ATTR_ENQ_DEPTH...) 334 * available for this port. 335 * @param flags 336 * RTE_EVENT_ETH_TX_ADAPTER_ENQUEUE_ flags. 337 * #RTE_EVENT_ETH_TX_ADAPTER_ENQUEUE_SAME_DEST signifies that all the packets 338 * which are enqueued are destined for the same Ethernet port & Tx queue. 339 * 340 * @return 341 * The number of event objects actually enqueued on the event device. The 342 * return value can be less than the value of the *nb_events* parameter when 343 * the event devices queue is full or if invalid parameters are specified in a 344 * *rte_event*. If the return value is less than *nb_events*, the remaining 345 * events at the end of ev[] are not consumed and the caller has to take care 346 * of them, and rte_errno is set accordingly. Possible errno values include: 347 * - EINVAL The port ID is invalid, device ID is invalid, an event's queue 348 * ID is invalid, or an event's sched type doesn't match the 349 * capabilities of the destination queue. 350 * - ENOSPC The event port was backpressured and unable to enqueue 351 * one or more events. This error code is only applicable to 352 * closed systems. 353 */ 354 static inline uint16_t 355 rte_event_eth_tx_adapter_enqueue(uint8_t dev_id, 356 uint8_t port_id, 357 struct rte_event ev[], 358 uint16_t nb_events, 359 const uint8_t flags) 360 { 361 const struct rte_event_fp_ops *fp_ops; 362 void *port; 363 364 fp_ops = &rte_event_fp_ops[dev_id]; 365 port = fp_ops->data[port_id]; 366 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG 367 if (dev_id >= RTE_EVENT_MAX_DEVS || 368 port_id >= RTE_EVENT_MAX_PORTS_PER_DEV) { 369 rte_errno = EINVAL; 370 return 0; 371 } 372 373 if (port == NULL) { 374 rte_errno = EINVAL; 375 return 0; 376 } 377 #endif 378 rte_eventdev_trace_eth_tx_adapter_enqueue(dev_id, port_id, ev, 379 nb_events, flags); 380 if (flags) 381 return fp_ops->txa_enqueue_same_dest(port, ev, nb_events); 382 else 383 return fp_ops->txa_enqueue(port, ev, nb_events); 384 } 385 386 /** 387 * Retrieve statistics for an adapter 388 * 389 * @param id 390 * Adapter identifier. 391 * @param [out] stats 392 * A pointer to structure used to retrieve statistics for an adapter. 393 * @return 394 * - 0: Success, statistics retrieved successfully. 395 * - <0: Error code on failure. 396 */ 397 int 398 rte_event_eth_tx_adapter_stats_get(uint8_t id, 399 struct rte_event_eth_tx_adapter_stats *stats); 400 401 /** 402 * Reset statistics for an adapter. 403 * 404 * @param id 405 * Adapter identifier. 406 * @return 407 * - 0: Success, statistics reset successfully. 408 * - <0: Error code on failure. 409 */ 410 int 411 rte_event_eth_tx_adapter_stats_reset(uint8_t id); 412 413 /** 414 * Retrieve the service ID of an adapter. If the adapter doesn't use 415 * a rte_service function, this function returns -ESRCH. 416 * 417 * @param id 418 * Adapter identifier. 419 * @param [out] service_id 420 * A pointer to a uint32_t, to be filled in with the service id. 421 * @return 422 * - 0: Success 423 * - <0: Error code on failure, if the adapter doesn't use a rte_service 424 * function, this function returns -ESRCH. 425 */ 426 int 427 rte_event_eth_tx_adapter_service_id_get(uint8_t id, uint32_t *service_id); 428 429 /** 430 * Get TX adapter instance id for TX queue 431 * 432 * @param eth_dev_id 433 * Port identifier of Ethernet device 434 * 435 * @param tx_queue_id 436 * Etherdev device TX queue index 437 * 438 * @param[out] txa_inst_id 439 * Pointer to TX adapter instance identifier 440 * Contains valid Tx adapter instance id when return value is 0 441 * 442 * @return 443 * - 0: Success 444 * - <0: Error code on failure 445 */ 446 __rte_experimental 447 int 448 rte_event_eth_tx_adapter_instance_get(uint16_t eth_dev_id, 449 uint16_t tx_queue_id, 450 uint8_t *txa_inst_id); 451 /** 452 * Enables the adapter to start enqueueing of packets to the 453 * Tx queue. 454 * 455 * This function is provided so that the application can 456 * resume enqueueing packets that reference packets for 457 * <eth_dev_id, tx_queue_id> after calling 458 * rte_event_eth_tx_adapter_queue_stop(). 459 * @see rte_event_eth_tx_adapter_queue_stop 460 * 461 * Use case: 462 * -------- 463 * The queue start/stop APIs help avoid some unexpected behavior with 464 * application stopping ethdev Tx queues and adapter being unaware of it. 465 * With these APIs, the application can call stop API to notify adapter 466 * that corresponding ethdev Tx queue is stopped and any in-flight 467 * packets are freed by adapter dataplane code. Adapter queue stop API 468 * is called before stopping the ethdev Tx queue. When ethdev Tx queue 469 * is enabled, application can notify adapter to resume processing of 470 * the packets for that queue by calling the start API. The ethdev Tx 471 * queue is started before calling adapter start API. 472 * 473 * @param eth_dev_id 474 * Port identifier of Ethernet device. 475 * @param tx_queue_id 476 * Ethernet device transmit queue index. 477 * @return 478 * - 0: Success 479 * - <0: Error code on failure 480 */ 481 __rte_experimental 482 int 483 rte_event_eth_tx_adapter_queue_start(uint16_t eth_dev_id, uint16_t tx_queue_id); 484 485 /** 486 * Stops the adapter runtime function from enqueueing any packets 487 * to the associated Tx queue. This API also frees any packets that may 488 * have been buffered for this queue. All inflight packets destined to the 489 * queue are freed by the adapter runtime until the queue is started again. 490 * @see rte_event_eth_tx_adapter_queue_start 491 * 492 * @param eth_dev_id 493 * Port identifier of Ethernet device. 494 * @param tx_queue_id 495 * Ethernet device transmit queue index. 496 * @return 497 * - 0: Success 498 * - <0: Error code on failure 499 */ 500 __rte_experimental 501 int 502 rte_event_eth_tx_adapter_queue_stop(uint16_t eth_dev_id, uint16_t tx_queue_id); 503 504 #ifdef __cplusplus 505 } 506 #endif 507 #endif /* _RTE_EVENT_ETH_TX_ADAPTER_ */ 508