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