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, capabilities in dev_conf.rxmode.offloads will be checked:
  72
  73 *   DEV_RX_OFFLOAD_VLAN_STRIP
  74
  75 *   DEV_RX_OFFLOAD_VLAN_EXTEND
  76
  77 *   DEV_RX_OFFLOAD_CHECKSUM
  78
  79 *   DEV_RX_OFFLOAD_HEADER_SPLIT
  80
  81 *   dev_conf
  82
  83 fdir_conf->mode will also be checked.
  84
  85 VF Runtime Options
  86 ^^^^^^^^^^^^^^^^^^
  87
  88 The following ``devargs`` options can be enabled at runtime. They must
  89 be passed as part of EAL arguments. For example,
  90
  91 .. code-block:: console
  92
  93    testpmd -w af:10.0,pflink_fullchk=1 -- -i
  94
  95 - ``pflink_fullchk`` (default **0**)
  96
  97   When calling ``rte_eth_link_get_nowait()`` to get VF link status,
  98   this option is used to control how VF synchronizes its status with
  99   PF's. If set, VF will not only check the PF's physical link status
 100   by reading related register, but also check the mailbox status. We
 101   call this behavior as fully checking. And checking mailbox will
 102   trigger PF's mailbox interrupt generation. If unset, the application
 103   can get the VF's link status quickly by just reading the PF's link
 104   status register, this will avoid the whole system's mailbox interrupt
 105   generation.
 106
 107   ``rte_eth_link_get()`` will still use the mailbox method regardless
 108   of the pflink_fullchk setting.
 109
 110 RX Burst Size
 111 ^^^^^^^^^^^^^
 112
 113 As vPMD is focused on high throughput, it assumes that the RX burst size is equal to or greater than 32 per burst.
 114 It returns zero if using nb_pkt < 32 as the expected packet number in the receive handler.
 115
 116 TX Constraint
 117 ~~~~~~~~~~~~~
 118
 119 Prerequisite
 120 ^^^^^^^^^^^^
 121
 122 The only prerequisite is related to tx_rs_thresh.
 123 The tx_rs_thresh value must be greater than or equal to RTE_PMD_IXGBE_TX_MAX_BURST,
 124 but less or equal to RTE_IXGBE_TX_MAX_FREE_BUF_SZ.
 125 Consequently, by default the tx_rs_thresh value is in the range 32 to 64.
 126
 127 Feature not Supported by TX Vector PMD
 128 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 129
 130 TX vPMD only works when offloads is set to 0
 131
 132 This means that it does not support any TX offload.
 133
 134 Application Programming Interface
 135 ---------------------------------
 136
 137 In DPDK release v16.11 an API for ixgbe specific functions has been added to the ixgbe PMD.
 138 The declarations for the API functions are in the header ``rte_pmd_ixgbe.h``.
 139
 140 Sample Application Notes
 141 ------------------------
 142
 143 l3fwd
 144 ~~~~~
 145
 146 When running l3fwd with vPMD, there is one thing to note.
 147 In the configuration, ensure that DEV_RX_OFFLOAD_CHECKSUM in port_conf.rxmode.offloads is NOT set.
 148 Otherwise, by default, RX vPMD is disabled.
 149
 150 load_balancer
 151 ~~~~~~~~~~~~~
 152
 153 As in the case of l3fwd, to enable vPMD, do NOT set DEV_RX_OFFLOAD_CHECKSUM in port_conf.rxmode.offloads.
 154 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.
 155
 156
 157 Limitations or Known issues
 158 ---------------------------
 159
 160 Malicious Driver Detection not Supported
 161 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 162
 163 The Intel x550 series NICs support a feature called MDD (Malicious
 164 Driver Detection) which checks the behavior of the VF driver.
 165 If this feature is enabled, the VF must use the advanced context descriptor
 166 correctly and set the CC (Check Context) bit.
 167 DPDK PF doesn't support MDD, but kernel PF does. We may hit problem in this
 168 scenario kernel PF + DPDK VF. If user enables MDD in kernel PF, DPDK VF will
 169 not work. Because kernel PF thinks the VF is malicious. But actually it's not.
 170 The only reason is the VF doesn't act as MDD required.
 171 There's significant performance impact to support MDD. DPDK should check if
 172 the advanced context descriptor should be set and set it. And DPDK has to ask
 173 the info about the header length from the upper layer, because parsing the
 174 packet itself is not acceptable. So, it's too expensive to support MDD.
 175 When using kernel PF + DPDK VF on x550, please make sure to use a kernel
 176 PF driver that disables MDD or can disable MDD.
 177
 178 Some kernel drivers already disable MDD by default while some kernels can use
 179 the command ``insmod ixgbe.ko MDD=0,0`` to disable MDD. Each "0" in the
 180 command refers to a port. For example, if there are 6 ixgbe ports, the command
 181 should be changed to ``insmod ixgbe.ko MDD=0,0,0,0,0,0``.
 182
 183
 184 Statistics
 185 ~~~~~~~~~~
 186
 187 The statistics of ixgbe hardware must be polled regularly in order for it to
 188 remain consistent. Running a DPDK application without polling the statistics will
 189 cause registers on hardware to count to the maximum value, and "stick" at
 190 that value.
 191
 192 In order to avoid statistic registers every reaching the maximum value,
 193 read the statistics from the hardware using ``rte_eth_stats_get()`` or
 194 ``rte_eth_xstats_get()``.
 195
 196 The maximum time between statistics polls that ensures consistent results can
 197 be calculated as follows:
 198
 199 .. code-block:: c
 200
 201   max_read_interval = UINT_MAX / max_packets_per_second
 202   max_read_interval = 4294967295 / 14880952
 203   max_read_interval = 288.6218096127183 (seconds)
 204   max_read_interval = ~4 mins 48 sec.
 205
 206 In order to ensure valid results, it is recommended to poll every 4 minutes.
 207
 208 MTU setting
 209 ~~~~~~~~~~~
 210
 211 Although the user can set the MTU separately on PF and VF ports, the ixgbe NIC
 212 only supports one global MTU per physical port.
 213 So when the user sets different MTUs on PF and VF ports in one physical port,
 214 the real MTU for all these PF and VF ports is the largest value set.
 215 This behavior is based on the kernel driver behavior.
 216
 217 VF MAC address setting
 218 ~~~~~~~~~~~~~~~~~~~~~~
 219
 220 On ixgbe, the concept of "pool" can be used for different things depending on
 221 the mode. In VMDq mode, "pool" means a VMDq pool. In IOV mode, "pool" means a
 222 VF.
 223
 224 There is no RTE API to add a VF's MAC address from the PF. On ixgbe, the
 225 ``rte_eth_dev_mac_addr_add()`` function can be used to add a VF's MAC address,
 226 as a workaround.
 227
 228 X550 does not support legacy interrupt mode
 229 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 230
 231 Description
 232 ^^^^^^^^^^^
 233 X550 cannot get interrupts if using ``uio_pci_generic`` module or using legacy
 234 interrupt mode of ``igb_uio`` or ``vfio``. Because the errata of X550 states
 235 that the Interrupt Status bit is not implemented. The errata is the item #22
 236 from `X550 spec update <https://www.intel.com/content/dam/www/public/us/en/
 237 documents/specification-updates/ethernet-x550-spec-update.pdf>`_
 238
 239 Implication
 240 ^^^^^^^^^^^
 241 When using ``uio_pci_generic`` module or using legacy interrupt mode of
 242 ``igb_uio`` or ``vfio``, the Interrupt Status bit would be checked if the
 243 interrupt is coming. Since the bit is not implemented in X550, the irq cannot
 244 be handled correctly and cannot report the event fd to DPDK apps. Then apps
 245 cannot get interrupts and ``dmesg`` will show messages like ``irq #No.: ``
 246 ``nobody cared.``
 247
 248 Workaround
 249 ^^^^^^^^^^
 250 Do not bind the ``uio_pci_generic`` module in X550 NICs.
 251 Do not bind ``igb_uio`` with legacy mode in X550 NICs.
 252 Before binding ``vfio`` with legacy mode in X550 NICs, use ``modprobe vfio ``
 253 ``nointxmask=1`` to load ``vfio`` module if the intx is not shared with other
 254 devices.
 255
 256 Inline crypto processing support
 257 --------------------------------
 258
 259 Inline IPsec processing is supported for ``RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO``
 260 mode for ESP packets only:
 261
 262 - ESP authentication only: AES-128-GMAC (128-bit key)
 263 - ESP encryption and authentication: AES-128-GCM (128-bit key)
 264
 265 IPsec Security Gateway Sample Application supports inline IPsec processing for
 266 ixgbe PMD.
 267
 268 For more details see the IPsec Security Gateway Sample Application and Security
 269 library documentation.
 270
 271
 272 Virtual Function Port Representors
 273 ----------------------------------
 274 The IXGBE PF PMD supports the creation of VF port representors for the control
 275 and monitoring of IXGBE virtual function devices. Each port representor
 276 corresponds to a single virtual function of that device. Using the ``devargs``
 277 option ``representor`` the user can specify which virtual functions to create
 278 port representors for on initialization of the PF PMD by passing the VF IDs of
 279 the VFs which are required.::
 280
 281   -w DBDF,representor=[0,1,4]
 282
 283 Currently hot-plugging of representor ports is not supported so all required
 284 representors must be specified on the creation of the PF.
 285
 286 Supported Chipsets and NICs
 287 ---------------------------
 288
 289 - Intel 82599EB 10 Gigabit Ethernet Controller
 290 - Intel 82598EB 10 Gigabit Ethernet Controller
 291 - Intel 82599ES 10 Gigabit Ethernet Controller
 292 - Intel 82599EN 10 Gigabit Ethernet Controller
 293 - Intel Ethernet Controller X540-AT2
 294 - Intel Ethernet Controller X550-BT2
 295 - Intel Ethernet Controller X550-AT2
 296 - Intel Ethernet Controller X550-AT
 297 - Intel Ethernet Converged Network Adapter X520-SR1
 298 - Intel Ethernet Converged Network Adapter X520-SR2
 299 - Intel Ethernet Converged Network Adapter X520-LR1
 300 - Intel Ethernet Converged Network Adapter X520-DA1
 301 - Intel Ethernet Converged Network Adapter X520-DA2
 302 - Intel Ethernet Converged Network Adapter X520-DA4
 303 - Intel Ethernet Converged Network Adapter X520-QDA1
 304 - Intel Ethernet Converged Network Adapter X520-T2
 305 - Intel 10 Gigabit AF DA Dual Port Server Adapter
 306 - Intel 10 Gigabit AT Server Adapter
 307 - Intel 10 Gigabit AT2 Server Adapter
 308 - Intel 10 Gigabit CX4 Dual Port Server Adapter
 309 - Intel 10 Gigabit XF LR Server Adapter
 310 - Intel 10 Gigabit XF SR Dual Port Server Adapter
 311 - Intel 10 Gigabit XF SR Server Adapter
 312 - Intel Ethernet Converged Network Adapter X540-T1
 313 - Intel Ethernet Converged Network Adapter X540-T2
 314 - Intel Ethernet Converged Network Adapter X550-T1
 315 - Intel Ethernet Converged Network Adapter X550-T2