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