emx: Add errata workaround for multiple TX queues
[dragonfly.git] / share / man / man4 / em.4
CommitLineData
984263bc
MD
1.\" Copyright (c) 2001-2003, Intel Corporation
2.\" All rights reserved.
1bf4b486 3.\"
984263bc
MD
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions are met:
6.\"
7.\" 1. Redistributions of source code must retain the above copyright notice,
8.\" this list of conditions and the following disclaimer.
9.\"
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" 3. Neither the name of the Intel Corporation nor the names of its
15.\" contributors may be used to endorse or promote products derived from
16.\" this software without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
22.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE.
29.\"
30.\" * Other names and brands may be claimed as the property of others.
31.\"
604af13b 32.\" $FreeBSD: src/share/man/man4/em.4,v 1.30 2008/10/06 21:55:53 simon Exp $
984263bc 33.\"
26595b18 34.Dd November 28, 2014
984263bc
MD
35.Dt EM 4
36.Os
37.Sh NAME
82020495
SW
38.Nm em ,
39.Nm emx
604af13b 40.Nd "Intel(R) PRO/1000 Gigabit Ethernet adapter driver"
984263bc 41.Sh SYNOPSIS
604af13b
SW
42To compile this driver into the kernel,
43place the following lines in your
44kernel configuration file:
45.Bd -ragged -offset indent
46.Cd "device ig_hal"
82020495
SW
47.Cd "device em # for em(4)"
48.Cd "device emx # for emx(4)"
604af13b
SW
49.Ed
50.Pp
51Alternatively, to load the driver as a
52module at boot time, place the following lines in
53.Xr loader.conf 5 :
54.Bd -literal -offset indent
55ig_hal_load="YES"
82020495
SW
56if_em_load="YES" # for em(4)
57if_emx_load="YES" # for emx(4)
604af13b 58.Ed
984263bc
MD
59.Sh DESCRIPTION
60The
61.Nm
604af13b
SW
62driver provides support for PCI Gigabit Ethernet adapters based on
63the Intel 82540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546,
1eb61d6b
SZ
6482546EB, 82546GB, 82547, 82571, 81572, 82573, 82574, I217 and I218
65Ethernet controller chips.
604af13b
SW
66The driver supports Transmit/Receive checksum offload
67and Jumbo Frames on all but 82542-based adapters.
1eb61d6b 68Furthermore it supports TCP segmentation offload (TSO) on PCI-E adapters.
984263bc 69.Pp
82020495
SW
70The
71.Nm emx
72is a version of the
73.Nm em
a1cbf014
SZ
74driver for 82571, 82572, 82573, 82574, I217 and I218 Ethernet controller chips
75that additionally supports Receive Side Scaling (RSS, 2 reception queues).
be871347
SZ
76By default,
77the
78.Nm emx
79driver will try enabling 2 reception queues
80if there are multiple CPUs on the system.
57f26b35 81For 82571, 82572, 82574, I217 and I218
be871347
SZ
82the
83.Nm emx
84driver could be configured to enable 2 transmission queues.
85By default,
86the
87.Nm emx
88driver only enables 1 transmission queue,
89since enabling 2 transmission queues will require setting up context
90descriptor for every packets requiring hardware transmission offloading,
91which hurts tiny packet transmission performance.
92However,
93if the workload is mainly bulk data
94or hardware transmission offloading is rarely required,
95extra transmission queue could be enabled to reduce contention on
96transmission path.
972 transmission queues will only be used when
98.Xr polling 4
99is enabled on the device.
e301539e
SZ
100If multiple transmission queues are used,
101the round-robin arbitration is performed among the transmission queues.
102It should be noted that
103if both TSO and multiple transmission queues are used,
104the round-robin arbitration between transmission queues is done
105at the TSO packet boundary.
984263bc 106.Pp
be871347
SZ
107.\"For questions related to hardware requirements,
108.\"refer to the documentation supplied with your Intel PRO/1000 adapter.
109.\"All hardware requirements listed apply to use with
110.\".Dx .
111.\".Pp
984263bc
MD
112Support for Jumbo Frames is provided via the interface MTU setting.
113Selecting an MTU larger than 1500 bytes with the
114.Xr ifconfig 8
115utility configures the adapter to receive and transmit Jumbo Frames.
604af13b 116The maximum MTU size for Jumbo Frames is 16114.
984263bc
MD
117.Pp
118This driver version supports VLANs.
984263bc
MD
119The
120.Nm
82020495
SW
121and
122.Nm emx
123drivers support the following media types:
984263bc
MD
124.Bl -tag -width ".Cm 10baseT/UTP"
125.It Cm autoselect
126Enables auto-negotiation for speed and duplex.
127.It Cm 10baseT/UTP
128Sets 10Mbps operation.
129Use the
130.Cm mediaopt
131option to select
132.Cm full-duplex
133mode.
134.It Cm 100baseTX
135Sets 100Mbps operation.
136Use the
137.Cm mediaopt
138option to select
139.Cm full-duplex
140mode.
141.It Cm 1000baseSX
142Sets 1000Mbps operation.
143Only
144.Cm full-duplex
145mode is supported at this speed.
829c4df6 146.It Cm 1000baseT
984263bc
MD
147Sets 1000Mbps operation.
148Only
149.Cm full-duplex
150mode is supported at this speed.
151.El
152.Pp
153The
154.Nm
82020495
SW
155and
156.Nm emx
157drivers support the following media options:
984263bc
MD
158.Bl -tag -width ".Cm full-duplex"
159.It Cm full-duplex
160Forces full-duplex operation
161.It Cm half-duplex
162Forces half-duplex operation.
163.El
164.Pp
165Only use
166.Cm mediaopt
167to set the driver to
168.Cm full-duplex .
169If
170.Cm mediaopt
171is not specified, the driver defaults to
172.Cm half-duplex .
173.Pp
174For more information on configuring this device, see
175.Xr ifconfig 8 .
82020495 176.Pp
d0569bf9
TN
177The
178.Nm
82020495
SW
179and
180.Nm emx
181drivers support
d0569bf9 182.Xr polling 4 .
604af13b
SW
183.Sh HARDWARE
184The
185.Nm
186driver supports Gigabit Ethernet adapters based on the Intel
18782540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, 82546EB,
4b2f06d6
SZ
18882546GB, 82547, 82571, 82572, 82573, 82574, I217 and I218
189controller chips:
604af13b
SW
190.Pp
191.Bl -bullet -compact
192.It
4b2f06d6 193Intel 82540EM Gigabit Ethernet Controller
604af13b 194.It
4b2f06d6 195Intel 82540EP Gigabit Ethernet Controller
604af13b 196.It
4b2f06d6 197Intel 82543GC Gigabit Ethernet Controller
604af13b 198.It
4b2f06d6 199Intel 82544 Gigabit Ethernet Controller
604af13b 200.It
4b2f06d6 201Intel 82544EI Gigabit Ethernet Controller
604af13b 202.It
4b2f06d6 203Intel 82545GM Gigabit Ethernet Controller
604af13b 204.It
4b2f06d6 205Intel 82546EB Gigabit Ethernet Controller
604af13b 206.It
4b2f06d6 207Intel 82547EI Gigabit Ethernet Controller
604af13b 208.It
4b2f06d6 209Intel 82547GI Gigabit Ethernet Controller
604af13b 210.It
4b2f06d6 211Intel 82567 Gigabit Ethernet Controller
604af13b 212.It
4b2f06d6 213Intel 82571EB Gigabit Ethernet Controller
604af13b 214.It
4b2f06d6 215Intel 82572EI Gigabit Ethernet Controller
604af13b 216.It
4b2f06d6 217Intel 82573E Gigabit Ethernet Controller
604af13b 218.It
4b2f06d6 219Intel 82573L Gigabit Ethernet Controller
604af13b 220.It
4b2f06d6 221Intel 82573V Gigabit Ethernet Controller
604af13b 222.It
4b2f06d6 223Intel 82574 Gigabit Ethernet Controller
604af13b 224.It
4b2f06d6 225Intel 82578 Gigabit Ethernet PHY
604af13b 226.It
4b2f06d6 227Intel 82579 Gigabit Ethernet Controller
604af13b 228.It
4b2f06d6 229Intel Ethernet Connection I217-LM
604af13b 230.It
4b2f06d6 231Intel Ethernet Connection I217-V
604af13b 232.It
4b2f06d6 233Intel Ethernet Connection I218-LM
604af13b 234.It
4b2f06d6 235Intel Ethernet Connection I218-V
604af13b 236.It
4b2f06d6
SZ
237Intel Gigabit CT Desktop Adapter
238.It
239Intel PRO/1000 F Server Adapter
240.It
241Intel PRO/1000 GT Quad Port Server Adapter
242.It
243Intel PRO/1000 MF Dual Port Server Adapter
244.It
245Intel PRO/1000 MF Server Adapter
246.It
247Intel PRO/1000 MF Server Adapter (LX)
248.It
249Intel PRO/1000 MT Dual Port Server Adapter
250.It
251Intel PRO/1000 MT Quad Port Server Adapter
252.It
253Intel PRO/1000 MT Server Adapter
254.It
255Intel PRO/1000 PF Dual Port Server Adapter
256.It
257Intel PRO/1000 PF Quad Port Server Adapter
258.It
259Intel PRO/1000 PF Server Adapter
260.It
261Intel PRO/1000 PT Dual Port Server Adapter
262.It
263Intel PRO/1000 PT Quad Port Low Profile Server Adapter
264.It
265Intel PRO/1000 PT Quad Port Server Adapter
266.It
267Intel PRO/1000 PT Server Adapter
268.It
269Intel PRO/1000 T Server Adapter
270.It
271Intel PRO/1000 XT Low Profile Server Adapter
272.It
3aa08cba 273Intel PRO/1000 XT Server Adapter
604af13b 274.El
82020495
SW
275.Pp
276The
277.Nm emx
278driver supports Gigabit Ethernet adapters based on the Intel
c84c3a21 27982571, 82572, 82573, 82574, I217 and I218 controller chips.
be871347 280.Sh TUNABLES
604af13b
SW
281Tunables can be set at the
282.Xr loader 8
283prompt before booting the kernel or stored in
284.Xr loader.conf 5 .
be871347
SZ
285.Em Y
286is the device unit number.
287.Bl -tag -width "hw.em.int_throttle_ceil"
c08223a6
SW
288.It Va hw.em.int_throttle_ceil
289Hardware interrupt throttling rate.
be871347
SZ
290The default value is 6000Hz.
291This tunable also applies to
292.Nm emx .
293.Nm emx
294has a per device tunable
295.Va hw.emxY.int_throttle_ceil ,
296which serves the same purpose.
7bc27c52
SW
297.It Va hw.em.rxd
298Number of receive descriptors allocated by the driver.
be871347 299The default value is 512.
7bc27c52
SW
300The 82542 and 82543-based adapters can handle up to 256 descriptors,
301while others can have up to 4096.
be871347
SZ
302This tunable also applies to
303.Nm emx .
304.Nm emx
305has a per device tunable
306.Va hw.emxY.rxd ,
307which serves the same purpose.
7bc27c52
SW
308.It Va hw.em.txd
309Number of transmit descriptors allocated by the driver.
be871347 310The default value is 512.
7bc27c52
SW
311The 82542 and 82543-based adapters can handle up to 256 descriptors,
312while others can have up to 4096.
be871347
SZ
313This tunable also applies to
314.Nm emx .
315.Nm emx
316has a per device tunable
317.Va hw.emxY.txd ,
318which serves the same purpose.
319.It Va hw.em.msi.enable Va hw.emY.msi.enable
320By default, the driver will use MSI if it is supported.
321This behavior can be turned off by setting these tunable to 0.
322These tunables also applies to
323.Nm emx .
324.It Va hw.emY.msi.cpu
325If MSI is used,
326it specifies the MSI's target CPU.
327This tunable also applies to
328.Nm emx .
329.It Va hw.emY.irq.unshared
330If legacy interrupt is used,
331by default,
332the driver assumes the interrupt could be shared.
333Setting this tunable to 1 allows the driver to
334perform certain optimization based on the knowledge
335that the interrupt is not shared.
336These tunables also applies to
337.Nm emx .
338.It Va hw.emx.rxr Va hw.emxY.rxr
339This tunable specifies the number of reception queues could be enabled.
340Maximum allowed value for these tunables is 2.
341Setting these tunables to 0 allows the driver to enable reception
342queues based on the number of CPUs.
343The default value is 0.
344.It Va hw.emx.txr Va hw.emxY.txr
345These tunables only take effect on 82571 and 82572.
346This tunable specifies the number of transmission queues could be enabled.
347Maximum allowed value for these tunables is 2.
348Setting these tunables to 0 allows the driver to enable transmission
349queues based on the number of CPUs.
350The default value is 1.
351.It Va hw.emxY.npoll.rxoff
352This tunable specifies the leading target CPU for reception queues
353.Xr polling 4
354processing.
355The value specificed must be aligned to the number of reception queues enabled
356and must be less than the power of 2 number of CPUs.
357.It Va hw.emxY.npoll.rxoff
358This tunable specifies the leading target CPU for transmission queues
359.Xr polling 4
360processing.
361The value specificed must be aligned to the number of transmission queues
362enabled
363and must be less than the power of 2 number of CPUs.
364.El
365.Sh MIB Variables
366A number of per-interface variables are implemented in the
26595b18 367.Va dev.emx. Ns Em Y
be871347 368or
26595b18 369.Va dev.em. Ns Em Y
be871347
SZ
370branch of the
371.Xr sysctl 3
372MIB.
373.Bl -tag -width "int_throttle_ceil"
374.It Va rxd
375Number of reception descriptors enabled (read-only).
376Use the tunable
377.Va hw.em.rxd
378or
379.Va hw.emY.rxd
380to configure it.
381.It Va txd
382Number of transmission descriptors enabled (read-only).
383Use the tunable
384.Va hw.em.txd
385or
386.Va hw.emY.txd
387to configure it.
388.It Va int_throttle_ceil
389See the tunable
390.Va hw.em.int_throttle_ceil .
391.It Va int_tx_nsegs
19bc33b2
SZ
392This value controls how many transmit descriptors should be consumed
393by the hardware before the hardware generates a transmit interrupt.
394The default value is 1/16 of the number of transmit descriptors.
7bc27c52 395If
19bc33b2
SZ
396.Xr polling 4
397is not used on the hardware and
398the major part of the transmitted data are bulk data,
399this value could safely be set to 1/2 of the number of transmit descriptors.
be871347
SZ
400.It Va tx_wreg_nsegs
401The number of transmission descriptors should be setup
402before the hardware register is written.
403Setting this value too high will have negative effect
404on transmission timeliness.
405Setting this value too low will hurt overall transmission due to
406the frequent hardware register writing.
407Default value is 8.
408.It Va rx_ring_cnt
f734ea4b 409Number of reception queues enabled (read-only).
be871347
SZ
410This sysctl only applies to
411.Nm emx .
412Use the tunable
413.Va hw.emx.rxr
414or
415.Va hw.emxY.rxr
416to configure it.
417.It Va tx_ring_cnt
f734ea4b 418Number of transmission queues that can be enabled (read-only).
be871347
SZ
419This sysctl only applies to
420.Nm emx .
421Use the tunable
422.Va hw.emx.txr
423or
424.Va hw.emxY.txr
425to configure it.
426.It Va tx_ring_inuse
427Number of transmission queues being used (read-only).
428This sysctl only applies to
429.Nm emx .
430.It Va npoll_rxoff
431See the tunable
432.Va hw.emxY.npoll.rxoff .
433The set value will take effect the next time
434.Xr polling 4
435is enabled on the device.
436This sysctl only applies to
437.Nm emx .
438.It Va npoll_txoff
439See the tunable
440.Va hw.emxY.npoll.txoff .
441The set value will take effect the next time
442.Xr polling 4
443is enabled on the device.
444This sysctl only applies to
445.Nm emx .
7bc27c52 446.El
be871347
SZ
447.\".Sh SUPPORT
448.\"For general information and support,
449.\"go to the Intel support website at:
450.\".Pa http://support.intel.com .
82020495 451.\".Pp
be871347
SZ
452.\"If an issue is identified with the released source code on the supported kernel
453.\"with a supported adapter, email the specific information related to the
454.\"issue to
b2a6f486 455.\".Aq Mt freebsdnic@mailbox.intel.com .
984263bc
MD
456.Sh SEE ALSO
457.Xr arp 4 ,
8985f72f 458.Xr ifmedia 4 ,
984263bc
MD
459.Xr netintro 4 ,
460.Xr ng_ether 4 ,
01fe1724 461.Xr polling 4 ,
984263bc
MD
462.Xr vlan 4 ,
463.Xr ifconfig 8
464.Sh HISTORY
465The
466.Nm
467device driver first appeared in
82020495
SW
468.Fx 4.4
469and the
470.Nm emx
471driver first appeared in
472.Dx 2.3 .
984263bc 473.Sh AUTHORS
82020495 474.An -nosplit
984263bc
MD
475The
476.Nm
477driver was written by
b2a6f486 478.An Intel Corporation Aq Mt freebsdnic@mailbox.intel.com .
82020495
SW
479.Pp
480The
481.Nm emx
482driver was written by
483.An Sepherosa Ziehau
484(in parts based on
485.Tn Intel Ap s ) .