lib/librte_ether/rte_ethdev.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2010-2012 Intel Corporation. All rights reserved.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  *
  33  */
  34
  35 #ifndef _RTE_ETHDEV_H_
  36 #define _RTE_ETHDEV_H_
  37
  38 /**
  39  * @file
  40  *
  41  * RTE Ethernet Device API
  42  *
  43  * The Ethernet Device API is composed of two parts:
  44  *
  45  * - The application-oriented Ethernet API that includes functions to setup
  46  *   an Ethernet device (configure it, setup its RX and TX queues and start it),
  47  *   to get its MAC address, the speed and the status of its physical link,
  48  *   to receive and to transmit packets, and so on.
  49  *
  50  * - The driver-oriented Ethernet API that exports a function allowing
  51  *   an Ethernet Poll Mode Driver (PMD) to simultaneously register itself as
  52  *   an Ethernet device driver and as a PCI driver for a set of matching PCI
  53  *   [Ethernet] devices classes.
  54  *
  55  * By default, all the functions of the Ethernet Device API exported by a PMD
  56  * are lock-free functions which assume to not be invoked in parallel on
  57  * different logical cores to work on the same target object.  For instance,
  58  * the receive function of a PMD cannot be invoked in parallel on two logical
  59  * cores to poll the same RX queue [of the same port]. Of course, this function
  60  * can be invoked in parallel by different logical cores on different RX queues.
  61  * It is the responsibility of the upper level application to enforce this rule.
  62  *
  63  * If needed, parallel accesses by multiple logical cores to shared queues
  64  * shall be explicitly protected by dedicated inline lock-aware functions
  65  * built on top of their corresponding lock-free functions of the PMD API.
  66  *
  67  * In all functions of the Ethernet API, the Ethernet device is
  68  * designated by an integer >= 0 named the device port identifier.
  69  *
  70  * At the Ethernet driver level, Ethernet devices are represented by a generic
  71  * data structure of type *rte_eth_dev*.
  72  *
  73  * Ethernet devices are dynamically registered during the PCI probing phase
  74  * performed at EAL initialization time.
  75  * When an Ethernet device is being probed, an *rte_eth_dev* structure and
  76  * a new port identifier are allocated for that device. Then, the eth_dev_init()
  77  * function supplied by the Ethernet driver matching the probed PCI
  78  * device is invoked to properly initialize the device.
  79  *
  80  * The role of the device init function consists of resetting the hardware,
  81  * checking access to Non-volatile Memory (NVM), reading the MAC address
  82  * from NVM etc.
  83  *
  84  * If the device init operation is successful, the correspondence between
  85  * the port identifier assigned to the new device and its associated
  86  * *rte_eth_dev* structure is effectively registered.
  87  * Otherwise, both the *rte_eth_dev* structure and the port identifier are
  88  * freed.
  89  *
  90  * The functions exported by the application Ethernet API to setup a device
  91  * designated by its port identifier must be invoked in the following order:
  92  *     - rte_eth_dev_configure()
  93  *     - rte_eth_tx_queue_setup()
  94  *     - rte_eth_rx_queue_setup()
  95  *     - rte_eth_dev_start()
  96  *
  97  * Then, the network application can invoke, in any order, the functions
  98  * exported by the Ethernet API to get the MAC address of a given device, to
  99  * get the speed and the status of a device physical link, to receive/transmit
 100  * [burst of] packets, and so on.
 101  *
 102  * If the application wants to change the configuration (i.e. call
 103  * rte_eth_dev_configure(), rte_eth_tx_queue_setup(), or
 104  * rte_eth_rx_queue_setup()), it must call rte_eth_dev_stop() first to stop the
 105  * device and then do the reconfiguration before calling rte_eth_dev_start()
 106  * again. The tramsit and receive functions should not be invoked when the
 107  * device is stopped.
 108  *
 109  * Please note that some configuration is not stored between calls to
 110  * rte_eth_dev_stop()/rte_eth_dev_start(). The following configuration will
 111  * be retained:
 112  *
 113  *     - flow control settings
 114  *     - receive mode configuration (promiscuous mode, hardware checksum mode,
 115  *       RSS/VMDQ settings etc.)
 116  *     - VLAN filtering configuration
 117  *     - MAC addresses supplied to MAC address array
 118  *     - flow director filtering mode (but not filtering rules)
 119  *     - NIC queue statistics mappings
 120  *
 121  * Any other configuration will not be stored and will need to be re-entered
 122  * after a call to rte_eth_dev_start().
 123  *
 124  * Finally, a network application can close an Ethernet device by invoking the
 125  * rte_eth_dev_close() function.
 126  *
 127  * Each function of the application Ethernet API invokes a specific function
 128  * of the PMD that controls the target device designated by its port
 129  * identifier.
 130  * For this purpose, all device-specific functions of an Ethernet driver are
 131  * supplied through a set of pointers contained in a generic structure of type
 132  * *eth_dev_ops*.
 133  * The address of the *eth_dev_ops* structure is stored in the *rte_eth_dev*
 134  * structure by the device init function of the Ethernet driver, which is
 135  * invoked during the PCI probing phase, as explained earlier.
 136  *
 137  * In other words, each function of the Ethernet API simply retrieves the
 138  * *rte_eth_dev* structure associated with the device port identifier and
 139  * performs an indirect invocation of the corresponding driver function
 140  * supplied in the *eth_dev_ops* structure of the *rte_eth_dev* structure.
 141  *
 142  * For performance reasons, the address of the burst-oriented RX and TX
 143  * functions of the Ethernet driver are not contained in the *eth_dev_ops*
 144  * structure. Instead, they are directly stored at the beginning of the
 145  * *rte_eth_dev* structure to avoid an extra indirect memory access during
 146  * their invocation.
 147  *
 148  * RTE ethernet device drivers do not use interrupts for transmitting or
 149  * receiving. Instead, Ethernet drivers export Poll-Mode receive and transmit
 150  * functions to applications.
 151  * Both receive and transmit functions are packet-burst oriented to minimize
 152  * their cost per packet through the following optimizations:
 153  *
 154  * - Sharing among multiple packets the incompressible cost of the
 155  *   invocation of receive/transmit functions.
 156  *
 157  * - Enabling receive/transmit functions to take advantage of burst-oriented
 158  *   hardware features (L1 cache, prefetch instructions, NIC head/tail
 159  *   registers) to minimize the number of CPU cycles per packet, for instance,
 160  *   by avoiding useless read memory accesses to ring descriptors, or by
 161  *   systematically using arrays of pointers that exactly fit L1 cache line
 162  *   boundaries and sizes.
 163  *
 164  * The burst-oriented receive function does not provide any error notification,
 165  * to avoid the corresponding overhead. As a hint, the upper-level application
 166  * might check the status of the device link once being systematically returned
 167  * a 0 value by the receive function of the driver for a given number of tries.
 168  */
 169
 170 #ifdef __cplusplus
 171 extern "C" {
 172 #endif
 173
 174 #include <stdint.h>
 175
 176 #include <rte_log.h>
 177 #include <rte_interrupts.h>
 178 #include <rte_pci.h>
 179 #include <rte_mbuf.h>
 180 #include "rte_ether.h"
 181
 182 /**
 183  * A structure used to retrieve statistics for an Ethernet port.
 184  */
 185 struct rte_eth_stats {
 186         uint64_t ipackets;  /**< Total number of successfully received packets. */
 187         uint64_t opackets;  /**< Total number of successfully transmitted packets.*/
 188         uint64_t ibytes;    /**< Total number of successfully received bytes. */
 189         uint64_t obytes;    /**< Total number of successfully transmitted bytes. */
 190         uint64_t ierrors;   /**< Total number of erroneous received packets. */
 191         uint64_t oerrors;   /**< Total number of failed transmitted packets. */
 192         uint64_t imcasts;   /**< Total number of multicast received packets. */
 193         uint64_t rx_nombuf; /**< Total number of RX mbuf allocation failures. */
 194         uint64_t fdirmatch; /**< Total number of RX packets matching a filter. */
 195         uint64_t fdirmiss;  /**< Total number of RX packets not matching any filter. */
 196         uint64_t q_ipackets[RTE_ETHDEV_QUEUE_STAT_CNTRS];
 197         /**< Total number of queue RX packets. */
 198         uint64_t q_opackets[RTE_ETHDEV_QUEUE_STAT_CNTRS];
 199         /**< Total number of queue TX packets. */
 200         uint64_t q_ibytes[RTE_ETHDEV_QUEUE_STAT_CNTRS];
 201         /**< Total number of successfully received queue bytes. */
 202         uint64_t q_obytes[RTE_ETHDEV_QUEUE_STAT_CNTRS];
 203         /**< Total number of successfully transmitted queue bytes. */
 204         uint64_t q_errors[RTE_ETHDEV_QUEUE_STAT_CNTRS];
 205         /**< Total number of queue packets received that are dropped. */
 206 };
 207
 208 /**
 209  * A structure used to retrieve link-level information of an Ethernet port.
 210  */
 211 struct rte_eth_link {
 212         uint16_t link_speed;      /**< ETH_LINK_SPEED_[10, 100, 1000, 10000] */
 213         uint16_t link_duplex;     /**< ETH_LINK_[HALF_DUPLEX, FULL_DUPLEX] */
 214         uint8_t  link_status : 1; /**< 1 -> link up, 0 -> link down */
 215 }__attribute__((aligned(8)));     /**< aligned for atomic64 read/write */
 216
 217 #define ETH_LINK_SPEED_AUTONEG  0       /**< Auto-negotiate link speed. */
 218 #define ETH_LINK_SPEED_10       10      /**< 10 megabits/second. */
 219 #define ETH_LINK_SPEED_100      100     /**< 100 megabits/second. */
 220 #define ETH_LINK_SPEED_1000     1000    /**< 1 gigabits/second. */
 221 #define ETH_LINK_SPEED_10000    10000   /**< 10 gigabits/second. */
 222
 223 #define ETH_LINK_AUTONEG_DUPLEX 0       /**< Auto-negotiate duplex. */
 224 #define ETH_LINK_HALF_DUPLEX    1       /**< Half-duplex connection. */
 225 #define ETH_LINK_FULL_DUPLEX    2       /**< Full-duplex connection. */
 226
 227 /**
 228  * A structure used to configure the ring threshold registers of an RX/TX
 229  * queue for an Ethernet port.
 230  */
 231 struct rte_eth_thresh {
 232         uint8_t pthresh; /**< Ring prefetch threshold. */
 233         uint8_t hthresh; /**< Ring host threshold. */
 234         uint8_t wthresh; /**< Ring writeback threshold. */
 235 };
 236
 237 /**
 238  *  A set of values to identify what method is to be used to route
 239  *  packets to multiple queues.
 240  */
 241 enum rte_eth_rx_mq_mode {
 242         ETH_RSS     = 0,     /**< Default to RSS mode */
 243         ETH_VMDQ_DCB,        /**< Use VMDQ+DCB to route traffic to queues */
 244         ETH_DCB_RX           /**< For RX side,only DCB is on. */
 245 };
 246
 247 /**
 248  * A set of values to identify what method is to be used to transmit
 249  * packets using multi-TCs.
 250  */
 251 enum rte_eth_tx_mq_mode {
 252         ETH_DCB_NONE    = 0,    /**< It is not in DCB mode. */
 253         ETH_VMDQ_DCB_TX,        /**< For TX side,both DCB and VT is on. */
 254         ETH_DCB_TX              /**< For TX side,only DCB is on. */
 255 };
 256
 257 /**
 258  * A structure used to configure the RX features of an Ethernet port.
 259  */
 260 struct rte_eth_rxmode {
 261         /** The multi-queue packet distribution mode to be used, e.g. RSS. */
 262         enum rte_eth_rx_mq_mode mq_mode;
 263         uint32_t max_rx_pkt_len;  /**< Only used if jumbo_frame enabled. */
 264         uint16_t split_hdr_size;  /**< hdr buf size (header_split enabled).*/
 265         uint8_t header_split : 1, /**< Header Split enable. */
 266                 hw_ip_checksum   : 1, /**< IP/UDP/TCP checksum offload enable. */
 267                 hw_vlan_filter   : 1, /**< VLAN filter enable. */
 268                 hw_vlan_strip    : 1, /**< VLAN strip enable. */
 269                 hw_vlan_extend   : 1, /**< Extended VLAN enable. */
 270                 jumbo_frame      : 1, /**< Jumbo Frame Receipt enable. */
 271                 hw_strip_crc     : 1; /**< Enable CRC stripping by hardware. */
 272 };
 273
 274 /**
 275  * A structure used to configure the Receive Side Scaling (RSS) feature
 276  * of an Ethernet port.
 277  * If not NULL, the *rss_key* pointer of the *rss_conf* structure points
 278  * to an array of 40 bytes holding the RSS key to use for hashing specific
 279  * header fields of received packets.
 280  * Otherwise, a default random hash key is used by the device driver.
 281  *
 282  * The *rss_hf* field of the *rss_conf* structure indicates the different
 283  * types of IPv4/IPv6 packets to which the RSS hashing must be applied.
 284  * Supplying an *rss_hf* equal to zero disables the RSS feature.
 285  */
 286 struct rte_eth_rss_conf {
 287         uint8_t  *rss_key;   /**< If not NULL, 40-byte hash key. */
 288         uint16_t rss_hf;     /**< Hash functions to apply - see below. */
 289 };
 290
 291 #define ETH_RSS_IPV4        0x0001 /**< IPv4 packet. */
 292 #define ETH_RSS_IPV4_TCP    0x0002 /**< IPv4/TCP packet. */
 293 #define ETH_RSS_IPV6        0x0004 /**< IPv6 packet. */
 294 #define ETH_RSS_IPV6_EX     0x0008 /**< IPv6 packet with extension headers.*/
 295 #define ETH_RSS_IPV6_TCP    0x0010 /**< IPv6/TCP packet. */
 296 #define ETH_RSS_IPV6_TCP_EX 0x0020 /**< IPv6/TCP with extension headers. */
 297 /* Intel RSS extensions to UDP packets */
 298 #define ETH_RSS_IPV4_UDP    0x0040 /**< IPv4/UDP packet. */
 299 #define ETH_RSS_IPV6_UDP    0x0080 /**< IPv6/UDP packet. */
 300 #define ETH_RSS_IPV6_UDP_EX 0x0100 /**< IPv6/UDP with extension headers. */
 301
 302 /* Definitions used for VMDQ and DCB functionality */
 303 #define ETH_VMDQ_MAX_VLAN_FILTERS   64 /**< Maximum nb. of VMDQ vlan filters. */
 304 #define ETH_DCB_NUM_USER_PRIORITIES 8  /**< Maximum nb. of DCB priorities. */
 305 #define ETH_VMDQ_DCB_NUM_QUEUES     128 /**< Maximum nb. of VMDQ DCB queues. */
 306 #define ETH_DCB_NUM_QUEUES          128 /**< Maximum nb. of DCB queues. */
 307
 308 /* DCB capability defines */
 309 #define ETH_DCB_PG_SUPPORT      0x00000001 /**< Priority Group(ETS) support. */
 310 #define ETH_DCB_PFC_SUPPORT     0x00000002 /**< Priority Flow Control support. */
 311
 312 /* Definitions used for VLAN Offload functionality */
 313 #define ETH_VLAN_STRIP_OFFLOAD   0x0001 /**< VLAN Strip  On/Off */
 314 #define ETH_VLAN_FILTER_OFFLOAD  0x0002 /**< VLAN Filter On/Off */
 315 #define ETH_VLAN_EXTEND_OFFLOAD  0x0004 /**< VLAN Extend On/Off */
 316
 317 /* Definitions used for mask VLAN setting */
 318 #define ETH_VLAN_STRIP_MASK   0x0001 /**< VLAN Strip  setting mask */
 319 #define ETH_VLAN_FILTER_MASK  0x0002 /**< VLAN Filter  setting mask*/
 320 #define ETH_VLAN_EXTEND_MASK  0x0004 /**< VLAN Extend  setting mask*/
 321
 322 /**
 323  * This enum indicates the possible number of traffic classes
 324  * in DCB configratioins
 325  */
 326 enum rte_eth_nb_tcs {
 327         ETH_4_TCS = 4, /**< 4 TCs with DCB. */
 328         ETH_8_TCS = 8  /**< 8 TCs with DCB. */
 329 };
 330
 331 /**
 332  * This enum indicates the possible number of queue pools
 333  * in VMDQ+DCB configurations.
 334  */
 335 enum rte_eth_nb_pools {
 336         ETH_16_POOLS = 16, /**< 16 pools with DCB. */
 337         ETH_32_POOLS = 32  /**< 32 pools with DCB. */
 338 };
 339
 340 /* This structure may be extended in future. */
 341 struct rte_eth_dcb_rx_conf {
 342         enum rte_eth_nb_tcs nb_tcs; /**< Possible DCB TCs, 4 or 8 TCs */
 343         uint8_t dcb_queue[ETH_DCB_NUM_USER_PRIORITIES];
 344         /**< Possible DCB queue,4 or 8. */
 345 };
 346
 347 struct rte_eth_vmdq_dcb_tx_conf {
 348         enum rte_eth_nb_pools nb_queue_pools; /**< With DCB, 16 or 32 pools. */
 349         uint8_t dcb_queue[ETH_DCB_NUM_USER_PRIORITIES];
 350         /**< Possible DCB queue,4 or 8. */
 351 };
 352
 353 struct rte_eth_dcb_tx_conf {
 354         enum rte_eth_nb_tcs nb_tcs; /**< possible DCB TCs, 4 or 8 TCs. */
 355         uint8_t dcb_queue[ETH_DCB_NUM_USER_PRIORITIES];
 356         /**< Possible DCB queue,4 or 8. */
 357 };
 358
 359 /**
 360  * A structure used to configure the VMDQ+DCB feature
 361  * of an Ethernet port.
 362  *
 363  * Using this feature, packets are routed to a pool of queues, based
 364  * on the vlan id in the vlan tag, and then to a specific queue within
 365  * that pool, using the user priority vlan tag field.
 366  *
 367  * A default pool may be used, if desired, to route all traffic which
 368  * does not match the vlan filter rules.
 369  */
 370 struct rte_eth_vmdq_dcb_conf {
 371         enum rte_eth_nb_pools nb_queue_pools; /**< With DCB, 16 or 32 pools */
 372         uint8_t enable_default_pool; /**< If non-zero, use a default pool */
 373         uint8_t default_pool; /**< The default pool, if applicable */
 374         uint8_t nb_pool_maps; /**< We can have up to 64 filters/mappings */
 375         struct {
 376                 uint16_t vlan_id; /**< The vlan id of the received frame */
 377                 uint64_t pools;   /**< Bitmask of pools for packet rx */
 378         } pool_map[ETH_VMDQ_MAX_VLAN_FILTERS]; /**< VMDq vlan pool maps. */
 379         uint8_t dcb_queue[ETH_DCB_NUM_USER_PRIORITIES];
 380         /**< Selects a queue in a pool */
 381 };
 382
 383 /**
 384  * A structure used to configure the TX features of an Ethernet port.
 385  */
 386 struct rte_eth_txmode {
 387         enum rte_eth_tx_mq_mode mq_mode; /**< TX multi-queues mode. */
 388 };
 389
 390 /**
 391  * A structure used to configure an RX ring of an Ethernet port.
 392  */
 393 struct rte_eth_rxconf {
 394         struct rte_eth_thresh rx_thresh; /**< RX ring threshold registers. */
 395         uint16_t rx_free_thresh; /**< Drives the freeing of RX descriptors. */
 396         uint8_t rx_drop_en; /**< Drop packets if no descriptors are available. */
 397 };
 398
 399 #define ETH_TXQ_FLAGS_NOMULTSEGS 0x0001 /**< nb_segs=1 for all mbufs */
 400 #define ETH_TXQ_FLAGS_NOREFCOUNT 0x0002 /**< refcnt can be ignored */
 401 #define ETH_TXQ_FLAGS_NOMULTMEMP 0x0004 /**< all bufs come from same mempool */
 402 #define ETH_TXQ_FLAGS_NOVLANOFFL 0x0100 /**< disable VLAN offload */
 403 #define ETH_TXQ_FLAGS_NOXSUMSCTP 0x0200 /**< disable SCTP checksum offload */
 404 #define ETH_TXQ_FLAGS_NOXSUMUDP  0x0400 /**< disable UDP checksum offload */
 405 #define ETH_TXQ_FLAGS_NOXSUMTCP  0x0800 /**< disable TCP checksum offload */
 406 #define ETH_TXQ_FLAGS_NOOFFLOADS \
 407                 (ETH_TXQ_FLAGS_NOVLANOFFL | ETH_TXQ_FLAGS_NOXSUMSCTP | \
 408                  ETH_TXQ_FLAGS_NOXSUMUDP  | ETH_TXQ_FLAGS_NOXSUMTCP)
 409 /**
 410  * A structure used to configure a TX ring of an Ethernet port.
 411  */
 412 struct rte_eth_txconf {
 413         struct rte_eth_thresh tx_thresh; /**< TX ring threshold registers. */
 414         uint16_t tx_rs_thresh; /**< Drives the setting of RS bit on TXDs. */
 415         uint16_t tx_free_thresh; /**< Drives the freeing of TX buffers. */
 416         uint32_t txq_flags; /**< Set flags for the Tx queue */
 417 };
 418
 419 /**
 420  * This enum indicates the flow control mode
 421  */
 422 enum rte_eth_fc_mode {
 423         RTE_FC_NONE = 0, /**< Disable flow control. */
 424         RTE_FC_RX_PAUSE, /**< RX pause frame, enable flowctrl on TX side. */
 425         RTE_FC_TX_PAUSE, /**< TX pause frame, enable flowctrl on RX side. */
 426         RTE_FC_FULL      /**< Enable flow control on both side. */
 427 };
 428
 429 /**
 430  * A structure used to configure Ethernet flow control parameter.
 431  * These parameters will be configured into the register of the NIC.
 432  * Please refer to the corresponding data sheet for proper value.
 433  */
 434 struct rte_eth_fc_conf {
 435         uint32_t high_water;  /**< High threshold value to trigger XOFF */
 436         uint32_t low_water;   /**< Low threshold value to trigger XON */
 437         uint16_t pause_time;  /**< Pause quota in the Pause frame */
 438         uint16_t send_xon;    /**< Is XON frame need be sent */
 439         enum rte_eth_fc_mode mode;  /**< Link flow control mode */
 440 };
 441
 442 /**
 443  *  Flow Director setting modes: none (default), signature or perfect.
 444  */
 445 enum rte_fdir_mode {
 446         RTE_FDIR_MODE_NONE      = 0, /**< Disable FDIR support. */
 447         RTE_FDIR_MODE_SIGNATURE,     /**< Enable FDIR signature filter mode. */
 448         RTE_FDIR_MODE_PERFECT,       /**< Enable FDIR perfect filter mode. */
 449 };
 450
 451 /**
 452  *  Memory space that can be configured to store Flow Director filters
 453  *  in the board memory.
 454  */
 455 enum rte_fdir_pballoc_type {
 456         RTE_FDIR_PBALLOC_64K = 0,  /**< 64k. */
 457         RTE_FDIR_PBALLOC_128K,     /**< 128k. */
 458         RTE_FDIR_PBALLOC_256K,     /**< 256k. */
 459 };
 460
 461 /**
 462  *  Select report mode of FDIR hash information in RX descriptors.
 463  */
 464 enum rte_fdir_status_mode {
 465         RTE_FDIR_NO_REPORT_STATUS = 0, /**< Never report FDIR hash. */
 466         RTE_FDIR_REPORT_STATUS, /**< Only report FDIR hash for matching pkts. */
 467         RTE_FDIR_REPORT_STATUS_ALWAYS, /**< Always report FDIR hash. */
 468 };
 469
 470 /**
 471  * A structure used to configure the Flow Director (FDIR) feature
 472  * of an Ethernet port.
 473  *
 474  * If mode is RTE_FDIR_DISABLE, the pballoc value is ignored.
 475  */
 476 struct rte_fdir_conf {
 477         enum rte_fdir_mode mode; /**< Flow Director mode. */
 478         enum rte_fdir_pballoc_type pballoc; /**< Space for FDIR filters. */
 479         enum rte_fdir_status_mode status;  /**< How to report FDIR hash. */
 480         /* Offset of flexbytes field in RX packets (in 16-bit word units). */
 481         uint8_t flexbytes_offset;
 482         /* RX queue of packets matching a "drop" filter in perfect mode. */
 483         uint8_t drop_queue;
 484 };
 485
 486 /**
 487  *  Possible l4type of FDIR filters.
 488  */
 489 enum rte_l4type {
 490         RTE_FDIR_L4TYPE_NONE = 0,       /**< None. */
 491         RTE_FDIR_L4TYPE_UDP,            /**< UDP. */
 492         RTE_FDIR_L4TYPE_TCP,            /**< TCP. */
 493         RTE_FDIR_L4TYPE_SCTP,           /**< SCTP. */
 494 };
 495
 496 /**
 497  *  Select IPv4 or IPv6 FDIR filters.
 498  */
 499 enum rte_iptype {
 500         RTE_FDIR_IPTYPE_IPV4 = 0,     /**< IPv4. */
 501         RTE_FDIR_IPTYPE_IPV6 ,        /**< IPv6. */
 502 };
 503
 504 /**
 505  *  A structure used to define a FDIR packet filter.
 506  */
 507 struct rte_fdir_filter {
 508         uint16_t flex_bytes; /**< Flex bytes value to match. */
 509         uint16_t vlan_id; /**< VLAN ID value to match, 0 otherwise. */
 510         uint16_t port_src; /**< Source port to match, 0 otherwise. */
 511         uint16_t port_dst; /**< Destination port to match, 0 otherwise. */
 512         union {
 513                 uint32_t ipv4_addr; /**< IPv4 source address to match. */
 514                 uint32_t ipv6_addr[4]; /**< IPv6 source address to match. */
 515         } ip_src; /**< IPv4/IPv6 source address to match (union of above). */
 516         union {
 517                 uint32_t ipv4_addr; /**< IPv4 destination address to match. */
 518                 uint32_t ipv6_addr[4]; /**< IPv6 destination address to match */
 519         } ip_dst; /**< IPv4/IPv6 destination address to match (union of above). */
 520         enum rte_l4type l4type; /**< l4type to match: NONE/UDP/TCP/SCTP. */
 521         enum rte_iptype iptype; /**< IP packet type to match: IPv4 or IPv6. */
 522 };
 523
 524 /**
 525  *  A structure used to configure FDIR masks that are used by the device
 526  *  to match the various fields of RX packet headers.
 527  *  @note The only_ip_flow field has the opposite meaning compared to other
 528  *  masks!
 529  */
 530 struct rte_fdir_masks {
 531         /** When set to 1, packet l4type is \b NOT relevant in filters, and
 532            source and destination port masks must be set to zero. */
 533         uint8_t only_ip_flow;
 534         /** If set to 1, vlan_id is relevant in filters. */
 535         uint8_t vlan_id;
 536         /** If set to 1, vlan_prio is relevant in filters. */
 537         uint8_t vlan_prio;
 538         /** If set to 1, flexbytes is relevant in filters. */
 539         uint8_t flexbytes;
 540         /** Mask of Destination IPv4 Address. All bits set to 1 define the
 541             relevant bits to use in the destination address of an IPv4 packet
 542             when matching it against FDIR filters. */
 543         uint32_t dst_ipv4_mask;
 544         /** Mask of Source IPv4 Address. All bits set to 1 define
 545             the relevant bits to use in the source address of an IPv4 packet
 546             when matching it against FDIR filters. */
 547         uint32_t src_ipv4_mask;
 548         /** Mask of Source IPv6 Address. All bits set to 1 define the
 549             relevant BYTES to use in the source address of an IPv6 packet
 550             when matching it against FDIR filters. */
 551         uint16_t src_ipv6_mask;
 552         /** Mask of Source Port. All bits set to 1 define the relevant
 553             bits to use in the source port of an IP packets when matching it
 554             against FDIR filters. */
 555         uint16_t src_port_mask;
 556         /** Mask of Destination Port. All bits set to 1 define the relevant
 557             bits to use in the destination port of an IP packet when matching it
 558             against FDIR filters. */
 559         uint16_t dst_port_mask;
 560 };
 561
 562 /**
 563  *  A structure used to report the status of the flow director filters in use.
 564  */
 565 struct rte_eth_fdir {
 566         /** Number of filters with collision indication. */
 567         uint16_t collision;
 568         /** Number of free (non programmed) filters. */
 569         uint16_t free;
 570         /** The Lookup hash value of the added filter that updated the value
 571            of the MAXLEN field */
 572         uint16_t maxhash;
 573         /** Longest linked list of filters in the table. */
 574         uint8_t maxlen;
 575         /** Number of added filters. */
 576         uint64_t add;
 577         /** Number of removed filters. */
 578         uint64_t remove;
 579         /** Number of failed added filters (no more space in device). */
 580         uint64_t f_add;
 581         /** Number of failed removed filters. */
 582         uint64_t f_remove;
 583 };
 584
 585 /**
 586  * A structure used to enable/disable specific device interrupts.
 587  */
 588 struct rte_intr_conf {
 589         /** enable/disable lsc interrupt. 0 (default) - disable, 1 enable */
 590         uint16_t lsc;
 591 };
 592
 593 /**
 594  * A structure used to configure an Ethernet port.
 595  * Depending upon the RX multi-queue mode, extra advanced
 596  * configuration settings may be needed.
 597  */
 598 struct rte_eth_conf {
 599         uint16_t link_speed;
 600         /**< ETH_LINK_SPEED_10[0|00|000], or 0 for autonegotation */
 601         uint16_t link_duplex;
 602         /**< ETH_LINK_[HALF_DUPLEX|FULL_DUPLEX], or 0 for autonegotation */
 603         struct rte_eth_rxmode rxmode; /**< Port RX configuration. */
 604         struct rte_eth_txmode txmode; /**< Port TX configuration. */
 605         union {
 606                 struct rte_eth_rss_conf rss_conf; /**< Port RSS configuration */
 607                 struct rte_eth_vmdq_dcb_conf vmdq_dcb_conf;
 608                 /**< Port vmdq+dcb configuration. */
 609                 struct rte_eth_dcb_rx_conf dcb_rx_conf;
 610                 /**< Port dcb RX configuration. */
 611         } rx_adv_conf; /**< Port RX filtering configuration (union). */
 612         union {
 613                 struct rte_eth_vmdq_dcb_tx_conf vmdq_dcb_tx_conf;
 614                 /**< Port vmdq+dcb TX configuration. */
 615                 struct rte_eth_dcb_tx_conf dcb_tx_conf;
 616                 /**< Port dcb TX configuration. */
 617         } tx_adv_conf; /**< Port TX DCB configuration (union). */
 618         /** Currently,Priority Flow Control(PFC) are supported,if DCB with PFC
 619             is needed,and the variable must be set ETH_DCB_PFC_SUPPORT. */
 620         uint32_t dcb_capability_en;
 621         struct rte_fdir_conf fdir_conf; /**< FDIR configuration. */
 622         struct rte_intr_conf intr_conf; /**< Interrupt mode configuration. */
 623 };
 624
 625 /**
 626  * A structure used to retrieve the contextual information of
 627  * an Ethernet device, such as the controlling driver of the device,
 628  * its PCI context, etc...
 629  */
 630 struct rte_eth_dev_info {
 631         struct rte_pci_device *pci_dev; /**< Device PCI information. */
 632         const char *driver_name; /**< Device Driver name. */
 633         uint32_t min_rx_bufsize; /**< Minimum size of RX buffer. */
 634         uint32_t max_rx_pktlen; /**< Maximum configurable length of RX pkt. */
 635         uint16_t max_rx_queues; /**< Maximum number of RX queues. */
 636         uint16_t max_tx_queues; /**< Maximum number of TX queues. */
 637         uint32_t max_mac_addrs; /**< Maximum number of MAC addresses. */
 638 };
 639
 640 struct rte_eth_dev;
 641
 642 struct rte_eth_dev_callback;
 643 /** @internal Structure to keep track of registered callbacks */
 644 TAILQ_HEAD(rte_eth_dev_cb_list, rte_eth_dev_callback);
 645
 646 /*
 647  * Definitions of all functions exported by an Ethernet driver through the
 648  * the generic structure of type *eth_dev_ops* supplied in the *rte_eth_dev*
 649  * structure associated with an Ethernet device.
 650  */
 651
 652 typedef int  (*eth_dev_configure_t)(struct rte_eth_dev *dev);
 653 /**< @internal Ethernet device configuration. */
 654
 655 typedef int  (*eth_dev_start_t)(struct rte_eth_dev *dev);
 656 /**< @internal Function used to start a configured Ethernet device. */
 657
 658 typedef void (*eth_dev_stop_t)(struct rte_eth_dev *dev);
 659 /**< @internal Function used to stop a configured Ethernet device. */
 660
 661 typedef void (*eth_dev_close_t)(struct rte_eth_dev *dev);
 662 /**< @internal Function used to close a configured Ethernet device. */
 663
 664 typedef void (*eth_promiscuous_enable_t)(struct rte_eth_dev *dev);
 665 /**< @internal Function used to enable the RX promiscuous mode of an Ethernet device. */
 666
 667 typedef void (*eth_promiscuous_disable_t)(struct rte_eth_dev *dev);
 668 /**< @internal Function used to disable the RX promiscuous mode of an Ethernet device. */
 669
 670 typedef void (*eth_allmulticast_enable_t)(struct rte_eth_dev *dev);
 671 /**< @internal Enable the receipt of all multicast packets by an Ethernet device. */
 672
 673 typedef void (*eth_allmulticast_disable_t)(struct rte_eth_dev *dev);
 674 /**< @internal Disable the receipt of all multicast packets by an Ethernet device. */
 675
 676 typedef int (*eth_link_update_t)(struct rte_eth_dev *dev,
 677                                 int wait_to_complete);
 678 /**< @internal Get link speed, duplex mode and state (up/down) of an Ethernet device. */
 679
 680 typedef void (*eth_stats_get_t)(struct rte_eth_dev *dev,
 681                                 struct rte_eth_stats *igb_stats);
 682 /**< @internal Get global I/O statistics of an Ethernet device. */
 683
 684 typedef void (*eth_stats_reset_t)(struct rte_eth_dev *dev);
 685 /**< @internal Reset global I/O statistics of an Ethernet device to 0. */
 686
 687 typedef int (*eth_queue_stats_mapping_set_t)(struct rte_eth_dev *dev,
 688                                              uint16_t queue_id,
 689                                              uint8_t stat_idx,
 690                                              uint8_t is_rx);
 691 /**< @internal Set a queue statistics mapping for a tx/rx queue of an Ethernet device. */
 692
 693 typedef void (*eth_dev_infos_get_t)(struct rte_eth_dev *dev,
 694                                     struct rte_eth_dev_info *dev_info);
 695 /**< @internal Get specific informations of an Ethernet device. */
 696
 697 typedef int (*eth_rx_queue_setup_t)(struct rte_eth_dev *dev,
 698                                     uint16_t rx_queue_id,
 699                                     uint16_t nb_rx_desc,
 700                                     unsigned int socket_id,
 701                                     const struct rte_eth_rxconf *rx_conf,
 702                                     struct rte_mempool *mb_pool);
 703 /**< @internal Set up a receive queue of an Ethernet device. */
 704
 705 typedef int (*eth_tx_queue_setup_t)(struct rte_eth_dev *dev,
 706                                     uint16_t tx_queue_id,
 707                                     uint16_t nb_tx_desc,
 708                                     unsigned int socket_id,
 709                                     const struct rte_eth_txconf *tx_conf);
 710 /**< @internal Setup a transmit queue of an Ethernet device. */
 711
 712 typedef void (*eth_queue_release_t)(void *queue);
 713 /**< @internal Release memory resources allocated by given RX/TX queue. */
 714
 715 typedef int (*vlan_filter_set_t)(struct rte_eth_dev *dev,
 716                                   uint16_t vlan_id,
 717                                   int on);
 718 /**< @internal filtering of a VLAN Tag Identifier by an Ethernet device. */
 719
 720 typedef void (*vlan_tpid_set_t)(struct rte_eth_dev *dev,
 721                                   uint16_t tpid);
 722 /**< @internal set the outer VLAN-TPID by an Ethernet device. */
 723
 724 typedef void (*vlan_offload_set_t)(struct rte_eth_dev *dev, int mask);
 725 /**< @internal set VLAN offload function by an Ethernet device. */
 726
 727 typedef void (*vlan_strip_queue_set_t)(struct rte_eth_dev *dev,
 728                                   uint16_t rx_queue_id,
 729                                   int on);
 730 /**< @internal VLAN stripping enable/disable by an queue of Ethernet device. */
 731
 732 typedef uint16_t (*eth_rx_burst_t)(void *rxq,
 733                                    struct rte_mbuf **rx_pkts,
 734                                    uint16_t nb_pkts);
 735 /**< @internal Retrieve input packets from a receive queue of an Ethernet device. */
 736
 737 typedef uint16_t (*eth_tx_burst_t)(void *txq,
 738                                    struct rte_mbuf **tx_pkts,
 739                                    uint16_t nb_pkts);
 740 /**< @internal Send output packets on a transmit queue of an Ethernet device. */
 741
 742 typedef int (*fdir_add_signature_filter_t)(struct rte_eth_dev *dev,
 743                                            struct rte_fdir_filter *fdir_ftr,
 744                                            uint8_t rx_queue);
 745 /**< @internal Setup a new signature filter rule on an Ethernet device */
 746
 747 typedef int (*fdir_update_signature_filter_t)(struct rte_eth_dev *dev,
 748                                               struct rte_fdir_filter *fdir_ftr,
 749                                               uint8_t rx_queue);
 750 /**< @internal Update a signature filter rule on an Ethernet device */
 751
 752 typedef int (*fdir_remove_signature_filter_t)(struct rte_eth_dev *dev,
 753                                               struct rte_fdir_filter *fdir_ftr);
 754 /**< @internal Remove a  signature filter rule on an Ethernet device */
 755
 756 typedef void (*fdir_infos_get_t)(struct rte_eth_dev *dev,
 757                                  struct rte_eth_fdir *fdir);
 758 /**< @internal Get information about fdir status */
 759
 760 typedef int (*fdir_add_perfect_filter_t)(struct rte_eth_dev *dev,
 761                                          struct rte_fdir_filter *fdir_ftr,
 762                                          uint16_t soft_id, uint8_t rx_queue,
 763                                          uint8_t drop);
 764 /**< @internal Setup a new perfect filter rule on an Ethernet device */
 765
 766 typedef int (*fdir_update_perfect_filter_t)(struct rte_eth_dev *dev,
 767                                             struct rte_fdir_filter *fdir_ftr,
 768                                             uint16_t soft_id, uint8_t rx_queue,
 769                                             uint8_t drop);
 770 /**< @internal Update a perfect filter rule on an Ethernet device */
 771
 772 typedef int (*fdir_remove_perfect_filter_t)(struct rte_eth_dev *dev,
 773                                             struct rte_fdir_filter *fdir_ftr,
 774                                             uint16_t soft_id);
 775 /**< @internal Remove a perfect filter rule on an Ethernet device */
 776
 777 typedef int (*fdir_set_masks_t)(struct rte_eth_dev *dev,
 778                                 struct rte_fdir_masks *fdir_masks);
 779 /**< @internal Setup flow director masks on an Ethernet device */
 780
 781 typedef int (*flow_ctrl_set_t)(struct rte_eth_dev *dev,
 782                                 struct rte_eth_fc_conf *fc_conf);
 783 /**< @internal Setup flow control parameter on an Ethernet device */
 784
 785 typedef int (*eth_dev_led_on_t)(struct rte_eth_dev *dev);
 786 /**< @internal Turn on SW controllable LED on an Ethernet device */
 787
 788 typedef int (*eth_dev_led_off_t)(struct rte_eth_dev *dev);
 789 /**< @internal Turn off SW controllable LED on an Ethernet device */
 790
 791 typedef void (*eth_mac_addr_remove_t)(struct rte_eth_dev *dev, uint32_t index);
 792 /**< @internal Remove MAC address from receive address register */
 793
 794 typedef void (*eth_mac_addr_add_t)(struct rte_eth_dev *dev,
 795                                   struct ether_addr *mac_addr,
 796                                   uint32_t index,
 797                                   uint32_t vmdq);
 798 /**< @internal Set a MAC address into Receive Address Address Register */
 799
 800 /**
 801  * @internal A structure containing the functions exported by an Ethernet driver.
 802  */
 803 struct eth_dev_ops {
 804         eth_dev_configure_t        dev_configure; /**< Configure device. */
 805         eth_dev_start_t            dev_start;     /**< Start device. */
 806         eth_dev_stop_t             dev_stop;      /**< Stop device. */
 807         eth_dev_close_t            dev_close;     /**< Close device. */
 808         eth_promiscuous_enable_t   promiscuous_enable; /**< Promiscuous ON. */
 809         eth_promiscuous_disable_t  promiscuous_disable;/**< Promiscuous OFF. */
 810         eth_allmulticast_enable_t  allmulticast_enable;/**< RX multicast ON. */
 811         eth_allmulticast_disable_t allmulticast_disable;/**< RX multicast OF. */
 812         eth_link_update_t          link_update;   /**< Get device link state. */
 813         eth_stats_get_t            stats_get;     /**< Get device statistics. */
 814         eth_stats_reset_t          stats_reset;   /**< Reset device statistics. */
 815         eth_queue_stats_mapping_set_t queue_stats_mapping_set;
 816         /**< Configure per queue stat counter mapping. */
 817         eth_dev_infos_get_t        dev_infos_get; /**< Get device info. */
 818         vlan_filter_set_t          vlan_filter_set;  /**< Filter VLAN Setup. */
 819         vlan_tpid_set_t            vlan_tpid_set;      /**< Outer VLAN TPID Setup. */
 820         vlan_strip_queue_set_t     vlan_strip_queue_set; /**< VLAN Stripping on queue. */
 821         vlan_offload_set_t         vlan_offload_set; /**< Set VLAN Offload. */
 822         eth_rx_queue_setup_t       rx_queue_setup;/**< Set up device RX queue.*/
 823         eth_queue_release_t        rx_queue_release;/**< Release RX queue.*/
 824         eth_tx_queue_setup_t       tx_queue_setup;/**< Set up device TX queue.*/
 825         eth_queue_release_t        tx_queue_release;/**< Release TX queue.*/
 826         eth_dev_led_on_t           dev_led_on;    /**< Turn on LED. */
 827         eth_dev_led_off_t          dev_led_off;   /**< Turn off LED. */
 828         flow_ctrl_set_t            flow_ctrl_set; /**< Setup flow control. */
 829         eth_mac_addr_remove_t      mac_addr_remove; /**< Remove MAC address */
 830         eth_mac_addr_add_t         mac_addr_add;  /**< Add a MAC address */
 831
 832         /** Add a signature filter. */
 833         fdir_add_signature_filter_t fdir_add_signature_filter;
 834         /** Update a signature filter. */
 835         fdir_update_signature_filter_t fdir_update_signature_filter;
 836         /** Remove a signature filter. */
 837         fdir_remove_signature_filter_t fdir_remove_signature_filter;
 838         /** Get information about FDIR status. */
 839         fdir_infos_get_t fdir_infos_get;
 840         /** Add a perfect filter. */
 841         fdir_add_perfect_filter_t fdir_add_perfect_filter;
 842         /** Update a perfect filter. */
 843         fdir_update_perfect_filter_t fdir_update_perfect_filter;
 844         /** Remove a perfect filter. */
 845         fdir_remove_perfect_filter_t fdir_remove_perfect_filter;
 846         /** Setup masks for FDIR filtering. */
 847         fdir_set_masks_t fdir_set_masks;
 848 };
 849
 850 /**
 851  * @internal
 852  * The generic data structure associated with each ethernet device.
 853  *
 854  * Pointers to burst-oriented packet receive and transmit functions are
 855  * located at the beginning of the structure, along with the pointer to
 856  * where all the data elements for the particular device are stored in shared
 857  * memory. This split allows the function pointer and driver data to be per-
 858  * process, while the actual configuration data for the device is shared.
 859  */
 860 struct rte_eth_dev {
 861         eth_rx_burst_t rx_pkt_burst; /**< Pointer to PMD receive function. */
 862         eth_tx_burst_t tx_pkt_burst; /**< Pointer to PMD transmit function. */
 863         struct rte_eth_dev_data *data;  /**< Pointer to device data */
 864         const struct eth_driver *driver;/**< Driver for this device */
 865         struct eth_dev_ops *dev_ops;    /**< Functions exported by PMD */
 866         struct rte_pci_device *pci_dev; /**< PCI info. supplied by probing */
 867         struct rte_eth_dev_cb_list callbacks; /**< User application callbacks */
 868 };
 869
 870 /**
 871  * @internal
 872  * The data part, with no function pointers, associated with each ethernet device.
 873  *
 874  * This structure is safe to place in shared memory to be common among different
 875  * processes in a multi-process configuration.
 876  */
 877 struct rte_eth_dev_data {
 878         void **rx_queues; /**< Array of pointers to RX queues. */
 879         void **tx_queues; /**< Array of pointers to TX queues. */
 880         uint16_t nb_rx_queues; /**< Number of RX queues. */
 881         uint16_t nb_tx_queues; /**< Number of TX queues. */
 882
 883         void *dev_private;              /**< PMD-specific private data */
 884
 885         struct rte_eth_link dev_link;
 886         /**< Link-level information & status */
 887
 888         struct rte_eth_conf dev_conf;   /**< Configuration applied to device. */
 889         uint16_t max_frame_size;        /**< Default is ETHER_MAX_LEN (1518). */
 890
 891         uint64_t rx_mbuf_alloc_failed; /**< RX ring mbuf allocation failures. */
 892         struct ether_addr* mac_addrs;/**< Device Ethernet Link address. */
 893         uint8_t port_id;           /**< Device [external] port identifier. */
 894         uint8_t promiscuous   : 1, /**< RX promiscuous mode ON(1) / OFF(0). */
 895                 scattered_rx : 1,  /**< RX of scattered packets is ON(1) / OFF(0) */
 896                 all_multicast : 1, /**< RX all multicast mode ON(1) / OFF(0). */
 897                 dev_started : 1;   /**< Device state: STARTED(1) / STOPPED(0). */
 898 };
 899
 900 /**
 901  * @internal
 902  * The pool of *rte_eth_dev* structures. The size of the pool
 903  * is configured at compile-time in the <rte_ethdev.c> file.
 904  */
 905 extern struct rte_eth_dev rte_eth_devices[];
 906
 907 /**
 908  * Get the total number of Ethernet devices that have been successfully
 909  * initialized by the [matching] Ethernet driver during the PCI probing phase.
 910  * All devices whose port identifier is in the range
 911  * [0,  rte_eth_dev_count() - 1] can be operated on by network applications.
 912  *
 913  * @return
 914  *   - The total number of usable Ethernet devices.
 915  */
 916 extern uint8_t rte_eth_dev_count(void);
 917
 918 struct eth_driver;
 919 /**
 920  * @internal
 921  * Initialization function of an Ethernet driver invoked for each matching
 922  * Ethernet PCI device detected during the PCI probing phase.
 923  *
 924  * @param eth_drv
 925  *   The pointer to the [matching] Ethernet driver structure supplied by
 926  *   the PMD when it registered itself.
 927  * @param eth_dev
 928  *   The *eth_dev* pointer is the address of the *rte_eth_dev* structure
 929  *   associated with the matching device and which have been [automatically]
 930  *   allocated in the *rte_eth_devices* array.
 931  *   The *eth_dev* structure is supplied to the driver initialization function
 932  *   with the following fields already initialized:
 933  *
 934  *   - *pci_dev*: Holds the pointers to the *rte_pci_device* structure which
 935  *     contains the generic PCI information of the matching device.
 936  *
 937  *   - *dev_private*: Holds a pointer to the device private data structure.
 938  *
 939  *   - *max_frame_size*: Contains the default Ethernet maximum frame length
 940  *     (1518).
 941  *
 942  *   - *port_id*: Contains the port index of the device (actually the index
 943  *     of the *eth_dev* structure in the *rte_eth_devices* array).
 944  *
 945  * @return
 946  *   - 0: Success, the device is properly initialized by the driver.
 947  *        In particular, the driver MUST have set up the *dev_ops* pointer
 948  *        of the *eth_dev* structure.
 949  *   - <0: Error code of the device initialization failure.
 950  */
 951 typedef int (*eth_dev_init_t)(struct eth_driver  *eth_drv,
 952                               struct rte_eth_dev *eth_dev);
 953
 954 /**
 955  * @internal
 956  * The structure associated with a PMD Ethernet driver.
 957  *
 958  * Each Ethernet driver acts as a PCI driver and is represented by a generic
 959  * *eth_driver* structure that holds:
 960  *
 961  * - An *rte_pci_driver* structure (which must be the first field).
 962  *
 963  * - The *eth_dev_init* function invoked for each matching PCI device.
 964  *
 965  * - The size of the private data to allocate for each matching device.
 966  */
 967 struct eth_driver {
 968         struct rte_pci_driver pci_drv;    /**< The PMD is also a PCI driver. */
 969         eth_dev_init_t eth_dev_init;      /**< Device init function. */
 970         unsigned int dev_private_size;    /**< Size of device private data. */
 971 };
 972
 973 /**
 974  * @internal
 975  * A function invoked by the initialization function of an Ethernet driver
 976  * to simultaneously register itself as a PCI driver and as an Ethernet
 977  * Poll Mode Driver (PMD).
 978  *
 979  * @param eth_drv
 980  *   The pointer to the *eth_driver* structure associated with
 981  *   the Ethernet driver.
 982  */
 983 extern void rte_eth_driver_register(struct eth_driver *eth_drv);
 984
 985 /**
 986  * The initialization function of the driver for
 987  * Intel(r) IGB Gigabit Ethernet Controller devices.
 988  * This function is invoked once at EAL start time.
 989  * @return
 990  *   0 on success
 991  */
 992 extern int rte_igb_pmd_init(void);
 993
 994 /**
 995  * The initialization function of the driver for
 996  * Intel(r) EM Gigabit Ethernet Controller devices.
 997  * This function is invoked once at EAL start time.
 998  * @return
 999  *   0 on success
1000  */
1001 extern int rte_em_pmd_init(void);
1002
1003 /**
1004  * The initialization function of the driver for 1Gbps Intel IGB_VF
1005  * Ethernet devices.
1006  * Invoked once at EAL start time.
1007  * @return
1008  *   0 on success
1009  */
1010 extern int rte_igbvf_pmd_init(void);
1011
1012 /**
1013  * The initialization function of the driver for 10Gbps Intel IXGBE
1014  * Ethernet devices.
1015  * Invoked once at EAL start time.
1016  * @return
1017  *   0 on success
1018  */
1019 extern int rte_ixgbe_pmd_init(void);
1020
1021 /**
1022  * The initialization function of the driver for 10Gbps Intel IXGBE_VF
1023  * Ethernet devices.
1024  * Invoked once at EAL start time.
1025  * @return
1026  *   0 on success
1027  */
1028 extern int rte_ixgbevf_pmd_init(void);
1029
1030 /**
1031  * The initialization function of *all* supported and enabled drivers.
1032  * Right now, the following PMDs are supported:
1033  *  - igb
1034  *  - igbvf
1035  *  - em
1036  *  - ixgbe
1037  *  - ixgbevf
1038  * This function is invoked once at EAL start time.
1039  * @return
1040  *   0 on success.
1041  *   Error code of the device initialization failure,
1042  *   -ENODEV if there are no drivers available
1043  *   (e.g. if all driver config options are = n).
1044  */
1045 static inline
1046 int rte_pmd_init_all(void)
1047 {
1048         int ret = -ENODEV;
1049
1050 #ifdef RTE_LIBRTE_IGB_PMD
1051         if ((ret = rte_igb_pmd_init()) != 0) {
1052                 RTE_LOG(ERR, PMD, "Cannot init igb PMD\n");
1053                 return (ret);
1054         }
1055         if ((ret = rte_igbvf_pmd_init()) != 0) {
1056                 RTE_LOG(ERR, PMD, "Cannot init igbvf PMD\n");
1057                 return (ret);
1058         }
1059 #endif /* RTE_LIBRTE_IGB_PMD */
1060
1061 #ifdef RTE_LIBRTE_EM_PMD
1062         if ((ret = rte_em_pmd_init()) != 0) {
1063                 RTE_LOG(ERR, PMD, "Cannot init em PMD\n");
1064                 return (ret);
1065         }
1066 #endif /* RTE_LIBRTE_EM_PMD */
1067
1068 #ifdef RTE_LIBRTE_IXGBE_PMD
1069         if ((ret = rte_ixgbe_pmd_init()) != 0) {
1070                 RTE_LOG(ERR, PMD, "Cannot init ixgbe PMD\n");
1071                 return (ret);
1072         }
1073         if ((ret = rte_ixgbevf_pmd_init()) != 0) {
1074                 RTE_LOG(ERR, PMD, "Cannot init ixgbevf PMD\n");
1075                 return (ret);
1076         }
1077 #endif /* RTE_LIBRTE_IXGBE_PMD */
1078
1079         if (ret == -ENODEV)
1080                 RTE_LOG(ERR, PMD, "No PMD(s) are configured\n");
1081         return (ret);
1082 }
1083
1084 /**
1085  * Configure an Ethernet device.
1086  * This function must be invoked first before any other function in the
1087  * Ethernet API. This function can also be re-invoked when a device is in the
1088  * stopped state.
1089  *
1090  * @param port_id
1091  *   The port identifier of the Ethernet device to configure.
1092  * @param nb_rx_queue
1093  *   The number of receive queues to set up for the Ethernet device.
1094  * @param nb_tx_queue
1095  *   The number of transmit queues to set up for the Ethernet device.
1096  * @param eth_conf
1097  *   The pointer to the configuration data to be used for the Ethernet device.
1098  *   The *rte_eth_conf* structure includes:
1099  *     -  the hardware offload features to activate, with dedicated fields for
1100  *        each statically configurable offload hardware feature provided by
1101  *        Ethernet devices, such as IP checksum or VLAN tag stripping for
1102  *        example.
1103  *     - the Receive Side Scaling (RSS) configuration when using multiple RX
1104  *         queues per port.
1105  *
1106  *   Embedding all configuration information in a single data structure
1107  *   is the more flexible method that allows the addition of new features
1108  *   without changing the syntax of the API.
1109  * @return
1110  *   - 0: Success, device configured.
1111  *   - <0: Error code returned by the driver configuration function.
1112  */
1113 extern int rte_eth_dev_configure(uint8_t port_id,
1114                                  uint16_t nb_rx_queue,
1115                                  uint16_t nb_tx_queue,
1116                                  const struct rte_eth_conf *eth_conf);
1117
1118 /**
1119  * Allocate and set up a receive queue for an Ethernet device.
1120  *
1121  * The function allocates a contiguous block of memory for *nb_rx_desc*
1122  * receive descriptors from a memory zone associated with *socket_id*
1123  * and initializes each receive descriptor with a network buffer allocated
1124  * from the memory pool *mb_pool*.
1125  *
1126  * @param port_id
1127  *   The port identifier of the Ethernet device.
1128  * @param rx_queue_id
1129  *   The index of the receive queue to set up.
1130  *   The value must be in the range [0, nb_rx_queue - 1] previously supplied
1131  *   to rte_eth_dev_configure().
1132  * @param nb_rx_desc
1133  *   The number of receive descriptors to allocate for the receive ring.
1134  * @param socket_id
1135  *   The *socket_id* argument is the socket identifier in case of NUMA.
1136  *   The value can be *SOCKET_ID_ANY* if there is no NUMA constraint for
1137  *   the DMA memory allocated for the receive descriptors of the ring.
1138  * @param rx_conf
1139  *   The pointer to the configuration data to be used for the receive queue.
1140  *   The *rx_conf* structure contains an *rx_thresh* structure with the values
1141  *   of the Prefetch, Host, and Write-Back threshold registers of the receive
1142  *   ring.
1143  * @param mb_pool
1144  *   The pointer to the memory pool from which to allocate *rte_mbuf* network
1145  *   memory buffers to populate each descriptor of the receive ring.
1146  * @return
1147  *   - 0: Success, receive queue correctly set up.
1148  *   - -EINVAL: The size of network buffers which can be allocated from the
1149  *      memory pool does not fit the various buffer sizes allowed by the
1150  *      device controller.
1151  *   - -ENOMEM: Unable to allocate the receive ring descriptors or to
1152  *      allocate network memory buffers from the memory pool when
1153  *      initializing receive descriptors.
1154  */
1155 extern int rte_eth_rx_queue_setup(uint8_t port_id, uint16_t rx_queue_id,
1156                                   uint16_t nb_rx_desc, unsigned int socket_id,
1157                                   const struct rte_eth_rxconf *rx_conf,
1158                                   struct rte_mempool *mb_pool);
1159
1160 /**
1161  * Allocate and set up a transmit queue for an Ethernet device.
1162  *
1163  * @param port_id
1164  *   The port identifier of the Ethernet device.
1165  * @param tx_queue_id
1166  *   The index of the transmit queue to set up.
1167  *   The value must be in the range [0, nb_tx_queue - 1] previously supplied
1168  *   to rte_eth_dev_configure().
1169  * @param nb_tx_desc
1170  *   The number of transmit descriptors to allocate for the transmit ring.
1171  * @param socket_id
1172  *   The *socket_id* argument is the socket identifier in case of NUMA.
1173  *   Its value can be *SOCKET_ID_ANY* if there is no NUMA constraint for
1174  *   the DMA memory allocated for the transmit descriptors of the ring.
1175  * @param tx_conf
1176  *   The pointer to the configuration data to be used for the transmit queue.
1177  *   The *tx_conf* structure contains the following data:
1178  *   - The *tx_thresh* structure with the values of the Prefetch, Host, and
1179  *     Write-Back threshold registers of the transmit ring.
1180  *     When setting Write-Back threshold to the value greater then zero,
1181  *     *tx_rs_thresh* value should be explicitly set to one.
1182  *   - The *tx_free_thresh* value indicates the [minimum] number of network
1183  *     buffers that must be pending in the transmit ring to trigger their
1184  *     [implicit] freeing by the driver transmit function.
1185  *   - The *tx_rs_thresh* value indicates the [minimum] number of transmit
1186  *     descriptors that must be pending in the transmit ring before setting the
1187  *     RS bit on a descriptor by the driver transmit function.
1188  *     The *tx_rs_thresh* value should be less or equal then
1189  *     *tx_free_thresh* value, and both of them should be less then
1190  *     *nb_tx_desc* - 3.
1191  *   - The *txq_flags* member contains flags to pass to the TX queue setup
1192  *     function to configure the behavior of the TX queue. This should be set
1193  *     to 0 if no special configuration is required.
1194  *
1195  *     Note that setting *tx_free_thresh* or *tx_rs_thresh* value to 0 forces
1196  *     the transmit function to use default values.
1197  * @return
1198  *   - 0: Success, the transmit queue is correctly set up.
1199  *   - -ENOMEM: Unable to allocate the transmit ring descriptors.
1200  */
1201 extern int rte_eth_tx_queue_setup(uint8_t port_id, uint16_t tx_queue_id,
1202                                   uint16_t nb_tx_desc, unsigned int socket_id,
1203                                   const struct rte_eth_txconf *tx_conf);
1204
1205 /**
1206  * Start an Ethernet device.
1207  *
1208  * The device start step is the last one and consists of setting the configured
1209  * offload features and in starting the transmit and the receive units of the
1210  * device.
1211  * On success, all basic functions exported by the Ethernet API (link status,
1212  * receive/transmit, and so on) can be invoked.
1213  *
1214  * @param port_id
1215  *   The port identifier of the Ethernet device.
1216  * @return
1217  *   - 0: Success, Ethernet device started.
1218  *   - <0: Error code of the driver device start function.
1219  */
1220 extern int rte_eth_dev_start(uint8_t port_id);
1221
1222 /**
1223  * Stop an Ethernet device. The device can be restarted with a call to
1224  * rte_eth_dev_start()
1225  *
1226  * @param port_id
1227  *   The port identifier of the Ethernet device.
1228  */
1229 extern void rte_eth_dev_stop(uint8_t port_id);
1230
1231 /**
1232  * Close an Ethernet device. The device cannot be restarted!
1233  *
1234  * @param port_id
1235  *   The port identifier of the Ethernet device.
1236  */
1237 extern void rte_eth_dev_close(uint8_t port_id);
1238
1239 /**
1240  * Enable receipt in promiscuous mode for an Ethernet device.
1241  *
1242  * @param port_id
1243  *   The port identifier of the Ethernet device.
1244  */
1245 extern void rte_eth_promiscuous_enable(uint8_t port_id);
1246
1247 /**
1248  * Disable receipt in promiscuous mode for an Ethernet device.
1249  *
1250  * @param port_id
1251  *   The port identifier of the Ethernet device.
1252  */
1253 extern void rte_eth_promiscuous_disable(uint8_t port_id);
1254
1255 /**
1256  * Return the value of promiscuous mode for an Ethernet device.
1257  *
1258  * @param port_id
1259  *   The port identifier of the Ethernet device.
1260  * @return
1261  *   - (1) if promiscuous is enabled
1262  *   - (0) if promiscuous is disabled.
1263  *   - (-1) on error
1264  */
1265 extern int rte_eth_promiscuous_get(uint8_t port_id);
1266
1267 /**
1268  * Enable the receipt of any multicast frame by an Ethernet device.
1269  *
1270  * @param port_id
1271  *   The port identifier of the Ethernet device.
1272  */
1273 extern void rte_eth_allmulticast_enable(uint8_t port_id);
1274
1275 /**
1276  * Disable the receipt of all multicast frames by an Ethernet device.
1277  *
1278  * @param port_id
1279  *   The port identifier of the Ethernet device.
1280  */
1281 extern void rte_eth_allmulticast_disable(uint8_t port_id);
1282
1283 /**
1284  * Return the value of allmulticast mode for an Ethernet device.
1285  *
1286  * @param port_id
1287  *   The port identifier of the Ethernet device.
1288  * @return
1289  *   - (1) if allmulticast is enabled
1290  *   - (0) if allmulticast is disabled.
1291  *   - (-1) on error
1292  */
1293 extern int rte_eth_allmulticast_get(uint8_t port_id);
1294
1295 /**
1296  * Retrieve the status (ON/OFF), the speed (in Mbps) and the mode (HALF-DUPLEX
1297  * or FULL-DUPLEX) of the physical link of an Ethernet device. It might need
1298  * to wait up to 9 seconds in it.
1299  *
1300  * @param port_id
1301  *   The port identifier of the Ethernet device.
1302  * @param link
1303  *   A pointer to an *rte_eth_link* structure to be filled with
1304  *   the status, the speed and the mode of the Ethernet device link.
1305  */
1306 extern void rte_eth_link_get(uint8_t port_id, struct rte_eth_link *link);
1307
1308 /**
1309  * Retrieve the status (ON/OFF), the speed (in Mbps) and the mode (HALF-DUPLEX
1310  * or FULL-DUPLEX) of the physical link of an Ethernet device. It is a no-wait
1311  * version of rte_eth_link_get().
1312  *
1313  * @param port_id
1314  *   The port identifier of the Ethernet device.
1315  * @param link
1316  *   A pointer to an *rte_eth_link* structure to be filled with
1317  *   the status, the speed and the mode of the Ethernet device link.
1318  */
1319 extern void rte_eth_link_get_nowait(uint8_t port_id,
1320                                 struct rte_eth_link *link);
1321
1322 /**
1323  * Retrieve the general I/O statistics of an Ethernet device.
1324  *
1325  * @param port_id
1326  *   The port identifier of the Ethernet device.
1327  * @param stats
1328  *   A pointer to a structure of type *rte_eth_stats* to be filled with
1329  *   the values of device counters for the following set of statistics:
1330  *   - *ipackets* with the total of successfully received packets.
1331  *   - *opackets* with the total of successfully transmitted packets.
1332  *   - *ibytes*   with the total of successfully received bytes.
1333  *   - *obytes*   with the total of successfully transmitted bytes.
1334  *   - *ierrors*  with the total of erroneous received packets.
1335  *   - *oerrors*  with the total of failed transmitted packets.
1336  */
1337 extern void rte_eth_stats_get(uint8_t port_id, struct rte_eth_stats *stats);
1338
1339 /**
1340  * Reset the general I/O statistics of an Ethernet device.
1341  *
1342  * @param port_id
1343  *   The port identifier of the Ethernet device.
1344  */
1345 extern void rte_eth_stats_reset(uint8_t port_id);
1346
1347 /**
1348  *  Set a mapping for the specified transmit queue to the specified per-queue
1349  *  statistics counter.
1350  *
1351  * @param port_id
1352  *   The port identifier of the Ethernet device.
1353  * @param tx_queue_id
1354  *   The index of the transmit queue for which a queue stats mapping is required.
1355  *   The value must be in the range [0, nb_tx_queue - 1] previously supplied
1356  *   to rte_eth_dev_configure().
1357  * @param stat_idx
1358  *   The per-queue packet statistics functionality number that the transmit
1359  *   queue is to be assigned.
1360  *   The value must be in the range [0, RTE_MAX_ETHPORT_QUEUE_STATS_MAPS - 1].
1361  * @return
1362  *   Zero if successful. Non-zero otherwise.
1363  */
1364 extern int rte_eth_dev_set_tx_queue_stats_mapping(uint8_t port_id,
1365                                                   uint16_t tx_queue_id,
1366                                                   uint8_t stat_idx);
1367
1368 /**
1369  *  Set a mapping for the specified receive queue to the specified per-queue
1370  *  statistics counter.
1371  *
1372  * @param port_id
1373  *   The port identifier of the Ethernet device.
1374  * @param rx_queue_id
1375  *   The index of the receive queue for which a queue stats mapping is required.
1376  *   The value must be in the range [0, nb_rx_queue - 1] previously supplied
1377  *   to rte_eth_dev_configure().
1378  * @param stat_idx
1379  *   The per-queue packet statistics functionality number that the receive
1380  *   queue is to be assigned.
1381  *   The value must be in the range [0, RTE_MAX_ETHPORT_QUEUE_STATS_MAPS - 1].
1382  * @return
1383  *   Zero if successful. Non-zero otherwise.
1384  */
1385 extern int rte_eth_dev_set_rx_queue_stats_mapping(uint8_t port_id,
1386                                                   uint16_t rx_queue_id,
1387                                                   uint8_t stat_idx);
1388
1389 /**
1390  * Retrieve the Ethernet address of an Ethernet device.
1391  *
1392  * @param port_id
1393  *   The port identifier of the Ethernet device.
1394  * @param mac_addr
1395  *   A pointer to a structure of type *ether_addr* to be filled with
1396  *   the Ethernet address of the Ethernet device.
1397  */
1398 extern void rte_eth_macaddr_get(uint8_t port_id, struct ether_addr *mac_addr);
1399
1400 /**
1401  * Retrieve the contextual information of an Ethernet device.
1402  *
1403  * @param port_id
1404  *   The port identifier of the Ethernet device.
1405  * @param dev_info
1406  *   A pointer to a structure of type *rte_eth_dev_info* to be filled with
1407  *   the contextual information of the Ethernet device.
1408  */
1409 extern void rte_eth_dev_info_get(uint8_t port_id,
1410                                  struct rte_eth_dev_info *dev_info);
1411
1412 /**
1413  * Enable/Disable hardware filtering by an Ethernet device of received
1414  * VLAN packets tagged with a given VLAN Tag Identifier.
1415  *
1416  * @param port_id
1417  *   The port identifier of the Ethernet device.
1418  * @param vlan_id
1419  *   The VLAN Tag Identifier whose filtering must be enabled or disabled.
1420  * @param on
1421  *   If > 0, enable VLAN filtering of VLAN packets tagged with *vlan_id*.
1422  *   Otherwise, disable VLAN filtering of VLAN packets tagged with *vlan_id*.
1423  * @return
1424  *   - (0) if successful.
1425  *   - (-ENOSUP) if hardware-assisted VLAN filtering not configured.
1426  *   - (-ENODEV) if *port_id* invalid.
1427  *   - (-ENOSYS) if VLAN filtering on *port_id* disabled.
1428  *   - (-EINVAL) if *vlan_id* > 4095.
1429  */
1430 extern int rte_eth_dev_vlan_filter(uint8_t port_id, uint16_t vlan_id , int on);
1431
1432 /**
1433  * Enable/Disable hardware VLAN Strip by a rx queue of an Ethernet device.
1434  * 82599/X540 can support VLAN stripping at the rx queue level
1435  *
1436  * @param port_id
1437  *   The port identifier of the Ethernet device.
1438  * @param rx_queue_id
1439  *   The index of the receive queue for which a queue stats mapping is required.
1440  *   The value must be in the range [0, nb_rx_queue - 1] previously supplied
1441  *   to rte_eth_dev_configure().
1442  * @param on
1443  *   If 1, Enable VLAN Stripping of the receive queue of the Ethernet port.
1444  *   If 0, Disable VLAN Stripping of the receive queue of the Ethernet port.
1445  * @return
1446  *   - (0) if successful.
1447  *   - (-ENOSUP) if hardware-assisted VLAN stripping not configured.
1448  *   - (-ENODEV) if *port_id* invalid.
1449  *   - (-EINVAL) if *rx_queue_id* invalid.
1450  */
1451 extern int rte_eth_dev_set_vlan_strip_on_queue(uint8_t port_id,
1452                 uint16_t rx_queue_id, int on);
1453
1454 /**
1455  * Set the Outer VLAN Ether Type by an Ethernet device, it can be inserted to
1456  * the VLAN Header. This is a register setup available on some Intel NIC, not
1457  * but all, please check the data sheet for availability.
1458  *
1459  * @param port_id
1460  *   The port identifier of the Ethernet device.
1461  * @param tag_type
1462  *   The Tag Protocol ID
1463  * @return
1464  *   - (0) if successful.
1465  *   - (-ENOSUP) if hardware-assisted VLAN TPID setup is not supported.
1466  *   - (-ENODEV) if *port_id* invalid.
1467  */
1468 extern int rte_eth_dev_set_vlan_ether_type(uint8_t port_id, uint16_t tag_type);
1469
1470 /**
1471  * Set VLAN offload configuration on an Ethernet device
1472  * Enable/Disable Extended VLAN by an Ethernet device, This is a register setup
1473  * available on some Intel NIC, not but all, please check the data sheet for
1474  * availability.
1475  * Enable/Disable VLAN Strip can be done on rx queue for certain NIC, but here
1476  * the configuration is applied on the port level.
1477  *
1478  * @param port_id
1479  *   The port identifier of the Ethernet device.
1480  * @param offload_mask
1481  *   The VLAN Offload bit mask can be mixed use with "OR"
1482  *       ETH_VLAN_STRIP_OFFLOAD
1483  *       ETH_VLAN_FILTER_OFFLOAD
1484  *       ETH_VLAN_EXTEND_OFFLOAD
1485  * @return
1486  *   - (0) if successful.
1487  *   - (-ENOSUP) if hardware-assisted VLAN filtering not configured.
1488  *   - (-ENODEV) if *port_id* invalid.
1489  */
1490 extern int rte_eth_dev_set_vlan_offload(uint8_t port_id, int offload_mask);
1491
1492 /**
1493  * Read VLAN Offload configuration from an Ethernet device
1494  *
1495  * @param port_id
1496  *   The port identifier of the Ethernet device.
1497  * @return
1498  *   - (>0) if successful. Bit mask to indicate
1499  *       ETH_VLAN_STRIP_OFFLOAD
1500  *       ETH_VLAN_FILTER_OFFLOAD
1501  *       ETH_VLAN_EXTEND_OFFLOAD
1502  *   - (-ENODEV) if *port_id* invalid.
1503  */
1504 extern int rte_eth_dev_get_vlan_offload(uint8_t port_id);
1505
1506 /**
1507  *
1508  * Retrieve a burst of input packets from a receive queue of an Ethernet
1509  * device. The retrieved packets are stored in *rte_mbuf* structures whose
1510  * pointers are supplied in the *rx_pkts* array.
1511  *
1512  * The rte_eth_rx_burst() function loops, parsing the RX ring of the
1513  * receive queue, up to *nb_pkts* packets, and for each completed RX
1514  * descriptor in the ring, it performs the following operations:
1515  *
1516  * - Initialize the *rte_mbuf* data structure associated with the
1517  *   RX descriptor according to the information provided by the NIC into
1518  *   that RX descriptor.
1519  *
1520  * - Store the *rte_mbuf* data structure into the next entry of the
1521  *   *rx_pkts* array.
1522  *
1523  * - Replenish the RX descriptor with a new *rte_mbuf* buffer
1524  *   allocated from the memory pool associated with the receive queue at
1525  *   initialization time.
1526  *
1527  * When retrieving an input packet that was scattered by the controller
1528  * into multiple receive descriptors, the rte_eth_rx_burst() function
1529  * appends the associated *rte_mbuf* buffers to the first buffer of the
1530  * packet.
1531  *
1532  * The rte_eth_rx_burst() function returns the number of packets
1533  * actually retrieved, which is the number of *rte_mbuf* data structures
1534  * effectively supplied into the *rx_pkts* array.
1535  * A return value equal to *nb_pkts* indicates that the RX queue contained
1536  * at least *rx_pkts* packets, and this is likely to signify that other
1537  * received packets remain in the input queue. Applications implementing
1538  * a "retrieve as much received packets as possible" policy can check this
1539  * specific case and keep invoking the rte_eth_rx_burst() function until
1540  * a value less than *nb_pkts* is returned.
1541  *
1542  * This receive method has the following advantages:
1543  *
1544  * - It allows a run-to-completion network stack engine to retrieve and
1545  *   to immediately process received packets in a fast burst-oriented
1546  *   approach, avoiding the overhead of unnecessary intermediate packet
1547  *   queue/dequeue operations.
1548  *
1549  * - Conversely, it also allows an asynchronous-oriented processing
1550  *   method to retrieve bursts of received packets and to immediately
1551  *   queue them for further parallel processing by another logical core,
1552  *   for instance. However, instead of having received packets being
1553  *   individually queued by the driver, this approach allows the invoker
1554  *   of the rte_eth_rx_burst() function to queue a burst of retrieved
1555  *   packets at a time and therefore dramatically reduce the cost of
1556  *   enqueue/dequeue operations per packet.
1557  *
1558  * - It allows the rte_eth_rx_burst() function of the driver to take
1559  *   advantage of burst-oriented hardware features (CPU cache,
1560  *   prefetch instructions, and so on) to minimize the number of CPU
1561  *   cycles per packet.
1562  *
1563  * To summarize, the proposed receive API enables many
1564  * burst-oriented optimizations in both synchronous and asynchronous
1565  * packet processing environments with no overhead in both cases.
1566  *
1567  * The rte_eth_rx_burst() function does not provide any error
1568  * notification to avoid the corresponding overhead. As a hint, the
1569  * upper-level application might check the status of the device link once
1570  * being systematically returned a 0 value for a given number of tries.
1571  *
1572  * @param port_id
1573  *   The port identifier of the Ethernet device.
1574  * @param queue_id
1575  *   The index of the receive queue from which to retrieve input packets.
1576  *   The value must be in the range [0, nb_rx_queue - 1] previously supplied
1577  *   to rte_eth_dev_configure().
1578  * @param rx_pkts
1579  *   The address of an array of pointers to *rte_mbuf* structures that
1580  *   must be large enough to store *nb_pkts* pointers in it.
1581  * @param nb_pkts
1582  *   The maximum number of packets to retrieve.
1583  * @return
1584  *   The number of packets actually retrieved, which is the number
1585  *   of pointers to *rte_mbuf* structures effectively supplied to the
1586  *   *rx_pkts* array.
1587  */
1588 #ifdef RTE_LIBRTE_ETHDEV_DEBUG
1589 extern uint16_t rte_eth_rx_burst(uint8_t port_id, uint16_t queue_id,
1590                                  struct rte_mbuf **rx_pkts, uint16_t nb_pkts);
1591 #else
1592 static inline uint16_t
1593 rte_eth_rx_burst(uint8_t port_id, uint16_t queue_id,
1594                  struct rte_mbuf **rx_pkts, uint16_t nb_pkts)
1595 {
1596         struct rte_eth_dev *dev;
1597
1598         dev = &rte_eth_devices[port_id];
1599         return (*dev->rx_pkt_burst)(dev->data->rx_queues[queue_id], rx_pkts, nb_pkts);
1600 }
1601 #endif
1602
1603 /**
1604  * Send a burst of output packets on a transmit queue of an Ethernet device.
1605  *
1606  * The rte_eth_tx_burst() function is invoked to transmit output packets
1607  * on the output queue *queue_id* of the Ethernet device designated by its
1608  * *port_id*.
1609  * The *nb_pkts* parameter is the number of packets to send which are
1610  * supplied in the *tx_pkts* array of *rte_mbuf* structures.
1611  * The rte_eth_tx_burst() function loops, sending *nb_pkts* packets,
1612  * up to the number of transmit descriptors available in the TX ring of the
1613  * transmit queue.
1614  * For each packet to send, the rte_eth_tx_burst() function performs
1615  * the following operations:
1616  *
1617  * - Pick up the next available descriptor in the transmit ring.
1618  *
1619  * - Free the network buffer previously sent with that descriptor, if any.
1620  *
1621  * - Initialize the transmit descriptor with the information provided
1622  *   in the *rte_mbuf data structure.
1623  *
1624  * In the case of a segmented packet composed of a list of *rte_mbuf* buffers,
1625  * the rte_eth_tx_burst() function uses several transmit descriptors
1626  * of the ring.
1627  *
1628  * The rte_eth_tx_burst() function returns the number of packets it
1629  * actually sent. A return value equal to *nb_pkts* means that all packets
1630  * have been sent, and this is likely to signify that other output packets
1631  * could be immediately transmitted again. Applications that implement a
1632  * "send as many packets to transmit as possible" policy can check this
1633  * specific case and keep invoking the rte_eth_tx_burst() function until
1634  * a value less than *nb_pkts* is returned.
1635  *
1636  * It is the responsibility of the rte_eth_tx_burst() function to
1637  * transparently free the memory buffers of packets previously sent.
1638  * This feature is driven by the *tx_free_thresh* value supplied to the
1639  * rte_eth_dev_configure() function at device configuration time.
1640  * When the number of previously sent packets reached the "minimum transmit
1641  * packets to free" threshold, the rte_eth_tx_burst() function must
1642  * [attempt to] free the *rte_mbuf*  buffers of those packets whose
1643  * transmission was effectively completed.
1644  *
1645  * @param port_id
1646  *   The port identifier of the Ethernet device.
1647  * @param queue_id
1648  *   The index of the transmit queue through which output packets must be
1649  *   sent.
1650  *   The value must be in the range [0, nb_tx_queue - 1] previously supplied
1651  *   to rte_eth_dev_configure().
1652  * @param tx_pkts
1653  *   The address of an array of *nb_pkts* pointers to *rte_mbuf* structures
1654  *   which contain the output packets.
1655  * @param nb_pkts
1656  *   The maximum number of packets to transmit.
1657  * @return
1658  *   The number of output packets actually stored in transmit descriptors of
1659  *   the transmit ring. The return value can be less than the value of the
1660  *   *tx_pkts* parameter when the transmit ring is full or has been filled up.
1661  */
1662 #ifdef RTE_LIBRTE_ETHDEV_DEBUG
1663 extern uint16_t rte_eth_tx_burst(uint8_t port_id, uint16_t queue_id,
1664                                  struct rte_mbuf **tx_pkts, uint16_t nb_pkts);
1665 #else
1666 static inline uint16_t
1667 rte_eth_tx_burst(uint8_t port_id, uint16_t queue_id,
1668                  struct rte_mbuf **tx_pkts, uint16_t nb_pkts)
1669 {
1670         struct rte_eth_dev *dev;
1671
1672         dev = &rte_eth_devices[port_id];
1673         return (*dev->tx_pkt_burst)(dev->data->tx_queues[queue_id], tx_pkts, nb_pkts);
1674 }
1675 #endif
1676
1677 /**
1678  * Setup a new signature filter rule on an Ethernet device
1679  *
1680  * @param port_id
1681  *   The port identifier of the Ethernet device.
1682  * @param fdir_filter
1683  *   The pointer to the fdir filter structure describing the signature filter
1684  *   rule.
1685  *   The *rte_fdir_filter* structure includes the values of the different fields
1686  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1687  *   and destination ports, and so on.
1688  * @param rx_queue
1689  *   The index of the RX queue where to store RX packets matching the added
1690  *   signature filter defined in fdir_filter.
1691  * @return
1692  *   - (0) if successful.
1693  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1694  *   - (-ENODEV) if *port_id* invalid.
1695  *   - (-ENOSYS) if the FDIR mode is not configured in signature mode
1696  *               on *port_id*.
1697  *   - (-EINVAL) if the fdir_filter information is not correct.
1698  */
1699 int rte_eth_dev_fdir_add_signature_filter(uint8_t port_id,
1700                                           struct rte_fdir_filter *fdir_filter,
1701                                           uint8_t rx_queue);
1702
1703 /**
1704  * Update a signature filter rule on an Ethernet device.
1705  * If the rule doesn't exits, it is created.
1706  *
1707  * @param port_id
1708  *   The port identifier of the Ethernet device.
1709  * @param fdir_ftr
1710  *   The pointer to the structure describing the signature filter rule.
1711  *   The *rte_fdir_filter* structure includes the values of the different fields
1712  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1713  *   and destination ports, and so on.
1714  * @param rx_queue
1715  *   The index of the RX queue where to store RX packets matching the added
1716  *   signature filter defined in fdir_ftr.
1717  * @return
1718  *   - (0) if successful.
1719  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1720  *   - (-ENODEV) if *port_id* invalid.
1721  *   - (-ENOSYS) if the flow director mode is not configured in signature mode
1722  *     on *port_id*.
1723  *   - (-EINVAL) if the fdir_filter information is not correct.
1724  */
1725 int rte_eth_dev_fdir_update_signature_filter(uint8_t port_id,
1726                                              struct rte_fdir_filter *fdir_ftr,
1727                                              uint8_t rx_queue);
1728
1729 /**
1730  * Remove a signature filter rule on an Ethernet device.
1731  *
1732  * @param port_id
1733  *   The port identifier of the Ethernet device.
1734  * @param fdir_ftr
1735  *   The pointer to the structure describing the signature filter rule.
1736  *   The *rte_fdir_filter* structure includes the values of the different fields
1737  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1738  *   and destination ports, and so on.
1739  * @return
1740  *   - (0) if successful.
1741  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1742  *   - (-ENODEV) if *port_id* invalid.
1743  *   - (-ENOSYS) if the flow director mode is not configured in signature mode
1744  *     on *port_id*.
1745  *   - (-EINVAL) if the fdir_filter information is not correct.
1746  */
1747 int rte_eth_dev_fdir_remove_signature_filter(uint8_t port_id,
1748                                              struct rte_fdir_filter *fdir_ftr);
1749
1750 /**
1751  * Retrieve the flow director information of an Ethernet device.
1752  *
1753  * @param port_id
1754  *   The port identifier of the Ethernet device.
1755  * @param fdir
1756  *   A pointer to a structure of type *rte_eth_dev_fdir* to be filled with
1757  *   the flow director information of the Ethernet device.
1758  * @return
1759  *   - (0) if successful.
1760  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1761  *   - (-ENODEV) if *port_id* invalid.
1762  *   - (-ENOSYS) if the flow director mode is not configured on *port_id*.
1763  */
1764 int rte_eth_dev_fdir_get_infos(uint8_t port_id, struct rte_eth_fdir *fdir);
1765
1766 /**
1767  * Add a new perfect filter rule on an Ethernet device.
1768  *
1769  * @param port_id
1770  *   The port identifier of the Ethernet device.
1771  * @param fdir_filter
1772  *   The pointer to the structure describing the perfect filter rule.
1773  *   The *rte_fdir_filter* structure includes the values of the different fields
1774  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1775  *   and destination ports, and so on.
1776  *   IPv6 are not supported.
1777  * @param soft_id
1778  *    The 16-bit value supplied in the field hash.fdir.id of mbuf for RX
1779  *    packets matching the perfect filter.
1780  * @param rx_queue
1781  *   The index of the RX queue where to store RX packets matching the added
1782  *   perfect filter defined in fdir_filter.
1783  * @param drop
1784  *    If drop is set to 1, matching RX packets are stored into the RX drop
1785  *    queue defined in the rte_fdir_conf.
1786  * @return
1787  *   - (0) if successful.
1788  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1789  *   - (-ENODEV) if *port_id* invalid.
1790  *   - (-ENOSYS) if the flow director mode is not configured in perfect mode
1791  *               on *port_id*.
1792  *   - (-EINVAL) if the fdir_filter information is not correct.
1793  */
1794 int rte_eth_dev_fdir_add_perfect_filter(uint8_t port_id,
1795                                         struct rte_fdir_filter *fdir_filter,
1796                                         uint16_t soft_id, uint8_t rx_queue,
1797                                         uint8_t drop);
1798
1799 /**
1800  * Update a perfect filter rule on an Ethernet device.
1801  * If the rule doesn't exits, it is created.
1802  *
1803  * @param port_id
1804  *   The port identifier of the Ethernet device.
1805  * @param fdir_filter
1806  *   The pointer to the structure describing the perfect filter rule.
1807  *   The *rte_fdir_filter* structure includes the values of the different fields
1808  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1809  *   and destination ports, and so on.
1810  *   IPv6 are not supported.
1811  * @param soft_id
1812  *    The 16-bit value supplied in the field hash.fdir.id of mbuf for RX
1813  *    packets matching the perfect filter.
1814  * @param rx_queue
1815  *   The index of the RX queue where to store RX packets matching the added
1816  *   perfect filter defined in fdir_filter.
1817  * @param drop
1818  *    If drop is set to 1, matching RX packets are stored into the RX drop
1819  *    queue defined in the rte_fdir_conf.
1820  * @return
1821  *   - (0) if successful.
1822  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1823  *   - (-ENODEV) if *port_id* invalid.
1824  *   - (-ENOSYS) if the flow director mode is not configured in perfect mode
1825  *      on *port_id*.
1826  *   - (-EINVAL) if the fdir_filter information is not correct.
1827  */
1828 int rte_eth_dev_fdir_update_perfect_filter(uint8_t port_id,
1829                                            struct rte_fdir_filter *fdir_filter,
1830                                            uint16_t soft_id, uint8_t rx_queue,
1831                                            uint8_t drop);
1832
1833 /**
1834  * Remove a perfect filter rule on an Ethernet device.
1835  *
1836  * @param port_id
1837  *   The port identifier of the Ethernet device.
1838  * @param fdir_filter
1839  *   The pointer to the structure describing the perfect filter rule.
1840  *   The *rte_fdir_filter* structure includes the values of the different fields
1841  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1842  *   and destination ports, and so on.
1843  *   IPv6 are not supported.
1844  * @param soft_id
1845  *    The soft_id value provided when adding/updating the removed filter.
1846  * @return
1847  *   - (0) if successful.
1848  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1849  *   - (-ENODEV) if *port_id* invalid.
1850  *   - (-ENOSYS) if the flow director mode is not configured in perfect mode
1851  *      on *port_id*.
1852  *   - (-EINVAL) if the fdir_filter information is not correct.
1853  */
1854 int rte_eth_dev_fdir_remove_perfect_filter(uint8_t port_id,
1855                                            struct rte_fdir_filter *fdir_filter,
1856                                            uint16_t soft_id);
1857 /**
1858  * Configure globally the masks for flow director mode for an Ethernet device.
1859  * For example, the device can match packets with only the first 24 bits of
1860  * the IPv4 source address.
1861  *
1862  * The following fields can be masked: IPv4 addresses and L4 port numbers.
1863  * The following fields can be either enabled or disabled completely for the
1864  * matching functionality: VLAN ID tag; VLAN Priority + CFI bit; Flexible 2-byte
1865  * tuple.
1866  * IPv6 masks are not supported.
1867  *
1868  * All filters must comply with the masks previously configured.
1869  * For example, with a mask equal to 255.255.255.0 for the source IPv4 address,
1870  * all IPv4 filters must be created with a source IPv4 address that fits the
1871  * "X.X.X.0" format.
1872  *
1873  * This function flushes all filters that have been previously added in
1874  * the device.
1875  *
1876  * @param port_id
1877  *   The port identifier of the Ethernet device.
1878  * @param fdir_mask
1879  *   The pointer to the fdir mask structure describing relevant headers fields
1880  *   and relevant bits to use when matching packets addresses and ports.
1881  *   IPv6 masks are not supported.
1882  * @return
1883  *   - (0) if successful.
1884  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1885  *   - (-ENODEV) if *port_id* invalid.
1886  *   - (-ENOSYS) if the flow director mode is not configured in perfect
1887  *      mode on *port_id*.
1888  *   - (-EINVAL) if the fdir_filter information is not correct
1889  */
1890 int rte_eth_dev_fdir_set_masks(uint8_t port_id,
1891                                struct rte_fdir_masks *fdir_mask);
1892
1893 /**
1894  * The eth device event type for interrupt, and maybe others in the future.
1895  */
1896 enum rte_eth_event_type {
1897         RTE_ETH_EVENT_UNKNOWN,  /**< unknown event type */
1898         RTE_ETH_EVENT_INTR_LSC, /**< lsc interrupt event */
1899         RTE_ETH_EVENT_MAX       /**< max value of this enum */
1900 };
1901
1902 typedef void (*rte_eth_dev_cb_fn)(uint8_t port_id, \
1903                 enum rte_eth_event_type event, void *cb_arg);
1904 /**< user application callback to be registered for interrupts */
1905
1906
1907
1908 /**
1909  * Register a callback function for specific port id.
1910  *
1911  * @param port_id
1912  *  Port id.
1913  * @param event
1914  *  Event interested.
1915  * @param cb_fn
1916  *  User supplied callback function to be called.
1917  * @param cb_arg
1918  *  Pointer to the parameters for the registered callback.
1919  *
1920  * @return
1921  *  - On success, zero.
1922  *  - On failure, a negative value.
1923  */
1924 int rte_eth_dev_callback_register(uint8_t port_id,
1925                         enum rte_eth_event_type event,
1926                 rte_eth_dev_cb_fn cb_fn, void *cb_arg);
1927
1928 /**
1929  * Unregister a callback function for specific port id.
1930  *
1931  * @param port_id
1932  *  Port id.
1933  * @param event
1934  *  Event interested.
1935  * @param cb_fn
1936  *  User supplied callback function to be called.
1937  * @param cb_arg
1938  *  Pointer to the parameters for the registered callback. -1 means to
1939  *  remove all for the same callback address and same event.
1940  *
1941  * @return
1942  *  - On success, zero.
1943  *  - On failure, a negative value.
1944  */
1945 int rte_eth_dev_callback_unregister(uint8_t port_id,
1946                         enum rte_eth_event_type event,
1947                 rte_eth_dev_cb_fn cb_fn, void *cb_arg);
1948
1949 /**
1950  * @internal Executes all the user application registered callbacks for
1951  * the specific device. It is for DPDK internal user only. User
1952  * application should not call it directly.
1953  *
1954  * @param dev
1955  *  Pointer to struct rte_eth_dev.
1956  * @param event
1957  *  Eth device interrupt event type.
1958  *
1959  * @return
1960  *  void
1961  */
1962 void _rte_eth_dev_callback_process(struct rte_eth_dev *dev,
1963                                 enum rte_eth_event_type event);
1964
1965 /**
1966  * Turn on the LED on the Ethernet device.
1967  * This function turns on the LED on the Ethernet device.
1968  *
1969  * @param port_id
1970  *   The port identifier of the Ethernet device.
1971  * @return
1972  *   - (0) if successful.
1973  *   - (-ENOTSUP) if underlying hardware OR driver doesn't support
1974  *     that operation.
1975  *   - (-ENODEV) if *port_id* invalid.
1976  */
1977 int  rte_eth_led_on(uint8_t port_id);
1978
1979 /**
1980  * Turn off the LED on the Ethernet device.
1981  * This function turns off the LED on the Ethernet device.
1982  *
1983  * @param port_id
1984  *   The port identifier of the Ethernet device.
1985  * @return
1986  *   - (0) if successful.
1987  *   - (-ENOTSUP) if underlying hardware OR driver doesn't support
1988  *     that operation.
1989  *   - (-ENODEV) if *port_id* invalid.
1990  */
1991 int  rte_eth_led_off(uint8_t port_id);
1992
1993 /**
1994  * Configure the Ethernet link flow control for Ethernet device
1995  *
1996  * @param port_id
1997  *   The port identifier of the Ethernet device.
1998  * @param fc_conf
1999  *   The pointer to the structure of the flow control parameters.
2000  * @return
2001  *   - (0) if successful.
2002  *   - (-ENOTSUP) if hardware doesn't support flow control mode.
2003  *   - (-ENODEV)  if *port_id* invalid.
2004  *   - (-EINVAL)  if bad parameter
2005  *   - (-EIO)     if flow control setup failure
2006  */
2007 int rte_eth_dev_flow_ctrl_set(uint8_t port_id,
2008                                 struct rte_eth_fc_conf *fc_conf);
2009
2010 /**
2011  * Add a MAC address to an internal array of addresses used to enable whitelist
2012  * filtering to accept packets only if the destination MAC address matches.
2013  *
2014  * @param port
2015  *   The port identifier of the Ethernet device.
2016  * @param mac_addr
2017  *   The MAC address to add.
2018  * @param pool
2019  *   VMDq pool index to associate address with (if VMDq is enabled). If VMDq is
2020  *   not enabled, this should be set to 0.
2021  * @return
2022  *   - (0) if successfully added or *mac_addr" was already added.
2023  *   - (-ENOTSUP) if hardware doesn't support this feature.
2024  *   - (-ENODEV) if *port* is invalid.
2025  *   - (-ENOSPC) if no more MAC addresses can be added.
2026  *   - (-EINVAL) if MAC address is invalid.
2027  */
2028 int rte_eth_dev_mac_addr_add(uint8_t port, struct ether_addr *mac_addr,
2029                                 uint32_t pool);
2030
2031 /**
2032  * Remove a MAC address from the internal array of addresses.
2033  *
2034  * @param port
2035  *   The port identifier of the Ethernet device.
2036  * @param mac_addr
2037  *   MAC address to remove.
2038  * @return
2039  *   - (0) if successful, or *mac_addr* didn't exist.
2040  *   - (-ENOTSUP) if hardware doesn't support.
2041  *   - (-ENODEV) if *port* invalid.
2042  *   - (-EADDRINUSE) if attempting to remove the default MAC address
2043  */
2044 int rte_eth_dev_mac_addr_remove(uint8_t port, struct ether_addr *mac_addr);
2045
2046
2047 #ifdef __cplusplus
2048 }
2049 #endif
2050
2051 #endif /* _RTE_ETHDEV_H_ */