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 To guarantee the constraint, configuration flags in dev_conf.rxmode will be checked:
  99
 100 *   hw_vlan_strip
 101
 102 *   hw_vlan_extend
 103
 104 *   hw_ip_checksum
 105
 106 *   header_split
 107
 108 *   dev_conf
 109
 110 fdir_conf->mode will also be checked.
 111
 112 RX Burst Size
 113 ^^^^^^^^^^^^^
 114
 115 As vPMD is focused on high throughput, it assumes that the RX burst size is equal to or greater than 32 per burst.
 116 It returns zero if using nb_pkt < 32 as the expected packet number in the receive handler.
 117
 118 TX Constraint
 119 ~~~~~~~~~~~~~
 120
 121 Prerequisite
 122 ^^^^^^^^^^^^
 123
 124 The only prerequisite is related to tx_rs_thresh.
 125 The tx_rs_thresh value must be greater than or equal to RTE_PMD_IXGBE_TX_MAX_BURST,
 126 but less or equal to RTE_IXGBE_TX_MAX_FREE_BUF_SZ.
 127 Consequently, by default the tx_rs_thresh value is in the range 32 to 64.
 128
 129 Feature not Supported by TX Vector PMD
 130 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 131
 132 TX vPMD only works when txq_flags is set to IXGBE_SIMPLE_FLAGS.
 133
 134 This means that it does not support TX multi-segment, VLAN offload and TX csum offload.
 135 The following MACROs are used for these three features:
 136
 137 *   ETH_TXQ_FLAGS_NOMULTSEGS
 138
 139 *   ETH_TXQ_FLAGS_NOVLANOFFL
 140
 141 *   ETH_TXQ_FLAGS_NOXSUMSCTP
 142
 143 *   ETH_TXQ_FLAGS_NOXSUMUDP
 144
 145 *   ETH_TXQ_FLAGS_NOXSUMTCP
 146
 147 Application Programming Interface
 148 ---------------------------------
 149
 150 In DPDK release v16.11 an API for ixgbe specific functions has been added to the ixgbe PMD.
 151 The declarations for the API functions are in the header ``rte_pmd_ixgbe.h``.
 152
 153 Sample Application Notes
 154 ------------------------
 155
 156 l3fwd
 157 ~~~~~
 158
 159 When running l3fwd with vPMD, there is one thing to note.
 160 In the configuration, ensure that port_conf.rxmode.hw_ip_checksum=0.
 161 Otherwise, by default, RX vPMD is disabled.
 162
 163 load_balancer
 164 ~~~~~~~~~~~~~
 165
 166 As in the case of l3fwd, set configure port_conf.rxmode.hw_ip_checksum=0 to enable vPMD.
 167 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.
 168
 169
 170 Limitations or Known issues
 171 ---------------------------
 172
 173 Malicious Driver Detection not Supported
 174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 175
 176 The Intel x550 series NICs support a feature called MDD (Malicious
 177 Driver Detection) which checks the behavior of the VF driver.
 178 If this feature is enabled, the VF must use the advanced context descriptor
 179 correctly and set the CC (Check Context) bit.
 180 DPDK PF doesn't support MDD, but kernel PF does. We may hit problem in this
 181 scenario kernel PF + DPDK VF. If user enables MDD in kernel PF, DPDK VF will
 182 not work. Because kernel PF thinks the VF is malicious. But actually it's not.
 183 The only reason is the VF doesn't act as MDD required.
 184 There's significant performance impact to support MDD. DPDK should check if
 185 the advanced context descriptor should be set and set it. And DPDK has to ask
 186 the info about the header length from the upper layer, because parsing the
 187 packet itself is not acceptable. So, it's too expensive to support MDD.
 188 When using kernel PF + DPDK VF on x550, please make sure to use a kernel
 189 PF driver that disables MDD or can disable MDD.
 190
 191 Some kernel drivers already disable MDD by default while some kernels can use
 192 the command ``insmod ixgbe.ko MDD=0,0`` to disable MDD. Each "0" in the
 193 command refers to a port. For example, if there are 6 ixgbe ports, the command
 194 should be changed to ``insmod ixgbe.ko MDD=0,0,0,0,0,0``.
 195
 196
 197 Statistics
 198 ~~~~~~~~~~
 199
 200 The statistics of ixgbe hardware must be polled regularly in order for it to
 201 remain consistent. Running a DPDK application without polling the statistics will
 202 cause registers on hardware to count to the maximum value, and "stick" at
 203 that value.
 204
 205 In order to avoid statistic registers every reaching the maximum value,
 206 read the statistics from the hardware using ``rte_eth_stats_get()`` or
 207 ``rte_eth_xstats_get()``.
 208
 209 The maximum time between statistics polls that ensures consistent results can
 210 be calculated as follows:
 211
 212 .. code-block:: c
 213
 214   max_read_interval = UINT_MAX / max_packets_per_second
 215   max_read_interval = 4294967295 / 14880952
 216   max_read_interval = 288.6218096127183 (seconds)
 217   max_read_interval = ~4 mins 48 sec.
 218
 219 In order to ensure valid results, it is recommended to poll every 4 minutes.
 220
 221 MTU setting
 222 ~~~~~~~~~~~
 223
 224 Although the user can set the MTU separately on PF and VF ports, the ixgbe NIC
 225 only supports one global MTU per physical port.
 226 So when the user sets different MTUs on PF and VF ports in one physical port,
 227 the real MTU for all these PF and VF ports is the largest value set.
 228 This behavior is based on the kernel driver behavior.
 229
 230 VF MAC address setting
 231 ~~~~~~~~~~~~~~~~~~~~~~
 232
 233 On ixgbe, the concept of "pool" can be used for different things depending on
 234 the mode. In VMDq mode, "pool" means a VMDq pool. In IOV mode, "pool" means a
 235 VF.
 236
 237 There is no RTE API to add a VF's MAC address from the PF. On ixgbe, the
 238 ``rte_eth_dev_mac_addr_add()`` function can be used to add a VF's MAC address,
 239 as a workaround.
 240
 241
 242 Inline crypto processing support
 243 --------------------------------
 244
 245 Inline IPsec processing is supported for ``RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO``
 246 mode for ESP packets only:
 247
 248 - ESP authentication only: AES-128-GMAC (128-bit key)
 249 - ESP encryption and authentication: AES-128-GCM (128-bit key)
 250
 251 IPsec Security Gateway Sample Application supports inline IPsec processing for
 252 ixgbe PMD.
 253
 254 For more details see the IPsec Security Gateway Sample Application and Security
 255 library documentation.
 256
 257
 258 Supported Chipsets and NICs
 259 ---------------------------
 260
 261 - Intel 82599EB 10 Gigabit Ethernet Controller
 262 - Intel 82598EB 10 Gigabit Ethernet Controller
 263 - Intel 82599ES 10 Gigabit Ethernet Controller
 264 - Intel 82599EN 10 Gigabit Ethernet Controller
 265 - Intel Ethernet Controller X540-AT2
 266 - Intel Ethernet Controller X550-BT2
 267 - Intel Ethernet Controller X550-AT2
 268 - Intel Ethernet Controller X550-AT
 269 - Intel Ethernet Converged Network Adapter X520-SR1
 270 - Intel Ethernet Converged Network Adapter X520-SR2
 271 - Intel Ethernet Converged Network Adapter X520-LR1
 272 - Intel Ethernet Converged Network Adapter X520-DA1
 273 - Intel Ethernet Converged Network Adapter X520-DA2
 274 - Intel Ethernet Converged Network Adapter X520-DA4
 275 - Intel Ethernet Converged Network Adapter X520-QDA1
 276 - Intel Ethernet Converged Network Adapter X520-T2
 277 - Intel 10 Gigabit AF DA Dual Port Server Adapter
 278 - Intel 10 Gigabit AT Server Adapter
 279 - Intel 10 Gigabit AT2 Server Adapter
 280 - Intel 10 Gigabit CX4 Dual Port Server Adapter
 281 - Intel 10 Gigabit XF LR Server Adapter
 282 - Intel 10 Gigabit XF SR Dual Port Server Adapter
 283 - Intel 10 Gigabit XF SR Server Adapter
 284 - Intel Ethernet Converged Network Adapter X540-T1
 285 - Intel Ethernet Converged Network Adapter X540-T2
 286 - Intel Ethernet Converged Network Adapter X550-T1
 287 - Intel Ethernet Converged Network Adapter X550-T2