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