lib/librte_eventdev/rte_event_eth_rx_adapter.h

   1 /*
   2  *   Copyright(c) 2017 Intel Corporation. All rights reserved.
   3  *   All rights reserved.
   4  *
   5  *   Redistribution and use in source and binary forms, with or without
   6  *   modification, are permitted provided that the following conditions
   7  *   are met:
   8  *
   9  *     * Redistributions of source code must retain the above copyright
  10  *       notice, this list of conditions and the following disclaimer.
  11  *     * Redistributions in binary form must reproduce the above copyright
  12  *       notice, this list of conditions and the following disclaimer in
  13  *       the documentation and/or other materials provided with the
  14  *       distribution.
  15  *     * Neither the name of Intel Corporation nor the names of its
  16  *       contributors may be used to endorse or promote products derived
  17  *       from this software without specific prior written permission.
  18  *
  19  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30  */
  31
  32 #ifndef _RTE_EVENT_ETH_RX_ADAPTER_
  33 #define _RTE_EVENT_ETH_RX_ADAPTER_
  34
  35 /**
  36  * @file
  37  *
  38  * RTE Event Ethernet Rx Adapter
  39  *
  40  * An eventdev-based packet processing application enqueues/dequeues mbufs
  41  * to/from the event device. Packet flow from the ethernet device to the event
  42  * device can be accomplished using either HW or SW mechanisms depending on the
  43  * platform and the particular combination of ethernet and event devices. The
  44  * event ethernet Rx adapter provides common APIs to configure the packet flow
  45  * from the ethernet devices to event devices across both these transfer
  46  * mechanisms.
  47  *
  48  * The adapter uses a EAL service core function for SW based packet transfer
  49  * and uses the eventdev PMD functions to configure HW based packet transfer
  50  * between the ethernet device and the event device. For SW based packet
  51  * transfer, if the mbuf does not have a timestamp set, the adapter adds a
  52  * timestamp to the mbuf using rte_get_tsc_cycles(), this provides a more
  53  * accurate timestamp as compared to if the application were to set the time
  54  * stamp since it avoids event device schedule latency.
  55  *
  56  * The ethernet Rx event adapter's functions are:
  57  *  - rte_event_eth_rx_adapter_create_ext()
  58  *  - rte_event_eth_rx_adapter_create()
  59  *  - rte_event_eth_rx_adapter_free()
  60  *  - rte_event_eth_rx_adapter_queue_add()
  61  *  - rte_event_eth_rx_adapter_queue_del()
  62  *  - rte_event_eth_rx_adapter_start()
  63  *  - rte_event_eth_rx_adapter_stop()
  64  *  - rte_event_eth_rx_adapter_stats_get()
  65  *  - rte_event_eth_rx_adapter_stats_reset()
  66  *
  67  * The application creates an ethernet to event adapter using
  68  * rte_event_eth_rx_adapter_create_ext() or rte_event_eth_rx_adapter_create()
  69  * functions.
  70  * The adapter needs to know which ethernet rx queues to poll for mbufs as well
  71  * as event device parameters such as the event queue identifier, event
  72  * priority and scheduling type that the adapter should use when constructing
  73  * events. The rte_event_eth_rx_adapter_queue_add() function is provided for
  74  * this purpose.
  75  * The servicing weight parameter in the rte_event_eth_rx_adapter_queue_conf
  76  * is applicable when the Rx adapter uses a service core function and is
  77  * intended to provide application control of the frequency of polling ethernet
  78  * device receive queues, for example, the application may want to poll higher
  79  * priority queues with a higher frequency but at the same time not starve
  80  * lower priority queues completely. If this parameter is zero and the receive
  81  * interrupt is enabled when configuring the device, the receive queue is
  82  * interrupt driven; else, the queue is assigned a servicing weight of one.
  83  *
  84  * The application can start/stop the adapter using the
  85  * rte_event_eth_rx_adapter_start() and the rte_event_eth_rx_adapter_stop()
  86  * functions. If the adapter uses a rte_service function, then the application
  87  * is also required to assign a core to the service function and control the
  88  * service core using the rte_service APIs. The
  89  * rte_event_eth_rx_adapter_service_id_get() function can be used to retrieve
  90  * the service function ID of the adapter in this case.
  91  *
  92  * Note: Interrupt driven receive queues are currently unimplemented.
  93  */
  94
  95 #ifdef __cplusplus
  96 extern "C" {
  97 #endif
  98
  99 #include <stdint.h>
 100
 101 #include <rte_service.h>
 102
 103 #include "rte_eventdev.h"
 104
 105 #define RTE_EVENT_ETH_RX_ADAPTER_MAX_INSTANCE 32
 106
 107 /* struct rte_event_eth_rx_adapter_queue_conf flags definitions */
 108 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID    0x1
 109 /**< This flag indicates the flow identifier is valid
 110  * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
 111  */
 112
 113 /**
 114  * @warning
 115  * @b EXPERIMENTAL: this API may change without prior notice
 116  *
 117  * Adapter configuration structure that the adapter configuration callback
 118  * function is expected to fill out
 119  * @see rte_event_eth_rx_adapter_conf_cb
 120  */
 121 struct rte_event_eth_rx_adapter_conf {
 122         uint8_t event_port_id;
 123         /**< Event port identifier, the adapter enqueues mbuf events to this
 124          * port.
 125          */
 126         uint32_t max_nb_rx;
 127         /**< The adapter can return early if it has processed at least
 128          * max_nb_rx mbufs. This isn't treated as a requirement; batching may
 129          * cause the adapter to process more than max_nb_rx mbufs.
 130          */
 131 };
 132
 133 /**
 134  * @warning
 135  * @b EXPERIMENTAL: this API may change without prior notice
 136  *
 137  * Function type used for adapter configuration callback. The callback is
 138  * used to fill in members of the struct rte_event_eth_rx_adapter_conf, this
 139  * callback is invoked when creating a SW service for packet transfer from
 140  * ethdev queues to the event device. The SW service is created within the
 141  * rte_event_eth_rx_adapter_queue_add() function if SW based packet transfers
 142  * from ethdev queues to the event device are required.
 143  *
 144  * @param id
 145  *  Adapter identifier.
 146  *
 147  * @param dev_id
 148  *  Event device identifier.
 149  *
 150  * @param [out] conf
 151  *  Structure that needs to be populated by this callback.
 152  *
 153  * @param arg
 154  *  Argument to the callback. This is the same as the conf_arg passed to the
 155  *  rte_event_eth_rx_adapter_create_ext().
 156  */
 157 typedef int (*rte_event_eth_rx_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
 158                         struct rte_event_eth_rx_adapter_conf *conf,
 159                         void *arg);
 160
 161 /**
 162  * @warning
 163  * @b EXPERIMENTAL: this API may change without prior notice
 164  *
 165  * Rx queue configuration structure
 166  */
 167 struct rte_event_eth_rx_adapter_queue_conf {
 168         uint32_t rx_queue_flags;
 169          /**< Flags for handling received packets
 170           * @see RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID
 171           */
 172         uint16_t servicing_weight;
 173         /**< Relative polling frequency of ethernet receive queue when the
 174          * adapter uses a service core function for ethernet to event device
 175          * transfers. If it is set to zero, the Rx queue is interrupt driven
 176          * (unless rx queue interrupts are not enabled for the ethernet
 177          * device).
 178          */
 179         struct rte_event ev;
 180         /**<
 181          *  The values from the following event fields will be used when
 182          *  queuing mbuf events:
 183          *   - event_queue_id: Targeted event queue ID for received packets.
 184          *   - event_priority: Event priority of packets from this Rx queue in
 185          *                     the event queue relative to other events.
 186          *   - sched_type: Scheduling type for packets from this Rx queue.
 187          *   - flow_id: If the RTE_ETH_RX_EVENT_ADAPTER_QUEUE_FLOW_ID_VALID bit
 188          *              is set in rx_queue_flags, this flow_id is used for all
 189          *              packets received from this queue. Otherwise the flow ID
 190          *              is set to the RSS hash of the src and dst IPv4/6
 191          *              addresses.
 192          *
 193          * The event adapter sets ev.event_type to RTE_EVENT_TYPE_ETHDEV in the
 194          * enqueued event.
 195          */
 196 };
 197
 198 /**
 199  * @warning
 200  * @b EXPERIMENTAL: this API may change without prior notice
 201  *
 202  * A structure used to retrieve statistics for an eth rx adapter instance.
 203  */
 204 struct rte_event_eth_rx_adapter_stats {
 205         uint64_t rx_poll_count;
 206         /**< Receive queue poll count */
 207         uint64_t rx_packets;
 208         /**< Received packet count */
 209         uint64_t rx_enq_count;
 210         /**< Eventdev enqueue count */
 211         uint64_t rx_enq_retry;
 212         /**< Eventdev enqueue retry count */
 213         uint64_t rx_enq_start_ts;
 214         /**< Rx enqueue start timestamp */
 215         uint64_t rx_enq_block_cycles;
 216         /**< Cycles for which the service is blocked by the event device,
 217          * i.e, the service fails to enqueue to the event device.
 218          */
 219         uint64_t rx_enq_end_ts;
 220         /**< Latest timestamp at which the service is unblocked
 221          * by the event device. The start, end timestamps and
 222          * block cycles can be used to compute the percentage of
 223          * cycles the service is blocked by the event device.
 224          */
 225 };
 226
 227 /**
 228  * @warning
 229  * @b EXPERIMENTAL: this API may change without prior notice
 230  *
 231  * Create a new ethernet Rx event adapter with the specified identifier.
 232  *
 233  * @param id
 234  *  The identifier of the ethernet Rx event adapter.
 235  *
 236  * @param dev_id
 237  *  The identifier of the device to configure.
 238  *
 239  * @param conf_cb
 240  *  Callback function that fills in members of a
 241  *  struct rte_event_eth_rx_adapter_conf struct passed into
 242  *  it.
 243  *
 244  * @param conf_arg
 245  *  Argument that is passed to the conf_cb function.
 246  *
 247  * @return
 248  *   - 0: Success
 249  *   - <0: Error code on failure
 250  */
 251 int rte_event_eth_rx_adapter_create_ext(uint8_t id, uint8_t dev_id,
 252                                 rte_event_eth_rx_adapter_conf_cb conf_cb,
 253                                 void *conf_arg);
 254
 255 /**
 256  * @warning
 257  * @b EXPERIMENTAL: this API may change without prior notice
 258  *
 259  * Create a new ethernet Rx event adapter with the specified identifier.
 260  * This function uses an internal configuration function that creates an event
 261  * port. This default function reconfigures the event device with an
 262  * additional event port and setups up the event port using the port_config
 263  * parameter passed into this function. In case the application needs more
 264  * control in configuration of the service, it should use the
 265  * rte_event_eth_rx_adapter_create_ext() version.
 266  *
 267  * @param id
 268  *  The identifier of the ethernet Rx event adapter.
 269  *
 270  * @param dev_id
 271  *  The identifier of the device to configure.
 272  *
 273  * @param port_config
 274  *  Argument of type *rte_event_port_conf* that is passed to the conf_cb
 275  *  function.
 276  *
 277  * @return
 278  *   - 0: Success
 279  *   - <0: Error code on failure
 280  */
 281 int rte_event_eth_rx_adapter_create(uint8_t id, uint8_t dev_id,
 282                                 struct rte_event_port_conf *port_config);
 283
 284 /**
 285  * @warning
 286  * @b EXPERIMENTAL: this API may change without prior notice
 287  *
 288  * Free an event adapter
 289  *
 290  * @param id
 291  *  Adapter identifier.
 292  *
 293  * @return
 294  *   - 0: Success
 295  *   - <0: Error code on failure, If the adapter still has Rx queues
 296  *      added to it, the function returns -EBUSY.
 297  */
 298 int rte_event_eth_rx_adapter_free(uint8_t id);
 299
 300 /**
 301  * @warning
 302  * @b EXPERIMENTAL: this API may change without prior notice
 303  *
 304  * Add receive queue to an event adapter. After a queue has been
 305  * added to the event adapter, the result of the application calling
 306  * rte_eth_rx_burst(eth_dev_id, rx_queue_id, ..) is undefined.
 307  *
 308  * @param id
 309  *  Adapter identifier.
 310  *
 311  * @param eth_dev_id
 312  *  Port identifier of Ethernet device.
 313  *
 314  * @param rx_queue_id
 315  *  Ethernet device receive queue index.
 316  *  If rx_queue_id is -1, then all Rx queues configured for
 317  *  the device are added. If the ethdev Rx queues can only be
 318  *  connected to a single event queue then rx_queue_id is
 319  *  required to be -1.
 320  * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
 321  *
 322  * @param conf
 323  *  Additional configuration structure of type *rte_event_eth_rx_adapter_conf*
 324  *
 325  * @return
 326  *  - 0: Success, Receive queue added correctly.
 327  *  - <0: Error code on failure.
 328  *  - (-EIO) device reconfiguration and restart error. The adapter reconfigures
 329  *  the event device with an additional port if it is required to use a service
 330  *  function for packet transfer from the ethernet device to the event device.
 331  *  If the device had been started before this call, this error code indicates
 332  *  an error in restart following an error in reconfiguration, i.e., a
 333  *  combination of the two error codes.
 334  */
 335 int rte_event_eth_rx_adapter_queue_add(uint8_t id,
 336                         uint8_t eth_dev_id,
 337                         int32_t rx_queue_id,
 338                         const struct rte_event_eth_rx_adapter_queue_conf *conf);
 339
 340 /**
 341  * @warning
 342  * @b EXPERIMENTAL: this API may change without prior notice
 343  *
 344  * Delete receive queue from an event adapter.
 345  *
 346  * @param id
 347  *  Adapter identifier.
 348  *
 349  * @param eth_dev_id
 350  *  Port identifier of Ethernet device.
 351  *
 352  * @param rx_queue_id
 353  *  Ethernet device receive queue index.
 354  *  If rx_queue_id is -1, then all Rx queues configured for
 355  *  the device are deleted. If the ethdev Rx queues can only be
 356  *  connected to a single event queue then rx_queue_id is
 357  *  required to be -1.
 358  * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
 359  *
 360  * @return
 361  *  - 0: Success, Receive queue deleted correctly.
 362  *  - <0: Error code on failure.
 363  */
 364 int rte_event_eth_rx_adapter_queue_del(uint8_t id, uint8_t eth_dev_id,
 365                                        int32_t rx_queue_id);
 366
 367 /**
 368  * @warning
 369  * @b EXPERIMENTAL: this API may change without prior notice
 370  *
 371  * Start ethernet Rx event adapter
 372  *
 373  * @param id
 374  *  Adapter identifier.
 375  *
 376  * @return
 377  *  - 0: Success, Adapter started correctly.
 378  *  - <0: Error code on failure.
 379  */
 380 int rte_event_eth_rx_adapter_start(uint8_t id);
 381
 382 /**
 383  * @warning
 384  * @b EXPERIMENTAL: this API may change without prior notice
 385  *
 386  * Stop  ethernet Rx event adapter
 387  *
 388  * @param id
 389  *  Adapter identifier.
 390  *
 391  * @return
 392  *  - 0: Success, Adapter started correctly.
 393  *  - <0: Error code on failure.
 394  */
 395 int rte_event_eth_rx_adapter_stop(uint8_t id);
 396
 397 /**
 398  * @warning
 399  * @b EXPERIMENTAL: this API may change without prior notice
 400  *
 401  * Retrieve statistics for an adapter
 402  *
 403  * @param id
 404  *  Adapter identifier.
 405  *
 406  * @param [out] stats
 407  *  A pointer to structure used to retrieve statistics for an adapter.
 408  *
 409  * @return
 410  *  - 0: Success, retrieved successfully.
 411  *  - <0: Error code on failure.
 412  */
 413 int rte_event_eth_rx_adapter_stats_get(uint8_t id,
 414                                 struct rte_event_eth_rx_adapter_stats *stats);
 415
 416 /**
 417  * @warning
 418  * @b EXPERIMENTAL: this API may change without prior notice
 419  *
 420  * Reset statistics for an adapter.
 421  *
 422  * @param id
 423  *  Adapter identifier.
 424  *
 425  * @return
 426  *  - 0: Success, statistics reset successfully.
 427  *  - <0: Error code on failure.
 428  */
 429 int rte_event_eth_rx_adapter_stats_reset(uint8_t id);
 430
 431 /**
 432  * @warning
 433  * @b EXPERIMENTAL: this API may change without prior notice
 434  *
 435  * Retrieve the service ID of an adapter. If the adapter doesn't use
 436  * a rte_service function, this function returns -ESRCH.
 437  *
 438  * @param id
 439  *  Adapter identifier.
 440  *
 441  * @param [out] service_id
 442  *  A pointer to a uint32_t, to be filled in with the service id.
 443  *
 444  * @return
 445  *  - 0: Success
 446  *  - <0: Error code on failure, if the adapter doesn't use a rte_service
 447  * function, this function returns -ESRCH.
 448  */
 449 int rte_event_eth_rx_adapter_service_id_get(uint8_t id, uint32_t *service_id);
 450
 451 #ifdef __cplusplus
 452 }
 453 #endif
 454 #endif  /* _RTE_EVENT_ETH_RX_ADAPTER_ */