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