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  * Note:
  67  * 1) Devices created after an instance of rte_event_eth_rx_adapter_create
  68  *  should be added to a new instance of the rx adapter.
  69  */
  70
  71 #ifdef __cplusplus
  72 extern "C" {
  73 #endif
  74
  75 #include <stdint.h>
  76
  77 #include <rte_service.h>
  78
  79 #include "rte_eventdev.h"
  80
  81 #define RTE_EVENT_ETH_RX_ADAPTER_MAX_INSTANCE 32
  82
  83 /* struct rte_event_eth_rx_adapter_queue_conf flags definitions */
  84 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID    0x1
  85 /**< This flag indicates the flow identifier is valid
  86  * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
  87  */
  88
  89 /**
  90  * @warning
  91  * @b EXPERIMENTAL: this API may change without prior notice
  92  *
  93  * Adapter configuration structure that the adapter configuration callback
  94  * function is expected to fill out
  95  * @see rte_event_eth_rx_adapter_conf_cb
  96  */
  97 struct rte_event_eth_rx_adapter_conf {
  98         uint8_t event_port_id;
  99         /**< Event port identifier, the adapter enqueues mbuf events to this
 100          * port.
 101          */
 102         uint32_t max_nb_rx;
 103         /**< The adapter can return early if it has processed at least
 104          * max_nb_rx mbufs. This isn't treated as a requirement; batching may
 105          * cause the adapter to process more than max_nb_rx mbufs.
 106          */
 107 };
 108
 109 /**
 110  * @warning
 111  * @b EXPERIMENTAL: this API may change without prior notice
 112  *
 113  * Function type used for adapter configuration callback. The callback is
 114  * used to fill in members of the struct rte_event_eth_rx_adapter_conf, this
 115  * callback is invoked when creating a SW service for packet transfer from
 116  * ethdev queues to the event device. The SW service is created within the
 117  * rte_event_eth_rx_adapter_queue_add() function if SW based packet transfers
 118  * from ethdev queues to the event device are required.
 119  *
 120  * @param id
 121  *  Adapter identifier.
 122  *
 123  * @param dev_id
 124  *  Event device identifier.
 125  *
 126  * @param [out] conf
 127  *  Structure that needs to be populated by this callback.
 128  *
 129  * @param arg
 130  *  Argument to the callback. This is the same as the conf_arg passed to the
 131  *  rte_event_eth_rx_adapter_create_ext().
 132  */
 133 typedef int (*rte_event_eth_rx_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
 134                         struct rte_event_eth_rx_adapter_conf *conf,
 135                         void *arg);
 136
 137 /**
 138  * @warning
 139  * @b EXPERIMENTAL: this API may change without prior notice
 140  *
 141  * Rx queue configuration structure
 142  */
 143 struct rte_event_eth_rx_adapter_queue_conf {
 144         uint32_t rx_queue_flags;
 145          /**< Flags for handling received packets
 146           * @see RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID
 147           */
 148         uint16_t servicing_weight;
 149         /**< Relative polling frequency of ethernet receive queue when the
 150          * adapter uses a service core function for ethernet to event device
 151          * transfers. If it is set to zero, the Rx queue is interrupt driven
 152          * (unless rx queue interrupts are not enabled for the ethernet
 153          * device).
 154          */
 155         struct rte_event ev;
 156         /**<
 157          *  The values from the following event fields will be used when
 158          *  queuing mbuf events:
 159          *   - event_queue_id: Targeted event queue ID for received packets.
 160          *   - event_priority: Event priority of packets from this Rx queue in
 161          *                     the event queue relative to other events.
 162          *   - sched_type: Scheduling type for packets from this Rx queue.
 163          *   - flow_id: If the RTE_ETH_RX_EVENT_ADAPTER_QUEUE_FLOW_ID_VALID bit
 164          *              is set in rx_queue_flags, this flow_id is used for all
 165          *              packets received from this queue. Otherwise the flow ID
 166          *              is set to the RSS hash of the src and dst IPv4/6
 167          *              addresses.
 168          *
 169          * The event adapter sets ev.event_type to RTE_EVENT_TYPE_ETHDEV in the
 170          * enqueued event.
 171          */
 172 };
 173
 174 /**
 175  * @warning
 176  * @b EXPERIMENTAL: this API may change without prior notice
 177  *
 178  * A structure used to retrieve statistics for an eth rx adapter instance.
 179  */
 180 struct rte_event_eth_rx_adapter_stats {
 181         uint64_t rx_poll_count;
 182         /**< Receive queue poll count */
 183         uint64_t rx_packets;
 184         /**< Received packet count */
 185         uint64_t rx_enq_count;
 186         /**< Eventdev enqueue count */
 187         uint64_t rx_enq_retry;
 188         /**< Eventdev enqueue retry count */
 189         uint64_t rx_enq_start_ts;
 190         /**< Rx enqueue start timestamp */
 191         uint64_t rx_enq_block_cycles;
 192         /**< Cycles for which the service is blocked by the event device,
 193          * i.e, the service fails to enqueue to the event device.
 194          */
 195         uint64_t rx_enq_end_ts;
 196         /**< Latest timestamp at which the service is unblocked
 197          * by the event device. The start, end timestamps and
 198          * block cycles can be used to compute the percentage of
 199          * cycles the service is blocked by the event device.
 200          */
 201         uint64_t rx_intr_packets;
 202         /**< Received packet count for interrupt mode Rx queues */
 203 };
 204
 205 /**
 206  * @warning
 207  * @b EXPERIMENTAL: this API may change without prior notice
 208  *
 209  * Create a new ethernet Rx event adapter with the specified identifier.
 210  *
 211  * @param id
 212  *  The identifier of the ethernet Rx event adapter.
 213  *
 214  * @param dev_id
 215  *  The identifier of the device to configure.
 216  *
 217  * @param conf_cb
 218  *  Callback function that fills in members of a
 219  *  struct rte_event_eth_rx_adapter_conf struct passed into
 220  *  it.
 221  *
 222  * @param conf_arg
 223  *  Argument that is passed to the conf_cb function.
 224  *
 225  * @return
 226  *   - 0: Success
 227  *   - <0: Error code on failure
 228  */
 229 int rte_event_eth_rx_adapter_create_ext(uint8_t id, uint8_t dev_id,
 230                                 rte_event_eth_rx_adapter_conf_cb conf_cb,
 231                                 void *conf_arg);
 232
 233 /**
 234  * @warning
 235  * @b EXPERIMENTAL: this API may change without prior notice
 236  *
 237  * Create a new ethernet Rx event adapter with the specified identifier.
 238  * This function uses an internal configuration function that creates an event
 239  * port. This default function reconfigures the event device with an
 240  * additional event port and setups up the event port using the port_config
 241  * parameter passed into this function. In case the application needs more
 242  * control in configuration of the service, it should use the
 243  * rte_event_eth_rx_adapter_create_ext() version.
 244  *
 245  * @param id
 246  *  The identifier of the ethernet Rx event adapter.
 247  *
 248  * @param dev_id
 249  *  The identifier of the device to configure.
 250  *
 251  * @param port_config
 252  *  Argument of type *rte_event_port_conf* that is passed to the conf_cb
 253  *  function.
 254  *
 255  * @return
 256  *   - 0: Success
 257  *   - <0: Error code on failure
 258  */
 259 int rte_event_eth_rx_adapter_create(uint8_t id, uint8_t dev_id,
 260                                 struct rte_event_port_conf *port_config);
 261
 262 /**
 263  * @warning
 264  * @b EXPERIMENTAL: this API may change without prior notice
 265  *
 266  * Free an event adapter
 267  *
 268  * @param id
 269  *  Adapter identifier.
 270  *
 271  * @return
 272  *   - 0: Success
 273  *   - <0: Error code on failure, If the adapter still has Rx queues
 274  *      added to it, the function returns -EBUSY.
 275  */
 276 int rte_event_eth_rx_adapter_free(uint8_t id);
 277
 278 /**
 279  * @warning
 280  * @b EXPERIMENTAL: this API may change without prior notice
 281  *
 282  * Add receive queue to an event adapter. After a queue has been
 283  * added to the event adapter, the result of the application calling
 284  * rte_eth_rx_burst(eth_dev_id, rx_queue_id, ..) is undefined.
 285  *
 286  * @param id
 287  *  Adapter identifier.
 288  *
 289  * @param eth_dev_id
 290  *  Port identifier of Ethernet device.
 291  *
 292  * @param rx_queue_id
 293  *  Ethernet device receive queue index.
 294  *  If rx_queue_id is -1, then all Rx queues configured for
 295  *  the device are added. If the ethdev Rx queues can only be
 296  *  connected to a single event queue then rx_queue_id is
 297  *  required to be -1.
 298  * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
 299  *
 300  * @param conf
 301  *  Additional configuration structure of type *rte_event_eth_rx_adapter_conf*
 302  *
 303  * @return
 304  *  - 0: Success, Receive queue added correctly.
 305  *  - <0: Error code on failure.
 306  *  - (-EIO) device reconfiguration and restart error. The adapter reconfigures
 307  *  the event device with an additional port if it is required to use a service
 308  *  function for packet transfer from the ethernet device to the event device.
 309  *  If the device had been started before this call, this error code indicates
 310  *  an error in restart following an error in reconfiguration, i.e., a
 311  *  combination of the two error codes.
 312  */
 313 int rte_event_eth_rx_adapter_queue_add(uint8_t id,
 314                         uint16_t eth_dev_id,
 315                         int32_t rx_queue_id,
 316                         const struct rte_event_eth_rx_adapter_queue_conf *conf);
 317
 318 /**
 319  * @warning
 320  * @b EXPERIMENTAL: this API may change without prior notice
 321  *
 322  * Delete receive queue from an event adapter.
 323  *
 324  * @param id
 325  *  Adapter identifier.
 326  *
 327  * @param eth_dev_id
 328  *  Port identifier of Ethernet device.
 329  *
 330  * @param rx_queue_id
 331  *  Ethernet device receive queue index.
 332  *  If rx_queue_id is -1, then all Rx queues configured for
 333  *  the device are deleted. If the ethdev Rx queues can only be
 334  *  connected to a single event queue then rx_queue_id is
 335  *  required to be -1.
 336  * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
 337  *
 338  * @return
 339  *  - 0: Success, Receive queue deleted correctly.
 340  *  - <0: Error code on failure.
 341  */
 342 int rte_event_eth_rx_adapter_queue_del(uint8_t id, uint16_t eth_dev_id,
 343                                        int32_t rx_queue_id);
 344
 345 /**
 346  * @warning
 347  * @b EXPERIMENTAL: this API may change without prior notice
 348  *
 349  * Start ethernet Rx event adapter
 350  *
 351  * @param id
 352  *  Adapter identifier.
 353  *
 354  * @return
 355  *  - 0: Success, Adapter started correctly.
 356  *  - <0: Error code on failure.
 357  */
 358 int rte_event_eth_rx_adapter_start(uint8_t id);
 359
 360 /**
 361  * @warning
 362  * @b EXPERIMENTAL: this API may change without prior notice
 363  *
 364  * Stop  ethernet Rx event adapter
 365  *
 366  * @param id
 367  *  Adapter identifier.
 368  *
 369  * @return
 370  *  - 0: Success, Adapter started correctly.
 371  *  - <0: Error code on failure.
 372  */
 373 int rte_event_eth_rx_adapter_stop(uint8_t id);
 374
 375 /**
 376  * @warning
 377  * @b EXPERIMENTAL: this API may change without prior notice
 378  *
 379  * Retrieve statistics for an adapter
 380  *
 381  * @param id
 382  *  Adapter identifier.
 383  *
 384  * @param [out] stats
 385  *  A pointer to structure used to retrieve statistics for an adapter.
 386  *
 387  * @return
 388  *  - 0: Success, retrieved successfully.
 389  *  - <0: Error code on failure.
 390  */
 391 int rte_event_eth_rx_adapter_stats_get(uint8_t id,
 392                                 struct rte_event_eth_rx_adapter_stats *stats);
 393
 394 /**
 395  * @warning
 396  * @b EXPERIMENTAL: this API may change without prior notice
 397  *
 398  * Reset statistics for an adapter.
 399  *
 400  * @param id
 401  *  Adapter identifier.
 402  *
 403  * @return
 404  *  - 0: Success, statistics reset successfully.
 405  *  - <0: Error code on failure.
 406  */
 407 int rte_event_eth_rx_adapter_stats_reset(uint8_t id);
 408
 409 /**
 410  * @warning
 411  * @b EXPERIMENTAL: this API may change without prior notice
 412  *
 413  * Retrieve the service ID of an adapter. If the adapter doesn't use
 414  * a rte_service function, this function returns -ESRCH.
 415  *
 416  * @param id
 417  *  Adapter identifier.
 418  *
 419  * @param [out] service_id
 420  *  A pointer to a uint32_t, to be filled in with the service id.
 421  *
 422  * @return
 423  *  - 0: Success
 424  *  - <0: Error code on failure, if the adapter doesn't use a rte_service
 425  * function, this function returns -ESRCH.
 426  */
 427 int rte_event_eth_rx_adapter_service_id_get(uint8_t id, uint32_t *service_id);
 428
 429 #ifdef __cplusplus
 430 }
 431 #endif
 432 #endif  /* _RTE_EVENT_ETH_RX_ADAPTER_ */