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         /** If set to 1, set the IPv6 masks. Otherwise set the IPv4 masks. */
 541         uint8_t set_ipv6_mask;
 542         /** When set to 1, comparison of destination IPv6 address with IP6AT
 543             registers is meaningful. */
 544         uint8_t comp_ipv6_dst;
 545         /** Mask of Destination IPv4 Address. All bits set to 1 define the
 546             relevant bits to use in the destination address of an IPv4 packet
 547             when matching it against FDIR filters. */
 548         uint32_t dst_ipv4_mask;
 549         /** Mask of Source IPv4 Address. All bits set to 1 define
 550             the relevant bits to use in the source address of an IPv4 packet
 551             when matching it against FDIR filters. */
 552         uint32_t src_ipv4_mask;
 553         /** Mask of Source IPv6 Address. All bits set to 1 define the
 554             relevant BYTES to use in the source address of an IPv6 packet
 555             when matching it against FDIR filters. */
 556         uint16_t dst_ipv6_mask;
 557         /** Mask of Destination IPv6 Address. All bits set to 1 define the
 558             relevant BYTES to use in the destination address of an IPv6 packet
 559             when matching it against FDIR filters. */
 560         uint16_t src_ipv6_mask;
 561         /** Mask of Source Port. All bits set to 1 define the relevant
 562             bits to use in the source port of an IP packets when matching it
 563             against FDIR filters. */
 564         uint16_t src_port_mask;
 565         /** Mask of Destination Port. All bits set to 1 define the relevant
 566             bits to use in the destination port of an IP packet when matching it
 567             against FDIR filters. */
 568         uint16_t dst_port_mask;
 569 };
 570
 571 /**
 572  *  A structure used to report the status of the flow director filters in use.
 573  */
 574 struct rte_eth_fdir {
 575         /** Number of filters with collision indication. */
 576         uint16_t collision;
 577         /** Number of free (non programmed) filters. */
 578         uint16_t free;
 579         /** The Lookup hash value of the added filter that updated the value
 580            of the MAXLEN field */
 581         uint16_t maxhash;
 582         /** Longest linked list of filters in the table. */
 583         uint8_t maxlen;
 584         /** Number of added filters. */
 585         uint64_t add;
 586         /** Number of removed filters. */
 587         uint64_t remove;
 588         /** Number of failed added filters (no more space in device). */
 589         uint64_t f_add;
 590         /** Number of failed removed filters. */
 591         uint64_t f_remove;
 592 };
 593
 594 /**
 595  * A structure used to enable/disable specific device interrupts.
 596  */
 597 struct rte_intr_conf {
 598         /** enable/disable lsc interrupt. 0 (default) - disable, 1 enable */
 599         uint16_t lsc;
 600 };
 601
 602 /**
 603  * A structure used to configure an Ethernet port.
 604  * Depending upon the RX multi-queue mode, extra advanced
 605  * configuration settings may be needed.
 606  */
 607 struct rte_eth_conf {
 608         uint16_t link_speed;
 609         /**< ETH_LINK_SPEED_10[0|00|000], or 0 for autonegotation */
 610         uint16_t link_duplex;
 611         /**< ETH_LINK_[HALF_DUPLEX|FULL_DUPLEX], or 0 for autonegotation */
 612         struct rte_eth_rxmode rxmode; /**< Port RX configuration. */
 613         struct rte_eth_txmode txmode; /**< Port TX configuration. */
 614         union {
 615                 struct rte_eth_rss_conf rss_conf; /**< Port RSS configuration */
 616                 struct rte_eth_vmdq_dcb_conf vmdq_dcb_conf;
 617                 /**< Port vmdq+dcb configuration. */
 618                 struct rte_eth_dcb_rx_conf dcb_rx_conf;
 619                 /**< Port dcb RX configuration. */
 620         } rx_adv_conf; /**< Port RX filtering configuration (union). */
 621         union {
 622                 struct rte_eth_vmdq_dcb_tx_conf vmdq_dcb_tx_conf;
 623                 /**< Port vmdq+dcb TX configuration. */
 624                 struct rte_eth_dcb_tx_conf dcb_tx_conf;
 625                 /**< Port dcb TX configuration. */
 626         } tx_adv_conf; /**< Port TX DCB configuration (union). */
 627         /** Currently,Priority Flow Control(PFC) are supported,if DCB with PFC
 628             is needed,and the variable must be set ETH_DCB_PFC_SUPPORT. */
 629         uint32_t dcb_capability_en;
 630         struct rte_fdir_conf fdir_conf; /**< FDIR configuration. */
 631         struct rte_intr_conf intr_conf; /**< Interrupt mode configuration. */
 632 };
 633
 634 /**
 635  * A structure used to retrieve the contextual information of
 636  * an Ethernet device, such as the controlling driver of the device,
 637  * its PCI context, etc...
 638  */
 639 struct rte_eth_dev_info {
 640         struct rte_pci_device *pci_dev; /**< Device PCI information. */
 641         const char *driver_name; /**< Device Driver name. */
 642         uint32_t min_rx_bufsize; /**< Minimum size of RX buffer. */
 643         uint32_t max_rx_pktlen; /**< Maximum configurable length of RX pkt. */
 644         uint16_t max_rx_queues; /**< Maximum number of RX queues. */
 645         uint16_t max_tx_queues; /**< Maximum number of TX queues. */
 646         uint32_t max_mac_addrs; /**< Maximum number of MAC addresses. */
 647 };
 648
 649 struct rte_eth_dev;
 650
 651 struct rte_eth_dev_callback;
 652 /** @internal Structure to keep track of registered callbacks */
 653 TAILQ_HEAD(rte_eth_dev_cb_list, rte_eth_dev_callback);
 654
 655 /*
 656  * Definitions of all functions exported by an Ethernet driver through the
 657  * the generic structure of type *eth_dev_ops* supplied in the *rte_eth_dev*
 658  * structure associated with an Ethernet device.
 659  */
 660
 661 typedef int  (*eth_dev_configure_t)(struct rte_eth_dev *dev);
 662 /**< @internal Ethernet device configuration. */
 663
 664 typedef int  (*eth_dev_start_t)(struct rte_eth_dev *dev);
 665 /**< @internal Function used to start a configured Ethernet device. */
 666
 667 typedef void (*eth_dev_stop_t)(struct rte_eth_dev *dev);
 668 /**< @internal Function used to stop a configured Ethernet device. */
 669
 670 typedef void (*eth_dev_close_t)(struct rte_eth_dev *dev);
 671 /**< @internal Function used to close a configured Ethernet device. */
 672
 673 typedef void (*eth_promiscuous_enable_t)(struct rte_eth_dev *dev);
 674 /**< @internal Function used to enable the RX promiscuous mode of an Ethernet device. */
 675
 676 typedef void (*eth_promiscuous_disable_t)(struct rte_eth_dev *dev);
 677 /**< @internal Function used to disable the RX promiscuous mode of an Ethernet device. */
 678
 679 typedef void (*eth_allmulticast_enable_t)(struct rte_eth_dev *dev);
 680 /**< @internal Enable the receipt of all multicast packets by an Ethernet device. */
 681
 682 typedef void (*eth_allmulticast_disable_t)(struct rte_eth_dev *dev);
 683 /**< @internal Disable the receipt of all multicast packets by an Ethernet device. */
 684
 685 typedef int (*eth_link_update_t)(struct rte_eth_dev *dev,
 686                                 int wait_to_complete);
 687 /**< @internal Get link speed, duplex mode and state (up/down) of an Ethernet device. */
 688
 689 typedef void (*eth_stats_get_t)(struct rte_eth_dev *dev,
 690                                 struct rte_eth_stats *igb_stats);
 691 /**< @internal Get global I/O statistics of an Ethernet device. */
 692
 693 typedef void (*eth_stats_reset_t)(struct rte_eth_dev *dev);
 694 /**< @internal Reset global I/O statistics of an Ethernet device to 0. */
 695
 696 typedef int (*eth_queue_stats_mapping_set_t)(struct rte_eth_dev *dev,
 697                                              uint16_t queue_id,
 698                                              uint8_t stat_idx,
 699                                              uint8_t is_rx);
 700 /**< @internal Set a queue statistics mapping for a tx/rx queue of an Ethernet device. */
 701
 702 typedef void (*eth_dev_infos_get_t)(struct rte_eth_dev *dev,
 703                                     struct rte_eth_dev_info *dev_info);
 704 /**< @internal Get specific informations of an Ethernet device. */
 705
 706 typedef int (*eth_rx_queue_setup_t)(struct rte_eth_dev *dev,
 707                                     uint16_t rx_queue_id,
 708                                     uint16_t nb_rx_desc,
 709                                     unsigned int socket_id,
 710                                     const struct rte_eth_rxconf *rx_conf,
 711                                     struct rte_mempool *mb_pool);
 712 /**< @internal Set up a receive queue of an Ethernet device. */
 713
 714 typedef int (*eth_tx_queue_setup_t)(struct rte_eth_dev *dev,
 715                                     uint16_t tx_queue_id,
 716                                     uint16_t nb_tx_desc,
 717                                     unsigned int socket_id,
 718                                     const struct rte_eth_txconf *tx_conf);
 719 /**< @internal Setup a transmit queue of an Ethernet device. */
 720
 721 typedef void (*eth_queue_release_t)(void *queue);
 722 /**< @internal Release memory resources allocated by given RX/TX queue. */
 723
 724 typedef int (*vlan_filter_set_t)(struct rte_eth_dev *dev,
 725                                   uint16_t vlan_id,
 726                                   int on);
 727 /**< @internal filtering of a VLAN Tag Identifier by an Ethernet device. */
 728
 729 typedef void (*vlan_tpid_set_t)(struct rte_eth_dev *dev,
 730                                   uint16_t tpid);
 731 /**< @internal set the outer VLAN-TPID by an Ethernet device. */
 732
 733 typedef void (*vlan_offload_set_t)(struct rte_eth_dev *dev, int mask);
 734 /**< @internal set VLAN offload function by an Ethernet device. */
 735
 736 typedef void (*vlan_strip_queue_set_t)(struct rte_eth_dev *dev,
 737                                   uint16_t rx_queue_id,
 738                                   int on);
 739 /**< @internal VLAN stripping enable/disable by an queue of Ethernet device. */
 740
 741 typedef uint16_t (*eth_rx_burst_t)(void *rxq,
 742                                    struct rte_mbuf **rx_pkts,
 743                                    uint16_t nb_pkts);
 744 /**< @internal Retrieve input packets from a receive queue of an Ethernet device. */
 745
 746 typedef uint16_t (*eth_tx_burst_t)(void *txq,
 747                                    struct rte_mbuf **tx_pkts,
 748                                    uint16_t nb_pkts);
 749 /**< @internal Send output packets on a transmit queue of an Ethernet device. */
 750
 751 typedef int (*fdir_add_signature_filter_t)(struct rte_eth_dev *dev,
 752                                            struct rte_fdir_filter *fdir_ftr,
 753                                            uint8_t rx_queue);
 754 /**< @internal Setup a new signature filter rule on an Ethernet device */
 755
 756 typedef int (*fdir_update_signature_filter_t)(struct rte_eth_dev *dev,
 757                                               struct rte_fdir_filter *fdir_ftr,
 758                                               uint8_t rx_queue);
 759 /**< @internal Update a signature filter rule on an Ethernet device */
 760
 761 typedef int (*fdir_remove_signature_filter_t)(struct rte_eth_dev *dev,
 762                                               struct rte_fdir_filter *fdir_ftr);
 763 /**< @internal Remove a  signature filter rule on an Ethernet device */
 764
 765 typedef void (*fdir_infos_get_t)(struct rte_eth_dev *dev,
 766                                  struct rte_eth_fdir *fdir);
 767 /**< @internal Get information about fdir status */
 768
 769 typedef int (*fdir_add_perfect_filter_t)(struct rte_eth_dev *dev,
 770                                          struct rte_fdir_filter *fdir_ftr,
 771                                          uint16_t soft_id, uint8_t rx_queue,
 772                                          uint8_t drop);
 773 /**< @internal Setup a new perfect filter rule on an Ethernet device */
 774
 775 typedef int (*fdir_update_perfect_filter_t)(struct rte_eth_dev *dev,
 776                                             struct rte_fdir_filter *fdir_ftr,
 777                                             uint16_t soft_id, uint8_t rx_queue,
 778                                             uint8_t drop);
 779 /**< @internal Update a perfect filter rule on an Ethernet device */
 780
 781 typedef int (*fdir_remove_perfect_filter_t)(struct rte_eth_dev *dev,
 782                                             struct rte_fdir_filter *fdir_ftr,
 783                                             uint16_t soft_id);
 784 /**< @internal Remove a perfect filter rule on an Ethernet device */
 785
 786 typedef int (*fdir_set_masks_t)(struct rte_eth_dev *dev,
 787                                 struct rte_fdir_masks *fdir_masks);
 788 /**< @internal Setup flow director masks on an Ethernet device */
 789
 790 typedef int (*flow_ctrl_set_t)(struct rte_eth_dev *dev,
 791                                 struct rte_eth_fc_conf *fc_conf);
 792 /**< @internal Setup flow control parameter on an Ethernet device */
 793
 794 typedef int (*eth_dev_led_on_t)(struct rte_eth_dev *dev);
 795 /**< @internal Turn on SW controllable LED on an Ethernet device */
 796
 797 typedef int (*eth_dev_led_off_t)(struct rte_eth_dev *dev);
 798 /**< @internal Turn off SW controllable LED on an Ethernet device */
 799
 800 typedef void (*eth_mac_addr_remove_t)(struct rte_eth_dev *dev, uint32_t index);
 801 /**< @internal Remove MAC address from receive address register */
 802
 803 typedef void (*eth_mac_addr_add_t)(struct rte_eth_dev *dev,
 804                                   struct ether_addr *mac_addr,
 805                                   uint32_t index,
 806                                   uint32_t vmdq);
 807 /**< @internal Set a MAC address into Receive Address Address Register */
 808
 809 /**
 810  * @internal A structure containing the functions exported by an Ethernet driver.
 811  */
 812 struct eth_dev_ops {
 813         eth_dev_configure_t        dev_configure; /**< Configure device. */
 814         eth_dev_start_t            dev_start;     /**< Start device. */
 815         eth_dev_stop_t             dev_stop;      /**< Stop device. */
 816         eth_dev_close_t            dev_close;     /**< Close device. */
 817         eth_promiscuous_enable_t   promiscuous_enable; /**< Promiscuous ON. */
 818         eth_promiscuous_disable_t  promiscuous_disable;/**< Promiscuous OFF. */
 819         eth_allmulticast_enable_t  allmulticast_enable;/**< RX multicast ON. */
 820         eth_allmulticast_disable_t allmulticast_disable;/**< RX multicast OF. */
 821         eth_link_update_t          link_update;   /**< Get device link state. */
 822         eth_stats_get_t            stats_get;     /**< Get device statistics. */
 823         eth_stats_reset_t          stats_reset;   /**< Reset device statistics. */
 824         eth_queue_stats_mapping_set_t queue_stats_mapping_set;
 825         /**< Configure per queue stat counter mapping. */
 826         eth_dev_infos_get_t        dev_infos_get; /**< Get device info. */
 827         vlan_filter_set_t          vlan_filter_set;  /**< Filter VLAN Setup. */
 828         vlan_tpid_set_t            vlan_tpid_set;      /**< Outer VLAN TPID Setup. */
 829         vlan_strip_queue_set_t     vlan_strip_queue_set; /**< VLAN Stripping on queue. */
 830         vlan_offload_set_t         vlan_offload_set; /**< Set VLAN Offload. */
 831         eth_rx_queue_setup_t       rx_queue_setup;/**< Set up device RX queue.*/
 832         eth_queue_release_t        rx_queue_release;/**< Release RX queue.*/
 833         eth_tx_queue_setup_t       tx_queue_setup;/**< Set up device TX queue.*/
 834         eth_queue_release_t        tx_queue_release;/**< Release TX queue.*/
 835         eth_dev_led_on_t           dev_led_on;    /**< Turn on LED. */
 836         eth_dev_led_off_t          dev_led_off;   /**< Turn off LED. */
 837         flow_ctrl_set_t            flow_ctrl_set; /**< Setup flow control. */
 838         eth_mac_addr_remove_t      mac_addr_remove; /**< Remove MAC address */
 839         eth_mac_addr_add_t         mac_addr_add;  /**< Add a MAC address */
 840
 841         /** Add a signature filter. */
 842         fdir_add_signature_filter_t fdir_add_signature_filter;
 843         /** Update a signature filter. */
 844         fdir_update_signature_filter_t fdir_update_signature_filter;
 845         /** Remove a signature filter. */
 846         fdir_remove_signature_filter_t fdir_remove_signature_filter;
 847         /** Get information about FDIR status. */
 848         fdir_infos_get_t fdir_infos_get;
 849         /** Add a perfect filter. */
 850         fdir_add_perfect_filter_t fdir_add_perfect_filter;
 851         /** Update a perfect filter. */
 852         fdir_update_perfect_filter_t fdir_update_perfect_filter;
 853         /** Remove a perfect filter. */
 854         fdir_remove_perfect_filter_t fdir_remove_perfect_filter;
 855         /** Setup masks for FDIR filtering. */
 856         fdir_set_masks_t fdir_set_masks;
 857 };
 858
 859 /**
 860  * @internal
 861  * The generic data structure associated with each ethernet device.
 862  *
 863  * Pointers to burst-oriented packet receive and transmit functions are
 864  * located at the beginning of the structure, along with the pointer to
 865  * where all the data elements for the particular device are stored in shared
 866  * memory. This split allows the function pointer and driver data to be per-
 867  * process, while the actual configuration data for the device is shared.
 868  */
 869 struct rte_eth_dev {
 870         eth_rx_burst_t rx_pkt_burst; /**< Pointer to PMD receive function. */
 871         eth_tx_burst_t tx_pkt_burst; /**< Pointer to PMD transmit function. */
 872         struct rte_eth_dev_data *data;  /**< Pointer to device data */
 873         const struct eth_driver *driver;/**< Driver for this device */
 874         struct eth_dev_ops *dev_ops;    /**< Functions exported by PMD */
 875         struct rte_pci_device *pci_dev; /**< PCI info. supplied by probing */
 876         struct rte_eth_dev_cb_list callbacks; /**< User application callbacks */
 877 };
 878
 879 /**
 880  * @internal
 881  * The data part, with no function pointers, associated with each ethernet device.
 882  *
 883  * This structure is safe to place in shared memory to be common among different
 884  * processes in a multi-process configuration.
 885  */
 886 struct rte_eth_dev_data {
 887         void **rx_queues; /**< Array of pointers to RX queues. */
 888         void **tx_queues; /**< Array of pointers to TX queues. */
 889         uint16_t nb_rx_queues; /**< Number of RX queues. */
 890         uint16_t nb_tx_queues; /**< Number of TX queues. */
 891
 892         void *dev_private;              /**< PMD-specific private data */
 893
 894         struct rte_eth_link dev_link;
 895         /**< Link-level information & status */
 896
 897         struct rte_eth_conf dev_conf;   /**< Configuration applied to device. */
 898         uint16_t max_frame_size;        /**< Default is ETHER_MAX_LEN (1518). */
 899
 900         uint64_t rx_mbuf_alloc_failed; /**< RX ring mbuf allocation failures. */
 901         struct ether_addr* mac_addrs;/**< Device Ethernet Link address. */
 902         uint8_t port_id;           /**< Device [external] port identifier. */
 903         uint8_t promiscuous   : 1, /**< RX promiscuous mode ON(1) / OFF(0). */
 904                 scattered_rx : 1,  /**< RX of scattered packets is ON(1) / OFF(0) */
 905                 all_multicast : 1, /**< RX all multicast mode ON(1) / OFF(0). */
 906                 dev_started : 1;   /**< Device state: STARTED(1) / STOPPED(0). */
 907 };
 908
 909 /**
 910  * @internal
 911  * The pool of *rte_eth_dev* structures. The size of the pool
 912  * is configured at compile-time in the <rte_ethdev.c> file.
 913  */
 914 extern struct rte_eth_dev rte_eth_devices[];
 915
 916 /**
 917  * Get the total number of Ethernet devices that have been successfully
 918  * initialized by the [matching] Ethernet driver during the PCI probing phase.
 919  * All devices whose port identifier is in the range
 920  * [0,  rte_eth_dev_count() - 1] can be operated on by network applications.
 921  *
 922  * @return
 923  *   - The total number of usable Ethernet devices.
 924  */
 925 extern uint8_t rte_eth_dev_count(void);
 926
 927 struct eth_driver;
 928 /**
 929  * @internal
 930  * Initialization function of an Ethernet driver invoked for each matching
 931  * Ethernet PCI device detected during the PCI probing phase.
 932  *
 933  * @param eth_drv
 934  *   The pointer to the [matching] Ethernet driver structure supplied by
 935  *   the PMD when it registered itself.
 936  * @param eth_dev
 937  *   The *eth_dev* pointer is the address of the *rte_eth_dev* structure
 938  *   associated with the matching device and which have been [automatically]
 939  *   allocated in the *rte_eth_devices* array.
 940  *   The *eth_dev* structure is supplied to the driver initialization function
 941  *   with the following fields already initialized:
 942  *
 943  *   - *pci_dev*: Holds the pointers to the *rte_pci_device* structure which
 944  *     contains the generic PCI information of the matching device.
 945  *
 946  *   - *dev_private*: Holds a pointer to the device private data structure.
 947  *
 948  *   - *max_frame_size*: Contains the default Ethernet maximum frame length
 949  *     (1518).
 950  *
 951  *   - *port_id*: Contains the port index of the device (actually the index
 952  *     of the *eth_dev* structure in the *rte_eth_devices* array).
 953  *
 954  * @return
 955  *   - 0: Success, the device is properly initialized by the driver.
 956  *        In particular, the driver MUST have set up the *dev_ops* pointer
 957  *        of the *eth_dev* structure.
 958  *   - <0: Error code of the device initialization failure.
 959  */
 960 typedef int (*eth_dev_init_t)(struct eth_driver  *eth_drv,
 961                               struct rte_eth_dev *eth_dev);
 962
 963 /**
 964  * @internal
 965  * The structure associated with a PMD Ethernet driver.
 966  *
 967  * Each Ethernet driver acts as a PCI driver and is represented by a generic
 968  * *eth_driver* structure that holds:
 969  *
 970  * - An *rte_pci_driver* structure (which must be the first field).
 971  *
 972  * - The *eth_dev_init* function invoked for each matching PCI device.
 973  *
 974  * - The size of the private data to allocate for each matching device.
 975  */
 976 struct eth_driver {
 977         struct rte_pci_driver pci_drv;    /**< The PMD is also a PCI driver. */
 978         eth_dev_init_t eth_dev_init;      /**< Device init function. */
 979         unsigned int dev_private_size;    /**< Size of device private data. */
 980 };
 981
 982 /**
 983  * @internal
 984  * A function invoked by the initialization function of an Ethernet driver
 985  * to simultaneously register itself as a PCI driver and as an Ethernet
 986  * Poll Mode Driver (PMD).
 987  *
 988  * @param eth_drv
 989  *   The pointer to the *eth_driver* structure associated with
 990  *   the Ethernet driver.
 991  */
 992 extern void rte_eth_driver_register(struct eth_driver *eth_drv);
 993
 994 /**
 995  * The initialization function of the driver for
 996  * Intel(r) IGB 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_igb_pmd_init(void);
1002
1003 /**
1004  * The initialization function of the driver for
1005  * Intel(r) EM Gigabit Ethernet Controller devices.
1006  * This function is invoked once at EAL start time.
1007  * @return
1008  *   0 on success
1009  */
1010 extern int rte_em_pmd_init(void);
1011
1012 /**
1013  * The initialization function of the driver for 1Gbps Intel IGB_VF
1014  * Ethernet devices.
1015  * Invoked once at EAL start time.
1016  * @return
1017  *   0 on success
1018  */
1019 extern int rte_igbvf_pmd_init(void);
1020
1021 /**
1022  * The initialization function of the driver for 10Gbps Intel IXGBE
1023  * Ethernet devices.
1024  * Invoked once at EAL start time.
1025  * @return
1026  *   0 on success
1027  */
1028 extern int rte_ixgbe_pmd_init(void);
1029
1030 /**
1031  * The initialization function of the driver for 10Gbps Intel IXGBE_VF
1032  * Ethernet devices.
1033  * Invoked once at EAL start time.
1034  * @return
1035  *   0 on success
1036  */
1037 extern int rte_ixgbevf_pmd_init(void);
1038
1039 /**
1040  * The initialization function of *all* supported and enabled drivers.
1041  * Right now, the following PMDs are supported:
1042  *  - igb
1043  *  - igbvf
1044  *  - em
1045  *  - ixgbe
1046  *  - ixgbevf
1047  * This function is invoked once at EAL start time.
1048  * @return
1049  *   0 on success.
1050  *   Error code of the device initialization failure,
1051  *   -ENODEV if there are no drivers available
1052  *   (e.g. if all driver config options are = n).
1053  */
1054 static inline
1055 int rte_pmd_init_all(void)
1056 {
1057         int ret = -ENODEV;
1058
1059 #ifdef RTE_LIBRTE_IGB_PMD
1060         if ((ret = rte_igb_pmd_init()) != 0) {
1061                 RTE_LOG(ERR, PMD, "Cannot init igb PMD\n");
1062                 return (ret);
1063         }
1064         if ((ret = rte_igbvf_pmd_init()) != 0) {
1065                 RTE_LOG(ERR, PMD, "Cannot init igbvf PMD\n");
1066                 return (ret);
1067         }
1068 #endif /* RTE_LIBRTE_IGB_PMD */
1069
1070 #ifdef RTE_LIBRTE_EM_PMD
1071         if ((ret = rte_em_pmd_init()) != 0) {
1072                 RTE_LOG(ERR, PMD, "Cannot init em PMD\n");
1073                 return (ret);
1074         }
1075 #endif /* RTE_LIBRTE_EM_PMD */
1076
1077 #ifdef RTE_LIBRTE_IXGBE_PMD
1078         if ((ret = rte_ixgbe_pmd_init()) != 0) {
1079                 RTE_LOG(ERR, PMD, "Cannot init ixgbe PMD\n");
1080                 return (ret);
1081         }
1082         if ((ret = rte_ixgbevf_pmd_init()) != 0) {
1083                 RTE_LOG(ERR, PMD, "Cannot init ixgbevf PMD\n");
1084                 return (ret);
1085         }
1086 #endif /* RTE_LIBRTE_IXGBE_PMD */
1087
1088         if (ret == -ENODEV)
1089                 RTE_LOG(ERR, PMD, "No PMD(s) are configured\n");
1090         return (ret);
1091 }
1092
1093 /**
1094  * Configure an Ethernet device.
1095  * This function must be invoked first before any other function in the
1096  * Ethernet API. This function can also be re-invoked when a device is in the
1097  * stopped state.
1098  *
1099  * @param port_id
1100  *   The port identifier of the Ethernet device to configure.
1101  * @param nb_rx_queue
1102  *   The number of receive queues to set up for the Ethernet device.
1103  * @param nb_tx_queue
1104  *   The number of transmit queues to set up for the Ethernet device.
1105  * @param eth_conf
1106  *   The pointer to the configuration data to be used for the Ethernet device.
1107  *   The *rte_eth_conf* structure includes:
1108  *     -  the hardware offload features to activate, with dedicated fields for
1109  *        each statically configurable offload hardware feature provided by
1110  *        Ethernet devices, such as IP checksum or VLAN tag stripping for
1111  *        example.
1112  *     - the Receive Side Scaling (RSS) configuration when using multiple RX
1113  *         queues per port.
1114  *
1115  *   Embedding all configuration information in a single data structure
1116  *   is the more flexible method that allows the addition of new features
1117  *   without changing the syntax of the API.
1118  * @return
1119  *   - 0: Success, device configured.
1120  *   - <0: Error code returned by the driver configuration function.
1121  */
1122 extern int rte_eth_dev_configure(uint8_t port_id,
1123                                  uint16_t nb_rx_queue,
1124                                  uint16_t nb_tx_queue,
1125                                  const struct rte_eth_conf *eth_conf);
1126
1127 /**
1128  * Allocate and set up a receive queue for an Ethernet device.
1129  *
1130  * The function allocates a contiguous block of memory for *nb_rx_desc*
1131  * receive descriptors from a memory zone associated with *socket_id*
1132  * and initializes each receive descriptor with a network buffer allocated
1133  * from the memory pool *mb_pool*.
1134  *
1135  * @param port_id
1136  *   The port identifier of the Ethernet device.
1137  * @param rx_queue_id
1138  *   The index of the receive queue to set up.
1139  *   The value must be in the range [0, nb_rx_queue - 1] previously supplied
1140  *   to rte_eth_dev_configure().
1141  * @param nb_rx_desc
1142  *   The number of receive descriptors to allocate for the receive ring.
1143  * @param socket_id
1144  *   The *socket_id* argument is the socket identifier in case of NUMA.
1145  *   The value can be *SOCKET_ID_ANY* if there is no NUMA constraint for
1146  *   the DMA memory allocated for the receive descriptors of the ring.
1147  * @param rx_conf
1148  *   The pointer to the configuration data to be used for the receive queue.
1149  *   The *rx_conf* structure contains an *rx_thresh* structure with the values
1150  *   of the Prefetch, Host, and Write-Back threshold registers of the receive
1151  *   ring.
1152  * @param mb_pool
1153  *   The pointer to the memory pool from which to allocate *rte_mbuf* network
1154  *   memory buffers to populate each descriptor of the receive ring.
1155  * @return
1156  *   - 0: Success, receive queue correctly set up.
1157  *   - -EINVAL: The size of network buffers which can be allocated from the
1158  *      memory pool does not fit the various buffer sizes allowed by the
1159  *      device controller.
1160  *   - -ENOMEM: Unable to allocate the receive ring descriptors or to
1161  *      allocate network memory buffers from the memory pool when
1162  *      initializing receive descriptors.
1163  */
1164 extern int rte_eth_rx_queue_setup(uint8_t port_id, uint16_t rx_queue_id,
1165                                   uint16_t nb_rx_desc, unsigned int socket_id,
1166                                   const struct rte_eth_rxconf *rx_conf,
1167                                   struct rte_mempool *mb_pool);
1168
1169 /**
1170  * Allocate and set up a transmit queue for an Ethernet device.
1171  *
1172  * @param port_id
1173  *   The port identifier of the Ethernet device.
1174  * @param tx_queue_id
1175  *   The index of the transmit queue to set up.
1176  *   The value must be in the range [0, nb_tx_queue - 1] previously supplied
1177  *   to rte_eth_dev_configure().
1178  * @param nb_tx_desc
1179  *   The number of transmit descriptors to allocate for the transmit ring.
1180  * @param socket_id
1181  *   The *socket_id* argument is the socket identifier in case of NUMA.
1182  *   Its value can be *SOCKET_ID_ANY* if there is no NUMA constraint for
1183  *   the DMA memory allocated for the transmit descriptors of the ring.
1184  * @param tx_conf
1185  *   The pointer to the configuration data to be used for the transmit queue.
1186  *   The *tx_conf* structure contains the following data:
1187  *   - The *tx_thresh* structure with the values of the Prefetch, Host, and
1188  *     Write-Back threshold registers of the transmit ring.
1189  *     When setting Write-Back threshold to the value greater then zero,
1190  *     *tx_rs_thresh* value should be explicitly set to one.
1191  *   - The *tx_free_thresh* value indicates the [minimum] number of network
1192  *     buffers that must be pending in the transmit ring to trigger their
1193  *     [implicit] freeing by the driver transmit function.
1194  *   - The *tx_rs_thresh* value indicates the [minimum] number of transmit
1195  *     descriptors that must be pending in the transmit ring before setting the
1196  *     RS bit on a descriptor by the driver transmit function.
1197  *     The *tx_rs_thresh* value should be less or equal then
1198  *     *tx_free_thresh* value, and both of them should be less then
1199  *     *nb_tx_desc* - 3.
1200  *   - The *txq_flags* member contains flags to pass to the TX queue setup
1201  *     function to configure the behavior of the TX queue. This should be set
1202  *     to 0 if no special configuration is required.
1203  *
1204  *     Note that setting *tx_free_thresh* or *tx_rs_thresh* value to 0 forces
1205  *     the transmit function to use default values.
1206  * @return
1207  *   - 0: Success, the transmit queue is correctly set up.
1208  *   - -ENOMEM: Unable to allocate the transmit ring descriptors.
1209  */
1210 extern int rte_eth_tx_queue_setup(uint8_t port_id, uint16_t tx_queue_id,
1211                                   uint16_t nb_tx_desc, unsigned int socket_id,
1212                                   const struct rte_eth_txconf *tx_conf);
1213
1214 /**
1215  * Start an Ethernet device.
1216  *
1217  * The device start step is the last one and consists of setting the configured
1218  * offload features and in starting the transmit and the receive units of the
1219  * device.
1220  * On success, all basic functions exported by the Ethernet API (link status,
1221  * receive/transmit, and so on) can be invoked.
1222  *
1223  * @param port_id
1224  *   The port identifier of the Ethernet device.
1225  * @return
1226  *   - 0: Success, Ethernet device started.
1227  *   - <0: Error code of the driver device start function.
1228  */
1229 extern int rte_eth_dev_start(uint8_t port_id);
1230
1231 /**
1232  * Stop an Ethernet device. The device can be restarted with a call to
1233  * rte_eth_dev_start()
1234  *
1235  * @param port_id
1236  *   The port identifier of the Ethernet device.
1237  */
1238 extern void rte_eth_dev_stop(uint8_t port_id);
1239
1240 /**
1241  * Close an Ethernet device. The device cannot be restarted!
1242  *
1243  * @param port_id
1244  *   The port identifier of the Ethernet device.
1245  */
1246 extern void rte_eth_dev_close(uint8_t port_id);
1247
1248 /**
1249  * Enable receipt in promiscuous mode for an Ethernet device.
1250  *
1251  * @param port_id
1252  *   The port identifier of the Ethernet device.
1253  */
1254 extern void rte_eth_promiscuous_enable(uint8_t port_id);
1255
1256 /**
1257  * Disable receipt in promiscuous mode for an Ethernet device.
1258  *
1259  * @param port_id
1260  *   The port identifier of the Ethernet device.
1261  */
1262 extern void rte_eth_promiscuous_disable(uint8_t port_id);
1263
1264 /**
1265  * Return the value of promiscuous mode for an Ethernet device.
1266  *
1267  * @param port_id
1268  *   The port identifier of the Ethernet device.
1269  * @return
1270  *   - (1) if promiscuous is enabled
1271  *   - (0) if promiscuous is disabled.
1272  *   - (-1) on error
1273  */
1274 extern int rte_eth_promiscuous_get(uint8_t port_id);
1275
1276 /**
1277  * Enable the receipt of any multicast frame by an Ethernet device.
1278  *
1279  * @param port_id
1280  *   The port identifier of the Ethernet device.
1281  */
1282 extern void rte_eth_allmulticast_enable(uint8_t port_id);
1283
1284 /**
1285  * Disable the receipt of all multicast frames by an Ethernet device.
1286  *
1287  * @param port_id
1288  *   The port identifier of the Ethernet device.
1289  */
1290 extern void rte_eth_allmulticast_disable(uint8_t port_id);
1291
1292 /**
1293  * Return the value of allmulticast mode for an Ethernet device.
1294  *
1295  * @param port_id
1296  *   The port identifier of the Ethernet device.
1297  * @return
1298  *   - (1) if allmulticast is enabled
1299  *   - (0) if allmulticast is disabled.
1300  *   - (-1) on error
1301  */
1302 extern int rte_eth_allmulticast_get(uint8_t port_id);
1303
1304 /**
1305  * Retrieve the status (ON/OFF), the speed (in Mbps) and the mode (HALF-DUPLEX
1306  * or FULL-DUPLEX) of the physical link of an Ethernet device. It might need
1307  * to wait up to 9 seconds in it.
1308  *
1309  * @param port_id
1310  *   The port identifier of the Ethernet device.
1311  * @param link
1312  *   A pointer to an *rte_eth_link* structure to be filled with
1313  *   the status, the speed and the mode of the Ethernet device link.
1314  */
1315 extern void rte_eth_link_get(uint8_t port_id, struct rte_eth_link *link);
1316
1317 /**
1318  * Retrieve the status (ON/OFF), the speed (in Mbps) and the mode (HALF-DUPLEX
1319  * or FULL-DUPLEX) of the physical link of an Ethernet device. It is a no-wait
1320  * version of rte_eth_link_get().
1321  *
1322  * @param port_id
1323  *   The port identifier of the Ethernet device.
1324  * @param link
1325  *   A pointer to an *rte_eth_link* structure to be filled with
1326  *   the status, the speed and the mode of the Ethernet device link.
1327  */
1328 extern void rte_eth_link_get_nowait(uint8_t port_id,
1329                                 struct rte_eth_link *link);
1330
1331 /**
1332  * Retrieve the general I/O statistics of an Ethernet device.
1333  *
1334  * @param port_id
1335  *   The port identifier of the Ethernet device.
1336  * @param stats
1337  *   A pointer to a structure of type *rte_eth_stats* to be filled with
1338  *   the values of device counters for the following set of statistics:
1339  *   - *ipackets* with the total of successfully received packets.
1340  *   - *opackets* with the total of successfully transmitted packets.
1341  *   - *ibytes*   with the total of successfully received bytes.
1342  *   - *obytes*   with the total of successfully transmitted bytes.
1343  *   - *ierrors*  with the total of erroneous received packets.
1344  *   - *oerrors*  with the total of failed transmitted packets.
1345  */
1346 extern void rte_eth_stats_get(uint8_t port_id, struct rte_eth_stats *stats);
1347
1348 /**
1349  * Reset the general I/O statistics of an Ethernet device.
1350  *
1351  * @param port_id
1352  *   The port identifier of the Ethernet device.
1353  */
1354 extern void rte_eth_stats_reset(uint8_t port_id);
1355
1356 /**
1357  *  Set a mapping for the specified transmit queue to the specified per-queue
1358  *  statistics counter.
1359  *
1360  * @param port_id
1361  *   The port identifier of the Ethernet device.
1362  * @param tx_queue_id
1363  *   The index of the transmit queue for which a queue stats mapping is required.
1364  *   The value must be in the range [0, nb_tx_queue - 1] previously supplied
1365  *   to rte_eth_dev_configure().
1366  * @param stat_idx
1367  *   The per-queue packet statistics functionality number that the transmit
1368  *   queue is to be assigned.
1369  *   The value must be in the range [0, RTE_MAX_ETHPORT_QUEUE_STATS_MAPS - 1].
1370  * @return
1371  *   Zero if successful. Non-zero otherwise.
1372  */
1373 extern int rte_eth_dev_set_tx_queue_stats_mapping(uint8_t port_id,
1374                                                   uint16_t tx_queue_id,
1375                                                   uint8_t stat_idx);
1376
1377 /**
1378  *  Set a mapping for the specified receive queue to the specified per-queue
1379  *  statistics counter.
1380  *
1381  * @param port_id
1382  *   The port identifier of the Ethernet device.
1383  * @param rx_queue_id
1384  *   The index of the receive queue for which a queue stats mapping is required.
1385  *   The value must be in the range [0, nb_rx_queue - 1] previously supplied
1386  *   to rte_eth_dev_configure().
1387  * @param stat_idx
1388  *   The per-queue packet statistics functionality number that the receive
1389  *   queue is to be assigned.
1390  *   The value must be in the range [0, RTE_MAX_ETHPORT_QUEUE_STATS_MAPS - 1].
1391  * @return
1392  *   Zero if successful. Non-zero otherwise.
1393  */
1394 extern int rte_eth_dev_set_rx_queue_stats_mapping(uint8_t port_id,
1395                                                   uint16_t rx_queue_id,
1396                                                   uint8_t stat_idx);
1397
1398 /**
1399  * Retrieve the Ethernet address of an Ethernet device.
1400  *
1401  * @param port_id
1402  *   The port identifier of the Ethernet device.
1403  * @param mac_addr
1404  *   A pointer to a structure of type *ether_addr* to be filled with
1405  *   the Ethernet address of the Ethernet device.
1406  */
1407 extern void rte_eth_macaddr_get(uint8_t port_id, struct ether_addr *mac_addr);
1408
1409 /**
1410  * Retrieve the contextual information of an Ethernet device.
1411  *
1412  * @param port_id
1413  *   The port identifier of the Ethernet device.
1414  * @param dev_info
1415  *   A pointer to a structure of type *rte_eth_dev_info* to be filled with
1416  *   the contextual information of the Ethernet device.
1417  */
1418 extern void rte_eth_dev_info_get(uint8_t port_id,
1419                                  struct rte_eth_dev_info *dev_info);
1420
1421 /**
1422  * Enable/Disable hardware filtering by an Ethernet device of received
1423  * VLAN packets tagged with a given VLAN Tag Identifier.
1424  *
1425  * @param port_id
1426  *   The port identifier of the Ethernet device.
1427  * @param vlan_id
1428  *   The VLAN Tag Identifier whose filtering must be enabled or disabled.
1429  * @param on
1430  *   If > 0, enable VLAN filtering of VLAN packets tagged with *vlan_id*.
1431  *   Otherwise, disable VLAN filtering of VLAN packets tagged with *vlan_id*.
1432  * @return
1433  *   - (0) if successful.
1434  *   - (-ENOSUP) if hardware-assisted VLAN filtering not configured.
1435  *   - (-ENODEV) if *port_id* invalid.
1436  *   - (-ENOSYS) if VLAN filtering on *port_id* disabled.
1437  *   - (-EINVAL) if *vlan_id* > 4095.
1438  */
1439 extern int rte_eth_dev_vlan_filter(uint8_t port_id, uint16_t vlan_id , int on);
1440
1441 /**
1442  * Enable/Disable hardware VLAN Strip by a rx queue of an Ethernet device.
1443  * 82599/X540 can support VLAN stripping at the rx queue level
1444  *
1445  * @param port_id
1446  *   The port identifier of the Ethernet device.
1447  * @param rx_queue_id
1448  *   The index of the receive queue for which a queue stats mapping is required.
1449  *   The value must be in the range [0, nb_rx_queue - 1] previously supplied
1450  *   to rte_eth_dev_configure().
1451  * @param on
1452  *   If 1, Enable VLAN Stripping of the receive queue of the Ethernet port.
1453  *   If 0, Disable VLAN Stripping of the receive queue of the Ethernet port.
1454  * @return
1455  *   - (0) if successful.
1456  *   - (-ENOSUP) if hardware-assisted VLAN stripping not configured.
1457  *   - (-ENODEV) if *port_id* invalid.
1458  *   - (-EINVAL) if *rx_queue_id* invalid.
1459  */
1460 extern int rte_eth_dev_set_vlan_strip_on_queue(uint8_t port_id,
1461                 uint16_t rx_queue_id, int on);
1462
1463 /**
1464  * Set the Outer VLAN Ether Type by an Ethernet device, it can be inserted to
1465  * the VLAN Header. This is a register setup available on some Intel NIC, not
1466  * but all, please check the data sheet for availability.
1467  *
1468  * @param port_id
1469  *   The port identifier of the Ethernet device.
1470  * @param tag_type
1471  *   The Tag Protocol ID
1472  * @return
1473  *   - (0) if successful.
1474  *   - (-ENOSUP) if hardware-assisted VLAN TPID setup is not supported.
1475  *   - (-ENODEV) if *port_id* invalid.
1476  */
1477 extern int rte_eth_dev_set_vlan_ether_type(uint8_t port_id, uint16_t tag_type);
1478
1479 /**
1480  * Set VLAN offload configuration on an Ethernet device
1481  * Enable/Disable Extended VLAN by an Ethernet device, This is a register setup
1482  * available on some Intel NIC, not but all, please check the data sheet for
1483  * availability.
1484  * Enable/Disable VLAN Strip can be done on rx queue for certain NIC, but here
1485  * the configuration is applied on the port level.
1486  *
1487  * @param port_id
1488  *   The port identifier of the Ethernet device.
1489  * @param offload_mask
1490  *   The VLAN Offload bit mask can be mixed use with "OR"
1491  *       ETH_VLAN_STRIP_OFFLOAD
1492  *       ETH_VLAN_FILTER_OFFLOAD
1493  *       ETH_VLAN_EXTEND_OFFLOAD
1494  * @return
1495  *   - (0) if successful.
1496  *   - (-ENOSUP) if hardware-assisted VLAN filtering not configured.
1497  *   - (-ENODEV) if *port_id* invalid.
1498  */
1499 extern int rte_eth_dev_set_vlan_offload(uint8_t port_id, int offload_mask);
1500
1501 /**
1502  * Read VLAN Offload configuration from an Ethernet device
1503  *
1504  * @param port_id
1505  *   The port identifier of the Ethernet device.
1506  * @return
1507  *   - (>0) if successful. Bit mask to indicate
1508  *       ETH_VLAN_STRIP_OFFLOAD
1509  *       ETH_VLAN_FILTER_OFFLOAD
1510  *       ETH_VLAN_EXTEND_OFFLOAD
1511  *   - (-ENODEV) if *port_id* invalid.
1512  */
1513 extern int rte_eth_dev_get_vlan_offload(uint8_t port_id);
1514
1515 /**
1516  *
1517  * Retrieve a burst of input packets from a receive queue of an Ethernet
1518  * device. The retrieved packets are stored in *rte_mbuf* structures whose
1519  * pointers are supplied in the *rx_pkts* array.
1520  *
1521  * The rte_eth_rx_burst() function loops, parsing the RX ring of the
1522  * receive queue, up to *nb_pkts* packets, and for each completed RX
1523  * descriptor in the ring, it performs the following operations:
1524  *
1525  * - Initialize the *rte_mbuf* data structure associated with the
1526  *   RX descriptor according to the information provided by the NIC into
1527  *   that RX descriptor.
1528  *
1529  * - Store the *rte_mbuf* data structure into the next entry of the
1530  *   *rx_pkts* array.
1531  *
1532  * - Replenish the RX descriptor with a new *rte_mbuf* buffer
1533  *   allocated from the memory pool associated with the receive queue at
1534  *   initialization time.
1535  *
1536  * When retrieving an input packet that was scattered by the controller
1537  * into multiple receive descriptors, the rte_eth_rx_burst() function
1538  * appends the associated *rte_mbuf* buffers to the first buffer of the
1539  * packet.
1540  *
1541  * The rte_eth_rx_burst() function returns the number of packets
1542  * actually retrieved, which is the number of *rte_mbuf* data structures
1543  * effectively supplied into the *rx_pkts* array.
1544  * A return value equal to *nb_pkts* indicates that the RX queue contained
1545  * at least *rx_pkts* packets, and this is likely to signify that other
1546  * received packets remain in the input queue. Applications implementing
1547  * a "retrieve as much received packets as possible" policy can check this
1548  * specific case and keep invoking the rte_eth_rx_burst() function until
1549  * a value less than *nb_pkts* is returned.
1550  *
1551  * This receive method has the following advantages:
1552  *
1553  * - It allows a run-to-completion network stack engine to retrieve and
1554  *   to immediately process received packets in a fast burst-oriented
1555  *   approach, avoiding the overhead of unnecessary intermediate packet
1556  *   queue/dequeue operations.
1557  *
1558  * - Conversely, it also allows an asynchronous-oriented processing
1559  *   method to retrieve bursts of received packets and to immediately
1560  *   queue them for further parallel processing by another logical core,
1561  *   for instance. However, instead of having received packets being
1562  *   individually queued by the driver, this approach allows the invoker
1563  *   of the rte_eth_rx_burst() function to queue a burst of retrieved
1564  *   packets at a time and therefore dramatically reduce the cost of
1565  *   enqueue/dequeue operations per packet.
1566  *
1567  * - It allows the rte_eth_rx_burst() function of the driver to take
1568  *   advantage of burst-oriented hardware features (CPU cache,
1569  *   prefetch instructions, and so on) to minimize the number of CPU
1570  *   cycles per packet.
1571  *
1572  * To summarize, the proposed receive API enables many
1573  * burst-oriented optimizations in both synchronous and asynchronous
1574  * packet processing environments with no overhead in both cases.
1575  *
1576  * The rte_eth_rx_burst() function does not provide any error
1577  * notification to avoid the corresponding overhead. As a hint, the
1578  * upper-level application might check the status of the device link once
1579  * being systematically returned a 0 value for a given number of tries.
1580  *
1581  * @param port_id
1582  *   The port identifier of the Ethernet device.
1583  * @param queue_id
1584  *   The index of the receive queue from which to retrieve input packets.
1585  *   The value must be in the range [0, nb_rx_queue - 1] previously supplied
1586  *   to rte_eth_dev_configure().
1587  * @param rx_pkts
1588  *   The address of an array of pointers to *rte_mbuf* structures that
1589  *   must be large enough to store *nb_pkts* pointers in it.
1590  * @param nb_pkts
1591  *   The maximum number of packets to retrieve.
1592  * @return
1593  *   The number of packets actually retrieved, which is the number
1594  *   of pointers to *rte_mbuf* structures effectively supplied to the
1595  *   *rx_pkts* array.
1596  */
1597 #ifdef RTE_LIBRTE_ETHDEV_DEBUG
1598 extern uint16_t rte_eth_rx_burst(uint8_t port_id, uint16_t queue_id,
1599                                  struct rte_mbuf **rx_pkts, uint16_t nb_pkts);
1600 #else
1601 static inline uint16_t
1602 rte_eth_rx_burst(uint8_t port_id, uint16_t queue_id,
1603                  struct rte_mbuf **rx_pkts, uint16_t nb_pkts)
1604 {
1605         struct rte_eth_dev *dev;
1606
1607         dev = &rte_eth_devices[port_id];
1608         return (*dev->rx_pkt_burst)(dev->data->rx_queues[queue_id], rx_pkts, nb_pkts);
1609 }
1610 #endif
1611
1612 /**
1613  * Send a burst of output packets on a transmit queue of an Ethernet device.
1614  *
1615  * The rte_eth_tx_burst() function is invoked to transmit output packets
1616  * on the output queue *queue_id* of the Ethernet device designated by its
1617  * *port_id*.
1618  * The *nb_pkts* parameter is the number of packets to send which are
1619  * supplied in the *tx_pkts* array of *rte_mbuf* structures.
1620  * The rte_eth_tx_burst() function loops, sending *nb_pkts* packets,
1621  * up to the number of transmit descriptors available in the TX ring of the
1622  * transmit queue.
1623  * For each packet to send, the rte_eth_tx_burst() function performs
1624  * the following operations:
1625  *
1626  * - Pick up the next available descriptor in the transmit ring.
1627  *
1628  * - Free the network buffer previously sent with that descriptor, if any.
1629  *
1630  * - Initialize the transmit descriptor with the information provided
1631  *   in the *rte_mbuf data structure.
1632  *
1633  * In the case of a segmented packet composed of a list of *rte_mbuf* buffers,
1634  * the rte_eth_tx_burst() function uses several transmit descriptors
1635  * of the ring.
1636  *
1637  * The rte_eth_tx_burst() function returns the number of packets it
1638  * actually sent. A return value equal to *nb_pkts* means that all packets
1639  * have been sent, and this is likely to signify that other output packets
1640  * could be immediately transmitted again. Applications that implement a
1641  * "send as many packets to transmit as possible" policy can check this
1642  * specific case and keep invoking the rte_eth_tx_burst() function until
1643  * a value less than *nb_pkts* is returned.
1644  *
1645  * It is the responsibility of the rte_eth_tx_burst() function to
1646  * transparently free the memory buffers of packets previously sent.
1647  * This feature is driven by the *tx_free_thresh* value supplied to the
1648  * rte_eth_dev_configure() function at device configuration time.
1649  * When the number of previously sent packets reached the "minimum transmit
1650  * packets to free" threshold, the rte_eth_tx_burst() function must
1651  * [attempt to] free the *rte_mbuf*  buffers of those packets whose
1652  * transmission was effectively completed.
1653  *
1654  * @param port_id
1655  *   The port identifier of the Ethernet device.
1656  * @param queue_id
1657  *   The index of the transmit queue through which output packets must be
1658  *   sent.
1659  *   The value must be in the range [0, nb_tx_queue - 1] previously supplied
1660  *   to rte_eth_dev_configure().
1661  * @param tx_pkts
1662  *   The address of an array of *nb_pkts* pointers to *rte_mbuf* structures
1663  *   which contain the output packets.
1664  * @param nb_pkts
1665  *   The maximum number of packets to transmit.
1666  * @return
1667  *   The number of output packets actually stored in transmit descriptors of
1668  *   the transmit ring. The return value can be less than the value of the
1669  *   *tx_pkts* parameter when the transmit ring is full or has been filled up.
1670  */
1671 #ifdef RTE_LIBRTE_ETHDEV_DEBUG
1672 extern uint16_t rte_eth_tx_burst(uint8_t port_id, uint16_t queue_id,
1673                                  struct rte_mbuf **tx_pkts, uint16_t nb_pkts);
1674 #else
1675 static inline uint16_t
1676 rte_eth_tx_burst(uint8_t port_id, uint16_t queue_id,
1677                  struct rte_mbuf **tx_pkts, uint16_t nb_pkts)
1678 {
1679         struct rte_eth_dev *dev;
1680
1681         dev = &rte_eth_devices[port_id];
1682         return (*dev->tx_pkt_burst)(dev->data->tx_queues[queue_id], tx_pkts, nb_pkts);
1683 }
1684 #endif
1685
1686 /**
1687  * Setup a new signature filter rule on an Ethernet device
1688  *
1689  * @param port_id
1690  *   The port identifier of the Ethernet device.
1691  * @param fdir_filter
1692  *   The pointer to the fdir filter structure describing the signature filter
1693  *   rule.
1694  *   The *rte_fdir_filter* structure includes the values of the different fields
1695  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1696  *   and destination ports, and so on.
1697  * @param rx_queue
1698  *   The index of the RX queue where to store RX packets matching the added
1699  *   signature filter defined in fdir_filter.
1700  * @return
1701  *   - (0) if successful.
1702  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1703  *   - (-ENODEV) if *port_id* invalid.
1704  *   - (-ENOSYS) if the FDIR mode is not configured in signature mode
1705  *               on *port_id*.
1706  *   - (-EINVAL) if the fdir_filter information is not correct.
1707  */
1708 int rte_eth_dev_fdir_add_signature_filter(uint8_t port_id,
1709                                           struct rte_fdir_filter *fdir_filter,
1710                                           uint8_t rx_queue);
1711
1712 /**
1713  * Update a signature filter rule on an Ethernet device.
1714  * If the rule doesn't exits, it is created.
1715  *
1716  * @param port_id
1717  *   The port identifier of the Ethernet device.
1718  * @param fdir_ftr
1719  *   The pointer to the structure describing the signature filter rule.
1720  *   The *rte_fdir_filter* structure includes the values of the different fields
1721  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1722  *   and destination ports, and so on.
1723  * @param rx_queue
1724  *   The index of the RX queue where to store RX packets matching the added
1725  *   signature filter defined in fdir_ftr.
1726  * @return
1727  *   - (0) if successful.
1728  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1729  *   - (-ENODEV) if *port_id* invalid.
1730  *   - (-ENOSYS) if the flow director mode is not configured in signature mode
1731  *     on *port_id*.
1732  *   - (-EINVAL) if the fdir_filter information is not correct.
1733  */
1734 int rte_eth_dev_fdir_update_signature_filter(uint8_t port_id,
1735                                              struct rte_fdir_filter *fdir_ftr,
1736                                              uint8_t rx_queue);
1737
1738 /**
1739  * Remove a signature filter rule on an Ethernet device.
1740  *
1741  * @param port_id
1742  *   The port identifier of the Ethernet device.
1743  * @param fdir_ftr
1744  *   The pointer to the structure describing the signature filter rule.
1745  *   The *rte_fdir_filter* structure includes the values of the different fields
1746  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1747  *   and destination ports, and so on.
1748  * @return
1749  *   - (0) if successful.
1750  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1751  *   - (-ENODEV) if *port_id* invalid.
1752  *   - (-ENOSYS) if the flow director mode is not configured in signature mode
1753  *     on *port_id*.
1754  *   - (-EINVAL) if the fdir_filter information is not correct.
1755  */
1756 int rte_eth_dev_fdir_remove_signature_filter(uint8_t port_id,
1757                                              struct rte_fdir_filter *fdir_ftr);
1758
1759 /**
1760  * Retrieve the flow director information of an Ethernet device.
1761  *
1762  * @param port_id
1763  *   The port identifier of the Ethernet device.
1764  * @param fdir
1765  *   A pointer to a structure of type *rte_eth_dev_fdir* to be filled with
1766  *   the flow director information of the Ethernet device.
1767  * @return
1768  *   - (0) if successful.
1769  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1770  *   - (-ENODEV) if *port_id* invalid.
1771  *   - (-ENOSYS) if the flow director mode is not configured on *port_id*.
1772  */
1773 int rte_eth_dev_fdir_get_infos(uint8_t port_id, struct rte_eth_fdir *fdir);
1774
1775 /**
1776  * Add a new perfect filter rule on an Ethernet device.
1777  *
1778  * @param port_id
1779  *   The port identifier of the Ethernet device.
1780  * @param fdir_filter
1781  *   The pointer to the structure describing the perfect filter rule.
1782  *   The *rte_fdir_filter* structure includes the values of the different fields
1783  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1784  *   and destination ports, and so on.
1785  *   IPv6 are not supported.
1786  * @param soft_id
1787  *    The 16-bit value supplied in the field hash.fdir.id of mbuf for RX
1788  *    packets matching the perfect filter.
1789  * @param rx_queue
1790  *   The index of the RX queue where to store RX packets matching the added
1791  *   perfect filter defined in fdir_filter.
1792  * @param drop
1793  *    If drop is set to 1, matching RX packets are stored into the RX drop
1794  *    queue defined in the rte_fdir_conf.
1795  * @return
1796  *   - (0) if successful.
1797  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1798  *   - (-ENODEV) if *port_id* invalid.
1799  *   - (-ENOSYS) if the flow director mode is not configured in perfect mode
1800  *               on *port_id*.
1801  *   - (-EINVAL) if the fdir_filter information is not correct.
1802  */
1803 int rte_eth_dev_fdir_add_perfect_filter(uint8_t port_id,
1804                                         struct rte_fdir_filter *fdir_filter,
1805                                         uint16_t soft_id, uint8_t rx_queue,
1806                                         uint8_t drop);
1807
1808 /**
1809  * Update a perfect filter rule on an Ethernet device.
1810  * If the rule doesn't exits, it is created.
1811  *
1812  * @param port_id
1813  *   The port identifier of the Ethernet device.
1814  * @param fdir_filter
1815  *   The pointer to the structure describing the perfect filter rule.
1816  *   The *rte_fdir_filter* structure includes the values of the different fields
1817  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1818  *   and destination ports, and so on.
1819  *   IPv6 are not supported.
1820  * @param soft_id
1821  *    The 16-bit value supplied in the field hash.fdir.id of mbuf for RX
1822  *    packets matching the perfect filter.
1823  * @param rx_queue
1824  *   The index of the RX queue where to store RX packets matching the added
1825  *   perfect filter defined in fdir_filter.
1826  * @param drop
1827  *    If drop is set to 1, matching RX packets are stored into the RX drop
1828  *    queue defined in the rte_fdir_conf.
1829  * @return
1830  *   - (0) if successful.
1831  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1832  *   - (-ENODEV) if *port_id* invalid.
1833  *   - (-ENOSYS) if the flow director mode is not configured in perfect mode
1834  *      on *port_id*.
1835  *   - (-EINVAL) if the fdir_filter information is not correct.
1836  */
1837 int rte_eth_dev_fdir_update_perfect_filter(uint8_t port_id,
1838                                            struct rte_fdir_filter *fdir_filter,
1839                                            uint16_t soft_id, uint8_t rx_queue,
1840                                            uint8_t drop);
1841
1842 /**
1843  * Remove a perfect filter rule on an Ethernet device.
1844  *
1845  * @param port_id
1846  *   The port identifier of the Ethernet device.
1847  * @param fdir_filter
1848  *   The pointer to the structure describing the perfect filter rule.
1849  *   The *rte_fdir_filter* structure includes the values of the different fields
1850  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1851  *   and destination ports, and so on.
1852  *   IPv6 are not supported.
1853  * @param soft_id
1854  *    The soft_id value provided when adding/updating the removed filter.
1855  * @return
1856  *   - (0) if successful.
1857  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1858  *   - (-ENODEV) if *port_id* invalid.
1859  *   - (-ENOSYS) if the flow director mode is not configured in perfect mode
1860  *      on *port_id*.
1861  *   - (-EINVAL) if the fdir_filter information is not correct.
1862  */
1863 int rte_eth_dev_fdir_remove_perfect_filter(uint8_t port_id,
1864                                            struct rte_fdir_filter *fdir_filter,
1865                                            uint16_t soft_id);
1866 /**
1867  * Configure globally the masks for flow director mode for an Ethernet device.
1868  * For example, the device can match packets with only the first 24 bits of
1869  * the IPv4 source address.
1870  *
1871  * The following fields can be masked: IPv4 addresses and L4 port numbers.
1872  * The following fields can be either enabled or disabled completely for the
1873  * matching functionality: VLAN ID tag; VLAN Priority + CFI bit; Flexible 2-byte
1874  * tuple.
1875  * IPv6 masks are not supported.
1876  *
1877  * All filters must comply with the masks previously configured.
1878  * For example, with a mask equal to 255.255.255.0 for the source IPv4 address,
1879  * all IPv4 filters must be created with a source IPv4 address that fits the
1880  * "X.X.X.0" format.
1881  *
1882  * This function flushes all filters that have been previously added in
1883  * the device.
1884  *
1885  * @param port_id
1886  *   The port identifier of the Ethernet device.
1887  * @param fdir_mask
1888  *   The pointer to the fdir mask structure describing relevant headers fields
1889  *   and relevant bits to use when matching packets addresses and ports.
1890  *   IPv6 masks are not supported.
1891  * @return
1892  *   - (0) if successful.
1893  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1894  *   - (-ENODEV) if *port_id* invalid.
1895  *   - (-ENOSYS) if the flow director mode is not configured in perfect
1896  *      mode on *port_id*.
1897  *   - (-EINVAL) if the fdir_filter information is not correct
1898  */
1899 int rte_eth_dev_fdir_set_masks(uint8_t port_id,
1900                                struct rte_fdir_masks *fdir_mask);
1901
1902 /**
1903  * The eth device event type for interrupt, and maybe others in the future.
1904  */
1905 enum rte_eth_event_type {
1906         RTE_ETH_EVENT_UNKNOWN,  /**< unknown event type */
1907         RTE_ETH_EVENT_INTR_LSC, /**< lsc interrupt event */
1908         RTE_ETH_EVENT_MAX       /**< max value of this enum */
1909 };
1910
1911 typedef void (*rte_eth_dev_cb_fn)(uint8_t port_id, \
1912                 enum rte_eth_event_type event, void *cb_arg);
1913 /**< user application callback to be registered for interrupts */
1914
1915
1916
1917 /**
1918  * Register a callback function for specific port id.
1919  *
1920  * @param port_id
1921  *  Port id.
1922  * @param event
1923  *  Event interested.
1924  * @param cb_fn
1925  *  User supplied callback function to be called.
1926  * @param cb_arg
1927  *  Pointer to the parameters for the registered callback.
1928  *
1929  * @return
1930  *  - On success, zero.
1931  *  - On failure, a negative value.
1932  */
1933 int rte_eth_dev_callback_register(uint8_t port_id,
1934                         enum rte_eth_event_type event,
1935                 rte_eth_dev_cb_fn cb_fn, void *cb_arg);
1936
1937 /**
1938  * Unregister a callback function for specific port id.
1939  *
1940  * @param port_id
1941  *  Port id.
1942  * @param event
1943  *  Event interested.
1944  * @param cb_fn
1945  *  User supplied callback function to be called.
1946  * @param cb_arg
1947  *  Pointer to the parameters for the registered callback. -1 means to
1948  *  remove all for the same callback address and same event.
1949  *
1950  * @return
1951  *  - On success, zero.
1952  *  - On failure, a negative value.
1953  */
1954 int rte_eth_dev_callback_unregister(uint8_t port_id,
1955                         enum rte_eth_event_type event,
1956                 rte_eth_dev_cb_fn cb_fn, void *cb_arg);
1957
1958 /**
1959  * @internal Executes all the user application registered callbacks for
1960  * the specific device. It is for DPDK internal user only. User
1961  * application should not call it directly.
1962  *
1963  * @param dev
1964  *  Pointer to struct rte_eth_dev.
1965  * @param event
1966  *  Eth device interrupt event type.
1967  *
1968  * @return
1969  *  void
1970  */
1971 void _rte_eth_dev_callback_process(struct rte_eth_dev *dev,
1972                                 enum rte_eth_event_type event);
1973
1974 /**
1975  * Turn on the LED on the Ethernet device.
1976  * This function turns on the LED on the Ethernet device.
1977  *
1978  * @param port_id
1979  *   The port identifier of the Ethernet device.
1980  * @return
1981  *   - (0) if successful.
1982  *   - (-ENOTSUP) if underlying hardware OR driver doesn't support
1983  *     that operation.
1984  *   - (-ENODEV) if *port_id* invalid.
1985  */
1986 int  rte_eth_led_on(uint8_t port_id);
1987
1988 /**
1989  * Turn off the LED on the Ethernet device.
1990  * This function turns off the LED on the Ethernet device.
1991  *
1992  * @param port_id
1993  *   The port identifier of the Ethernet device.
1994  * @return
1995  *   - (0) if successful.
1996  *   - (-ENOTSUP) if underlying hardware OR driver doesn't support
1997  *     that operation.
1998  *   - (-ENODEV) if *port_id* invalid.
1999  */
2000 int  rte_eth_led_off(uint8_t port_id);
2001
2002 /**
2003  * Configure the Ethernet link flow control for Ethernet device
2004  *
2005  * @param port_id
2006  *   The port identifier of the Ethernet device.
2007  * @param fc_conf
2008  *   The pointer to the structure of the flow control parameters.
2009  * @return
2010  *   - (0) if successful.
2011  *   - (-ENOTSUP) if hardware doesn't support flow control mode.
2012  *   - (-ENODEV)  if *port_id* invalid.
2013  *   - (-EINVAL)  if bad parameter
2014  *   - (-EIO)     if flow control setup failure
2015  */
2016 int rte_eth_dev_flow_ctrl_set(uint8_t port_id,
2017                                 struct rte_eth_fc_conf *fc_conf);
2018
2019 /**
2020  * Add a MAC address to an internal array of addresses used to enable whitelist
2021  * filtering to accept packets only if the destination MAC address matches.
2022  *
2023  * @param port
2024  *   The port identifier of the Ethernet device.
2025  * @param mac_addr
2026  *   The MAC address to add.
2027  * @param pool
2028  *   VMDq pool index to associate address with (if VMDq is enabled). If VMDq is
2029  *   not enabled, this should be set to 0.
2030  * @return
2031  *   - (0) if successfully added or *mac_addr" was already added.
2032  *   - (-ENOTSUP) if hardware doesn't support this feature.
2033  *   - (-ENODEV) if *port* is invalid.
2034  *   - (-ENOSPC) if no more MAC addresses can be added.
2035  *   - (-EINVAL) if MAC address is invalid.
2036  */
2037 int rte_eth_dev_mac_addr_add(uint8_t port, struct ether_addr *mac_addr,
2038                                 uint32_t pool);
2039
2040 /**
2041  * Remove a MAC address from the internal array of addresses.
2042  *
2043  * @param port
2044  *   The port identifier of the Ethernet device.
2045  * @param mac_addr
2046  *   MAC address to remove.
2047  * @return
2048  *   - (0) if successful, or *mac_addr* didn't exist.
2049  *   - (-ENOTSUP) if hardware doesn't support.
2050  *   - (-ENODEV) if *port* invalid.
2051  *   - (-EADDRINUSE) if attempting to remove the default MAC address
2052  */
2053 int rte_eth_dev_mac_addr_remove(uint8_t port, struct ether_addr *mac_addr);
2054
2055
2056 #ifdef __cplusplus
2057 }
2058 #endif
2059
2060 #endif /* _RTE_ETHDEV_H_ */