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