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