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