mirror of
https://github.com/freebsd/freebsd-src
synced 2024-09-06 09:10:28 +00:00
ba222f6fb4
MFC after: 3 days Reviewed by: erj Differential Revision: https://reviews.freebsd.org/D43093
354 lines
11 KiB
Groff
354 lines
11 KiB
Groff
.\"-
|
|
.\" SPDX-License-Identifier: BSD-3-Clause
|
|
.\"
|
|
.\" Copyright (c) 2013-2018, Intel Corporation
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions are met:
|
|
.\"
|
|
.\" 1. Redistributions of source code must retain the above copyright notice,
|
|
.\" this list of conditions and the following disclaimer.
|
|
.\"
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" 3. Neither the name of the Intel Corporation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived from
|
|
.\" this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
|
|
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" * Other names and brands may be claimed as the property of others.
|
|
.\"
|
|
.Dd May 21, 2024
|
|
.Dt IAVF 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm iavf
|
|
.Nd "Intel Ethernet Adaptive Virtual Function Driver"
|
|
.Sh SYNOPSIS
|
|
To compile this driver into the kernel, place the following lines in your
|
|
kernel configuration file:
|
|
.Bd -ragged -offset indent
|
|
.Cd "device iflib"
|
|
.Cd "device iavf"
|
|
.Ed
|
|
.Pp
|
|
To load the driver as a module at boot time, place the following lines in
|
|
.Xr loader.conf 5 :
|
|
.Bd -literal -offset indent
|
|
if_iavf_load="YES"
|
|
.Ed
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver provides support for any PCI Virtual Function created from certain
|
|
Intel Ethernet devices.
|
|
This driver is compatible with virtual functions bound to devices based on the
|
|
following:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
Intel\(rg Ethernet Controller E810\-C
|
|
.It
|
|
Intel\(rg Ethernet Controller E810\-XXV
|
|
.It
|
|
Intel\(rg Ethernet Connection E822\-C
|
|
.It
|
|
Intel\(rg Ethernet Connection E822\-L
|
|
.It
|
|
Intel\(rg Ethernet Connection E823\-C
|
|
.It
|
|
Intel\(rg Ethernet Connection E823\-L
|
|
.It
|
|
Intel\(rg Ethernet Controller I710
|
|
.It
|
|
Intel\(rg Ethernet Controller X710
|
|
.It
|
|
Intel\(rg Ethernet Controller XL710
|
|
.It
|
|
Intel\(rg Ethernet Network Connection X722
|
|
.It
|
|
Intel\(rg Ethernet Controller XXV710
|
|
.It
|
|
Intel\(rg Ethernet Controller V710
|
|
.El
|
|
.Pp
|
|
The associated Physical Function (PF) drivers for this VF driver are:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
.Xr ice 4
|
|
.It
|
|
.Xr ixl 4
|
|
.El
|
|
.Pp
|
|
For questions related to hardware requirements, refer to the documentation
|
|
supplied with your Intel Ethernet Adapter.
|
|
All hardware requirements listed apply to use with
|
|
.Fx .
|
|
.Ss The VF Driver
|
|
The VF driver is normally used in a virtualized environment where a host driver
|
|
manages SR\-IOV, and provides a VF device to the guest.
|
|
.Pp
|
|
In the
|
|
.Fx
|
|
guest, the iavf driver would be loaded and will function using
|
|
the VF device assigned to it.
|
|
.Pp
|
|
The VF driver provides most of the same functionality as the core driver, but
|
|
is actually a subordinate to the host.
|
|
Access to many controls is accomplished by a request to the host via what is
|
|
called the "Admin queue."
|
|
These are startup and initialization events, however; once in operation, the
|
|
device is self\-contained and should achieve near native performance.
|
|
.Pp
|
|
Some notable limitations of the VF environment:
|
|
.Bl -bullet
|
|
.It
|
|
The PF can configure the VF to allow promiscuous mode, using a configuration
|
|
parameter in
|
|
.Xr iovctl.conf 5 ;
|
|
otherwise, promiscuous mode will not work
|
|
.It
|
|
Media info is not available from the PF, so the active media will always be
|
|
displayed as auto in
|
|
.Xr ifconfig 8
|
|
.El
|
|
.Ss Adaptive Virtual Function
|
|
Adaptive Virtual Function (AVF) allows the virtual function driver, or VF, to
|
|
adapt to changing feature sets of the physical function driver (PF) with which
|
|
it is associated.
|
|
This allows system administrators to update a PF without having to update all
|
|
the VFs associated with it.
|
|
All AVFs have a single common device ID and branding string.
|
|
.Pp
|
|
AVFs have a minimum set of features known as "base mode," but may provide
|
|
additional features depending on what features are available in the PF with
|
|
which the AVF is associated.
|
|
The following are base mode features:
|
|
.Bl -bullet -compact
|
|
.It
|
|
4 Queue Pairs (QP) and associated Configuration Status Registers (CSRs)
|
|
for Tx/Rx
|
|
.It
|
|
iavf descriptors and ring format
|
|
.It
|
|
Descriptor write\-back completion
|
|
.It
|
|
1 control queue, with iavf descriptors, CSRs and ring format
|
|
.It
|
|
5 MSI\-X interrupt vectors and corresponding iavf CSRs
|
|
.It
|
|
1 Interrupt Throttle Rate (ITR) index
|
|
.It
|
|
1 Virtual Station Interface (VSI) per VF
|
|
.It
|
|
1 Traffic Class (TC), TC0
|
|
.It
|
|
Receive Side Scaling (RSS) with 64 entry indirection table and key,
|
|
configured through the PF
|
|
.It
|
|
1 unicast MAC address reserved per VF
|
|
.It
|
|
8 MAC address filters for each VF on an Intel\(rg Ethernet 800 Series device
|
|
.It
|
|
16 MAC address filters for each VF on an Intel\(rg Ethernet 700 Series device
|
|
.It
|
|
Stateless offloads \- non\-tunneled checksums
|
|
.It
|
|
AVF device ID
|
|
.It
|
|
HW mailbox is used for VF to PF communications
|
|
.El
|
|
.Sh CONFIGURATION AND TUNING
|
|
.Ss Important System Configuration Changes
|
|
It is important to note that 100G operation can generate high
|
|
numbers of interrupts, often incorrectly being interpreted as
|
|
a storm condition in the kernel.
|
|
It is suggested that this be resolved by setting
|
|
.Va hw.intr_storm_threshold
|
|
to 0.
|
|
.Pp
|
|
The default is 1000.
|
|
.Pp
|
|
Best throughput results are seen with a large MTU; use 9706 if possible.
|
|
The default number of descriptors per ring is 1024.
|
|
Increasing this may improve performance, depending on your use case.
|
|
.Ss Configuring for no iflib
|
|
.Xr iflib 4
|
|
is a common framework for network interface drivers for
|
|
.Fx
|
|
that uses a shared set of sysctl names.
|
|
.Pp
|
|
The default
|
|
.Nm
|
|
driver depends on it, but it can be compiled without it.
|
|
.Ss Jumbo Frames
|
|
Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU)
|
|
to a value larger than the default value of 1500.
|
|
.Pp
|
|
Use the
|
|
.Xr ifconfig 8
|
|
command to increase the MTU size.
|
|
.Pp
|
|
To confirm the MTU used between two specific devices, use
|
|
.Xr route 8 :
|
|
.Bd -literal -offset indent
|
|
route get <destination_IP_address>
|
|
.Ed
|
|
.Pp
|
|
NOTE:
|
|
.Bl -bullet
|
|
.It
|
|
The maximum MTU setting for jumbo frames is 9706.
|
|
This corresponds to the maximum jumbo frame size of 9728 bytes.
|
|
.It
|
|
This driver will attempt to use multiple page-sized buffers to receive
|
|
each jumbo packet.
|
|
This should help to avoid buffer starvation issues when allocating receive
|
|
packets.
|
|
.It
|
|
Packet loss may have a greater impact on throughput when you use jumbo
|
|
frames.
|
|
If you observe a drop in performance after enabling jumbo frames, enabling
|
|
flow control may mitigate the issue.
|
|
.El
|
|
.Ss Checksum Offload
|
|
Checksum offloading supports both TCP and UDP packets and is supported for both
|
|
transmit and receive.
|
|
.Pp
|
|
TSO (TCP Segmentation Offload) supports both IPv4 and IPv6.
|
|
Both of these features are enabled and disabled via
|
|
.Xr ifconfig 8 .
|
|
.Pp
|
|
NOTE:
|
|
.Bl -bullet -compact
|
|
.It
|
|
TSO requires Tx checksum; if Tx checksum is disabled then TSO will also
|
|
be disabled.
|
|
.El
|
|
.Ss LRO
|
|
LRO (Large Receive Offload) may provide Rx performance improvement.
|
|
However, it is incompatible with packet\-forwarding workloads.
|
|
You should carefully evaluate the environment and enable LRO when possible.
|
|
.Ss Rx and Tx Descriptor Rings
|
|
Allows you to set the Rx and Tx descriptor rings independently.
|
|
Set them via these
|
|
.Xr iflib 4
|
|
sysctls:
|
|
.Bl -tag -width indent
|
|
.It dev.iavf.#.iflib.override_nrxds
|
|
.It dev.iavf.#.iflib.override_ntxds
|
|
.El
|
|
.Ss Link\-Level Flow Control (LFC)
|
|
The VF driver does not have access to flow control settings.
|
|
It must be managed from the host side.
|
|
.Sh SEE ALSO
|
|
.Xr arp 4 ,
|
|
.Xr ice 4 ,
|
|
.Xr iflib 4 ,
|
|
.Xr ixl 4 ,
|
|
.Xr netintro 4 ,
|
|
.Xr vlan 4 ,
|
|
.Xr ifconfig 8
|
|
.Pp
|
|
See the
|
|
.Dq Intel\(rg Ethernet Adapters and Devices User Guide
|
|
for additional information on features.
|
|
It is available on the Intel website at either of the following:
|
|
.Bl -bullet
|
|
.It
|
|
.Lk https://cdrdv2.intel.com/v1/dl/getContent/705831
|
|
.It
|
|
.Lk https://www.intel.com/content/www/us/en/download/19373/adapter\-user\-guide\-for\-intel\-ethernet\-adapters.html
|
|
.El
|
|
.Pp
|
|
For information on how to identify your adapter, and for the latest Intel
|
|
network drivers, refer to the Intel Support website:
|
|
.Aq Lk http://www.intel.com/support
|
|
.Sh CAVEATS
|
|
.Ss Driver Buffer Overflow Fix
|
|
The fix to resolve CVE\-2016\-8105, referenced in Intel SA\-00069
|
|
.Aq Lk https://www.intel.com/content/www/us/en/security\-center/advisory/intel\-sa\-00069.html ,
|
|
is included in this and future versions of the driver.
|
|
.Ss Network Memory Buffer Allocation
|
|
.Fx
|
|
may have a low number of network memory buffers (mbufs) by default.
|
|
If your mbuf value is too low, it may cause the driver to fail to initialize
|
|
and/or cause the system to become unresponsive.
|
|
You can check to see if the system is mbuf\-starved by running
|
|
.Li "netstat -m" .
|
|
Increase the number of mbufs by editing the lines below in
|
|
.Xr sysctl.conf 5 :
|
|
.Bd -literal -offset indent
|
|
kern.ipc.nmbclusters
|
|
kern.ipc.nmbjumbop
|
|
kern.ipc.nmbjumbo9
|
|
kern.ipc.nmbjumbo16
|
|
kern.ipc.nmbufs
|
|
.Ed
|
|
.Pp
|
|
The amount of memory that you allocate is system specific, and may require
|
|
some trial and error.
|
|
Also, increasing the following in
|
|
.Xr sysctl.conf 5
|
|
could help increase
|
|
network performance:
|
|
.Bd -literal -offset indent
|
|
kern.ipc.maxsockbuf
|
|
net.inet.tcp.sendspace
|
|
net.inet.tcp.recvspace
|
|
net.inet.udp.maxdgram
|
|
net.inet.udp.recvspace
|
|
.Ed
|
|
.Ss UDP Stress Test Dropped Packet Issue
|
|
Under small packet UDP stress with the
|
|
.Nm
|
|
driver, the system may drop UDP packets due to socket buffers being full.
|
|
Setting the PF driver's Flow Control variables to the minimum may resolve the
|
|
issue.
|
|
.Ss Disable LRO when routing/bridging
|
|
LRO must be turned off when forwarding traffic.
|
|
.Sh SUPPORT
|
|
For general information, go to the Intel support website at
|
|
.Aq Lk http://www.intel.com/support/ .
|
|
.Pp
|
|
If an issue is identified with the released source code on a supported kernel
|
|
with a supported adapter, email the specific information related to the issue
|
|
to
|
|
.Aq Mt freebsd@intel.com .
|
|
.Sh LEGAL
|
|
Intel\(rg is a trademark or registered trademark of Intel Corporation
|
|
or its subsidiaries in the United States and / or other countries.
|
|
.Pp
|
|
Other names and brands may be claimed as the property of others.
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
device driver first appeared in
|
|
.Fx 10.1
|
|
under the name
|
|
.Nm ixlv .
|
|
It was converted to use
|
|
.Xr iflib 4
|
|
and renamed in
|
|
.Fx 12.4 .
|
|
.Sh AUTHORS
|
|
The
|
|
.Nm
|
|
driver was written by the
|
|
.An Intel Corporation Aq Mt freebsd@intel.com
|