1.\"- 2.\" SPDX-License-Identifier: BSD-3-Clause 3.\" 4.\" Copyright (c) 2013-2018, Intel Corporation 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 are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright notice, 11.\" this list of conditions and the following disclaimer. 12.\" 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" 3. Neither the name of the Intel Corporation nor the names of its 18.\" contributors may be used to endorse or promote products derived from 19.\" this software without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 22.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 25.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 26.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 27.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 28.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 29.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 30.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 31.\" POSSIBILITY OF SUCH DAMAGE. 32.\" 33.\" * Other names and brands may be claimed as the property of others. 34.\" 35.Dd May 21, 2024 36.Dt IAVF 4 37.Os 38.Sh NAME 39.Nm iavf 40.Nd "Intel Ethernet Adaptive Virtual Function Driver" 41.Sh SYNOPSIS 42To compile this driver into the kernel, place the following lines in your 43kernel configuration file: 44.Bd -ragged -offset indent 45.Cd "device iflib" 46.Cd "device iavf" 47.Ed 48.Pp 49To load the driver as a module at boot time, place the following lines in 50.Xr loader.conf 5 : 51.Bd -literal -offset indent 52if_iavf_load="YES" 53.Ed 54.Sh DESCRIPTION 55The 56.Nm 57driver provides support for any PCI Virtual Function created from certain 58Intel Ethernet devices. 59This driver is compatible with virtual functions bound to devices based on the 60following: 61.Pp 62.Bl -bullet -compact 63.It 64Intel\(rg Ethernet Controller E810\-C 65.It 66Intel\(rg Ethernet Controller E810\-XXV 67.It 68Intel\(rg Ethernet Connection E822\-C 69.It 70Intel\(rg Ethernet Connection E822\-L 71.It 72Intel\(rg Ethernet Connection E823\-C 73.It 74Intel\(rg Ethernet Connection E823\-L 75.It 76Intel\(rg Ethernet Controller I710 77.It 78Intel\(rg Ethernet Controller X710 79.It 80Intel\(rg Ethernet Controller XL710 81.It 82Intel\(rg Ethernet Network Connection X722 83.It 84Intel\(rg Ethernet Controller XXV710 85.It 86Intel\(rg Ethernet Controller V710 87.El 88.Pp 89The associated Physical Function (PF) drivers for this VF driver are: 90.Pp 91.Bl -bullet -compact 92.It 93.Xr ice 4 94.It 95.Xr ixl 4 96.El 97.Pp 98For questions related to hardware requirements, refer to the documentation 99supplied with your Intel Ethernet Adapter. 100All hardware requirements listed apply to use with 101.Fx . 102.Ss The VF Driver 103The VF driver is normally used in a virtualized environment where a host driver 104manages SR\-IOV, and provides a VF device to the guest. 105.Pp 106In the 107.Fx 108guest, the iavf driver would be loaded and will function using 109the VF device assigned to it. 110.Pp 111The VF driver provides most of the same functionality as the core driver, but 112is actually a subordinate to the host. 113Access to many controls is accomplished by a request to the host via what is 114called the "Admin queue." 115These are startup and initialization events, however; once in operation, the 116device is self\-contained and should achieve near native performance. 117.Pp 118Some notable limitations of the VF environment: 119.Bl -bullet 120.It 121The PF can configure the VF to allow promiscuous mode, using a configuration 122parameter in 123.Xr iovctl.conf 5 ; 124otherwise, promiscuous mode will not work 125.It 126Media info is not available from the PF, so the active media will always be 127displayed as auto in 128.Xr ifconfig 8 129.El 130.Ss Adaptive Virtual Function 131Adaptive Virtual Function (AVF) allows the virtual function driver, or VF, to 132adapt to changing feature sets of the physical function driver (PF) with which 133it is associated. 134This allows system administrators to update a PF without having to update all 135the VFs associated with it. 136All AVFs have a single common device ID and branding string. 137.Pp 138AVFs have a minimum set of features known as "base mode," but may provide 139additional features depending on what features are available in the PF with 140which the AVF is associated. 141The following are base mode features: 142.Bl -bullet -compact 143.It 1444 Queue Pairs (QP) and associated Configuration Status Registers (CSRs) 145for Tx/Rx 146.It 147iavf descriptors and ring format 148.It 149Descriptor write\-back completion 150.It 1511 control queue, with iavf descriptors, CSRs and ring format 152.It 1535 MSI\-X interrupt vectors and corresponding iavf CSRs 154.It 1551 Interrupt Throttle Rate (ITR) index 156.It 1571 Virtual Station Interface (VSI) per VF 158.It 1591 Traffic Class (TC), TC0 160.It 161Receive Side Scaling (RSS) with 64 entry indirection table and key, 162configured through the PF 163.It 1641 unicast MAC address reserved per VF 165.It 1668 MAC address filters for each VF on an Intel\(rg Ethernet 800 Series device 167.It 16816 MAC address filters for each VF on an Intel\(rg Ethernet 700 Series device 169.It 170Stateless offloads \- non\-tunneled checksums 171.It 172AVF device ID 173.It 174HW mailbox is used for VF to PF communications 175.El 176.Sh CONFIGURATION AND TUNING 177.Ss Important System Configuration Changes 178It is important to note that 100G operation can generate high 179numbers of interrupts, often incorrectly being interpreted as 180a storm condition in the kernel. 181It is suggested that this be resolved by setting 182.Va hw.intr_storm_threshold 183to 0. 184.Pp 185The default is 1000. 186.Pp 187Best throughput results are seen with a large MTU; use 9706 if possible. 188The default number of descriptors per ring is 1024. 189Increasing this may improve performance, depending on your use case. 190.Ss Configuring for no iflib 191.Xr iflib 4 192is a common framework for network interface drivers for 193.Fx 194that uses a shared set of sysctl names. 195.Pp 196The default 197.Nm 198driver depends on it, but it can be compiled without it. 199.Ss Jumbo Frames 200Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU) 201to a value larger than the default value of 1500. 202.Pp 203Use the 204.Xr ifconfig 8 205command to increase the MTU size. 206.Pp 207To confirm the MTU used between two specific devices, use 208.Xr route 8 : 209.Bd -literal -offset indent 210route get <destination_IP_address> 211.Ed 212.Pp 213NOTE: 214.Bl -bullet 215.It 216The maximum MTU setting for jumbo frames is 9706. 217This corresponds to the maximum jumbo frame size of 9728 bytes. 218.It 219This driver will attempt to use multiple page-sized buffers to receive 220each jumbo packet. 221This should help to avoid buffer starvation issues when allocating receive 222packets. 223.It 224Packet loss may have a greater impact on throughput when you use jumbo 225frames. 226If you observe a drop in performance after enabling jumbo frames, enabling 227flow control may mitigate the issue. 228.El 229.Ss Checksum Offload 230Checksum offloading supports both TCP and UDP packets and is supported for both 231transmit and receive. 232.Pp 233TSO (TCP Segmentation Offload) supports both IPv4 and IPv6. 234Both of these features are enabled and disabled via 235.Xr ifconfig 8 . 236.Pp 237NOTE: 238.Bl -bullet -compact 239.It 240TSO requires Tx checksum; if Tx checksum is disabled then TSO will also 241be disabled. 242.El 243.Ss LRO 244LRO (Large Receive Offload) may provide Rx performance improvement. 245However, it is incompatible with packet\-forwarding workloads. 246You should carefully evaluate the environment and enable LRO when possible. 247.Ss Rx and Tx Descriptor Rings 248Allows you to set the Rx and Tx descriptor rings independently. 249Set them via these 250.Xr iflib 4 251sysctls: 252.Bl -tag -width indent 253.It dev.iavf.#.iflib.override_nrxds 254.It dev.iavf.#.iflib.override_ntxds 255.El 256.Ss Link\-Level Flow Control (LFC) 257The VF driver does not have access to flow control settings. 258It must be managed from the host side. 259.Sh SEE ALSO 260.Xr arp 4 , 261.Xr ice 4 , 262.Xr iflib 4 , 263.Xr ixl 4 , 264.Xr netintro 4 , 265.Xr vlan 4 , 266.Xr ifconfig 8 267.Pp 268See the 269.Dq Intel\(rg Ethernet Adapters and Devices User Guide 270for additional information on features. 271It is available on the Intel website at either of the following: 272.Bl -bullet 273.It 274.Lk https://cdrdv2.intel.com/v1/dl/getContent/705831 275.It 276.Lk https://www.intel.com/content/www/us/en/download/19373/adapter\-user\-guide\-for\-intel\-ethernet\-adapters.html 277.El 278.Pp 279For information on how to identify your adapter, and for the latest Intel 280network drivers, refer to the Intel Support website: 281.Aq Lk http://www.intel.com/support 282.Sh CAVEATS 283.Ss Driver Buffer Overflow Fix 284The fix to resolve CVE\-2016\-8105, referenced in Intel SA\-00069 285.Aq Lk https://www.intel.com/content/www/us/en/security\-center/advisory/intel\-sa\-00069.html , 286is included in this and future versions of the driver. 287.Ss Network Memory Buffer Allocation 288.Fx 289may have a low number of network memory buffers (mbufs) by default. 290If your mbuf value is too low, it may cause the driver to fail to initialize 291and/or cause the system to become unresponsive. 292You can check to see if the system is mbuf\-starved by running 293.Li "netstat -m" . 294Increase the number of mbufs by editing the lines below in 295.Xr sysctl.conf 5 : 296.Bd -literal -offset indent 297kern.ipc.nmbclusters 298kern.ipc.nmbjumbop 299kern.ipc.nmbjumbo9 300kern.ipc.nmbjumbo16 301kern.ipc.nmbufs 302.Ed 303.Pp 304The amount of memory that you allocate is system specific, and may require 305some trial and error. 306Also, increasing the following in 307.Xr sysctl.conf 5 308could help increase 309network performance: 310.Bd -literal -offset indent 311kern.ipc.maxsockbuf 312net.inet.tcp.sendspace 313net.inet.tcp.recvspace 314net.inet.udp.maxdgram 315net.inet.udp.recvspace 316.Ed 317.Ss UDP Stress Test Dropped Packet Issue 318Under small packet UDP stress with the 319.Nm 320driver, the system may drop UDP packets due to socket buffers being full. 321Setting the PF driver's Flow Control variables to the minimum may resolve the 322issue. 323.Ss Disable LRO when routing/bridging 324LRO must be turned off when forwarding traffic. 325.Sh SUPPORT 326For general information, go to the Intel support website at 327.Aq Lk http://www.intel.com/support/ . 328.Pp 329If an issue is identified with the released source code on a supported kernel 330with a supported adapter, email the specific information related to the issue 331to 332.Aq Mt freebsd@intel.com . 333.Sh LEGAL 334Intel\(rg is a trademark or registered trademark of Intel Corporation 335or its subsidiaries in the United States and / or other countries. 336.Pp 337Other names and brands may be claimed as the property of others. 338.Sh HISTORY 339The 340.Nm 341device driver first appeared in 342.Fx 10.1 343under the name 344.Nm ixlv . 345It was converted to use 346.Xr iflib 4 347and renamed in 348.Fx 12.4 . 349.Sh AUTHORS 350The 351.Nm 352driver was written by the 353.An Intel Corporation Aq Mt freebsd@intel.com 354