1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright (c) 2018 Joyent, Inc. 13.\" Copyright 2020 Ryan Zezeski 14.\" Copyright 2021 Oxide Computer Company 15.\" 16.Dd January 18, 2021 17.Dt I40E 4D 18.Os 19.Sh NAME 20.Nm i40e 21.Nd Intel 710/722 Ethernet Device Driver 22.Sh SYNOPSIS 23.Pa /dev/net/i40e* 24.Sh DESCRIPTION 25The 26.Nm 27driver is a GLDv3, multi-threaded, clonable, loadable device driver that 28supports the Data Link Provider Interface, 29.Xr dlpi 4P . 30The 31.Nm 32driver supports the Intel 710 and 722 Ethernet Controller families of 33networking interface cards which support speeds of 1 GbE, 2.5 GbE, 5 GbE, 10 34GbE, 25 GbE, and 40 GbE. 35.Pp 36In addition to basic device initialization and the sending and receiving 37of frames, it supports the following features: 38.Bl -dash -offset indent 39.It 40Jumbo frames up to 9710 bytes. 41.It 42Promiscuous access via 43.Xr snoop 8 and 44.Xr dlpi 4P 45.It 46IPv4 Checksum Offload 47.It 48TCP, UDP, and SCTP checksum offload 49.It 50IPv4 and IPv6 TCP Segmentation offload 51.El 52.Pp 53At this time, the 54.Nm 55driver does not enable the use of energy efficient Ethernet (EEE) or 56support the use of flow control through hardware pause frames. 57.Sh APPLICATION PROGRAMMING INTERFACE 58For each device supported by the 59.Nm 60installed in the system, a character-special file will be created. 61This file supports the Data Link Provider Interface (DLPI) which is documented 62in 63.Xr dlpi 4P . 64For most consumers, the use of 65.Xr libdlpi 3LIB , 66is recommended. 67.Pp 68Each instance is assigned a unique ascending integer identifier. 69A device which has multiple ports may appear to the system as separate 70instances. 71The system does not provide a guarantee on how these will be presented. 72Using this instance identifier, one can determine the exact character-special 73file to open. 74For example, the first instance enumerated in the system, with id 0, would be 75named 76.Sy i40e0 . 77It exists in the file system at 78.Pa /dev/net/i40e0 . 79.Sh CONFIGURATION 80The 81.Nm i40e 82driver always performs auto-negotiation and depending on the model may 83negotiate to 40 Gbps, 25 Gbps, 10 Gbps, or 1 Gbps. 84At this time, the driver requires the use of auto-negotiation. 85.Pp 86The 87.Nm 88driver is managed by the 89.Xr dladm 8 90utility. 91.Xr dladm 8 92is the preferred interface for setting all properties. 93While 94.Xr driver.conf 5 95based configuration is possible, 96.Xr dladm 8 97is recommended. 98The 99.Nm 100driver may be joined into an aggregation based on the link aggregation 101control protocol (LACP) through 102.Xr dladm 8 . 103.Sh PROPERTIES 104The device supports the following properties which may be tuned through 105its driver.conf file, 106.Pa /kernel/drv/i40e.conf . 107Most of these properties cannot be changed after the device has been started. 108The device is started in response to a DLPI consumer opening the device and 109binding to it. 110This happens when an IP interfaces is plumbed or another 111.Xr dlpi 4P 112consumer such as 113.Xr snoop 8 114or an LLDP daemon is started. 115.Pp 116Some properties may be tuned at runtime with the 117.Xr dladm 8 118utility. 119Properties that can be will have the name of the dladm property called out 120explicitly. 121.Pp 122These properties are not considered stable at this time. 123They may change and should not be relied on. 124They are considered 125.Sy Volatile . 126It is not expected that administrators of the system will have to tune 127these values. 128.Bl -hang -width Ds 129.It Sy default_mtu 130.Bd -filled -compact 131Minimum: 132.Sy 1500 | 133Maximum: 134.Sy 9710 | 135Runtime Property: 136.Sy mtu 137.Ed 138.Bd -filled 139The 140.Sy default_mtu 141property determines the starting MTU of the various device instances. 142Note that the device's MTU also determines the upper bound of the MTU of 143all VNICs created over the device. 144The default MTU is 145.Sy 1500 . 146.Ed 147.It Sy mr_enable 148.Bd -filled -compact 149Minimum: 150.Sy 0 | 151Maximum: 152.Sy 1 153.Ed 154.Bd -filled 155The 156.Sy mr_enable 157property determines whether or not support for multiple rings is enabled 158for the device. 159The default is always to enable them. 160It is not recommended to to disable them. 161.Ed 162.It Sy rx_num_groups 163.Bd -filled -compact 164Minimum: 165.Sy 1 | 166Maximum: 167.Sy 32 168.Ed 169.Bd -filled 170The 171.Sy rx_num_groups 172property determines the number of receive mac groups provided by the driver. 173Each group can handle all unicast traffic for a single MAC address, more groups 174means more unicast traffic that can be steered by hardware. 175However, more groups also means more demand for kernel memory. 176If you are not making heavy use of VNICs, or do not need the efficiency gains 177of hardware steering, then reducing this number can reduce kernel memory 178taken by 179.Nm i40e. 180.Ed 181.It Sy rx_ring_size 182.Bd -filled -compact 183Minimum: 184.Sy 64 | 185Maximum: 186.Sy 4096 187.Ed 188.Bd -filled 189The 190.Sy rx_ring_size 191property determines the number of descriptors that will be used in each 192receive ring on the card. 193Administrators should not normally need to tune this value. 194Hardware requires that the ring size be a multiple of 32. 195The system will round up the set value to the nearest multiple of 32. 196.Ed 197.It Sy tx_ring_size 198.Bd -filled -compact 199Minimum: 200.Sy 64 | 201Maximum: 202.Sy 4096 203.Ed 204.Bd -filled 205The 206.Sy tx_ring_size 207property determines the number of descriptors that will be used in each 208transmit ring on the card. 209Administrators should not normally need to tune this value. 210Hardware requires that the ring size be a multiple of 32. 211The system will round up the set value to the nearest multiple of 32. 212.Ed 213.It Sy tx_resched_threshold 214.Bd -filled -compact 215Minimum: 216.Sy 8 | 217Maximum: 218.Sy Variable 219.Ed 220.Bd -filled 221The 222.Sy tx_resched_threshold 223property determines the number of descriptors that must be available for 224a frame to be transmitted. 225The maximum is variable. 226It is dependent on the value of the 227.Sy tx_ring_size 228property. 229At least eight descriptors must be available for the device to function 230correctly. 231.Ed 232.It Sy rx_limit_per_intr 233.Bd -filled -compact 234Minimum: 235.Sy 16 | 236Maximum: 237.Sy 4096 238.Ed 239.Bd -filled 240The 241.Sy rx_limit_per_intr 242property determines the maximum number of packets that will be processed 243on a given ring during a single interrupt. 244This is done to try and guarantee some amount of liveness in the system. 245It is not expected that administrators will have to tune this value. 246.Ed 247.It Sy tx_hcksum_enable 248.Bd -filled -compact 249Minimum: 250.Sy 0 | 251Maximum: 252.Sy 1 253.Ed 254.Bd -filled 255The 256.Sy tx_hcksum_enable 257property controls whether or not the device enables support for hardware 258checksumming of outgoing packets. 259The default is to always enable support for this. 260Turning it off will increase latency and decrease throughput when transmitting 261packets, but should be done if a hardware bug is suspected. 262.Ed 263.It Sy rx_hcksum_enable 264.Bd -filled -compact 265Minimum: 266.Sy 0 | 267Maximum: 268.Sy 1 269.Ed 270.Bd -filled 271The 272.Sy rx_hcksum_enable 273property controls whether or not the device enables support for hardware 274checksumming of incoming packets. 275The default is to always enable support for this. 276Turning it off will increase latency and decrease throughput when receiving 277packets, but should be done if a hardware bug is suspected. 278.Ed 279.It Sy rx_dma_threshold 280.Bd -filled -compact 281Minimum: 282.Sy 0 | 283Maximum: 284.Sy INT32_MAX | 285Runtime Property: 286.Sy _rx_dma_threshold 287.Ed 288.Bd -filled 289The 290.Sy rx_dma_threshold 291indicates the size in bytes of a received frame, including all of its 292headers, at which the driver should not copy the frame but instead bind 293DMA memory. 294By setting this property to its minimum, all frames will be processed with DMA 295binding. 296By setting this property to its maximum, all frames will be processed by copying 297the frame. 298.Ed 299.It Sy tx_lso_enable 300.Bd -filled -compact 301Minimum: 302.Sy 0 | 303Maximum: 304.Sy 1 305.Ed 306.Bd -filled 307The 308.Sy tx_lso_enable 309property controls whether or not the device enables support for Large Segment 310Offloand (LSO) when transmitting packets. 311The default is to always enable support for this. 312Turning it off will decrease throughput when transmitting packets, but should 313be done if a hardware bug is suspected. 314.Ed 315.El 316.Sh ARCHITECTURE 317The 318.Nm 319driver is only supported on 320.Sy x86 321systems at this time. 322.Sh FILES 323.Bl -tag -width Pa 324.It Pa /dev/net/i40e* 325Per-instance character device. 326.It Pa /kernel/drv/amd64/i40e 327Device driver (x86) 328.It Pa /kernel/drv/i40e.conf 329Driver configuration file 330.El 331.Sh SEE ALSO 332.Xr dlpi 4P , 333.Xr driver.conf 5 , 334.Xr dladm 8 , 335.Xr snoop 8 336