.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright (c) 2018 Joyent, Inc.
.\" Copyright 2020 Ryan Zezeski
.\" Copyright 2021 Oxide Computer Company
.\"
.Dd March 10, 2024
.Dt I40E 4D
.Os
.Sh NAME
.Nm i40e
.Nd Intel 710/722 Ethernet Device Driver
.Sh SYNOPSIS
.Pa /dev/net/i40e*
.Sh DESCRIPTION
The
.Nm
driver is a GLDv3, multi-threaded, clonable, loadable device driver that
supports the Data Link Provider Interface,
.Xr dlpi 4P .
The
.Nm
driver supports the Intel 710 and 722 Ethernet Controller families of
networking interface cards which support speeds of 1 GbE, 2.5 GbE, 5 GbE, 10
GbE, 25 GbE, and 40 GbE.
.Pp
In addition to basic device initialization and the sending and receiving
of frames, it supports the following features:
.Bl -dash -offset indent
.It
Jumbo frames up to 9710 bytes.
.It
Promiscuous access via
.Xr snoop 8 and
.Xr dlpi 4P
.It
IPv4 Checksum Offload
.It
TCP, UDP, and SCTP Checksum Offload
.It
IPv4 and IPv6 TCP Segmentation Offload
.El
.Pp
At this time, the
.Nm
driver does not enable the use of energy efficient Ethernet
.Pq EEE
or support the use of flow control through hardware pause frames.
.Sh APPLICATION PROGRAMMING INTERFACE
For each device supported by the
.Nm
installed in the system, a character-special file will be created.
This file supports the Data Link Provider Interface
.Pq DLPI
which is documented in
.Xr dlpi 4P .
For most consumers, the use of
.Xr libdlpi 3LIB ,
is recommended.
.Pp
Each instance is assigned a unique ascending integer identifier.
A device which has multiple ports may appear to the system as separate
instances.
The system does not provide a guarantee on how these will be presented.
Using this instance identifier, one can determine the exact character-special
file to open.
For example, the first instance enumerated in the system, with id 0, would be
named
.Sy i40e0 .
It exists in the file system at
.Pa /dev/net/i40e0 .
.Sh CONFIGURATION
The
.Nm i40e
driver always performs auto-negotiation and depending on the model may
negotiate to 40 Gbps, 25 Gbps, 10 Gbps, or 1 Gbps.
At this time, the driver requires the use of auto-negotiation.
.Pp
The
.Nm
driver is managed by the
.Xr dladm 8
utility.
.Xr dladm 8
is the preferred interface for setting all properties.
While
.Xr driver.conf 5
based configuration is possible,
.Xr dladm 8
is recommended.
The
.Nm
driver may be joined into an aggregation based on the link aggregation
control protocol
.Pq LACP
through
.Xr dladm 8 .
.Sh PROPERTIES
The device supports the following properties which may be tuned through
its driver.conf file,
.Pa /kernel/drv/i40e.conf .
Most of these properties cannot be changed after the device has been started.
The device is started in response to a DLPI consumer opening the device and
binding to it.
This happens when an IP interfaces is plumbed or another
.Xr dlpi 4P
consumer such as
.Xr snoop 8
or an LLDP daemon is started.
.Pp
Some properties may be tuned at runtime with the
.Xr dladm 8
utility.
Properties that can be will have the name of the dladm property called out
explicitly.
.Pp
These properties are not considered stable at this time.
They may change and should not be relied on.
They are considered
.Sy Volatile .
It is not expected that administrators of the system will have to tune
these values.
.Bl -hang -width Ds
.It Sy default_mtu
.Bd -filled -compact
Minimum:
.Sy 1500 |
Maximum:
.Sy 9710 |
Runtime Property:
.Sy mtu
.Ed
.Bd -filled
The
.Sy default_mtu
property determines the starting MTU of the various device instances.
Note that the device's MTU also determines the upper bound of the MTU of
all VNICs created over the device.
The default MTU is
.Sy 1500 .
.Ed
.It Sy mr_enable
.Bd -filled -compact
Minimum:
.Sy 0 |
Maximum:
.Sy 1
.Ed
.Bd -filled
The
.Sy mr_enable
property determines whether or not support for multiple rings is enabled
for the device.
The default is always to enable them.
It is not recommended to to disable them.
.Ed
.It Sy rx_num_groups
.Bd -filled -compact
Minimum:
.Sy 1 |
Maximum:
.Sy 32
.Ed
.Bd -filled
The
.Sy rx_num_groups
property determines the number of receive mac groups provided by the driver.
Each group can handle all unicast traffic for a single MAC address, more groups
means more unicast traffic that can be steered by hardware.
However, more groups also means more demand for kernel memory.
If you are not making heavy use of VNICs, or do not need the efficiency gains
of hardware steering, then reducing this number can reduce kernel memory
taken by
.Nm i40e.
.Ed
.It Sy rx_ring_size
.Bd -filled -compact
Minimum:
.Sy 64 |
Maximum:
.Sy 4096
.Ed
.Bd -filled
The
.Sy rx_ring_size
property determines the number of descriptors that will be used in each
receive ring on the card.
Administrators should not normally need to tune this value.
Hardware requires that the ring size be a multiple of 32.
The system will round up the set value to the nearest multiple of 32.
.Ed
.It Sy tx_ring_size
.Bd -filled -compact
Minimum:
.Sy 64 |
Maximum:
.Sy 4096
.Ed
.Bd -filled
The
.Sy tx_ring_size
property determines the number of descriptors that will be used in each
transmit ring on the card.
Administrators should not normally need to tune this value.
Hardware requires that the ring size be a multiple of 32.
The system will round up the set value to the nearest multiple of 32.
.Ed
.It Sy tx_resched_threshold
.Bd -filled -compact
Minimum:
.Sy 8 |
Maximum:
.Sy Variable
.Ed
.Bd -filled
The
.Sy tx_resched_threshold
property determines the number of descriptors that must be available for
a frame to be transmitted.
The maximum is variable.
It is dependent on the value of the
.Sy tx_ring_size
property.
At least eight descriptors must be available for the device to function
correctly.
.Ed
.It Sy rx_limit_per_intr
.Bd -filled -compact
Minimum:
.Sy 16 |
Maximum:
.Sy 4096
.Ed
.Bd -filled
The
.Sy rx_limit_per_intr
property determines the maximum number of packets that will be processed
on a given ring during a single interrupt.
This is done to try and guarantee some amount of liveness in the system.
It is not expected that administrators will have to tune this value.
.Ed
.It Sy tx_hcksum_enable
.Bd -filled -compact
Minimum:
.Sy 0 |
Maximum:
.Sy 1
.Ed
.Bd -filled
The
.Sy tx_hcksum_enable
property controls whether or not the device enables support for hardware
checksumming of outgoing packets.
The default is to always enable support for this.
Turning it off will increase latency and decrease throughput when transmitting
packets, but should be done if a hardware bug is suspected.
.Ed
.It Sy rx_hcksum_enable
.Bd -filled -compact
Minimum:
.Sy 0 |
Maximum:
.Sy 1
.Ed
.Bd -filled
The
.Sy rx_hcksum_enable
property controls whether or not the device enables support for hardware
checksumming of incoming packets.
The default is to always enable support for this.
Turning it off will increase latency and decrease throughput when receiving
packets, but should be done if a hardware bug is suspected.
.Ed
.It Sy rx_dma_threshold
.Bd -filled -compact
Minimum:
.Sy 0 |
Maximum:
.Sy INT32_MAX |
Runtime Property:
.Sy _rx_dma_threshold
.Ed
.Bd -filled
The
.Sy rx_dma_threshold
indicates the size in bytes of a received frame, including all of its
headers, at which the driver should not copy the frame but instead bind
DMA memory.
By setting this property to its minimum, all frames will be processed with DMA
binding.
By setting this property to its maximum, all frames will be processed by copying
the frame.
.Ed
.It Sy tx_lso_enable
.Bd -filled -compact
Minimum:
.Sy 0 |
Maximum:
.Sy 1
.Ed
.Bd -filled
The
.Sy tx_lso_enable
property controls whether or not the device enables support for Large Segment
Offload
.Pq LSO
when transmitting packets.
The default is to always enable support for this.
Turning it off will decrease throughput when transmitting packets, but should
be done if a hardware bug is suspected.
.Ed
.El
.Sh ARCHITECTURE
The
.Nm
driver is only supported on
.Sy x86
systems at this time.
.Sh FILES
.Bl -tag -width Pa
.It Pa /dev/net/i40e*
Per-instance character device.
.It Pa /kernel/drv/amd64/i40e
Device driver
.Pq x86
.It Pa /kernel/drv/i40e.conf
Driver configuration file
.El
.Sh SEE ALSO
.Xr dlpi 4P ,
.Xr driver.conf 5 ,
.Xr dladm 8 ,
.Xr snoop 8