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