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