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