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