doc/guides/nics/ixgbe.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2010-2016 Intel Corporation. All rights reserved.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of Intel Corporation nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 IXGBE Driver
  32 ============
  33
  34 Vector PMD for IXGBE
  35 --------------------
  36
  37 Vector PMD uses Intel® SIMD instructions to optimize packet I/O.
  38 It improves load/store bandwidth efficiency of L1 data cache by using a wider SSE/AVX register 1 (1).
  39 The wider register gives space to hold multiple packet buffers so as to save instruction number when processing bulk of packets.
  40
  41 There is no change to PMD API. The RX/TX handler are the only two entries for vPMD packet I/O.
  42 They are transparently registered at runtime RX/TX execution if all condition checks pass.
  43
  44 1.  To date, only an SSE version of IX GBE vPMD is available.
  45     To ensure that vPMD is in the binary code, ensure that the option CONFIG_RTE_IXGBE_INC_VECTOR=y is in the configure file.
  46
  47 Some constraints apply as pre-conditions for specific optimizations on bulk packet transfers.
  48 The following sections explain RX and TX constraints in the vPMD.
  49
  50 RX Constraints
  51 ~~~~~~~~~~~~~~
  52
  53 Prerequisites and Pre-conditions
  54 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  55
  56 The following prerequisites apply:
  57
  58 *   To enable vPMD to work for RX, bulk allocation for Rx must be allowed.
  59
  60 Ensure that the following pre-conditions are satisfied:
  61
  62 *   rxq->rx_free_thresh >= RTE_PMD_IXGBE_RX_MAX_BURST
  63
  64 *   rxq->rx_free_thresh < rxq->nb_rx_desc
  65
  66 *   (rxq->nb_rx_desc % rxq->rx_free_thresh) == 0
  67
  68 *   rxq->nb_rx_desc  < (IXGBE_MAX_RING_DESC - RTE_PMD_IXGBE_RX_MAX_BURST)
  69
  70 These conditions are checked in the code.
  71
  72 Scattered packets are not supported in this mode.
  73 If an incoming packet is greater than the maximum acceptable length of one "mbuf" data size (by default, the size is 2 KB),
  74 vPMD for RX would be disabled.
  75
  76 By default, IXGBE_MAX_RING_DESC is set to 4096 and RTE_PMD_IXGBE_RX_MAX_BURST is set to 32.
  77
  78 Feature not Supported by RX Vector PMD
  79 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  80
  81 Some features are not supported when trying to increase the throughput in vPMD.
  82 They are:
  83
  84 *   IEEE1588
  85
  86 *   FDIR
  87
  88 *   Header split
  89
  90 *   RX checksum off load
  91
  92 Other features are supported using optional MACRO configuration. They include:
  93
  94 *   HW VLAN strip
  95
  96 *   HW extend dual VLAN
  97
  98 *   Enabled by RX_OLFLAGS (RTE_IXGBE_RX_OLFLAGS_ENABLE=y)
  99
 100
 101 To guarantee the constraint, configuration flags in dev_conf.rxmode will be checked:
 102
 103 *   hw_vlan_strip
 104
 105 *   hw_vlan_extend
 106
 107 *   hw_ip_checksum
 108
 109 *   header_split
 110
 111 *   dev_conf
 112
 113 fdir_conf->mode will also be checked.
 114
 115 RX Burst Size
 116 ^^^^^^^^^^^^^
 117
 118 As vPMD is focused on high throughput, it assumes that the RX burst size is equal to or greater than 32 per burst.
 119 It returns zero if using nb_pkt < 32 as the expected packet number in the receive handler.
 120
 121 TX Constraint
 122 ~~~~~~~~~~~~~
 123
 124 Prerequisite
 125 ^^^^^^^^^^^^
 126
 127 The only prerequisite is related to tx_rs_thresh.
 128 The tx_rs_thresh value must be greater than or equal to RTE_PMD_IXGBE_TX_MAX_BURST,
 129 but less or equal to RTE_IXGBE_TX_MAX_FREE_BUF_SZ.
 130 Consequently, by default the tx_rs_thresh value is in the range 32 to 64.
 131
 132 Feature not Supported by RX Vector PMD
 133 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 134
 135 TX vPMD only works when txq_flags is set to IXGBE_SIMPLE_FLAGS.
 136
 137 This means that it does not support TX multi-segment, VLAN offload and TX csum offload.
 138 The following MACROs are used for these three features:
 139
 140 *   ETH_TXQ_FLAGS_NOMULTSEGS
 141
 142 *   ETH_TXQ_FLAGS_NOVLANOFFL
 143
 144 *   ETH_TXQ_FLAGS_NOXSUMSCTP
 145
 146 *   ETH_TXQ_FLAGS_NOXSUMUDP
 147
 148 *   ETH_TXQ_FLAGS_NOXSUMTCP
 149
 150 Application Programming Interface
 151 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 152
 153 In DPDK release v16.11 an API for ixgbe specific functions has been added to the ixgbe PMD.
 154 The declarations for the API functions are in the header ``rte_pmd_ixgbe.h``.
 155
 156 Sample Application Notes
 157 ~~~~~~~~~~~~~~~~~~~~~~~~
 158
 159 testpmd
 160 ^^^^^^^
 161
 162 By default, using CONFIG_RTE_IXGBE_RX_OLFLAGS_ENABLE=y:
 163
 164 .. code-block:: console
 165
 166     ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i --burst=32 --rxfreet=32 --mbcache=250 --txpt=32 --rxht=8 --rxwt=0 --txfreet=32 --txrst=32 --txqflags=0xf01
 167
 168 When CONFIG_RTE_IXGBE_RX_OLFLAGS_ENABLE=n, better performance can be achieved:
 169
 170 .. code-block:: console
 171
 172     ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i --burst=32 --rxfreet=32 --mbcache=250 --txpt=32 --rxht=8 --rxwt=0 --txfreet=32 --txrst=32 --txqflags=0xf01 --disable-hw-vlan
 173
 174 l3fwd
 175 ^^^^^
 176
 177 When running l3fwd with vPMD, there is one thing to note.
 178 In the configuration, ensure that port_conf.rxmode.hw_ip_checksum=0.
 179 Otherwise, by default, RX vPMD is disabled.
 180
 181 load_balancer
 182 ^^^^^^^^^^^^^
 183
 184 As in the case of l3fwd, set configure port_conf.rxmode.hw_ip_checksum=0 to enable vPMD.
 185 In addition, for improved performance, use -bsz "(32,32),(64,64),(32,32)" in load_balancer to avoid using the default burst size of 144.
 186
 187
 188 Malicious Driver Detection not Supported
 189 ----------------------------------------
 190
 191 The Intel x550 series NICs support a feature called MDD (Malicious
 192 Driver Detection) which checks the behavior of the VF driver.
 193 If this feature is enabled, the VF must use the advanced context descriptor
 194 correctly and set the CC (Check Context) bit.
 195 DPDK PF doesn't support MDD, but kernel PF does. We may hit problem in this
 196 scenario kernel PF + DPDK VF. If user enables MDD in kernel PF, DPDK VF will
 197 not work. Because kernel PF thinks the VF is malicious. But actually it's not.
 198 The only reason is the VF doesn't act as MDD required.
 199 There's significant performance impact to support MDD. DPDK should check if
 200 the advanced context descriptor should be set and set it. And DPDK has to ask
 201 the info about the header length from the upper layer, because parsing the
 202 packet itself is not acceptable. So, it's too expensive to support MDD.
 203 When using kernel PF + DPDK VF on x550, please make sure using the kernel
 204 driver that disables MDD or can disable MDD. (Some kernel driver can use
 205 this CLI 'insmod ixgbe.ko MDD=0,0' to disable MDD. Some kernel driver disables
 206 it by default.)
 207
 208
 209 Statistics
 210 ----------
 211
 212 The statistics of ixgbe hardware must be polled regularly in order for it to
 213 remain consistent. Running a DPDK application without polling the statistics will
 214 cause registers on hardware to count to the maximum value, and "stick" at
 215 that value.
 216
 217 In order to avoid statistic registers every reaching the maximum value,
 218 read the statistics from the hardware using ``rte_eth_stats_get()`` or
 219 ``rte_eth_xstats_get()``.
 220
 221 The maximum time between statistics polls that ensures consistent results can
 222 be calculated as follows:
 223
 224 .. code-block:: c
 225
 226   max_read_interval = UINT_MAX / max_packets_per_second
 227   max_read_interval = 4294967295 / 14880952
 228   max_read_interval = 288.6218096127183 (seconds)
 229   max_read_interval = ~4 mins 48 sec.
 230
 231 In order to ensure valid results, it is recommended to poll every 4 minutes.
 232
 233
 234 Supported Chipsets and NICs
 235 ---------------------------
 236
 237 - Intel 82599EB 10 Gigabit Ethernet Controller
 238 - Intel 82598EB 10 Gigabit Ethernet Controller
 239 - Intel 82599ES 10 Gigabit Ethernet Controller
 240 - Intel 82599EN 10 Gigabit Ethernet Controller
 241 - Intel Ethernet Controller X540-AT2
 242 - Intel Ethernet Controller X550-BT2
 243 - Intel Ethernet Controller X550-AT2
 244 - Intel Ethernet Controller X550-AT
 245 - Intel Ethernet Converged Network Adapter X520-SR1
 246 - Intel Ethernet Converged Network Adapter X520-SR2
 247 - Intel Ethernet Converged Network Adapter X520-LR1
 248 - Intel Ethernet Converged Network Adapter X520-DA1
 249 - Intel Ethernet Converged Network Adapter X520-DA2
 250 - Intel Ethernet Converged Network Adapter X520-DA4
 251 - Intel Ethernet Converged Network Adapter X520-QDA1
 252 - Intel Ethernet Converged Network Adapter X520-T2
 253 - Intel 10 Gigabit AF DA Dual Port Server Adapter
 254 - Intel 10 Gigabit AT Server Adapter
 255 - Intel 10 Gigabit AT2 Server Adapter
 256 - Intel 10 Gigabit CX4 Dual Port Server Adapter
 257 - Intel 10 Gigabit XF LR Server Adapter
 258 - Intel 10 Gigabit XF SR Dual Port Server Adapter
 259 - Intel 10 Gigabit XF SR Server Adapter
 260 - Intel Ethernet Converged Network Adapter X540-T1
 261 - Intel Ethernet Converged Network Adapter X540-T2
 262 - Intel Ethernet Converged Network Adapter X550-T1
 263 - Intel Ethernet Converged Network Adapter X550-T2