lib/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.
  25  *
  26  * The ethernet Rx event adapter's functions are:
  27  *  - rte_event_eth_rx_adapter_create_ext()
  28  *  - rte_event_eth_rx_adapter_create()
  29  *  - rte_event_eth_rx_adapter_free()
  30  *  - rte_event_eth_rx_adapter_queue_add()
  31  *  - rte_event_eth_rx_adapter_queue_del()
  32  *  - rte_event_eth_rx_adapter_start()
  33  *  - rte_event_eth_rx_adapter_stop()
  34  *  - rte_event_eth_rx_adapter_stats_get()
  35  *  - rte_event_eth_rx_adapter_stats_reset()
  36  *  - rte_event_eth_rx_adapter_queue_conf_get()
  37  *
  38  * The application creates an ethernet to event adapter using
  39  * rte_event_eth_rx_adapter_create_ext() or rte_event_eth_rx_adapter_create()
  40  * functions.
  41  * The adapter needs to know which ethernet rx queues to poll for mbufs as well
  42  * as event device parameters such as the event queue identifier, event
  43  * priority and scheduling type that the adapter should use when constructing
  44  * events. The rte_event_eth_rx_adapter_queue_add() function is provided for
  45  * this purpose.
  46  * The servicing weight parameter in the rte_event_eth_rx_adapter_queue_conf
  47  * is applicable when the Rx adapter uses a service core function and is
  48  * intended to provide application control of the frequency of polling ethernet
  49  * device receive queues, for example, the application may want to poll higher
  50  * priority queues with a higher frequency but at the same time not starve
  51  * lower priority queues completely. If this parameter is zero and the receive
  52  * interrupt is enabled when configuring the device, the receive queue is
  53  * interrupt driven; else, the queue is assigned a servicing weight of one.
  54  *
  55  * The application can start/stop the adapter using the
  56  * rte_event_eth_rx_adapter_start() and the rte_event_eth_rx_adapter_stop()
  57  * functions. If the adapter uses a rte_service function, then the application
  58  * is also required to assign a core to the service function and control the
  59  * service core using the rte_service APIs. The
  60  * rte_event_eth_rx_adapter_service_id_get() function can be used to retrieve
  61  * the service function ID of the adapter in this case.
  62  *
  63  * For SW based packet transfers, i.e., when the
  64  * RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT is not set in the adapter's
  65  * capabilities flags for a particular ethernet device, the service function
  66  * temporarily enqueues events to an event buffer before batch enqueuing these
  67  * to the event device. If the buffer fills up, the service function stops
  68  * dequeuing packets from the ethernet device. The application may want to
  69  * monitor the buffer fill level and instruct the service function to
  70  * selectively buffer events. The application may also use some other
  71  * criteria to decide which packets should enter the event device even when
  72  * the event buffer fill level is low or may want to enqueue packets to an
  73  * internal event port. The rte_event_eth_rx_adapter_cb_register() function
  74  * allows the application to register a callback that selects which packets are
  75  * enqueued to the event device by the SW adapter. The callback interface is
  76  * event based so the callback can also modify the event data if it needs to.
  77  */
  78
  79 #ifdef __cplusplus
  80 extern "C" {
  81 #endif
  82
  83 #include <stdint.h>
  84
  85 #include <rte_service.h>
  86
  87 #include "rte_eventdev.h"
  88
  89 #define RTE_EVENT_ETH_RX_ADAPTER_MAX_INSTANCE 32
  90
  91 /* struct rte_event_eth_rx_adapter_queue_conf flags definitions */
  92 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID    0x1
  93 /**< This flag indicates the flow identifier is valid
  94  * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
  95  */
  96 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR     0x2
  97 /**< This flag indicates that mbufs arriving on the queue need to be vectorized
  98  * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
  99  */
 100
 101 /**
 102  * Adapter configuration structure that the adapter configuration callback
 103  * function is expected to fill out
 104  * @see rte_event_eth_rx_adapter_conf_cb
 105  */
 106 struct rte_event_eth_rx_adapter_conf {
 107         uint8_t event_port_id;
 108         /**< Event port identifier, the adapter enqueues mbuf events to this
 109          * port.
 110          */
 111         uint32_t max_nb_rx;
 112         /**< The adapter can return early if it has processed at least
 113          * max_nb_rx mbufs. This isn't treated as a requirement; batching may
 114          * cause the adapter to process more than max_nb_rx mbufs.
 115          */
 116 };
 117
 118 /**
 119  * Function type used for adapter configuration callback. The callback is
 120  * used to fill in members of the struct rte_event_eth_rx_adapter_conf, this
 121  * callback is invoked when creating a SW service for packet transfer from
 122  * ethdev queues to the event device. The SW service is created within the
 123  * rte_event_eth_rx_adapter_queue_add() function if SW based packet transfers
 124  * from ethdev queues to the event device are required.
 125  *
 126  * @param id
 127  *  Adapter identifier.
 128  *
 129  * @param dev_id
 130  *  Event device identifier.
 131  *
 132  * @param [out] conf
 133  *  Structure that needs to be populated by this callback.
 134  *
 135  * @param arg
 136  *  Argument to the callback. This is the same as the conf_arg passed to the
 137  *  rte_event_eth_rx_adapter_create_ext().
 138  */
 139 typedef int (*rte_event_eth_rx_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
 140                         struct rte_event_eth_rx_adapter_conf *conf,
 141                         void *arg);
 142
 143 /**
 144  * Rx queue configuration structure
 145  */
 146 struct rte_event_eth_rx_adapter_queue_conf {
 147         uint32_t rx_queue_flags;
 148          /**< Flags for handling received packets
 149           * @see RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID
 150           */
 151         uint16_t servicing_weight;
 152         /**< Relative polling frequency of ethernet receive queue when the
 153          * adapter uses a service core function for ethernet to event device
 154          * transfers. If it is set to zero, the Rx queue is interrupt driven
 155          * (unless rx queue interrupts are not enabled for the ethernet
 156          * device).
 157          */
 158         struct rte_event ev;
 159         /**<
 160          *  The values from the following event fields will be used when
 161          *  queuing mbuf events:
 162          *   - event_queue_id: Targeted event queue ID for received packets.
 163          *   - event_priority: Event priority of packets from this Rx queue in
 164          *                     the event queue relative to other events.
 165          *   - sched_type: Scheduling type for packets from this Rx queue.
 166          *   - flow_id: If the RTE_ETH_RX_EVENT_ADAPTER_QUEUE_FLOW_ID_VALID bit
 167          *              is set in rx_queue_flags, this flow_id is used for all
 168          *              packets received from this queue. Otherwise the flow ID
 169          *              is set to the RSS hash of the src and dst IPv4/6
 170          *              addresses.
 171          *
 172          * The event adapter sets ev.event_type to RTE_EVENT_TYPE_ETHDEV in the
 173          * enqueued event.
 174          */
 175         uint16_t vector_sz;
 176         /**<
 177          * Indicates the maximum number for mbufs to combine and form a vector.
 178          * Should be within
 179          * @see rte_event_eth_rx_adapter_vector_limits::min_vector_sz
 180          * @see rte_event_eth_rx_adapter_vector_limits::max_vector_sz
 181          * Valid when RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR flag is set in
 182          * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
 183          */
 184         uint64_t vector_timeout_ns;
 185         /**<
 186          * Indicates the maximum number of nanoseconds to wait for receiving
 187          * mbufs. Should be within vectorization limits of the
 188          * adapter
 189          * @see rte_event_eth_rx_adapter_vector_limits::min_vector_ns
 190          * @see rte_event_eth_rx_adapter_vector_limits::max_vector_ns
 191          * Valid when RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR flag is set in
 192          * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
 193          */
 194         struct rte_mempool *vector_mp;
 195         /**<
 196          * Indicates the mempool that should be used for allocating
 197          * rte_event_vector container.
 198          * Should be created by using `rte_event_vector_pool_create`.
 199          * Valid when RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR flag is set in
 200          * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags.
 201          */
 202 };
 203
 204 /**
 205  * A structure used to retrieve statistics for an eth rx adapter instance.
 206  */
 207 struct rte_event_eth_rx_adapter_stats {
 208         uint64_t rx_poll_count;
 209         /**< Receive queue poll count */
 210         uint64_t rx_packets;
 211         /**< Received packet count */
 212         uint64_t rx_enq_count;
 213         /**< Eventdev enqueue count */
 214         uint64_t rx_enq_retry;
 215         /**< Eventdev enqueue retry count */
 216         uint64_t rx_dropped;
 217         /**< Received packet dropped count */
 218         uint64_t rx_enq_start_ts;
 219         /**< Rx enqueue start timestamp */
 220         uint64_t rx_enq_block_cycles;
 221         /**< Cycles for which the service is blocked by the event device,
 222          * i.e, the service fails to enqueue to the event device.
 223          */
 224         uint64_t rx_enq_end_ts;
 225         /**< Latest timestamp at which the service is unblocked
 226          * by the event device. The start, end timestamps and
 227          * block cycles can be used to compute the percentage of
 228          * cycles the service is blocked by the event device.
 229          */
 230         uint64_t rx_intr_packets;
 231         /**< Received packet count for interrupt mode Rx queues */
 232 };
 233
 234 /**
 235  * A structure used to retrieve eth rx adapter vector limits.
 236  */
 237 struct rte_event_eth_rx_adapter_vector_limits {
 238         uint16_t min_sz;
 239         /**< Minimum vector limit configurable.
 240          * @see rte_event_eth_rx_adapter_event_vector_config::vector_sz
 241          */
 242         uint16_t max_sz;
 243         /**< Maximum vector limit configurable.
 244          * @see rte_event_eth_rx_adapter_event_vector_config::vector_sz
 245          */
 246         uint8_t log2_sz;
 247         /**< True if the size configured should be in log2.
 248          * @see rte_event_eth_rx_adapter_event_vector_config::vector_sz
 249          */
 250         uint64_t min_timeout_ns;
 251         /**< Minimum vector timeout configurable.
 252          * @see rte_event_eth_rx_adapter_event_vector_config::vector_timeout_ns
 253          */
 254         uint64_t max_timeout_ns;
 255         /**< Maximum vector timeout configurable.
 256          * @see rte_event_eth_rx_adapter_event_vector_config::vector_timeout_ns
 257          */
 258 };
 259
 260 /**
 261  *
 262  * Callback function invoked by the SW adapter before it continues
 263  * to process events. The callback is passed the size of the enqueue
 264  * buffer in the SW adapter and the occupancy of the buffer. The
 265  * callback can use these values to decide which events are
 266  * enqueued to the event device by the SW adapter. The callback may
 267  * also enqueue events internally using its own event port. The SW
 268  * adapter populates the event information based on the Rx queue
 269  * configuration in the adapter. The callback can modify the this event
 270  * information for the events to be enqueued by the SW adapter.
 271  *
 272  * The callback return value is the number of events from the
 273  * beginning of the event array that are to be enqueued by
 274  * the SW adapter. It is the callback's responsibility to arrange
 275  * these events at the beginning of the array, if these events are
 276  * not contiguous in the original array. The *nb_dropped* parameter is
 277  * a pointer to the number of events dropped by the callback, this
 278  * number is used by the adapter to indicate the number of dropped packets
 279  * as part of its statistics.
 280  *
 281  * @param eth_dev_id
 282  *  Port identifier of the Ethernet device.
 283  * @param queue_id
 284  *  Receive queue index.
 285  * @param enqueue_buf_size
 286  *  Total enqueue buffer size.
 287  * @param enqueue_buf_count
 288  *  Event count in enqueue buffer.
 289  * @param[in, out] ev
 290  *  Event array.
 291  * @param nb_event
 292  *  Event array length.
 293  * @param cb_arg
 294  *  Callback argument.
 295  * @param[out] nb_dropped
 296  *  Packets dropped by callback.
 297  * @return
 298  *  - The number of events to be enqueued by the SW adapter.
 299  */
 300 typedef uint16_t (*rte_event_eth_rx_adapter_cb_fn)(uint16_t eth_dev_id,
 301                                                 uint16_t queue_id,
 302                                                 uint32_t enqueue_buf_size,
 303                                                 uint32_t enqueue_buf_count,
 304                                                 struct rte_event *ev,
 305                                                 uint16_t nb_event,
 306                                                 void *cb_arg,
 307                                                 uint16_t *nb_dropped);
 308
 309 /**
 310  * Create a new ethernet Rx event adapter with the specified identifier.
 311  *
 312  * @param id
 313  *  The identifier of the ethernet Rx event adapter.
 314  *
 315  * @param dev_id
 316  *  The identifier of the device to configure.
 317  *
 318  * @param conf_cb
 319  *  Callback function that fills in members of a
 320  *  struct rte_event_eth_rx_adapter_conf struct passed into
 321  *  it.
 322  *
 323  * @param conf_arg
 324  *  Argument that is passed to the conf_cb function.
 325  *
 326  * @return
 327  *   - 0: Success
 328  *   - <0: Error code on failure
 329  */
 330 int rte_event_eth_rx_adapter_create_ext(uint8_t id, uint8_t dev_id,
 331                                 rte_event_eth_rx_adapter_conf_cb conf_cb,
 332                                 void *conf_arg);
 333
 334 /**
 335  * Create a new ethernet Rx event adapter with the specified identifier.
 336  * This function uses an internal configuration function that creates an event
 337  * port. This default function reconfigures the event device with an
 338  * additional event port and setups up the event port using the port_config
 339  * parameter passed into this function. In case the application needs more
 340  * control in configuration of the service, it should use the
 341  * rte_event_eth_rx_adapter_create_ext() version.
 342  *
 343  * @param id
 344  *  The identifier of the ethernet Rx event adapter.
 345  *
 346  * @param dev_id
 347  *  The identifier of the device to configure.
 348  *
 349  * @param port_config
 350  *  Argument of type *rte_event_port_conf* that is passed to the conf_cb
 351  *  function.
 352  *
 353  * @return
 354  *   - 0: Success
 355  *   - <0: Error code on failure
 356  */
 357 int rte_event_eth_rx_adapter_create(uint8_t id, uint8_t dev_id,
 358                                 struct rte_event_port_conf *port_config);
 359
 360 /**
 361  * Free an event adapter
 362  *
 363  * @param id
 364  *  Adapter identifier.
 365  *
 366  * @return
 367  *   - 0: Success
 368  *   - <0: Error code on failure, If the adapter still has Rx queues
 369  *      added to it, the function returns -EBUSY.
 370  */
 371 int rte_event_eth_rx_adapter_free(uint8_t id);
 372
 373 /**
 374  * Add receive queue to an event adapter. After a queue has been
 375  * added to the event adapter, the result of the application calling
 376  * rte_eth_rx_burst(eth_dev_id, rx_queue_id, ..) is undefined.
 377  *
 378  * @param id
 379  *  Adapter identifier.
 380  *
 381  * @param eth_dev_id
 382  *  Port identifier of Ethernet device.
 383  *
 384  * @param rx_queue_id
 385  *  Ethernet device receive queue index.
 386  *  If rx_queue_id is -1, then all Rx queues configured for
 387  *  the device are added. If the ethdev Rx queues can only be
 388  *  connected to a single event queue then rx_queue_id is
 389  *  required to be -1.
 390  * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
 391  *
 392  * @param conf
 393  *  Additional configuration structure of type *rte_event_eth_rx_adapter_conf*
 394  *
 395  * @return
 396  *  - 0: Success, Receive queue added correctly.
 397  *  - <0: Error code on failure.
 398  *  - (-EIO) device reconfiguration and restart error. The adapter reconfigures
 399  *  the event device with an additional port if it is required to use a service
 400  *  function for packet transfer from the ethernet device to the event device.
 401  *  If the device had been started before this call, this error code indicates
 402  *  an error in restart following an error in reconfiguration, i.e., a
 403  *  combination of the two error codes.
 404  */
 405 int rte_event_eth_rx_adapter_queue_add(uint8_t id,
 406                         uint16_t eth_dev_id,
 407                         int32_t rx_queue_id,
 408                         const struct rte_event_eth_rx_adapter_queue_conf *conf);
 409
 410 /**
 411  * Delete receive queue from an event adapter.
 412  *
 413  * @param id
 414  *  Adapter identifier.
 415  *
 416  * @param eth_dev_id
 417  *  Port identifier of Ethernet device.
 418  *
 419  * @param rx_queue_id
 420  *  Ethernet device receive queue index.
 421  *  If rx_queue_id is -1, then all Rx queues configured for
 422  *  the device are deleted. If the ethdev Rx queues can only be
 423  *  connected to a single event queue then rx_queue_id is
 424  *  required to be -1.
 425  * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
 426  *
 427  * @return
 428  *  - 0: Success, Receive queue deleted correctly.
 429  *  - <0: Error code on failure.
 430  */
 431 int rte_event_eth_rx_adapter_queue_del(uint8_t id, uint16_t eth_dev_id,
 432                                        int32_t rx_queue_id);
 433
 434 /**
 435  * Start ethernet Rx event adapter
 436  *
 437  * @param id
 438  *  Adapter identifier.
 439  *
 440  * @return
 441  *  - 0: Success, Adapter started correctly.
 442  *  - <0: Error code on failure.
 443  *
 444  * @note
 445  *  The eventdev to which the event_eth_rx_adapter is connected needs to
 446  *  be started before calling rte_event_eth_rx_adapter_start().
 447  */
 448 int rte_event_eth_rx_adapter_start(uint8_t id);
 449
 450 /**
 451  * Stop  ethernet Rx event adapter
 452  *
 453  * @param id
 454  *  Adapter identifier.
 455  *
 456  * @return
 457  *  - 0: Success, Adapter started correctly.
 458  *  - <0: Error code on failure.
 459  */
 460 int rte_event_eth_rx_adapter_stop(uint8_t id);
 461
 462 /**
 463  * Retrieve statistics for an adapter
 464  *
 465  * @param id
 466  *  Adapter identifier.
 467  *
 468  * @param [out] stats
 469  *  A pointer to structure used to retrieve statistics for an adapter.
 470  *
 471  * @return
 472  *  - 0: Success, retrieved successfully.
 473  *  - <0: Error code on failure.
 474  */
 475 int rte_event_eth_rx_adapter_stats_get(uint8_t id,
 476                                   struct rte_event_eth_rx_adapter_stats *stats);
 477
 478 /**
 479  * Reset statistics for an adapter.
 480  *
 481  * @param id
 482  *  Adapter identifier.
 483  *
 484  * @return
 485  *  - 0: Success, statistics reset successfully.
 486  *  - <0: Error code on failure.
 487  */
 488 int rte_event_eth_rx_adapter_stats_reset(uint8_t id);
 489
 490 /**
 491  * Retrieve the service ID of an adapter. If the adapter doesn't use
 492  * a rte_service function, this function returns -ESRCH.
 493  *
 494  * @param id
 495  *  Adapter identifier.
 496  *
 497  * @param [out] service_id
 498  *  A pointer to a uint32_t, to be filled in with the service id.
 499  *
 500  * @return
 501  *  - 0: Success
 502  *  - <0: Error code on failure, if the adapter doesn't use a rte_service
 503  * function, this function returns -ESRCH.
 504  */
 505 int rte_event_eth_rx_adapter_service_id_get(uint8_t id, uint32_t *service_id);
 506
 507 /**
 508  * Register callback to process Rx packets, this is supported for
 509  * SW based packet transfers.
 510  * @see rte_event_eth_rx_cb_fn
 511  *
 512  * @param id
 513  *  Adapter identifier.
 514  * @param eth_dev_id
 515  *  Port identifier of Ethernet device.
 516  * @param cb_fn
 517  *  Callback function.
 518  * @param cb_arg
 519  *  Callback arg.
 520  * @return
 521  *  - 0: Success
 522  *  - <0: Error code on failure.
 523  */
 524 int rte_event_eth_rx_adapter_cb_register(uint8_t id, uint16_t eth_dev_id,
 525                                          rte_event_eth_rx_adapter_cb_fn cb_fn,
 526                                          void *cb_arg);
 527
 528 /**
 529  * Retrieve vector limits for a given event dev and eth dev pair.
 530  * @see rte_event_eth_rx_adapter_vector_limits
 531  *
 532  * @param dev_id
 533  *  Event device identifier.
 534  * @param eth_port_id
 535  *  Port identifier of the ethernet device.
 536  * @param [out] limits
 537  *  A pointer to rte_event_eth_rx_adapter_vector_limits structure that has to
 538  * be filled.
 539  *
 540  * @return
 541  *  - 0: Success.
 542  *  - <0: Error code on failure.
 543  */
 544 __rte_experimental
 545 int rte_event_eth_rx_adapter_vector_limits_get(
 546         uint8_t dev_id, uint16_t eth_port_id,
 547         struct rte_event_eth_rx_adapter_vector_limits *limits);
 548
 549 /**
 550  * Retrieve Rx queue config information.
 551  *
 552  * @param id
 553  *  Adapter identifier.
 554
 555  * @param eth_dev_id
 556  *  Port identifier of Ethernet device.
 557
 558  * @param rx_queue_id
 559  *  Ethernet device receive queue index.
 560
 561  * @param[out] queue_conf
 562  *  Pointer to struct rte_event_eth_rx_adapter_queue_conf
 563
 564  * @return
 565  *  - 0: Success, Receive queue added correctly.
 566  *  - <0: Error code on failure.
 567  */
 568 __rte_experimental
 569 int rte_event_eth_rx_adapter_queue_conf_get(uint8_t id,
 570                         uint16_t eth_dev_id,
 571                         uint16_t rx_queue_id,
 572                         struct rte_event_eth_rx_adapter_queue_conf *queue_conf);
 573
 574
 575 #ifdef __cplusplus
 576 }
 577 #endif
 578 #endif  /* _RTE_EVENT_ETH_RX_ADAPTER_ */