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 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_enqueue_depth() available for this port.
 369  *
 370  * @return
 371  *   The number of event objects actually enqueued on the event device. The
 372  *   return value can be less than the value of the *nb_events* parameter when
 373  *   the event devices queue is full or if invalid parameters are specified in a
 374  *   *rte_event*. If the return value is less than *nb_events*, the remaining
 375  *   events at the end of ev[] are not consumed and the caller has to take care
 376  *   of them, and rte_errno is set accordingly. Possible errno values include:
 377  *   - -EINVAL  The port ID is invalid, device ID is invalid, an event's queue
 378  *              ID is invalid, or an event's sched type doesn't match the
 379  *              capabilities of the destination queue.
 380  *   - -ENOSPC  The event port was backpressured and unable to enqueue
 381  *              one or more events. This error code is only applicable to
 382  *              closed systems.
 383  */
 384 static inline uint16_t __rte_experimental
 385 rte_event_eth_tx_adapter_enqueue(uint8_t dev_id,
 386                                 uint8_t port_id,
 387                                 struct rte_event ev[],
 388                                 uint16_t nb_events)
 389 {
 390         const struct rte_eventdev *dev = &rte_eventdevs[dev_id];
 391
 392 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
 393         if (dev_id >= RTE_EVENT_MAX_DEVS ||
 394                 !rte_eventdevs[dev_id].attached) {
 395                 rte_errno = -EINVAL;
 396                 return 0;
 397         }
 398
 399         if (port_id >= dev->data->nb_ports) {
 400                 rte_errno = -EINVAL;
 401                 return 0;
 402         }
 403 #endif
 404         return dev->txa_enqueue(dev->data->ports[port_id], ev, nb_events);
 405 }
 406
 407 /**
 408  * @warning
 409  * @b EXPERIMENTAL: this API may change without prior notice
 410  *
 411  * Retrieve statistics for an adapter
 412  *
 413  * @param id
 414  *  Adapter identifier.
 415  * @param [out] stats
 416  *  A pointer to structure used to retrieve statistics for an adapter.
 417  * @return
 418  *  - 0: Success, statistics retrieved successfully.
 419  *  - <0: Error code on failure.
 420  */
 421 int __rte_experimental
 422 rte_event_eth_tx_adapter_stats_get(uint8_t id,
 423                                 struct rte_event_eth_tx_adapter_stats *stats);
 424
 425 /**
 426  * @warning
 427  * @b EXPERIMENTAL: this API may change without prior notice
 428  *
 429  * Reset statistics for an adapter.
 430  *
 431  * @param id
 432  *  Adapter identifier.
 433  * @return
 434  *  - 0: Success, statistics reset successfully.
 435  *  - <0: Error code on failure.
 436  */
 437 int __rte_experimental
 438 rte_event_eth_tx_adapter_stats_reset(uint8_t id);
 439
 440 /**
 441  * @warning
 442  * @b EXPERIMENTAL: this API may change without prior notice
 443  *
 444  * Retrieve the service ID of an adapter. If the adapter doesn't use
 445  * a rte_service function, this function returns -ESRCH.
 446  *
 447  * @param id
 448  *  Adapter identifier.
 449  * @param [out] service_id
 450  *  A pointer to a uint32_t, to be filled in with the service id.
 451  * @return
 452  *  - 0: Success
 453  *  - <0: Error code on failure, if the adapter doesn't use a rte_service
 454  * function, this function returns -ESRCH.
 455  */
 456 int __rte_experimental
 457 rte_event_eth_tx_adapter_service_id_get(uint8_t id, uint32_t *service_id);
 458
 459 #ifdef __cplusplus
 460 }
 461 #endif
 462 #endif  /* _RTE_EVENT_ETH_TX_ADAPTER_ */