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  *
 120  * Any other configuration will not be stored and will need to be re-entered
 121  * after a call to rte_eth_dev_start().
 122  *
 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 };
 197
 198 /**
 199  * A structure used to retrieve link-level information of an Ethernet port.
 200  */
 201 struct rte_eth_link {
 202         uint16_t link_speed;      /**< ETH_LINK_SPEED_[10, 100, 1000, 10000] */
 203         uint16_t link_duplex;     /**< ETH_LINK_[HALF_DUPLEX, FULL_DUPLEX] */
 204         uint8_t  link_status : 1; /**< 1 -> link up, 0 -> link down */
 205 }__attribute__((aligned(8)));     /**< aligned for atomic64 read/write */
 206
 207 #define ETH_LINK_SPEED_AUTONEG  0       /**< Auto-negotiate link speed. */
 208 #define ETH_LINK_SPEED_10       10      /**< 10 megabits/second. */
 209 #define ETH_LINK_SPEED_100      100     /**< 100 megabits/second. */
 210 #define ETH_LINK_SPEED_1000     1000    /**< 1 gigabits/second. */
 211 #define ETH_LINK_SPEED_10000    10000   /**< 10 gigabits/second. */
 212
 213 #define ETH_LINK_AUTONEG_DUPLEX 0       /**< Auto-negotiate duplex. */
 214 #define ETH_LINK_HALF_DUPLEX    1       /**< Half-duplex connection. */
 215 #define ETH_LINK_FULL_DUPLEX    2       /**< Full-duplex connection. */
 216
 217 /**
 218  * A structure used to configure the ring threshold registers of an RX/TX
 219  * queue for an Ethernet port.
 220  */
 221 struct rte_eth_thresh {
 222         uint8_t pthresh; /**< Ring prefetch threshold. */
 223         uint8_t hthresh; /**< Ring host threshold. */
 224         uint8_t wthresh; /**< Ring writeback threshold. */
 225 };
 226
 227 /**
 228  *  A set of values to identify what method is to be used to route
 229  *  packets to multiple queues.
 230  */
 231 enum rte_eth_rx_mq_mode {
 232         ETH_RSS     = 0,     /**< Default to RSS mode */
 233         ETH_VMDQ_DCB         /**< Use VMDQ+DCB to route traffic to queues */
 234 };
 235
 236 /**
 237  * A structure used to configure the RX features of an Ethernet port.
 238  */
 239 struct rte_eth_rxmode {
 240         /** The multi-queue packet distribution mode to be used, e.g. RSS. */
 241         enum rte_eth_rx_mq_mode mq_mode;
 242         uint32_t max_rx_pkt_len;    /**< Only used if jumbo_frame enabled. */
 243         uint16_t split_hdr_size;    /**< hdr buf size (header_split enabled).*/
 244         uint8_t header_split   : 1, /**< Header Split enable. */
 245                 hw_ip_checksum : 1, /**< IP/UDP/TCP checksum offload enable. */
 246                 hw_vlan_filter : 1, /**< VLAN filter enable. */
 247                 jumbo_frame    : 1, /**< Jumbo Frame Receipt enable. */
 248                 hw_strip_crc   : 1; /**< Enable CRC stripping by hardware. */
 249 };
 250
 251 /**
 252  * A structure used to configure the Receive Side Scaling (RSS) feature
 253  * of an Ethernet port.
 254  * If not NULL, the *rss_key* pointer of the *rss_conf* structure points
 255  * to an array of 40 bytes holding the RSS key to use for hashing specific
 256  * header fields of received packets.
 257  * Otherwise, a default random hash key is used by the device driver.
 258  *
 259  * The *rss_hf* field of the *rss_conf* structure indicates the different
 260  * types of IPv4/IPv6 packets to which the RSS hashing must be applied.
 261  * Supplying an *rss_hf* equal to zero disables the RSS feature.
 262  */
 263 struct rte_eth_rss_conf {
 264         uint8_t  *rss_key;   /**< If not NULL, 40-byte hash key. */
 265         uint16_t rss_hf;     /**< Hash functions to apply - see below. */
 266 };
 267
 268 #define ETH_RSS_IPV4        0x0001 /**< IPv4 packet. */
 269 #define ETH_RSS_IPV4_TCP    0x0002 /**< IPv4/TCP packet. */
 270 #define ETH_RSS_IPV6        0x0004 /**< IPv6 packet. */
 271 #define ETH_RSS_IPV6_EX     0x0008 /**< IPv6 packet with extension headers.*/
 272 #define ETH_RSS_IPV6_TCP    0x0010 /**< IPv6/TCP packet. */
 273 #define ETH_RSS_IPV6_TCP_EX 0x0020 /**< IPv6/TCP with extension headers. */
 274 /* Intel RSS extensions to UDP packets */
 275 #define ETH_RSS_IPV4_UDP    0x0040 /**< IPv4/UDP packet. */
 276 #define ETH_RSS_IPV6_UDP    0x0080 /**< IPv6/UDP packet. */
 277 #define ETH_RSS_IPV6_UDP_EX 0x0100 /**< IPv6/UDP with extension headers. */
 278
 279 /* Definitions used for VMDQ and DCB functionality */
 280 #define ETH_VMDQ_MAX_VLAN_FILTERS   64 /**< Maximum nb. of VMDQ vlan filters. */
 281 #define ETH_DCB_NUM_USER_PRIORITIES 8  /**< Maximum nb. of DCB priorities. */
 282 #define ETH_VMDQ_DCB_NUM_QUEUES     128 /**< Maximum nb. of VMDQ DCB queues. */
 283
 284 /**
 285  * This enum indicates the possible number of queue pools
 286  * in VMDQ+DCB configurations.
 287  */
 288 enum rte_eth_nb_pools {
 289         ETH_16_POOLS = 16, /**< 16 pools with DCB. */
 290         ETH_32_POOLS = 32  /**< 32 pools with DCB. */
 291 };
 292
 293 /**
 294  * A structure used to configure the VMDQ+DCB feature
 295  * of an Ethernet port.
 296  *
 297  * Using this feature, packets are routed to a pool of queues, based
 298  * on the vlan id in the vlan tag, and then to a specific queue within
 299  * that pool, using the user priority vlan tag field.
 300  *
 301  * A default pool may be used, if desired, to route all traffic which
 302  * does not match the vlan filter rules.
 303  */
 304 struct rte_eth_vmdq_dcb_conf {
 305         enum rte_eth_nb_pools nb_queue_pools; /**< With DCB, 16 or 32 pools */
 306         uint8_t enable_default_pool; /**< If non-zero, use a default pool */
 307         uint8_t default_pool; /**< The default pool, if applicable */
 308         uint8_t nb_pool_maps; /**< We can have up to 64 filters/mappings */
 309         struct {
 310                 uint16_t vlan_id; /**< The vlan id of the received frame */
 311                 uint64_t pools;   /**< Bitmask of pools for packet rx */
 312         } pool_map[ETH_VMDQ_MAX_VLAN_FILTERS]; /**< VMDq vlan pool maps. */
 313         uint8_t dcb_queue[ETH_DCB_NUM_USER_PRIORITIES];
 314         /**< Selects a queue in a pool */
 315 };
 316
 317 /**
 318  * A structure used to configure the TX features of an Ethernet port.
 319  * For future extensions.
 320  */
 321 struct rte_eth_txmode {
 322 };
 323
 324 /**
 325  * A structure used to configure an RX ring of an Ethernet port.
 326  */
 327 struct rte_eth_rxconf {
 328         struct rte_eth_thresh rx_thresh; /**< RX ring threshold registers. */
 329         uint16_t rx_free_thresh; /**< Drives the freeing of RX descriptors. */
 330 };
 331
 332 /**
 333  * A structure used to configure a TX ring of an Ethernet port.
 334  */
 335 struct rte_eth_txconf {
 336         struct rte_eth_thresh tx_thresh; /**< TX ring threshold registers. */
 337         uint16_t tx_rs_thresh; /**< Drives the setting of RS bit on TXDs. */
 338         uint16_t tx_free_thresh; /**< Drives the freeing of TX buffers. */
 339 };
 340
 341 /**
 342  * This enum indicates the flow control mode
 343  */
 344 enum rte_eth_fc_mode {
 345         RTE_FC_NONE = 0, /**< Disable flow control. */
 346         RTE_FC_RX_PAUSE, /**< RX pause frame, enable flowctrl on TX side. */
 347         RTE_FC_TX_PAUSE, /**< TX pause frame, enable flowctrl on RX side. */
 348         RTE_FC_FULL      /**< Enable flow control on both side. */
 349 };
 350
 351 /**
 352  * A structure used to configure Ethernet flow control parameter.
 353  * These parameters will be configured into the register of the NIC.
 354  * Please refer to the corresponding data sheet for proper value.
 355  */
 356 struct rte_eth_fc_conf {
 357         uint32_t high_water;  /**< High threshold value to trigger XOFF */
 358         uint32_t low_water;   /**< Low threshold value to trigger XON */
 359         uint16_t pause_time;  /**< Pause quota in the Pause frame */
 360         uint16_t send_xon;    /**< Is XON frame need be sent */
 361         enum rte_eth_fc_mode mode;  /**< Link flow control mode */
 362 };
 363
 364 /**
 365  *  Flow Director setting modes: none (default), signature or perfect.
 366  */
 367 enum rte_fdir_mode {
 368         RTE_FDIR_MODE_NONE      = 0, /**< Disable FDIR support. */
 369         RTE_FDIR_MODE_SIGNATURE,     /**< Enable FDIR signature filter mode. */
 370         RTE_FDIR_MODE_PERFECT,       /**< Enable FDIR perfect filter mode. */
 371 };
 372
 373 /**
 374  *  Memory space that can be configured to store Flow Director filters
 375  *  in the board memory.
 376  */
 377 enum rte_fdir_pballoc_type {
 378         RTE_FDIR_PBALLOC_64K = 0,  /**< 64k. */
 379         RTE_FDIR_PBALLOC_128K,     /**< 128k. */
 380         RTE_FDIR_PBALLOC_256K,     /**< 256k. */
 381 };
 382
 383 /**
 384  *  Select report mode of FDIR hash information in RX descriptors.
 385  */
 386 enum rte_fdir_status_mode {
 387         RTE_FDIR_NO_REPORT_STATUS = 0, /**< Never report FDIR hash. */
 388         RTE_FDIR_REPORT_STATUS, /**< Only report FDIR hash for matching pkts. */
 389         RTE_FDIR_REPORT_STATUS_ALWAYS, /**< Always report FDIR hash. */
 390 };
 391
 392 /**
 393  * A structure used to configure the Flow Director (FDIR) feature
 394  * of an Ethernet port.
 395  *
 396  * If mode is RTE_FDIR_DISABLE, the pballoc value is ignored.
 397  */
 398 struct rte_fdir_conf {
 399         enum rte_fdir_mode mode; /**< Flow Director mode. */
 400         enum rte_fdir_pballoc_type pballoc; /**< Space for FDIR filters. */
 401         enum rte_fdir_status_mode status;  /**< How to report FDIR hash. */
 402         /* Offset of flexbytes field in RX packets (in 16-bit word units). */
 403         uint8_t flexbytes_offset;
 404         /* RX queue of packets matching a "drop" filter in perfect mode. */
 405         uint8_t drop_queue;
 406 };
 407
 408 /**
 409  *  Possible l4type of FDIR filters.
 410  */
 411 enum rte_l4type {
 412         RTE_FDIR_L4TYPE_NONE = 0,       /**< Nnoe. */
 413         RTE_FDIR_L4TYPE_UDP,            /**< UDP. */
 414         RTE_FDIR_L4TYPE_TCP,            /**< TCP. */
 415         RTE_FDIR_L4TYPE_SCTP,           /**< SCTP. */
 416 };
 417
 418 /**
 419  *  Select IPv4 or IPv6 FDIR filters.
 420  */
 421 enum rte_iptype {
 422         RTE_FDIR_IPTYPE_IPV4 = 0,     /**< IPv4. */
 423         RTE_FDIR_IPTYPE_IPV6 ,        /**< IPv6. */
 424 };
 425
 426 /**
 427  *  A structure used to define a FDIR packet filter.
 428  */
 429 struct rte_fdir_filter {
 430         uint16_t flex_bytes; /**< Flex bytes value to match. */
 431         uint16_t vlan_id; /**< VLAN ID value to match, 0 otherwise. */
 432         uint16_t port_src; /**< Source port to match, 0 otherwise. */
 433         uint16_t port_dst; /**< Destination port to match, 0 otherwise. */
 434         union {
 435                 uint32_t ipv4_addr; /**< IPv4 source address to match. */
 436                 uint32_t ipv6_addr[4]; /**< IPv6 source address to match. */
 437         } ip_src; /**< IPv4/IPv6 source address to match (union of above). */
 438         union {
 439                 uint32_t ipv4_addr; /**< IPv4 destination address to match. */
 440                 uint32_t ipv6_addr[4]; /**< IPv6 destination address to match */
 441         } ip_dst; /**< IPv4/IPv6 destination address to match (union of above). */
 442         enum rte_l4type l4type; /**< l4type to match: NONE/UDP/TCP/SCTP. */
 443         enum rte_iptype iptype; /**< IP packet type to match: IPv4 or IPv6. */
 444 };
 445
 446 /**
 447  *  A structure used to configure FDIR masks that are used by the device
 448  *  to match the various fields of RX packet headers.
 449  */
 450 struct rte_fdir_masks {
 451         /** When set to 1, packet l4type is not relevant in filters, and
 452            source and destination port masks must be set to zero. */
 453         uint8_t only_ip_flow;
 454         uint8_t vlan_id; /**< If set to 1, vlan_id is relevant in filters. */
 455         uint8_t vlan_prio; /**< If set to 1, vlan_prio is relevant in filters. */
 456         uint8_t flexbytes; /**< If set to 1, flexbytes is relevant in filters. */
 457         /** Mask of Destination IPv4 Address. All bits set to 1 define the
 458            relevant bits to use in the destination address of an IPv4 packet
 459            when matching it against FDIR filters. */
 460         uint32_t dst_ipv4_mask;
 461         /** Mask of Source IPv4 Address. All bits set to 1 define
 462            the relevant bits to use in the source address of an IPv4 packet
 463            when matching it against FDIR filters. */
 464         uint32_t src_ipv4_mask;
 465         /** Mask of Source IPv6 Address. All bits set to 1 define the
 466            relevant BYTES to use in the source address of an IPv6 packet
 467            when matching it against FDIR filters. */
 468         uint16_t src_ipv6_mask;
 469         /** Mask of Source Port. All bits set to 1 define the relevant
 470            bits to use in the source port of an IP packets when matching it
 471            against FDIR filters. */
 472         uint16_t src_port_mask;
 473         /** Mask of Destination Port. All bits set to 1 define the relevant
 474            bits to use in the destination port of an IP packet when matching it
 475            against FDIR filters. */
 476         uint16_t dst_port_mask;
 477 };
 478
 479 /**
 480  *  A structure used to report the status of the flow director filters in use.
 481  */
 482 struct rte_eth_fdir {
 483         /** Number of filters with collision indication. */
 484         uint16_t collision;
 485         /** Number of free (non programmed) filters. */
 486         uint16_t free;
 487         /** The Lookup hash value of the added filter that updated the value
 488            of the MAXLEN field */
 489         uint16_t maxhash;
 490         /** Longest linked list of filters in the table. */
 491         uint8_t maxlen;
 492         /** Number of added filters. */
 493         uint64_t add;
 494         /** Number of removed filters. */
 495         uint64_t remove;
 496         /** Number of failed added filters (no more space in device). */
 497         uint64_t f_add;
 498         /** Number of failed removed filters. */
 499         uint64_t f_remove;
 500 };
 501
 502 /**
 503  * A structure used to enable/disable specific device interrupts.
 504  */
 505 struct rte_intr_conf {
 506         /** enable/disable lsc interrupt. 0 (default) - disable, 1 enable */
 507         uint16_t lsc;
 508 };
 509
 510 /**
 511  * A structure used to configure an Ethernet port.
 512  * Depending upon the RX multi-queue mode, extra advanced
 513  * configuration settings may be needed.
 514  */
 515 struct rte_eth_conf {
 516         uint16_t link_speed;
 517         /**< ETH_LINK_SPEED_10[0|00|000], or 0 for autonegotation */
 518         uint16_t link_duplex;
 519         /**< ETH_LINK_[HALF_DUPLEX|FULL_DUPLEX], or 0 for autonegotation */
 520         struct rte_eth_rxmode rxmode; /**< Port RX configuration. */
 521         struct rte_eth_txmode txmode; /**< Port TX configuration. */
 522         union {
 523                 struct rte_eth_rss_conf rss_conf; /**< Port RSS configuration */
 524                 struct rte_eth_vmdq_dcb_conf vmdq_dcb_conf;
 525                 /**< Port vmdq+dcb configuration. */
 526         } rx_adv_conf; /**< Port RX filtering configuration (union). */
 527         struct rte_fdir_conf fdir_conf; /**< FDIR configuration. */
 528         struct rte_intr_conf intr_conf; /**< Interrupt mode configuration. */
 529 };
 530
 531 /**
 532  * A structure used to retrieve the contextual information of
 533  * an Ethernet device, such as the controlling driver of the device,
 534  * its PCI context, etc...
 535  */
 536 struct rte_eth_dev_info {
 537         struct rte_pci_device *pci_dev; /**< Device PCI information. */
 538         const char *driver_name; /**< Device Driver name. */
 539         uint32_t min_rx_bufsize; /**< Minimum size of RX buffer. */
 540         uint32_t max_rx_pktlen; /**< Maximum configurable length of RX pkt. */
 541         uint16_t max_rx_queues; /**< Maximum number of RX queues. */
 542         uint16_t max_tx_queues; /**< Maximum number of TX queues. */
 543         uint32_t max_mac_addrs; /**< Maximum number of MAC addresses. */
 544 };
 545
 546 struct rte_eth_dev;
 547 struct igb_rx_queue;
 548 struct igb_tx_queue;
 549
 550 struct rte_eth_dev_callback;
 551 /** @internal Structure to keep track of registered callbacks */
 552 TAILQ_HEAD(rte_eth_dev_cb_list, rte_eth_dev_callback);
 553
 554 /*
 555  * Definitions of all functions exported by an Ethernet driver through the
 556  * the generic structure of type *eth_dev_ops* supplied in the *rte_eth_dev*
 557  * structure associated with an Ethernet device.
 558  */
 559
 560 typedef int  (*eth_dev_configure_t)(struct rte_eth_dev *dev, uint16_t nb_rx_q,
 561                                     uint16_t nb_tx_q);
 562 /**< Ethernet device configuration. */
 563
 564 typedef int  (*eth_dev_start_t)(struct rte_eth_dev *dev);
 565 /**< Function used to start a configured Ethernet device. */
 566
 567 typedef void (*eth_dev_stop_t)(struct rte_eth_dev *dev);
 568 /**< Function used to stop a configured Ethernet device. */
 569
 570 typedef void (*eth_dev_close_t)(struct rte_eth_dev *dev);
 571 /**< @internal Function used to close a configured Ethernet device. */
 572
 573 typedef void (*eth_promiscuous_enable_t)(struct rte_eth_dev *dev);
 574 /**< Function used to enable the RX promiscuous mode of an Ethernet device. */
 575
 576 typedef void (*eth_promiscuous_disable_t)(struct rte_eth_dev *dev);
 577 /**< Function used to disable the RX promiscuous mode of an Ethernet device. */
 578
 579 typedef void (*eth_allmulticast_enable_t)(struct rte_eth_dev *dev);
 580 /**< Enable the receipt of all multicast packets by an Ethernet device. */
 581
 582 typedef void (*eth_allmulticast_disable_t)(struct rte_eth_dev *dev);
 583 /**< Disable the receipt of all multicast packets by an Ethernet device. */
 584
 585 typedef int (*eth_link_update_t)(struct rte_eth_dev *dev,
 586                                 int wait_to_complete);
 587 /**< Get link speed, duplex mode and state (up/down) of an Ethernet device. */
 588
 589 typedef void (*eth_stats_get_t)(struct rte_eth_dev *dev,
 590                                 struct rte_eth_stats *igb_stats);
 591 /**< Get global I/O statistics of an Ethernet device. */
 592
 593 typedef void (*eth_stats_reset_t)(struct rte_eth_dev *dev);
 594 /**< Reset global I/O statistics of an Ethernet device to 0. */
 595
 596 typedef void (*eth_dev_infos_get_t)(struct rte_eth_dev *dev,
 597                                     struct rte_eth_dev_info *dev_info);
 598 /**< Get specific informations of an Ethernet device. */
 599
 600 typedef int (*eth_rx_queue_setup_t)(struct rte_eth_dev *dev,
 601                                     uint16_t rx_queue_id,
 602                                     uint16_t nb_rx_desc,
 603                                     unsigned int socket_id,
 604                                     const struct rte_eth_rxconf *rx_conf,
 605                                     struct rte_mempool *mb_pool);
 606 /**< Set up a receive queue of an Ethernet device. */
 607
 608 typedef int (*eth_tx_queue_setup_t)(struct rte_eth_dev *dev,
 609                                     uint16_t tx_queue_id,
 610                                     uint16_t nb_tx_desc,
 611                                     unsigned int socket_id,
 612                                     const struct rte_eth_txconf *tx_conf);
 613 /**< Setup a transmit queue of an Ethernet device. */
 614
 615 typedef void (*vlan_filter_set_t)(struct rte_eth_dev *dev,
 616                                   uint16_t vlan_id,
 617                                   int on);
 618 /**< Enable/Disable filtering of a VLAN Tag Identifier by an Ethernet device. */
 619
 620 typedef uint16_t (*eth_rx_burst_t)(struct igb_rx_queue *rxq,
 621                                    struct rte_mbuf **rx_pkts,
 622                                    uint16_t nb_pkts);
 623 /**< Retrieve input packets from a receive queue of an Ethernet device. */
 624
 625 typedef uint16_t (*eth_tx_burst_t)(struct igb_tx_queue *txq,
 626                                    struct rte_mbuf **tx_pkts,
 627                                    uint16_t nb_pkts);
 628 /**< Send output packets on a transmit queue of an Ethernet device. */
 629
 630 typedef int (*fdir_add_signature_filter_t)(struct rte_eth_dev *dev,
 631                                            struct rte_fdir_filter *fdir_ftr,
 632                                            uint8_t rx_queue);
 633 /**< Setup a new signature filter rule on an Ethernet device */
 634
 635 typedef int (*fdir_update_signature_filter_t)(struct rte_eth_dev *dev,
 636                                               struct rte_fdir_filter *fdir_ftr,
 637                                               uint8_t rx_queue);
 638 /**< Update a signature filter rule on an Ethernet device */
 639
 640 typedef int (*fdir_remove_signature_filter_t)(struct rte_eth_dev *dev,
 641                                               struct rte_fdir_filter *fdir_ftr);
 642 /**< Remove a  signature filter rule on an Ethernet device */
 643
 644 typedef void (*fdir_infos_get_t)(struct rte_eth_dev *dev,
 645                                  struct rte_eth_fdir *fdir);
 646 /**< Get information about fdir status */
 647
 648 typedef int (*fdir_add_perfect_filter_t)(struct rte_eth_dev *dev,
 649                                          struct rte_fdir_filter *fdir_ftr,
 650                                          uint16_t soft_id, uint8_t rx_queue,
 651                                          uint8_t drop);
 652 /**< Setup a new perfect filter rule on an Ethernet device */
 653
 654 typedef int (*fdir_update_perfect_filter_t)(struct rte_eth_dev *dev,
 655                                             struct rte_fdir_filter *fdir_ftr,
 656                                             uint16_t soft_id, uint8_t rx_queue,
 657                                             uint8_t drop);
 658 /**< Update a perfect filter rule on an Ethernet device */
 659
 660 typedef int (*fdir_remove_perfect_filter_t)(struct rte_eth_dev *dev,
 661                                             struct rte_fdir_filter *fdir_ftr,
 662                                             uint16_t soft_id);
 663 /**< Remove a perfect filter rule on an Ethernet device */
 664
 665 typedef int (*fdir_set_masks_t)(struct rte_eth_dev *dev,
 666                                 struct rte_fdir_masks *fdir_masks);
 667 /**< Setup flow director masks on an Ethernet device */
 668
 669 typedef int (*flow_ctrl_set_t)(struct rte_eth_dev *dev,
 670                                 struct rte_eth_fc_conf *fc_conf);
 671 /**< Setup flow control parameter on an Ethernet device */
 672
 673 typedef int (*eth_dev_led_on_t)(struct rte_eth_dev *dev);
 674 /**<  Turn on SW controllable LED on an Ethernet device */
 675
 676 typedef int (*eth_dev_led_off_t)(struct rte_eth_dev *dev);
 677 /**<  Turn off SW controllable LED on an Ethernet device */
 678
 679 typedef void (*eth_mac_addr_remove_t)(struct rte_eth_dev *dev, uint32_t index);
 680 /**< Remove MAC address from receive address register */
 681
 682 typedef void (*eth_mac_addr_add_t)(struct rte_eth_dev *dev,
 683                                   struct ether_addr *mac_addr,
 684                                   uint32_t index,
 685                                   uint32_t vmdq);
 686 /**< Set a MAC address into Receive Address Address Register */
 687
 688 /**
 689  * A structure containing the functions exported by an Ethernet driver.
 690  */
 691 struct eth_dev_ops {
 692         eth_dev_configure_t        dev_configure; /**< Configure device. */
 693         eth_dev_start_t            dev_start;     /**< Start device. */
 694         eth_dev_stop_t             dev_stop;      /**< Stop device. */
 695         eth_dev_close_t            dev_close;     /**< Close device. */
 696         eth_promiscuous_enable_t   promiscuous_enable; /**< Promiscuous ON. */
 697         eth_promiscuous_disable_t  promiscuous_disable;/**< Promiscuous OFF. */
 698         eth_allmulticast_enable_t  allmulticast_enable;/**< RX multicast ON. */
 699         eth_allmulticast_disable_t allmulticast_disable;/**< RX multicast OF. */
 700         eth_link_update_t          link_update;   /**< Get device link state. */
 701         eth_stats_get_t            stats_get;     /**< Get device statistics. */
 702         eth_stats_reset_t          stats_reset;   /**< Reset device statistics. */
 703         eth_dev_infos_get_t        dev_infos_get; /**< Get device info. */
 704         vlan_filter_set_t          vlan_filter_set; /**< Filter VLAN on/off. */
 705         eth_rx_queue_setup_t       rx_queue_setup;/**< Set up device RX queue.*/
 706         eth_tx_queue_setup_t       tx_queue_setup;/**< Set up device TX queue.*/
 707         eth_dev_led_on_t           dev_led_on;    /**< Turn on LED. */
 708         eth_dev_led_off_t          dev_led_off;   /**< Turn off LED. */
 709         flow_ctrl_set_t            flow_ctrl_set; /**< Setup flow control. */
 710         eth_mac_addr_remove_t      mac_addr_remove; /**< Remove MAC address */
 711         eth_mac_addr_add_t         mac_addr_add;  /**< Add a MAC address */
 712
 713         /** Add a signature filter. */
 714         fdir_add_signature_filter_t fdir_add_signature_filter;
 715         /** Update a signature filter. */
 716         fdir_update_signature_filter_t fdir_update_signature_filter;
 717         /** Remove a signature filter. */
 718         fdir_remove_signature_filter_t fdir_remove_signature_filter;
 719         /** Get information about FDIR status. */
 720         fdir_infos_get_t fdir_infos_get;
 721         /** Add a perfect filter. */
 722         fdir_add_perfect_filter_t fdir_add_perfect_filter;
 723         /** Update a perfect filter. */
 724         fdir_update_perfect_filter_t fdir_update_perfect_filter;
 725         /** Remove a perfect filter. */
 726         fdir_remove_perfect_filter_t fdir_remove_perfect_filter;
 727         /** Setup masks for FDIR filtering. */
 728         fdir_set_masks_t fdir_set_masks;
 729 };
 730
 731 /**
 732  * The generic data structure associated with each ethernet device.
 733  *
 734  * Pointers to burst-oriented packet receive and transmit functions are
 735  * located at the beginning of the structure, along with the pointer to
 736  * where all the data elements for the particular device are stored in shared
 737  * memory. This split allows the function pointer and driver data to be per-
 738  * process, while the actual configuration data for the device is shared.
 739  */
 740 struct rte_eth_dev {
 741         eth_rx_burst_t rx_pkt_burst; /**< Pointer to PMD receive function. */
 742         eth_tx_burst_t tx_pkt_burst; /**< Pointer to PMD transmit function. */
 743         struct rte_eth_dev_data *data;  /**< Pointer to device data */
 744         const struct eth_driver *driver;/**< Driver for this device */
 745         struct eth_dev_ops *dev_ops;    /**< Functions exported by PMD */
 746         struct rte_pci_device *pci_dev; /**< PCI info. supplied by probing */
 747         struct rte_eth_dev_cb_list callbacks; /**< User application callbacks */
 748 };
 749
 750 /**
 751  * The data part, with no function pointers, associated with each ethernet device.
 752  *
 753  * This structure is safe to place in shared memory to be common among different
 754  * processes in a multi-process configuration.
 755  */
 756 struct rte_eth_dev_data {
 757         struct igb_rx_queue **rx_queues; /**< Array of pointers to RX queues. */
 758         struct igb_tx_queue **tx_queues; /**< Array of pointers to TX queues. */
 759         uint16_t nb_rx_queues; /**< Number of RX queues. */
 760         uint16_t nb_tx_queues; /**< Number of TX queues. */
 761
 762         void *dev_private;              /**< PMD-specific private data */
 763
 764         struct rte_eth_link dev_link;
 765         /**< Link-level information & status */
 766
 767         struct rte_eth_conf dev_conf;   /**< Configuration applied to device. */
 768         uint16_t max_frame_size;        /**< Default is ETHER_MAX_LEN (1518). */
 769
 770         uint64_t rx_mbuf_alloc_failed; /**< RX ring mbuf allocation failures. */
 771         struct ether_addr* mac_addrs;/**< Device Ethernet Link address. */
 772         uint8_t port_id;           /**< Device [external] port identifier. */
 773         uint8_t promiscuous   : 1, /**< RX promiscuous mode ON(1) / OFF(0). */
 774                 scattered_rx : 1,  /**< RX of scattered packets is ON(1) / OFF(0) */
 775                 all_multicast : 1, /**< RX all multicast mode ON(1) / OFF(0). */
 776                 dev_started : 1;   /**< Device state: STARTED(1) / STOPPED(0). */
 777 };
 778
 779 /**
 780  * The pool of *rte_eth_dev* structures. The size of the pool
 781  * is configured at compile-time in the <rte_ethdev.c> file.
 782  */
 783 extern struct rte_eth_dev rte_eth_devices[];
 784
 785 /**
 786  * Get the total number of Ethernet devices that have been successfully
 787  * initialized by the [matching] Ethernet driver during the PCI probing phase.
 788  * All devices whose port identifier is in the range
 789  * [0,  rte_eth_dev_count() - 1] can be operated on by network applications.
 790  *
 791  * @return
 792  *   - The total number of usable Ethernet devices.
 793  */
 794 extern uint8_t rte_eth_dev_count(void);
 795
 796 struct eth_driver;
 797 /**
 798  * Initialization function of an Ethernet driver invoked for each matching
 799  * Ethernet PCI device detected during the PCI probing phase.
 800  *
 801  * @param eth_drv
 802  *   The pointer to the [matching] Ethernet driver structure supplied by
 803  *   the PMD when it registered itself.
 804  * @param eth_dev
 805  *   The *eth_dev* pointer is the address of the *rte_eth_dev* structure
 806  *   associated with the matching device and which have been [automatically]
 807  *   allocated in the *rte_eth_devices* array.
 808  *   The *eth_dev* structure is supplied to the driver initialization function
 809  *   with the following fields already initialized:
 810  *
 811  *   - *pci_dev*: Holds the pointers to the *rte_pci_device* structure which
 812  *     contains the generic PCI information of the matching device.
 813  *
 814  *   - *dev_private*: Holds a pointer to the device private data structure.
 815  *
 816  *   - *max_frame_size*: Contains the default Ethernet maximum frame length
 817  *     (1518).
 818  *
 819  *   - *port_id*: Contains the port index of the device (actually the index
 820  *     of the *eth_dev* structure in the *rte_eth_devices* array).
 821  *
 822  * @return
 823  *   - 0: Success, the device is properly initialized by the driver.
 824  *        In particular, the driver MUST have set up the *dev_ops* pointer
 825  *        of the *eth_dev* structure.
 826  *   - <0: Error code of the device initialization failure.
 827  */
 828 typedef int (*eth_dev_init_t)(struct eth_driver  *eth_drv,
 829                               struct rte_eth_dev *eth_dev);
 830
 831 /**
 832  * The structure associated with a PMD Ethernet driver.
 833  *
 834  * Each Ethernet driver acts as a PCI driver and is represented by a generic
 835  * *eth_driver* structure that holds:
 836  *
 837  * - An *rte_pci_driver* structure (which must be the first field).
 838  *
 839  * - The *eth_dev_init* function invoked for each matching PCI device.
 840  *
 841  * - The size of the private data to allocate for each matching device.
 842  */
 843 struct eth_driver {
 844         struct rte_pci_driver pci_drv;    /**< The PMD is also a PCI driver. */
 845         eth_dev_init_t eth_dev_init;      /**< Device init function. */
 846         unsigned int dev_private_size;    /**< Size of device private data. */
 847 };
 848
 849 /**
 850  * A function invoked by the initialization function of an Ethernet driver
 851  * to simultaneously register itself as a PCI driver and as an Ethernet
 852  * Poll Mode Driver (PMD).
 853  *
 854  * @param eth_drv
 855  *   The pointer to the *eth_driver* structure associated with
 856  *   the Ethernet driver.
 857  */
 858 extern void rte_eth_driver_register(struct eth_driver *eth_drv);
 859
 860 /**
 861  * The initialization function of the driver for
 862  * Intel(r) IGB Gigabit Ethernet Controller devices.
 863  * This function is invoked once at EAL start time.
 864  * @return
 865  *   0 on success
 866  */
 867 extern int rte_igb_pmd_init(void);
 868
 869 /**
 870  * The initialization function of the driver for 10Gbps Intel IXGBE
 871  * Ethernet devices.
 872  * Invoked once at EAL start time.
 873  * @return
 874  *   0 on success
 875  */
 876 extern int rte_ixgbe_pmd_init(void);
 877
 878 /**
 879  * The initialization function of the driver for 10Gbps Intel IXGBE_VF
 880  * Ethernet devices.
 881  * Invoked once at EAL start time.
 882  * @return
 883  *   0 on success
 884  */
 885 extern int rte_ixgbevf_pmd_init(void);
 886
 887 /**
 888  * Configure an Ethernet device.
 889  * This function must be invoked first before any other function in the
 890  * Ethernet API. This function can also be re-invoked when a device is in the
 891  * stopped state.
 892  *
 893  * @param port_id
 894  *   The port identifier of the Ethernet device to configure.
 895  * @param nb_rx_queue
 896  *   The number of receive queues to set up for the Ethernet device.
 897  * @param nb_tx_queue
 898  *   The number of transmit queues to set up for the Ethernet device.
 899  * @param eth_conf
 900  *   The pointer to the configuration data to be used for the Ethernet device.
 901  *   The *rte_eth_conf* structure includes:
 902  *     -  the hardware offload features to activate, with dedicated fields for
 903  *        each statically configurable offload hardware feature provided by
 904  *        Ethernet devices, such as IP checksum or VLAN tag stripping for
 905  *        example.
 906  *     - the Receive Side Scaling (RSS) configuration when using multiple RX
 907  *         queues per port.
 908  *
 909  *   Embedding all configuration information in a single data structure
 910  *   is the more flexible method that allows the addition of new features
 911  *   without changing the syntax of the API.
 912  * @return
 913  *   - 0: Success, device configured.
 914  *   - <0: Error code returned by the driver configuration function.
 915  */
 916 extern int rte_eth_dev_configure(uint8_t port_id,
 917                                  uint16_t nb_rx_queue,
 918                                  uint16_t nb_tx_queue,
 919                                  const struct rte_eth_conf *eth_conf);
 920
 921 /**
 922  * Allocate and set up a receive queue for an Ethernet device.
 923  *
 924  * The function allocates a contiguous block of memory for *nb_rx_desc*
 925  * receive descriptors from a memory zone associated with *socket_id*
 926  * and initializes each receive descriptor with a network buffer allocated
 927  * from the memory pool *mb_pool*.
 928  *
 929  * @param port_id
 930  *   The port identifier of the Ethernet device.
 931  * @param rx_queue_id
 932  *   The index of the receive queue to set up.
 933  *   The value must be in the range [0, nb_rx_queue - 1] previously supplied
 934  *   to rte_eth_dev_configure().
 935  * @param nb_rx_desc
 936  *   The number of receive descriptors to allocate for the receive ring.
 937  * @param socket_id
 938  *   The *socket_id* argument is the socket identifier in case of NUMA.
 939  *   The value can be *SOCKET_ID_ANY* if there is no NUMA constraint for
 940  *   the DMA memory allocated for the receive descriptors of the ring.
 941  * @param rx_conf
 942  *   The pointer to the configuration data to be used for the receive queue.
 943  *   The *rx_conf* structure contains an *rx_thresh* structure with the values
 944  *   of the Prefetch, Host, and Write-Back threshold registers of the receive
 945  *   ring.
 946  * @param mb_pool
 947  *   The pointer to the memory pool from which to allocate *rte_mbuf* network
 948  *   memory buffers to populate each descriptor of the receive ring.
 949  * @return
 950  *   - 0: Success, receive queue correctly set up.
 951  *   - -EINVAL: The size of network buffers which can be allocated from the
 952  *      memory pool does not fit the various buffer sizes allowed by the
 953  *      device controller.
 954  *   - -ENOMEM: Unable to allocate the receive ring descriptors or to
 955  *      allocate network memory buffers from the memory pool when
 956  *      initializing receive descriptors.
 957  */
 958 extern int rte_eth_rx_queue_setup(uint8_t port_id, uint16_t rx_queue_id,
 959                                   uint16_t nb_rx_desc, unsigned int socket_id,
 960                                   const struct rte_eth_rxconf *rx_conf,
 961                                   struct rte_mempool *mb_pool);
 962
 963 /**
 964  * Allocate and set up a transmit queue for an Ethernet device.
 965  *
 966  * @param port_id
 967  *   The port identifier of the Ethernet device.
 968  * @param tx_queue_id
 969  *   The index of the transmit queue to set up.
 970  *   The value must be in the range [0, nb_tx_queue - 1] previously supplied
 971  *   to rte_eth_dev_configure().
 972  * @param nb_tx_desc
 973  *   The number of transmit descriptors to allocate for the transmit ring.
 974  * @param socket_id
 975  *   The *socket_id* argument is the socket identifier in case of NUMA.
 976  *   Its value can be *SOCKET_ID_ANY* if there is no NUMA constraint for
 977  *   the DMA memory allocated for the transmit descriptors of the ring.
 978  * @param tx_conf
 979  *   The pointer to the configuration data to be used for the transmit queue.
 980  *   The *tx_conf* structure contains the following data:
 981  *   - The *tx_thresh* structure with the values of the Prefetch, Host, and
 982  *     Write-Back threshold registers of the transmit ring.
 983  *     When setting Write-Back threshold to the value greater then zero,
 984  *     *tx_rs_thresh* value should be explicitly set to one.
 985  *   - The *tx_free_thresh* value indicates the [minimum] number of network
 986  *     buffers that must be pending in the transmit ring to trigger their
 987  *     [implicit] freeing by the driver transmit function.
 988  *   - The *tx_rs_thresh* value indicates the [minimum] number of transmit
 989  *     descriptors that must be pending in the transmit ring before setting the
 990  *     RS bit on a descriptor by the driver transmit function.
 991  *     The *tx_rs_thresh* value should be less or equal then
 992  *     *tx_free_thresh* value, and both of them should be less then
 993  *     *nb_tx_desc* - 3.
 994  *
 995  *     Note that setting *tx_free_thresh* or *tx_rs_thresh* value to 0 forces
 996  *     the transmit function to use default values.
 997  * @return
 998  *   - 0: Success, the transmit queue is correctly set up.
 999  *   - -ENOMEM: Unable to allocate the transmit ring descriptors.
1000  */
1001 extern int rte_eth_tx_queue_setup(uint8_t port_id, uint16_t tx_queue_id,
1002                                   uint16_t nb_tx_desc, unsigned int socket_id,
1003                                   const struct rte_eth_txconf *tx_conf);
1004
1005 /**
1006  * Start an Ethernet device.
1007  *
1008  * The device start step is the last one and consists of setting the configured
1009  * offload features and in starting the transmit and the receive units of the
1010  * device.
1011  * On success, all basic functions exported by the Ethernet API (link status,
1012  * receive/transmit, and so on) can be invoked.
1013  *
1014  * @param port_id
1015  *   The port identifier of the Ethernet device.
1016  * @return
1017  *   - 0: Success, Ethernet device started.
1018  *   - <0: Error code of the driver device start function.
1019  */
1020 extern int rte_eth_dev_start(uint8_t port_id);
1021
1022 /**
1023  * Stop an Ethernet device. The device can be restarted with a call to
1024  * rte_eth_dev_start()
1025  *
1026  * @param port_id
1027  *   The port identifier of the Ethernet device.
1028  */
1029 extern void rte_eth_dev_stop(uint8_t port_id);
1030
1031 /**
1032  * Close an Ethernet device. The device cannot be restarted!
1033  *
1034  * @param port_id
1035  *   The port identifier of the Ethernet device.
1036  */
1037 extern void rte_eth_dev_close(uint8_t port_id);
1038
1039 /**
1040  * Enable receipt in promiscuous mode for an Ethernet device.
1041  *
1042  * @param port_id
1043  *   The port identifier of the Ethernet device.
1044  */
1045 extern void rte_eth_promiscuous_enable(uint8_t port_id);
1046
1047 /**
1048  * Disable receipt in promiscuous mode for an Ethernet device.
1049  *
1050  * @param port_id
1051  *   The port identifier of the Ethernet device.
1052  */
1053 extern void rte_eth_promiscuous_disable(uint8_t port_id);
1054
1055 /**
1056  * Return the value of promiscuous mode for an Ethernet device.
1057  *
1058  * @param port_id
1059  *   The port identifier of the Ethernet device.
1060  * @return
1061  *   - (1) if promiscuous is enabled
1062  *   - (0) if promiscuous is disabled.
1063  *   - (-1) on error
1064  */
1065 extern int rte_eth_promiscuous_get(uint8_t port_id);
1066
1067 /**
1068  * Enable the receipt of any multicast frame by an Ethernet device.
1069  *
1070  * @param port_id
1071  *   The port identifier of the Ethernet device.
1072  */
1073 extern void rte_eth_allmulticast_enable(uint8_t port_id);
1074
1075 /**
1076  * Disable the receipt of all multicast frames by an Ethernet device.
1077  *
1078  * @param port_id
1079  *   The port identifier of the Ethernet device.
1080  */
1081 extern void rte_eth_allmulticast_disable(uint8_t port_id);
1082
1083 /**
1084  * Return the value of allmulticast mode for an Ethernet device.
1085  *
1086  * @param port_id
1087  *   The port identifier of the Ethernet device.
1088  * @return
1089  *   - (1) if allmulticast is enabled
1090  *   - (0) if allmulticast is disabled.
1091  *   - (-1) on error
1092  */
1093 extern int rte_eth_allmulticast_get(uint8_t port_id);
1094
1095 /**
1096  * Retrieve the status (ON/OFF), the speed (in Mbps) and the mode (HALF-DUPLEX
1097  * or FULL-DUPLEX) of the physical link of an Ethernet device. It might need
1098  * to wait up to 9 seconds in it.
1099  *
1100  * @param port_id
1101  *   The port identifier of the Ethernet device.
1102  * @param link
1103  *   A pointer to an *rte_eth_link* structure to be filled with
1104  *   the status, the speed and the mode of the Ethernet device link.
1105  */
1106 extern void rte_eth_link_get(uint8_t port_id, struct rte_eth_link *link);
1107
1108 /**
1109  * Retrieve the status (ON/OFF), the speed (in Mbps) and the mode (HALF-DUPLEX
1110  * or FULL-DUPLEX) of the physical link of an Ethernet device. It is a no-wait
1111  * version of rte_eth_link_get().
1112  *
1113  * @param port_id
1114  *   The port identifier of the Ethernet device.
1115  * @param link
1116  *   A pointer to an *rte_eth_link* structure to be filled with
1117  *   the status, the speed and the mode of the Ethernet device link.
1118  */
1119 extern void rte_eth_link_get_nowait(uint8_t port_id,
1120                                 struct rte_eth_link *link);
1121
1122 /**
1123  * Retrieve the general I/O statistics of an Ethernet device.
1124  *
1125  * @param port_id
1126  *   The port identifier of the Ethernet device.
1127  * @param stats
1128  *   A pointer to a structure of type *rte_eth_stats* to be filled with
1129  *   the values of device counters for the following set of statistics:
1130  *   - *ipackets* with the total of successfully received packets.
1131  *   - *opackets* with the total of successfully transmitted packets.
1132  *   - *ibytes*   with the total of successfully received bytes.
1133  *   - *obytes*   with the total of successfully transmitted bytes.
1134  *   - *ierrors*  with the total of erroneous received packets.
1135  *   - *oerrors*  with the total of failed transmitted packets.
1136  */
1137 extern void rte_eth_stats_get(uint8_t port_id, struct rte_eth_stats *stats);
1138
1139 /**
1140  * Reset the general I/O statistics of an Ethernet device.
1141  *
1142  * @param port_id
1143  *   The port identifier of the Ethernet device.
1144  */
1145 extern void rte_eth_stats_reset(uint8_t port_id);
1146
1147 /**
1148  * Retrieve the Ethernet address of an Ethernet device.
1149  *
1150  * @param port_id
1151  *   The port identifier of the Ethernet device.
1152  * @param mac_addr
1153  *   A pointer to a structure of type *ether_addr* to be filled with
1154  *   the Ethernet address of the Ethernet device.
1155  */
1156 extern void rte_eth_macaddr_get(uint8_t port_id, struct ether_addr *mac_addr);
1157
1158 /**
1159  * Retrieve the contextual information of an Ethernet device.
1160  *
1161  * @param port_id
1162  *   The port identifier of the Ethernet device.
1163  * @param dev_info
1164  *   A pointer to a structure of type *rte_eth_dev_info* to be filled with
1165  *   the contextual information of the Ethernet device.
1166  */
1167 extern void rte_eth_dev_info_get(uint8_t port_id,
1168                                  struct rte_eth_dev_info *dev_info);
1169
1170 /**
1171  * Enable/Disable hardware filtering by an Ethernet device of received
1172  * VLAN packets tagged with a given VLAN Tag Identifier.
1173  *
1174  * @param port_id
1175  *   The port identifier of the Ethernet device.
1176  * @param vlan_id
1177  *   The VLAN Tag Identifier whose filtering must be enabled or disabled.
1178  * @param on
1179  *   If > 0, enable VLAN filtering of VLAN packets tagged with *vlan_id*.
1180  *   Otherwise, disable VLAN filtering of VLAN packets tagged with *vlan_id*.
1181  * @return
1182  *   - (0) if successful.
1183  *   - (-ENOSUP) if hardware-assisted VLAN filtering not configured.
1184  *   - (-ENODEV) if *port_id* invalid.
1185  *   - (-ENOSYS) if VLAN filtering on *port_id* disabled.
1186  *   - (-EINVAL) if *vlan_id* > 4095.
1187  */
1188 extern int rte_eth_dev_vlan_filter(uint8_t port_id, uint16_t vlan_id, int on);
1189
1190 /**
1191  *
1192  * Retrieve a burst of input packets from a receive queue of an Ethernet
1193  * device. The retrieved packets are stored in *rte_mbuf* structures whose
1194  * pointers are supplied in the *rx_pkts* array.
1195  *
1196  * The rte_eth_rx_burst() function loops, parsing the RX ring of the
1197  * receive queue, up to *nb_pkts* packets, and for each completed RX
1198  * descriptor in the ring, it performs the following operations:
1199  *
1200  * - Initialize the *rte_mbuf* data structure associated with the
1201  *   RX descriptor according to the information provided by the NIC into
1202  *   that RX descriptor.
1203  *
1204  * - Store the *rte_mbuf* data structure into the next entry of the
1205  *   *rx_pkts* array.
1206  *
1207  * - Replenish the RX descriptor with a new *rte_mbuf* buffer
1208  *   allocated from the memory pool associated with the receive queue at
1209  *   initialization time.
1210  *
1211  * When retrieving an input packet that was scattered by the controller
1212  * into multiple receive descriptors, the rte_eth_rx_burst() function
1213  * appends the associated *rte_mbuf* buffers to the first buffer of the
1214  * packet.
1215  *
1216  * The rte_eth_rx_burst() function returns the number of packets
1217  * actually retrieved, which is the number of *rte_mbuf* data structures
1218  * effectively supplied into the *rx_pkts* array.
1219  * A return value equal to *nb_pkts* indicates that the RX queue contained
1220  * at least *rx_pkts* packets, and this is likely to signify that other
1221  * received packets remain in the input queue. Applications implementing
1222  * a "retrieve as much received packets as possible" policy can check this
1223  * specific case and keep invoking the rte_eth_rx_burst() function until
1224  * a value less than *nb_pkts* is returned.
1225  *
1226  * This receive method has the following advantages:
1227  *
1228  * - It allows a run-to-completion network stack engine to retrieve and
1229  *   to immediately process received packets in a fast burst-oriented
1230  *   approach, avoiding the overhead of unnecessary intermediate packet
1231  *   queue/dequeue operations.
1232  *
1233  * - Conversely, it also allows an asynchronous-oriented processing
1234  *   method to retrieve bursts of received packets and to immediately
1235  *   queue them for further parallel processing by another logical core,
1236  *   for instance. However, instead of having received packets being
1237  *   individually queued by the driver, this approach allows the invoker
1238  *   of the rte_eth_rx_burst() function to queue a burst of retrieved
1239  *   packets at a time and therefore dramatically reduce the cost of
1240  *   enqueue/dequeue operations per packet.
1241  *
1242  * - It allows the rte_eth_rx_burst() function of the driver to take
1243  *   advantage of burst-oriented hardware features (CPU cache,
1244  *   prefetch instructions, and so on) to minimize the number of CPU
1245  *   cycles per packet.
1246  *
1247  * To summarize, the proposed receive API enables many
1248  * burst-oriented optimizations in both synchronous and asynchronous
1249  * packet processing environments with no overhead in both cases.
1250  *
1251  * The rte_eth_rx_burst() function does not provide any error
1252  * notification to avoid the corresponding overhead. As a hint, the
1253  * upper-level application might check the status of the device link once
1254  * being systematically returned a 0 value for a given number of tries.
1255  *
1256  * @param port_id
1257  *   The port identifier of the Ethernet device.
1258  * @param queue_id
1259  *   The index of the receive queue from which to retrieve input packets.
1260  *   The value must be in the range [0, nb_rx_queue - 1] previously supplied
1261  *   to rte_eth_dev_configure().
1262  * @param rx_pkts
1263  *   The address of an array of pointers to *rte_mbuf* structures that
1264  *   must be large enough to store *nb_pkts* pointers in it.
1265  * @param nb_pkts
1266  *   The maximum number of packets to retrieve.
1267  * @return
1268  *   The number of packets actually retrieved, which is the number
1269  *   of pointers to *rte_mbuf* structures effectively supplied to the
1270  *   *rx_pkts* array.
1271  */
1272 #ifdef RTE_LIBRTE_ETHDEV_DEBUG
1273 extern uint16_t rte_eth_rx_burst(uint8_t port_id, uint16_t queue_id,
1274                                  struct rte_mbuf **rx_pkts, uint16_t nb_pkts);
1275 #else
1276 static inline uint16_t
1277 rte_eth_rx_burst(uint8_t port_id, uint16_t queue_id,
1278                  struct rte_mbuf **rx_pkts, uint16_t nb_pkts)
1279 {
1280         struct rte_eth_dev *dev;
1281
1282         dev = &rte_eth_devices[port_id];
1283         return (*dev->rx_pkt_burst)(dev->data->rx_queues[queue_id], rx_pkts, nb_pkts);
1284 }
1285 #endif
1286
1287 /**
1288  * Send a burst of output packets on a transmit queue of an Ethernet device.
1289  *
1290  * The rte_eth_tx_burst() function is invoked to transmit output packets
1291  * on the output queue *queue_id* of the Ethernet device designated by its
1292  * *port_id*.
1293  * The *nb_pkts* parameter is the number of packets to send which are
1294  * supplied in the *tx_pkts* array of *rte_mbuf* structures.
1295  * The rte_eth_tx_burst() function loops, sending *nb_pkts* packets,
1296  * up to the number of transmit descriptors available in the TX ring of the
1297  * transmit queue.
1298  * For each packet to send, the rte_eth_tx_burst() function performs
1299  * the following operations:
1300  *
1301  * - Pick up the next available descriptor in the transmit ring.
1302  *
1303  * - Free the network buffer previously sent with that descriptor, if any.
1304  *
1305  * - Initialize the transmit descriptor with the information provided
1306  *   in the *rte_mbuf data structure.
1307  *
1308  * In the case of a segmented packet composed of a list of *rte_mbuf* buffers,
1309  * the rte_eth_tx_burst() function uses several transmit descriptors
1310  * of the ring.
1311  *
1312  * The rte_eth_tx_burst() function returns the number of packets it
1313  * actually sent. A return value equal to *nb_pkts* means that all packets
1314  * have been sent, and this is likely to signify that other output packets
1315  * could be immediately transmitted again. Applications that implement a
1316  * "send as many packets to transmit as possible" policy can check this
1317  * specific case and keep invoking the rte_eth_tx_burst() function until
1318  * a value less than *nb_pkts* is returned.
1319  *
1320  * It is the responsibility of the rte_eth_tx_burst() function to
1321  * transparently free the memory buffers of packets previously sent.
1322  * This feature is driven by the *tx_free_thresh* value supplied to the
1323  * rte_eth_dev_configure() function at device configuration time.
1324  * When the number of previously sent packets reached the "minimum transmit
1325  * packets to free" threshold, the rte_eth_tx_burst() function must
1326  * [attempt to] free the *rte_mbuf*  buffers of those packets whose
1327  * transmission was effectively completed.
1328  *
1329  * @param port_id
1330  *   The port identifier of the Ethernet device.
1331  * @param queue_id
1332  *   The index of the transmit queue through which output packets must be
1333  *   sent.
1334  *   The value must be in the range [0, nb_tx_queue - 1] previously supplied
1335  *   to rte_eth_dev_configure().
1336  * @param tx_pkts
1337  *   The address of an array of *nb_pkts* pointers to *rte_mbuf* structures
1338  *   which contain the output packets.
1339  * @param nb_pkts
1340  *   The maximum number of packets to transmit.
1341  * @return
1342  *   The number of output packets actually stored in transmit descriptors of
1343  *   the transmit ring. The return value can be less than the value of the
1344  *   *tx_pkts* parameter when the transmit ring is full or has been filled up.
1345  */
1346 #ifdef RTE_LIBRTE_ETHDEV_DEBUG
1347 extern uint16_t rte_eth_tx_burst(uint8_t port_id, uint16_t queue_id,
1348                                  struct rte_mbuf **tx_pkts, uint16_t nb_pkts);
1349 #else
1350 static inline uint16_t
1351 rte_eth_tx_burst(uint8_t port_id, uint16_t queue_id,
1352                  struct rte_mbuf **tx_pkts, uint16_t nb_pkts)
1353 {
1354         struct rte_eth_dev *dev;
1355
1356         dev = &rte_eth_devices[port_id];
1357         return (*dev->tx_pkt_burst)(dev->data->tx_queues[queue_id], tx_pkts, nb_pkts);
1358 }
1359 #endif
1360
1361 /**
1362  * Setup a new signature filter rule on an Ethernet device
1363  *
1364  * @param port_id
1365  *   The port identifier of the Ethernet device.
1366  * @param fdir_filter
1367  *   The pointer to the fdir filter structure describing the signature filter
1368  *   rule.
1369  *   The *rte_fdir_filter* structure includes the values of the different fields
1370  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1371  *   and destination ports, and so on.
1372  * @param rx_queue
1373  *   The index of the RX queue where to store RX packets matching the added
1374  *   signature filter defined in fdir_filter.
1375  * @return
1376  *   - (0) if successful.
1377  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1378  *   - (-ENODEV) if *port_id* invalid.
1379  *   - (-ENOSYS) if the FDIR mode is not configured in signature mode
1380  *               on *port_id*.
1381  *   - (-EINVAL) if the fdir_filter information is not correct.
1382  */
1383 int rte_eth_dev_fdir_add_signature_filter(uint8_t port_id,
1384                                           struct rte_fdir_filter *fdir_filter,
1385                                           uint8_t rx_queue);
1386
1387 /**
1388  * Update a signature filter rule on an Ethernet device.
1389  * If the rule doesn't exits, it is created.
1390  *
1391  * @param port_id
1392  *   The port identifier of the Ethernet device.
1393  * @param fdir_ftr
1394  *   The pointer to the structure describing the signature filter rule.
1395  *   The *rte_fdir_filter* structure includes the values of the different fields
1396  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1397  *   and destination ports, and so on.
1398  * @param rx_queue
1399  *   The index of the RX queue where to store RX packets matching the added
1400  *   signature filter defined in fdir_ftr.
1401  * @return
1402  *   - (0) if successful.
1403  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1404  *   - (-ENODEV) if *port_id* invalid.
1405  *   - (-ENOSYS) if the flow director mode is not configured in signature mode
1406  *     on *port_id*.
1407  *   - (-EINVAL) if the fdir_filter information is not correct.
1408  */
1409 int rte_eth_dev_fdir_update_signature_filter(uint8_t port_id,
1410                                              struct rte_fdir_filter *fdir_ftr,
1411                                              uint8_t rx_queue);
1412
1413 /**
1414  * Remove a signature filter rule on an Ethernet device.
1415  *
1416  * @param port_id
1417  *   The port identifier of the Ethernet device.
1418  * @param fdir_ftr
1419  *   The pointer to the structure describing the signature filter rule.
1420  *   The *rte_fdir_filter* structure includes the values of the different fields
1421  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1422  *   and destination ports, and so on.
1423  * @return
1424  *   - (0) if successful.
1425  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1426  *   - (-ENODEV) if *port_id* invalid.
1427  *   - (-ENOSYS) if the flow director mode is not configured in signature mode
1428  *     on *port_id*.
1429  *   - (-EINVAL) if the fdir_filter information is not correct.
1430  */
1431 int rte_eth_dev_fdir_remove_signature_filter(uint8_t port_id,
1432                                              struct rte_fdir_filter *fdir_ftr);
1433
1434 /**
1435  * Retrieve the flow director information of an Ethernet device.
1436  *
1437  * @param port_id
1438  *   The port identifier of the Ethernet device.
1439  * @param fdir
1440  *   A pointer to a structure of type *rte_eth_dev_fdir* to be filled with
1441  *   the flow director information of the Ethernet device.
1442  * @return
1443  *   - (0) if successful.
1444  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1445  *   - (-ENODEV) if *port_id* invalid.
1446  *   - (-ENOSYS) if the flow director mode is not configured on *port_id*.
1447  */
1448 int rte_eth_dev_fdir_get_infos(uint8_t port_id, struct rte_eth_fdir *fdir);
1449
1450 /**
1451  * Add a new perfect filter rule on an Ethernet device.
1452  *
1453  * @param port_id
1454  *   The port identifier of the Ethernet device.
1455  * @param fdir_filter
1456  *   The pointer to the structure describing the perfect filter rule.
1457  *   The *rte_fdir_filter* structure includes the values of the different fields
1458  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1459  *   and destination ports, and so on.
1460  *   IPv6 are not supported.
1461  * @param soft_id
1462  *    The 16-bit value supplied in the field hash.fdir.id of mbuf for RX
1463  *    packets matching the perfect filter.
1464  * @param rx_queue
1465  *   The index of the RX queue where to store RX packets matching the added
1466  *   perfect filter defined in fdir_filter.
1467  * @param drop
1468  *    If drop is set to 1, matching RX packets are stored into the RX drop
1469  *    queue defined in the rte_fdir_conf.
1470  * @return
1471  *   - (0) if successful.
1472  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1473  *   - (-ENODEV) if *port_id* invalid.
1474  *   - (-ENOSYS) if the flow director mode is not configured in perfect mode
1475  *               on *port_id*.
1476  *   - (-EINVAL) if the fdir_filter information is not correct.
1477  */
1478 int rte_eth_dev_fdir_add_perfect_filter(uint8_t port_id,
1479                                         struct rte_fdir_filter *fdir_filter,
1480                                         uint16_t soft_id, uint8_t rx_queue,
1481                                         uint8_t drop);
1482
1483 /**
1484  * Update a perfect filter rule on an Ethernet device.
1485  * If the rule doesn't exits, it is created.
1486  *
1487  * @param port_id
1488  *   The port identifier of the Ethernet device.
1489  * @param fdir_filter
1490  *   The pointer to the structure describing the perfect filter rule.
1491  *   The *rte_fdir_filter* structure includes the values of the different fields
1492  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1493  *   and destination ports, and so on.
1494  *   IPv6 are not supported.
1495  * @param soft_id
1496  *    The 16-bit value supplied in the field hash.fdir.id of mbuf for RX
1497  *    packets matching the perfect filter.
1498  * @param rx_queue
1499  *   The index of the RX queue where to store RX packets matching the added
1500  *   perfect filter defined in fdir_filter.
1501  * @param drop
1502  *    If drop is set to 1, matching RX packets are stored into the RX drop
1503  *    queue defined in the rte_fdir_conf.
1504  * @return
1505  *   - (0) if successful.
1506  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1507  *   - (-ENODEV) if *port_id* invalid.
1508  *   - (-ENOSYS) if the flow director mode is not configured in perfect mode
1509  *      on *port_id*.
1510  *   - (-EINVAL) if the fdir_filter information is not correct.
1511  */
1512 int rte_eth_dev_fdir_update_perfect_filter(uint8_t port_id,
1513                                            struct rte_fdir_filter *fdir_filter,
1514                                            uint16_t soft_id, uint8_t rx_queue,
1515                                            uint8_t drop);
1516
1517 /**
1518  * Remove a perfect filter rule on an Ethernet device.
1519  *
1520  * @param port_id
1521  *   The port identifier of the Ethernet device.
1522  * @param fdir_filter
1523  *   The pointer to the structure describing the perfect filter rule.
1524  *   The *rte_fdir_filter* structure includes the values of the different fields
1525  *   to match: source and destination IP addresses, vlan id, flexbytes, source
1526  *   and destination ports, and so on.
1527  *   IPv6 are not supported.
1528  * @param soft_id
1529  *    The soft_id value provided when adding/updating the removed filter.
1530  * @return
1531  *   - (0) if successful.
1532  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1533  *   - (-ENODEV) if *port_id* invalid.
1534  *   - (-ENOSYS) if the flow director mode is not configured in perfect mode
1535  *      on *port_id*.
1536  *   - (-EINVAL) if the fdir_filter information is not correct.
1537  */
1538 int rte_eth_dev_fdir_remove_perfect_filter(uint8_t port_id,
1539                                            struct rte_fdir_filter *fdir_filter,
1540                                            uint16_t soft_id);
1541 /**
1542  * Configure globally the masks for flow director mode for an Ethernet device.
1543  * For example, the device can match packets with only the first 24 bits of
1544  * the IPv4 source address.
1545  *
1546  * The following fields can be masked: IPv4 addresses and L4 port numbers.
1547  * The following fields can be either enabled or disabled completely for the
1548  * matching functionality: VLAN ID tag; VLAN Priority + CFI bit; Flexible 2-byte
1549  * tuple.
1550  * IPv6 masks are not supported.
1551  *
1552  * All filters must comply with the masks previously configured.
1553  * For example, with a mask equal to 255.255.255.0 for the source IPv4 address,
1554  * all IPv4 filters must be created with a source IPv4 address that fits the
1555  * "X.X.X.0" format.
1556  *
1557  * This function flushes all filters that have been previously added in
1558  * the device.
1559  *
1560  * @param port_id
1561  *   The port identifier of the Ethernet device.
1562  * @param fdir_mask
1563  *   The pointer to the fdir mask structure describing relevant headers fields
1564  *   and relevant bits to use when matching packets addresses and ports.
1565  *   IPv6 masks are not supported.
1566  * @return
1567  *   - (0) if successful.
1568  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1569  *   - (-ENODEV) if *port_id* invalid.
1570  *   - (-ENOSYS) if the flow director mode is not configured in perfect
1571  *      mode on *port_id*.
1572  *   - (-EINVAL) if the fdir_filter information is not correct
1573  */
1574 int rte_eth_dev_fdir_set_masks(uint8_t port_id,
1575                                struct rte_fdir_masks *fdir_mask);
1576
1577 /**
1578  * The eth device event type for interrupt, and maybe others in the future.
1579  */
1580 enum rte_eth_event_type {
1581         RTE_ETH_EVENT_UNKNOWN,  /**< unknown event type */
1582         RTE_ETH_EVENT_INTR_LSC, /**< lsc interrupt event */
1583         RTE_ETH_EVENT_MAX       /**< max value of this enum */
1584 };
1585
1586 typedef void (*rte_eth_dev_cb_fn)(uint8_t port_id, \
1587                 enum rte_eth_event_type event, void *cb_arg);
1588 /**< user application callback to be registered for interrupts */
1589
1590
1591
1592 /**
1593  * Register a callback function for specific port id.
1594  *
1595  * @param port_id
1596  *  Port id.
1597  * @param event
1598  *  Event interested.
1599  * @param cb_fn
1600  *  User supplied callback function to be called.
1601  * @param cb_arg
1602  *  Pointer to the parameters for the registered callback.
1603  *
1604  * @return
1605  *  - On success, zero.
1606  *  - On failure, a negative value.
1607  */
1608 int rte_eth_dev_callback_register(uint8_t port_id,
1609                         enum rte_eth_event_type event,
1610                 rte_eth_dev_cb_fn cb_fn, void *cb_arg);
1611
1612 /**
1613  * Unregister a callback function for specific port id.
1614  *
1615  * @param port_id
1616  *  Port id.
1617  * @param event
1618  *  Event interested.
1619  * @param cb_fn
1620  *  User supplied callback function to be called.
1621  * @param cb_arg
1622  *  Pointer to the parameters for the registered callback. -1 means to
1623  *  remove all for the same callback address and same event.
1624  *
1625  * @return
1626  *  - On success, zero.
1627  *  - On failure, a negative value.
1628  */
1629 int rte_eth_dev_callback_unregister(uint8_t port_id,
1630                         enum rte_eth_event_type event,
1631                 rte_eth_dev_cb_fn cb_fn, void *cb_arg);
1632
1633 /**
1634  * @internal Executes all the user application registered callbacks for
1635  * the specific device. It is for DPDK internal user only. User
1636  * application should not call it directly.
1637  *
1638  * @param dev
1639  *  Pointer to struct rte_eth_dev.
1640  * @param event
1641  *  Eth device interrupt event type.
1642  *
1643  * @return
1644  *  void
1645  */
1646 void _rte_eth_dev_callback_process(struct rte_eth_dev *dev,
1647                                 enum rte_eth_event_type event);
1648
1649 /**
1650  * Turn on the LED on the Ethernet device.
1651  * This function turns on the LED on the Ethernet device.
1652  *
1653  * @param port_id
1654  *   The port identifier of the Ethernet device.
1655  * @return
1656  *   - (0) if successful.
1657  *   - (-ENOTSUP) if underlying hardware OR driver doesn't support
1658  *     that operation.
1659  *   - (-ENODEV) if *port_id* invalid.
1660  */
1661 int  rte_eth_led_on(uint8_t port_id);
1662
1663 /**
1664  * Turn off the LED on the Ethernet device.
1665  * This function turns off the LED on the Ethernet device.
1666  *
1667  * @param port_id
1668  *   The port identifier of the Ethernet device.
1669  * @return
1670  *   - (0) if successful.
1671  *   - (-ENOTSUP) if underlying hardware OR driver doesn't support
1672  *     that operation.
1673  *   - (-ENODEV) if *port_id* invalid.
1674  */
1675 int  rte_eth_led_off(uint8_t port_id);
1676
1677 /**
1678  * Configure the Ethernet link flow control for Ethernet device
1679  *
1680  * @param port_id
1681  *   The port identifier of the Ethernet device.
1682  * @param fc_conf
1683  *   The pointer to the structure of the flow control parameters.
1684  * @return
1685  *   - (0) if successful.
1686  *   - (-ENOTSUP) if hardware doesn't support flow director mode.
1687  *   - (-ENODEV)  if *port_id* invalid.
1688  *   - (-EINVAL)  if bad parameter
1689  *   - (-EIO)     if flow control setup failure
1690  */
1691 int rte_eth_dev_flow_ctrl_set(uint8_t port_id,
1692                                 struct rte_eth_fc_conf *fc_conf);
1693
1694 /**
1695  * Add a MAC address to an internal array of addresses used to enable whitelist
1696  * filtering to accept packets only if the destination MAC address matches.
1697  *
1698  * @param port
1699  *   The port identifier of the Ethernet device.
1700  * @param mac_addr
1701  *   The MAC address to add.
1702  * @param pool
1703  *   VMDq pool index to associate address with (if VMDq is enabled). If VMDq is
1704  *   not enabled, this should be set to 0.
1705  * @return
1706  *   - (0) if successfully added or *mac_addr" was already added.
1707  *   - (-ENOTSUP) if hardware doesn't support this feature.
1708  *   - (-ENODEV) if *port* is invalid.
1709  *   - (-ENOSPC) if no more MAC addresses can be added.
1710  *   - (-EINVAL) if MAC address is invalid.
1711  */
1712 int rte_eth_dev_mac_addr_add(uint8_t port, struct ether_addr *mac_addr,
1713                                 uint32_t pool);
1714
1715 /**
1716  * Remove a MAC address from the internal array of addresses.
1717  *
1718  * @param port
1719  *   The port identifier of the Ethernet device.
1720  * @param mac_addr
1721  *   MAC address to remove.
1722  * @return
1723  *   - (0) if successful, or *mac_addr* didn't exist.
1724  *   - (-ENOTSUP) if hardware doesn't support.
1725  *   - (-ENODEV) if *port* invalid.
1726  *   - (-EADDRINUSE) if attempting to remove the default MAC address
1727  */
1728 int rte_eth_dev_mac_addr_remove(uint8_t port, struct ether_addr *mac_addr);
1729
1730
1731 /*-------------------------- Deprecated definitions --------------------------*/
1732
1733 /* Needed to stop deprecation warnings becoming errors with GCC. */
1734 #ifndef __INTEL_COMPILER
1735 #pragma GCC diagnostic warning "-Wdeprecated-declarations"
1736 #endif
1737
1738 #ifdef RTE_LIBRTE_82576_PMD
1739 #pragma message "\nWARNING: CONFIG_RTE_LIBRTE_82576_PMD is deprecated. " \
1740 "CONFIG_RTE_LIBRTE_IGB_PMD must be set in the config file to use Intel(R) " \
1741 "DPDK supported Gigabit Ethernet Controllers."
1742 #endif
1743
1744 #ifdef RTE_LIBRTE_IGB_PMD
1745 /**
1746  * @deprecated The config file option CONFIG_RTE_LIBRTE_82576_PMD and resulting
1747  * preprocessor define RTE_LIBRTE_82576_PMD are deprecated.
1748  * CONFIG_RTE_LIBRTE_IGB_PMD must be set in the config file to use Intel(R) DPDK
1749  * supported Gigabit Ethernet Controllers, and RTE_LIBRTE_IGB_PMD should be used
1750  * in code.
1751  */
1752 #define RTE_LIBRTE_82576_PMD 1
1753 #endif
1754
1755 /**
1756  * @deprecated rte_82576_pmd_init() is deprecated and will be removed from
1757  * future versions of Intel(R) DPDK. It has been replaced by rte_igb_pmd_init().
1758  *
1759  * @return
1760  *   0 on success
1761  */
1762 static inline int __attribute__((deprecated))
1763 rte_82576_pmd_init(void) {
1764         RTE_LOG(WARNING, PMD, "rte_82576_pmd_init() is deprecated and will be "
1765                         "removed from future version of Intel(R) DPDK. It has "
1766                         "been replaced by rte_igb_pmd_init()");
1767         return rte_igb_pmd_init();
1768 }
1769
1770
1771 #ifdef RTE_LIBRTE_82599_PMD
1772 #pragma message "\nWARNING: CONFIG_RTE_LIBRTE_82599_PMD is deprecated. " \
1773 "CONFIG_RTE_LIBRTE_IXGBE_PMD must be set in the config file to use Intel(R) " \
1774 "DPDK supported 10 Gigabit Ethernet Controllers."
1775 #endif
1776
1777 #ifdef RTE_LIBRTE_IXGBE_PMD
1778 /**
1779  * @deprecated The config file option CONFIG_RTE_LIBRTE_82599_PMD and resulting
1780  * preprocessor define RTE_LIBRTE_82599_PMD are deprecated.
1781  * CONFIG_RTE_LIBRTE_IXGBE_PMD must be set in the config file to use Intel(R)
1782  * DPDK supported Gigabit Ethernet Controllers, and RTE_LIBRTE_IXGBE_PMD should
1783  * be used in code.
1784  */
1785 #define RTE_LIBRTE_82599_PMD 1
1786 #endif
1787
1788 /**
1789  * @deprecated rte_82599_pmd_init() is deprecated and will be removed from
1790  * future versions of Intel(R) DPDK. It has been replaced by
1791  * rte_ixgbe_pmd_init().
1792  *
1793  * @return
1794  *   0 on success
1795  */
1796 static inline int __attribute__((deprecated))
1797 rte_82599_pmd_init(void) {
1798         RTE_LOG(WARNING, PMD, "rte_82599_pmd_init() is deprecated and will be "
1799                         "removed from future version of Intel(R) DPDK. It has "
1800                         "been replaced by rte_ixgbe_pmd_init()");
1801         return rte_ixgbe_pmd_init();
1802 }
1803
1804 #ifdef __cplusplus
1805 }
1806 #endif
1807
1808 #endif /* _RTE_ETHDEV_H_ */