lib/librte_eventdev/rte_event_eth_rx_adapter.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2017 Intel Corporation.
   3  * All rights reserved.
   4  */
   5
   6 #ifndef _RTE_EVENT_ETH_RX_ADAPTER_
   7 #define _RTE_EVENT_ETH_RX_ADAPTER_
   8
   9 /**
  10  * @file
  11  *
  12  * RTE Event Ethernet Rx Adapter
  13  *
  14  * An eventdev-based packet processing application enqueues/dequeues mbufs
  15  * to/from the event device. Packet flow from the ethernet device to the event
  16  * device can be accomplished using either HW or SW mechanisms depending on the
  17  * platform and the particular combination of ethernet and event devices. The
  18  * event ethernet Rx adapter provides common APIs to configure the packet flow
  19  * from the ethernet devices to event devices across both these transfer
  20  * mechanisms.
  21  *
  22  * The adapter uses a EAL service core function for SW based packet transfer
  23  * and uses the eventdev PMD functions to configure HW based packet transfer
  24  * between the ethernet device and the event device. For SW based packet
  25  * transfer, if the mbuf does not have a timestamp set, the adapter adds a
  26  * timestamp to the mbuf using rte_get_tsc_cycles(), this provides a more
  27  * accurate timestamp as compared to if the application were to set the time
  28  * stamp since it avoids event device schedule latency.
  29  *
  30  * The ethernet Rx event adapter's functions are:
  31  *  - rte_event_eth_rx_adapter_create_ext()
  32  *  - rte_event_eth_rx_adapter_create()
  33  *  - rte_event_eth_rx_adapter_free()
  34  *  - rte_event_eth_rx_adapter_queue_add()
  35  *  - rte_event_eth_rx_adapter_queue_del()
  36  *  - rte_event_eth_rx_adapter_start()
  37  *  - rte_event_eth_rx_adapter_stop()
  38  *  - rte_event_eth_rx_adapter_stats_get()
  39  *  - rte_event_eth_rx_adapter_stats_reset()
  40  *
  41  * The application creates an ethernet to event adapter using
  42  * rte_event_eth_rx_adapter_create_ext() or rte_event_eth_rx_adapter_create()
  43  * functions.
  44  * The adapter needs to know which ethernet rx queues to poll for mbufs as well
  45  * as event device parameters such as the event queue identifier, event
  46  * priority and scheduling type that the adapter should use when constructing
  47  * events. The rte_event_eth_rx_adapter_queue_add() function is provided for
  48  * this purpose.
  49  * The servicing weight parameter in the rte_event_eth_rx_adapter_queue_conf
  50  * is applicable when the Rx adapter uses a service core function and is
  51  * intended to provide application control of the frequency of polling ethernet
  52  * device receive queues, for example, the application may want to poll higher
  53  * priority queues with a higher frequency but at the same time not starve
  54  * lower priority queues completely. If this parameter is zero and the receive
  55  * interrupt is enabled when configuring the device, the receive queue is
  56  * interrupt driven; else, the queue is assigned a servicing weight of one.
  57  *
  58  * The application can start/stop the adapter using the
  59  * rte_event_eth_rx_adapter_start() and the rte_event_eth_rx_adapter_stop()
  60  * functions. If the adapter uses a rte_service function, then the application
  61  * is also required to assign a core to the service function and control the
  62  * service core using the rte_service APIs. The
  63  * rte_event_eth_rx_adapter_service_id_get() function can be used to retrieve
  64  * the service function ID of the adapter in this case.
  65  *
  66  * For SW based packet transfers, i.e., when the
  67  * RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT is not set in the adapter's
  68  * capabilities flags for a particular ethernet device, the service function
  69  * temporarily enqueues mbufs to an event buffer before batch enqueueing these
  70  * to the event device. If the buffer fills up, the service function stops
  71  * dequeueing packets from the ethernet device. The application may want to
  72  * monitor the buffer fill level and instruct the service function to
  73  * selectively buffer packets. The application may also use some other
  74  * criteria to decide which packets should enter the event device even when
  75  * the event buffer fill level is low. The
  76  * rte_event_eth_rx_adapter_cb_register() function allows the
  77  * application to register a callback that selects which packets to enqueue
  78  * to the event device.
  79  *
  80  * Note:
  81  * 1) Devices created after an instance of rte_event_eth_rx_adapter_create
  82  *  should be added to a new instance of the rx adapter.
  83  */
  84
  85 #ifdef __cplusplus
  86 extern "C" {
  87 #endif
  88
  89 #include <stdint.h>
  90
  91 #include <rte_service.h>
  92
  93 #include "rte_eventdev.h"
  94
  95 #define RTE_EVENT_ETH_RX_ADAPTER_MAX_INSTANCE 32
  96
  97 /* struct rte_event_eth_rx_adapter_queue_conf flags definitions */
  98 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID    0x1
  99 /**< This flag indicates the flow identifier is valid
 100  * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
 101  */
 102
 103 /**
 104  * @warning
 105  * @b EXPERIMENTAL: this API may change without prior notice
 106  *
 107  * Adapter configuration structure that the adapter configuration callback
 108  * function is expected to fill out
 109  * @see rte_event_eth_rx_adapter_conf_cb
 110  */
 111 struct rte_event_eth_rx_adapter_conf {
 112         uint8_t event_port_id;
 113         /**< Event port identifier, the adapter enqueues mbuf events to this
 114          * port.
 115          */
 116         uint32_t max_nb_rx;
 117         /**< The adapter can return early if it has processed at least
 118          * max_nb_rx mbufs. This isn't treated as a requirement; batching may
 119          * cause the adapter to process more than max_nb_rx mbufs.
 120          */
 121 };
 122
 123 /**
 124  * @warning
 125  * @b EXPERIMENTAL: this API may change without prior notice
 126  *
 127  * Function type used for adapter configuration callback. The callback is
 128  * used to fill in members of the struct rte_event_eth_rx_adapter_conf, this
 129  * callback is invoked when creating a SW service for packet transfer from
 130  * ethdev queues to the event device. The SW service is created within the
 131  * rte_event_eth_rx_adapter_queue_add() function if SW based packet transfers
 132  * from ethdev queues to the event device are required.
 133  *
 134  * @param id
 135  *  Adapter identifier.
 136  *
 137  * @param dev_id
 138  *  Event device identifier.
 139  *
 140  * @param [out] conf
 141  *  Structure that needs to be populated by this callback.
 142  *
 143  * @param arg
 144  *  Argument to the callback. This is the same as the conf_arg passed to the
 145  *  rte_event_eth_rx_adapter_create_ext().
 146  */
 147 typedef int (*rte_event_eth_rx_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
 148                         struct rte_event_eth_rx_adapter_conf *conf,
 149                         void *arg);
 150
 151 /**
 152  * @warning
 153  * @b EXPERIMENTAL: this API may change without prior notice
 154  *
 155  * Rx queue configuration structure
 156  */
 157 struct rte_event_eth_rx_adapter_queue_conf {
 158         uint32_t rx_queue_flags;
 159          /**< Flags for handling received packets
 160           * @see RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID
 161           */
 162         uint16_t servicing_weight;
 163         /**< Relative polling frequency of ethernet receive queue when the
 164          * adapter uses a service core function for ethernet to event device
 165          * transfers. If it is set to zero, the Rx queue is interrupt driven
 166          * (unless rx queue interrupts are not enabled for the ethernet
 167          * device).
 168          */
 169         struct rte_event ev;
 170         /**<
 171          *  The values from the following event fields will be used when
 172          *  queuing mbuf events:
 173          *   - event_queue_id: Targeted event queue ID for received packets.
 174          *   - event_priority: Event priority of packets from this Rx queue in
 175          *                     the event queue relative to other events.
 176          *   - sched_type: Scheduling type for packets from this Rx queue.
 177          *   - flow_id: If the RTE_ETH_RX_EVENT_ADAPTER_QUEUE_FLOW_ID_VALID bit
 178          *              is set in rx_queue_flags, this flow_id is used for all
 179          *              packets received from this queue. Otherwise the flow ID
 180          *              is set to the RSS hash of the src and dst IPv4/6
 181          *              addresses.
 182          *
 183          * The event adapter sets ev.event_type to RTE_EVENT_TYPE_ETHDEV in the
 184          * enqueued event.
 185          */
 186 };
 187
 188 /**
 189  * @warning
 190  * @b EXPERIMENTAL: this API may change without prior notice
 191  *
 192  * A structure used to retrieve statistics for an eth rx adapter instance.
 193  */
 194 struct rte_event_eth_rx_adapter_stats {
 195         uint64_t rx_poll_count;
 196         /**< Receive queue poll count */
 197         uint64_t rx_packets;
 198         /**< Received packet count */
 199         uint64_t rx_enq_count;
 200         /**< Eventdev enqueue count */
 201         uint64_t rx_enq_retry;
 202         /**< Eventdev enqueue retry count */
 203         uint64_t rx_enq_start_ts;
 204         /**< Rx enqueue start timestamp */
 205         uint64_t rx_enq_block_cycles;
 206         /**< Cycles for which the service is blocked by the event device,
 207          * i.e, the service fails to enqueue to the event device.
 208          */
 209         uint64_t rx_enq_end_ts;
 210         /**< Latest timestamp at which the service is unblocked
 211          * by the event device. The start, end timestamps and
 212          * block cycles can be used to compute the percentage of
 213          * cycles the service is blocked by the event device.
 214          */
 215         uint64_t rx_intr_packets;
 216         /**< Received packet count for interrupt mode Rx queues */
 217 };
 218
 219 /**
 220  * @warning
 221  * @b EXPERIMENTAL: this API may change without prior notice
 222  *
 223  * Callback function invoked by the SW adapter before it continues
 224  * to process packets. The callback is passed the size of the enqueue
 225  * buffer in the SW adapter and the occupancy of the buffer. The
 226  * callback can use these values to decide which mbufs should be
 227  * enqueued to the event device. If the return value of the callback
 228  * is less than nb_mbuf then the SW adapter uses the return value to
 229  * enqueue enq_mbuf[] to the event device.
 230  *
 231  * @param eth_dev_id
 232  *  Port identifier of the Ethernet device.
 233  * @param queue_id
 234  *  Receive queue index.
 235  * @param enqueue_buf_size
 236  *  Total enqueue buffer size.
 237  * @param enqueue_buf_count
 238  *  mbuf count in enqueue buffer.
 239  * @param mbuf
 240  *  mbuf array.
 241  * @param nb_mbuf
 242  *  mbuf count.
 243  * @param cb_arg
 244  *  Callback argument.
 245  * @param[out] enq_mbuf
 246  *  The adapter enqueues enq_mbuf[] if the return value of the
 247  *  callback is less than nb_mbuf
 248  * @return
 249  *  Returns the number of mbufs should be enqueued to eventdev
 250  */
 251 typedef uint16_t (*rte_event_eth_rx_adapter_cb_fn)(uint16_t eth_dev_id,
 252                                                 uint16_t queue_id,
 253                                                 uint32_t enqueue_buf_size,
 254                                                 uint32_t enqueue_buf_count,
 255                                                 struct rte_mbuf **mbuf,
 256                                                 uint16_t nb_mbuf,
 257                                                 void *cb_arg,
 258                                                 struct rte_mbuf **enq_buf);
 259
 260 /**
 261  * @warning
 262  * @b EXPERIMENTAL: this API may change without prior notice
 263  *
 264  * Create a new ethernet Rx event adapter with the specified identifier.
 265  *
 266  * @param id
 267  *  The identifier of the ethernet Rx event adapter.
 268  *
 269  * @param dev_id
 270  *  The identifier of the device to configure.
 271  *
 272  * @param conf_cb
 273  *  Callback function that fills in members of a
 274  *  struct rte_event_eth_rx_adapter_conf struct passed into
 275  *  it.
 276  *
 277  * @param conf_arg
 278  *  Argument that is passed to the conf_cb function.
 279  *
 280  * @return
 281  *   - 0: Success
 282  *   - <0: Error code on failure
 283  */
 284 int rte_event_eth_rx_adapter_create_ext(uint8_t id, uint8_t dev_id,
 285                                 rte_event_eth_rx_adapter_conf_cb conf_cb,
 286                                 void *conf_arg);
 287
 288 /**
 289  * @warning
 290  * @b EXPERIMENTAL: this API may change without prior notice
 291  *
 292  * Create a new ethernet Rx event adapter with the specified identifier.
 293  * This function uses an internal configuration function that creates an event
 294  * port. This default function reconfigures the event device with an
 295  * additional event port and setups up the event port using the port_config
 296  * parameter passed into this function. In case the application needs more
 297  * control in configuration of the service, it should use the
 298  * rte_event_eth_rx_adapter_create_ext() version.
 299  *
 300  * @param id
 301  *  The identifier of the ethernet Rx event adapter.
 302  *
 303  * @param dev_id
 304  *  The identifier of the device to configure.
 305  *
 306  * @param port_config
 307  *  Argument of type *rte_event_port_conf* that is passed to the conf_cb
 308  *  function.
 309  *
 310  * @return
 311  *   - 0: Success
 312  *   - <0: Error code on failure
 313  */
 314 int rte_event_eth_rx_adapter_create(uint8_t id, uint8_t dev_id,
 315                                 struct rte_event_port_conf *port_config);
 316
 317 /**
 318  * @warning
 319  * @b EXPERIMENTAL: this API may change without prior notice
 320  *
 321  * Free an event adapter
 322  *
 323  * @param id
 324  *  Adapter identifier.
 325  *
 326  * @return
 327  *   - 0: Success
 328  *   - <0: Error code on failure, If the adapter still has Rx queues
 329  *      added to it, the function returns -EBUSY.
 330  */
 331 int rte_event_eth_rx_adapter_free(uint8_t id);
 332
 333 /**
 334  * @warning
 335  * @b EXPERIMENTAL: this API may change without prior notice
 336  *
 337  * Add receive queue to an event adapter. After a queue has been
 338  * added to the event adapter, the result of the application calling
 339  * rte_eth_rx_burst(eth_dev_id, rx_queue_id, ..) is undefined.
 340  *
 341  * @param id
 342  *  Adapter identifier.
 343  *
 344  * @param eth_dev_id
 345  *  Port identifier of Ethernet device.
 346  *
 347  * @param rx_queue_id
 348  *  Ethernet device receive queue index.
 349  *  If rx_queue_id is -1, then all Rx queues configured for
 350  *  the device are added. If the ethdev Rx queues can only be
 351  *  connected to a single event queue then rx_queue_id is
 352  *  required to be -1.
 353  * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
 354  *
 355  * @param conf
 356  *  Additional configuration structure of type *rte_event_eth_rx_adapter_conf*
 357  *
 358  * @return
 359  *  - 0: Success, Receive queue added correctly.
 360  *  - <0: Error code on failure.
 361  *  - (-EIO) device reconfiguration and restart error. The adapter reconfigures
 362  *  the event device with an additional port if it is required to use a service
 363  *  function for packet transfer from the ethernet device to the event device.
 364  *  If the device had been started before this call, this error code indicates
 365  *  an error in restart following an error in reconfiguration, i.e., a
 366  *  combination of the two error codes.
 367  */
 368 int rte_event_eth_rx_adapter_queue_add(uint8_t id,
 369                         uint16_t eth_dev_id,
 370                         int32_t rx_queue_id,
 371                         const struct rte_event_eth_rx_adapter_queue_conf *conf);
 372
 373 /**
 374  * @warning
 375  * @b EXPERIMENTAL: this API may change without prior notice
 376  *
 377  * Delete receive queue from an event adapter.
 378  *
 379  * @param id
 380  *  Adapter identifier.
 381  *
 382  * @param eth_dev_id
 383  *  Port identifier of Ethernet device.
 384  *
 385  * @param rx_queue_id
 386  *  Ethernet device receive queue index.
 387  *  If rx_queue_id is -1, then all Rx queues configured for
 388  *  the device are deleted. If the ethdev Rx queues can only be
 389  *  connected to a single event queue then rx_queue_id is
 390  *  required to be -1.
 391  * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
 392  *
 393  * @return
 394  *  - 0: Success, Receive queue deleted correctly.
 395  *  - <0: Error code on failure.
 396  */
 397 int rte_event_eth_rx_adapter_queue_del(uint8_t id, uint16_t eth_dev_id,
 398                                        int32_t rx_queue_id);
 399
 400 /**
 401  * @warning
 402  * @b EXPERIMENTAL: this API may change without prior notice
 403  *
 404  * Start ethernet Rx event adapter
 405  *
 406  * @param id
 407  *  Adapter identifier.
 408  *
 409  * @return
 410  *  - 0: Success, Adapter started correctly.
 411  *  - <0: Error code on failure.
 412  */
 413 int rte_event_eth_rx_adapter_start(uint8_t id);
 414
 415 /**
 416  * @warning
 417  * @b EXPERIMENTAL: this API may change without prior notice
 418  *
 419  * Stop  ethernet Rx event adapter
 420  *
 421  * @param id
 422  *  Adapter identifier.
 423  *
 424  * @return
 425  *  - 0: Success, Adapter started correctly.
 426  *  - <0: Error code on failure.
 427  */
 428 int rte_event_eth_rx_adapter_stop(uint8_t id);
 429
 430 /**
 431  * @warning
 432  * @b EXPERIMENTAL: this API may change without prior notice
 433  *
 434  * Retrieve statistics for an adapter
 435  *
 436  * @param id
 437  *  Adapter identifier.
 438  *
 439  * @param [out] stats
 440  *  A pointer to structure used to retrieve statistics for an adapter.
 441  *
 442  * @return
 443  *  - 0: Success, retrieved successfully.
 444  *  - <0: Error code on failure.
 445  */
 446 int rte_event_eth_rx_adapter_stats_get(uint8_t id,
 447                                 struct rte_event_eth_rx_adapter_stats *stats);
 448
 449 /**
 450  * @warning
 451  * @b EXPERIMENTAL: this API may change without prior notice
 452  *
 453  * Reset statistics for an adapter.
 454  *
 455  * @param id
 456  *  Adapter identifier.
 457  *
 458  * @return
 459  *  - 0: Success, statistics reset successfully.
 460  *  - <0: Error code on failure.
 461  */
 462 int rte_event_eth_rx_adapter_stats_reset(uint8_t id);
 463
 464 /**
 465  * @warning
 466  * @b EXPERIMENTAL: this API may change without prior notice
 467  *
 468  * Retrieve the service ID of an adapter. If the adapter doesn't use
 469  * a rte_service function, this function returns -ESRCH.
 470  *
 471  * @param id
 472  *  Adapter identifier.
 473  *
 474  * @param [out] service_id
 475  *  A pointer to a uint32_t, to be filled in with the service id.
 476  *
 477  * @return
 478  *  - 0: Success
 479  *  - <0: Error code on failure, if the adapter doesn't use a rte_service
 480  * function, this function returns -ESRCH.
 481  */
 482 int rte_event_eth_rx_adapter_service_id_get(uint8_t id, uint32_t *service_id);
 483
 484 /**
 485  * @warning
 486  * @b EXPERIMENTAL: this API may change without prior notice
 487  *
 488  * Register callback to process Rx packets, this is supported for
 489  * SW based packet transfers.
 490  * @see rte_event_eth_rx_cb_fn
 491  *
 492  * @param id
 493  *  Adapter identifier.
 494  * @param eth_dev_id
 495  *  Port identifier of Ethernet device.
 496  * @param cb_fn
 497  *  Callback function.
 498  * @param cb_arg
 499  *  Callback arg.
 500  * @return
 501  *  - 0: Success
 502  *  - <0: Error code on failure.
 503  */
 504 int __rte_experimental
 505 rte_event_eth_rx_adapter_cb_register(uint8_t id,
 506                                 uint16_t eth_dev_id,
 507                                 rte_event_eth_rx_adapter_cb_fn cb_fn,
 508                                 void *cb_arg);
 509
 510 #ifdef __cplusplus
 511 }
 512 #endif
 513 #endif  /* _RTE_EVENT_ETH_RX_ADAPTER_ */