lib/librte_eventdev/rte_event_eth_tx_adapter.h

   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_eventdev *dev = &rte_eventdevs[dev_id];
 359
 360 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
 361         if (dev_id >= RTE_EVENT_MAX_DEVS ||
 362                 !rte_eventdevs[dev_id].attached) {
 363                 rte_errno = EINVAL;
 364                 return 0;
 365         }
 366
 367         if (port_id >= dev->data->nb_ports) {
 368                 rte_errno = EINVAL;
 369                 return 0;
 370         }
 371 #endif
 372         rte_eventdev_trace_eth_tx_adapter_enqueue(dev_id, port_id, ev,
 373                 nb_events, flags);
 374         if (flags)
 375                 return dev->txa_enqueue_same_dest(dev->data->ports[port_id],
 376                                                   ev, nb_events);
 377         else
 378                 return dev->txa_enqueue(dev->data->ports[port_id], ev,
 379                                         nb_events);
 380 }
 381
 382 /**
 383  * Retrieve statistics for an adapter
 384  *
 385  * @param id
 386  *  Adapter identifier.
 387  * @param [out] stats
 388  *  A pointer to structure used to retrieve statistics for an adapter.
 389  * @return
 390  *  - 0: Success, statistics retrieved successfully.
 391  *  - <0: Error code on failure.
 392  */
 393 int
 394 rte_event_eth_tx_adapter_stats_get(uint8_t id,
 395                                 struct rte_event_eth_tx_adapter_stats *stats);
 396
 397 /**
 398  * Reset statistics for an adapter.
 399  *
 400  * @param id
 401  *  Adapter identifier.
 402  * @return
 403  *  - 0: Success, statistics reset successfully.
 404  *  - <0: Error code on failure.
 405  */
 406 int
 407 rte_event_eth_tx_adapter_stats_reset(uint8_t id);
 408
 409 /**
 410  * Retrieve the service ID of an adapter. If the adapter doesn't use
 411  * a rte_service function, this function returns -ESRCH.
 412  *
 413  * @param id
 414  *  Adapter identifier.
 415  * @param [out] service_id
 416  *  A pointer to a uint32_t, to be filled in with the service id.
 417  * @return
 418  *  - 0: Success
 419  *  - <0: Error code on failure, if the adapter doesn't use a rte_service
 420  * function, this function returns -ESRCH.
 421  */
 422 int
 423 rte_event_eth_tx_adapter_service_id_get(uint8_t id, uint32_t *service_id);
 424
 425 #ifdef __cplusplus
 426 }
 427 #endif
 428 #endif  /* _RTE_EVENT_ETH_TX_ADAPTER_ */