xref: /illumos-gate/usr/src/man/man4d/i40e.4d (revision 9164a50bf932130cbb5097a16f6986873ce0e6e5)
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