doc/guides/nics/ixgbe.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2016 Intel Corporation.
   3
   4 IXGBE Driver
   5 ============
   6
   7 Vector PMD for IXGBE
   8 --------------------
   9
  10 Vector PMD uses Intel® SIMD instructions to optimize packet I/O.
  11 It improves load/store bandwidth efficiency of L1 data cache by using a wider SSE/AVX register 1 (1).
  12 The wider register gives space to hold multiple packet buffers so as to save instruction number when processing bulk of packets.
  13
  14 There is no change to PMD API. The RX/TX handler are the only two entries for vPMD packet I/O.
  15 They are transparently registered at runtime RX/TX execution if all condition checks pass.
  16
  17 1.  To date, only an SSE version of IX GBE vPMD is available.
  18     To ensure that vPMD is in the binary code, ensure that the option CONFIG_RTE_IXGBE_INC_VECTOR=y is in the configure file.
  19
  20 Some constraints apply as pre-conditions for specific optimizations on bulk packet transfers.
  21 The following sections explain RX and TX constraints in the vPMD.
  22
  23 RX Constraints
  24 ~~~~~~~~~~~~~~
  25
  26 Prerequisites and Pre-conditions
  27 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  28
  29 The following prerequisites apply:
  30
  31 *   To enable vPMD to work for RX, bulk allocation for Rx must be allowed.
  32
  33 Ensure that the following pre-conditions are satisfied:
  34
  35 *   rxq->rx_free_thresh >= RTE_PMD_IXGBE_RX_MAX_BURST
  36
  37 *   rxq->rx_free_thresh < rxq->nb_rx_desc
  38
  39 *   (rxq->nb_rx_desc % rxq->rx_free_thresh) == 0
  40
  41 *   rxq->nb_rx_desc  < (IXGBE_MAX_RING_DESC - RTE_PMD_IXGBE_RX_MAX_BURST)
  42
  43 These conditions are checked in the code.
  44
  45 Scattered packets are not supported in this mode.
  46 If an incoming packet is greater than the maximum acceptable length of one "mbuf" data size (by default, the size is 2 KB),
  47 vPMD for RX would be disabled.
  48
  49 By default, IXGBE_MAX_RING_DESC is set to 4096 and RTE_PMD_IXGBE_RX_MAX_BURST is set to 32.
  50
  51 Feature not Supported by RX Vector PMD
  52 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  53
  54 Some features are not supported when trying to increase the throughput in vPMD.
  55 They are:
  56
  57 *   IEEE1588
  58
  59 *   FDIR
  60
  61 *   Header split
  62
  63 *   RX checksum off load
  64
  65 Other features are supported using optional MACRO configuration. They include:
  66
  67 *   HW VLAN strip
  68
  69 *   HW extend dual VLAN
  70
  71 To guarantee the constraint, configuration flags in dev_conf.rxmode will be checked:
  72
  73 *   hw_vlan_strip
  74
  75 *   hw_vlan_extend
  76
  77 *   hw_ip_checksum
  78
  79 *   header_split
  80
  81 *   dev_conf
  82
  83 fdir_conf->mode will also be checked.
  84
  85 RX Burst Size
  86 ^^^^^^^^^^^^^
  87
  88 As vPMD is focused on high throughput, it assumes that the RX burst size is equal to or greater than 32 per burst.
  89 It returns zero if using nb_pkt < 32 as the expected packet number in the receive handler.
  90
  91 TX Constraint
  92 ~~~~~~~~~~~~~
  93
  94 Prerequisite
  95 ^^^^^^^^^^^^
  96
  97 The only prerequisite is related to tx_rs_thresh.
  98 The tx_rs_thresh value must be greater than or equal to RTE_PMD_IXGBE_TX_MAX_BURST,
  99 but less or equal to RTE_IXGBE_TX_MAX_FREE_BUF_SZ.
 100 Consequently, by default the tx_rs_thresh value is in the range 32 to 64.
 101
 102 Feature not Supported by TX Vector PMD
 103 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 104
 105 TX vPMD only works when txq_flags is set to IXGBE_SIMPLE_FLAGS.
 106
 107 This means that it does not support TX multi-segment, VLAN offload and TX csum offload.
 108 The following MACROs are used for these three features:
 109
 110 *   ETH_TXQ_FLAGS_NOMULTSEGS
 111
 112 *   ETH_TXQ_FLAGS_NOVLANOFFL
 113
 114 *   ETH_TXQ_FLAGS_NOXSUMSCTP
 115
 116 *   ETH_TXQ_FLAGS_NOXSUMUDP
 117
 118 *   ETH_TXQ_FLAGS_NOXSUMTCP
 119
 120 Application Programming Interface
 121 ---------------------------------
 122
 123 In DPDK release v16.11 an API for ixgbe specific functions has been added to the ixgbe PMD.
 124 The declarations for the API functions are in the header ``rte_pmd_ixgbe.h``.
 125
 126 Sample Application Notes
 127 ------------------------
 128
 129 l3fwd
 130 ~~~~~
 131
 132 When running l3fwd with vPMD, there is one thing to note.
 133 In the configuration, ensure that port_conf.rxmode.hw_ip_checksum=0.
 134 Otherwise, by default, RX vPMD is disabled.
 135
 136 load_balancer
 137 ~~~~~~~~~~~~~
 138
 139 As in the case of l3fwd, set configure port_conf.rxmode.hw_ip_checksum=0 to enable vPMD.
 140 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.
 141
 142
 143 Limitations or Known issues
 144 ---------------------------
 145
 146 Malicious Driver Detection not Supported
 147 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 148
 149 The Intel x550 series NICs support a feature called MDD (Malicious
 150 Driver Detection) which checks the behavior of the VF driver.
 151 If this feature is enabled, the VF must use the advanced context descriptor
 152 correctly and set the CC (Check Context) bit.
 153 DPDK PF doesn't support MDD, but kernel PF does. We may hit problem in this
 154 scenario kernel PF + DPDK VF. If user enables MDD in kernel PF, DPDK VF will
 155 not work. Because kernel PF thinks the VF is malicious. But actually it's not.
 156 The only reason is the VF doesn't act as MDD required.
 157 There's significant performance impact to support MDD. DPDK should check if
 158 the advanced context descriptor should be set and set it. And DPDK has to ask
 159 the info about the header length from the upper layer, because parsing the
 160 packet itself is not acceptable. So, it's too expensive to support MDD.
 161 When using kernel PF + DPDK VF on x550, please make sure to use a kernel
 162 PF driver that disables MDD or can disable MDD.
 163
 164 Some kernel drivers already disable MDD by default while some kernels can use
 165 the command ``insmod ixgbe.ko MDD=0,0`` to disable MDD. Each "0" in the
 166 command refers to a port. For example, if there are 6 ixgbe ports, the command
 167 should be changed to ``insmod ixgbe.ko MDD=0,0,0,0,0,0``.
 168
 169
 170 Statistics
 171 ~~~~~~~~~~
 172
 173 The statistics of ixgbe hardware must be polled regularly in order for it to
 174 remain consistent. Running a DPDK application without polling the statistics will
 175 cause registers on hardware to count to the maximum value, and "stick" at
 176 that value.
 177
 178 In order to avoid statistic registers every reaching the maximum value,
 179 read the statistics from the hardware using ``rte_eth_stats_get()`` or
 180 ``rte_eth_xstats_get()``.
 181
 182 The maximum time between statistics polls that ensures consistent results can
 183 be calculated as follows:
 184
 185 .. code-block:: c
 186
 187   max_read_interval = UINT_MAX / max_packets_per_second
 188   max_read_interval = 4294967295 / 14880952
 189   max_read_interval = 288.6218096127183 (seconds)
 190   max_read_interval = ~4 mins 48 sec.
 191
 192 In order to ensure valid results, it is recommended to poll every 4 minutes.
 193
 194 MTU setting
 195 ~~~~~~~~~~~
 196
 197 Although the user can set the MTU separately on PF and VF ports, the ixgbe NIC
 198 only supports one global MTU per physical port.
 199 So when the user sets different MTUs on PF and VF ports in one physical port,
 200 the real MTU for all these PF and VF ports is the largest value set.
 201 This behavior is based on the kernel driver behavior.
 202
 203 VF MAC address setting
 204 ~~~~~~~~~~~~~~~~~~~~~~
 205
 206 On ixgbe, the concept of "pool" can be used for different things depending on
 207 the mode. In VMDq mode, "pool" means a VMDq pool. In IOV mode, "pool" means a
 208 VF.
 209
 210 There is no RTE API to add a VF's MAC address from the PF. On ixgbe, the
 211 ``rte_eth_dev_mac_addr_add()`` function can be used to add a VF's MAC address,
 212 as a workaround.
 213
 214
 215 Inline crypto processing support
 216 --------------------------------
 217
 218 Inline IPsec processing is supported for ``RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO``
 219 mode for ESP packets only:
 220
 221 - ESP authentication only: AES-128-GMAC (128-bit key)
 222 - ESP encryption and authentication: AES-128-GCM (128-bit key)
 223
 224 IPsec Security Gateway Sample Application supports inline IPsec processing for
 225 ixgbe PMD.
 226
 227 For more details see the IPsec Security Gateway Sample Application and Security
 228 library documentation.
 229
 230
 231 Supported Chipsets and NICs
 232 ---------------------------
 233
 234 - Intel 82599EB 10 Gigabit Ethernet Controller
 235 - Intel 82598EB 10 Gigabit Ethernet Controller
 236 - Intel 82599ES 10 Gigabit Ethernet Controller
 237 - Intel 82599EN 10 Gigabit Ethernet Controller
 238 - Intel Ethernet Controller X540-AT2
 239 - Intel Ethernet Controller X550-BT2
 240 - Intel Ethernet Controller X550-AT2
 241 - Intel Ethernet Controller X550-AT
 242 - Intel Ethernet Converged Network Adapter X520-SR1
 243 - Intel Ethernet Converged Network Adapter X520-SR2
 244 - Intel Ethernet Converged Network Adapter X520-LR1
 245 - Intel Ethernet Converged Network Adapter X520-DA1
 246 - Intel Ethernet Converged Network Adapter X520-DA2
 247 - Intel Ethernet Converged Network Adapter X520-DA4
 248 - Intel Ethernet Converged Network Adapter X520-QDA1
 249 - Intel Ethernet Converged Network Adapter X520-T2
 250 - Intel 10 Gigabit AF DA Dual Port Server Adapter
 251 - Intel 10 Gigabit AT Server Adapter
 252 - Intel 10 Gigabit AT2 Server Adapter
 253 - Intel 10 Gigabit CX4 Dual Port Server Adapter
 254 - Intel 10 Gigabit XF LR Server Adapter
 255 - Intel 10 Gigabit XF SR Dual Port Server Adapter
 256 - Intel 10 Gigabit XF SR Server Adapter
 257 - Intel Ethernet Converged Network Adapter X540-T1
 258 - Intel Ethernet Converged Network Adapter X540-T2
 259 - Intel Ethernet Converged Network Adapter X550-T1
 260 - Intel Ethernet Converged Network Adapter X550-T2