Commit | Line | Data |
---|---|---|
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 | .\" |
74dc3754 | 34 | .Dd December 17, 2017 |
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 |
42 | To compile this driver into the kernel, |
43 | place the following lines in your | |
44 | kernel 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 | |
51 | Alternatively, to load the driver as a | |
52 | module at boot time, place the following lines in | |
53 | .Xr loader.conf 5 : | |
54 | .Bd -literal -offset indent | |
55 | ig_hal_load="YES" | |
82020495 SW |
56 | if_em_load="YES" # for em(4) |
57 | if_emx_load="YES" # for emx(4) | |
604af13b | 58 | .Ed |
984263bc MD |
59 | .Sh DESCRIPTION |
60 | The | |
61 | .Nm | |
604af13b SW |
62 | driver provides support for PCI Gigabit Ethernet adapters based on |
63 | the Intel 82540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, | |
d5020db1 SW |
64 | 82546EB, 82546GB, 82547, 82571, 81572, 82573, 82574, I217, I218 and |
65 | i219 Ethernet controller chips. | |
604af13b SW |
66 | The driver supports Transmit/Receive checksum offload |
67 | and Jumbo Frames on all but 82542-based adapters. | |
1eb61d6b | 68 | Furthermore it supports TCP segmentation offload (TSO) on PCI-E adapters. |
984263bc | 69 | .Pp |
82020495 SW |
70 | The |
71 | .Nm emx | |
72 | is a version of the | |
73 | .Nm em | |
d5020db1 SW |
74 | driver for 82571, 82572, 82573, 82574, I217, I218 and I219 Ethernet |
75 | controller chips | |
a1cbf014 | 76 | that additionally supports Receive Side Scaling (RSS, 2 reception queues). |
be871347 SZ |
77 | By default, |
78 | the | |
79 | .Nm emx | |
80 | driver will try enabling 2 reception queues | |
81 | if there are multiple CPUs on the system. | |
d5020db1 | 82 | For 82571, 82572, 82574, I217, I218 and I219 |
be871347 SZ |
83 | the |
84 | .Nm emx | |
85 | driver could be configured to enable 2 transmission queues. | |
86 | By default, | |
87 | the | |
88 | .Nm emx | |
89 | driver only enables 1 transmission queue, | |
90 | since enabling 2 transmission queues will require setting up context | |
91 | descriptor for every packets requiring hardware transmission offloading, | |
92 | which hurts tiny packet transmission performance. | |
93 | However, | |
94 | if the workload is mainly bulk data | |
95 | or hardware transmission offloading is rarely required, | |
96 | extra transmission queue could be enabled to reduce contention on | |
97 | transmission path. | |
98 | 2 transmission queues will only be used when | |
99 | .Xr polling 4 | |
100 | is enabled on the device. | |
e301539e SZ |
101 | If multiple transmission queues are used, |
102 | the round-robin arbitration is performed among the transmission queues. | |
103 | It should be noted that | |
104 | if both TSO and multiple transmission queues are used, | |
105 | the round-robin arbitration between transmission queues is done | |
106 | at the TSO packet boundary. | |
984263bc | 107 | .Pp |
be871347 SZ |
108 | .\"For questions related to hardware requirements, |
109 | .\"refer to the documentation supplied with your Intel PRO/1000 adapter. | |
110 | .\"All hardware requirements listed apply to use with | |
111 | .\".Dx . | |
112 | .\".Pp | |
984263bc MD |
113 | Support for Jumbo Frames is provided via the interface MTU setting. |
114 | Selecting an MTU larger than 1500 bytes with the | |
115 | .Xr ifconfig 8 | |
116 | utility configures the adapter to receive and transmit Jumbo Frames. | |
604af13b | 117 | The maximum MTU size for Jumbo Frames is 16114. |
984263bc MD |
118 | .Pp |
119 | This driver version supports VLANs. | |
984263bc MD |
120 | The |
121 | .Nm | |
82020495 SW |
122 | and |
123 | .Nm emx | |
124 | drivers support the following media types: | |
984263bc MD |
125 | .Bl -tag -width ".Cm 10baseT/UTP" |
126 | .It Cm autoselect | |
127 | Enables auto-negotiation for speed and duplex. | |
128 | .It Cm 10baseT/UTP | |
129 | Sets 10Mbps operation. | |
130 | Use the | |
131 | .Cm mediaopt | |
132 | option to select | |
133 | .Cm full-duplex | |
134 | mode. | |
135 | .It Cm 100baseTX | |
136 | Sets 100Mbps operation. | |
137 | Use the | |
138 | .Cm mediaopt | |
139 | option to select | |
140 | .Cm full-duplex | |
141 | mode. | |
142 | .It Cm 1000baseSX | |
143 | Sets 1000Mbps operation. | |
144 | Only | |
145 | .Cm full-duplex | |
146 | mode is supported at this speed. | |
829c4df6 | 147 | .It Cm 1000baseT |
984263bc MD |
148 | Sets 1000Mbps operation. |
149 | Only | |
150 | .Cm full-duplex | |
151 | mode is supported at this speed. | |
152 | .El | |
153 | .Pp | |
154 | The | |
155 | .Nm | |
82020495 SW |
156 | and |
157 | .Nm emx | |
158 | drivers support the following media options: | |
984263bc MD |
159 | .Bl -tag -width ".Cm full-duplex" |
160 | .It Cm full-duplex | |
161 | Forces full-duplex operation | |
162 | .It Cm half-duplex | |
163 | Forces half-duplex operation. | |
81ac62f7 SZ |
164 | .It Cm rxpause |
165 | Enable flow control PAUSE reception. | |
166 | This is only supported by | |
167 | .Cm autoselect | |
168 | and | |
169 | .Cm full-duplex | |
170 | mode. | |
171 | .It Cm txpause | |
172 | Enable flow control PAUSE transmission. | |
173 | This is only supported by | |
174 | .Cm autoselect | |
175 | and | |
176 | .Cm full-duplex | |
177 | mode. | |
178 | .It Cm forcepause | |
179 | Force flow control PAUSE operation as configured by | |
180 | .Cm rxpause | |
181 | and | |
182 | .Cm txpause | |
183 | media options. | |
984263bc MD |
184 | .El |
185 | .Pp | |
186 | Only use | |
187 | .Cm mediaopt | |
188 | to set the driver to | |
189 | .Cm full-duplex . | |
190 | If | |
191 | .Cm mediaopt | |
192 | is not specified, the driver defaults to | |
193 | .Cm half-duplex . | |
194 | .Pp | |
195 | For more information on configuring this device, see | |
196 | .Xr ifconfig 8 . | |
82020495 | 197 | .Pp |
d0569bf9 TN |
198 | The |
199 | .Nm | |
82020495 SW |
200 | and |
201 | .Nm emx | |
202 | drivers support | |
d0569bf9 | 203 | .Xr polling 4 . |
604af13b SW |
204 | .Sh HARDWARE |
205 | The | |
206 | .Nm | |
207 | driver supports Gigabit Ethernet adapters based on the Intel | |
208 | 82540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, 82546EB, | |
d5020db1 | 209 | 82546GB, 82547, 82571, 82572, 82573, 82574, I217, I218 and I219 |
4b2f06d6 | 210 | controller chips: |
604af13b SW |
211 | .Pp |
212 | .Bl -bullet -compact | |
213 | .It | |
4b2f06d6 | 214 | Intel 82540EM Gigabit Ethernet Controller |
604af13b | 215 | .It |
4b2f06d6 | 216 | Intel 82540EP Gigabit Ethernet Controller |
604af13b | 217 | .It |
4b2f06d6 | 218 | Intel 82543GC Gigabit Ethernet Controller |
604af13b | 219 | .It |
4b2f06d6 | 220 | Intel 82544EI Gigabit Ethernet Controller |
604af13b | 221 | .It |
74dc3754 SZ |
222 | Intel 82544GC Gigabit Ethernet Controller |
223 | .It | |
4b2f06d6 | 224 | Intel 82545GM Gigabit Ethernet Controller |
604af13b | 225 | .It |
4b2f06d6 | 226 | Intel 82546EB Gigabit Ethernet Controller |
604af13b | 227 | .It |
4b2f06d6 | 228 | Intel 82547GI Gigabit Ethernet Controller |
604af13b | 229 | .It |
4b2f06d6 | 230 | Intel 82567 Gigabit Ethernet Controller |
604af13b | 231 | .It |
4b2f06d6 | 232 | Intel 82571EB Gigabit Ethernet Controller |
604af13b | 233 | .It |
4b2f06d6 | 234 | Intel 82572EI Gigabit Ethernet Controller |
604af13b | 235 | .It |
4b2f06d6 | 236 | Intel 82573E Gigabit Ethernet Controller |
604af13b | 237 | .It |
4b2f06d6 | 238 | Intel 82573L Gigabit Ethernet Controller |
604af13b | 239 | .It |
4b2f06d6 | 240 | Intel 82573V Gigabit Ethernet Controller |
604af13b | 241 | .It |
74dc3754 SZ |
242 | Intel 82574IT Gigabit Ethernet Controller |
243 | .It | |
244 | Intel 82574L Gigabit Ethernet Controller | |
245 | .It | |
246 | Intel 82578DC Gigabit Ethernet PHY | |
247 | .It | |
248 | Intel 82578DM Gigabit Ethernet PHY | |
604af13b | 249 | .It |
74dc3754 | 250 | Intel 82579LM Gigabit Ethernet PHY |
604af13b | 251 | .It |
74dc3754 | 252 | Intel 82579V Gigabit Ethernet PHY |
604af13b | 253 | .It |
4b2f06d6 | 254 | Intel Ethernet Connection I217-LM |
604af13b | 255 | .It |
4b2f06d6 | 256 | Intel Ethernet Connection I217-V |
604af13b | 257 | .It |
4b2f06d6 | 258 | Intel Ethernet Connection I218-LM |
604af13b | 259 | .It |
4b2f06d6 | 260 | Intel Ethernet Connection I218-V |
604af13b | 261 | .It |
d5020db1 SW |
262 | Intel Ethernet Connection I219-LM |
263 | .It | |
264 | Intel Ethernet Connection I219-V | |
265 | .It | |
4b2f06d6 SZ |
266 | Intel Gigabit CT Desktop Adapter |
267 | .It | |
268 | Intel PRO/1000 F Server Adapter | |
269 | .It | |
4b2f06d6 SZ |
270 | Intel PRO/1000 MF Dual Port Server Adapter |
271 | .It | |
272 | Intel PRO/1000 MF Server Adapter | |
273 | .It | |
274 | Intel PRO/1000 MF Server Adapter (LX) | |
275 | .It | |
276 | Intel PRO/1000 MT Dual Port Server Adapter | |
277 | .It | |
278 | Intel PRO/1000 MT Quad Port Server Adapter | |
279 | .It | |
4b2f06d6 SZ |
280 | Intel PRO/1000 PF Dual Port Server Adapter |
281 | .It | |
4b2f06d6 SZ |
282 | Intel PRO/1000 PT Dual Port Server Adapter |
283 | .It | |
284 | Intel PRO/1000 PT Quad Port Low Profile Server Adapter | |
285 | .It | |
286 | Intel PRO/1000 PT Quad Port Server Adapter | |
287 | .It | |
4b2f06d6 SZ |
288 | Intel PRO/1000 T Server Adapter |
289 | .It | |
290 | Intel PRO/1000 XT Low Profile Server Adapter | |
291 | .It | |
3aa08cba | 292 | Intel PRO/1000 XT Server Adapter |
604af13b | 293 | .El |
82020495 SW |
294 | .Pp |
295 | The | |
296 | .Nm emx | |
297 | driver supports Gigabit Ethernet adapters based on the Intel | |
d5020db1 | 298 | 82571, 82572, 82573, 82574, I217, I218 and I219 controller chips. |
be871347 | 299 | .Sh TUNABLES |
604af13b SW |
300 | Tunables can be set at the |
301 | .Xr loader 8 | |
302 | prompt before booting the kernel or stored in | |
303 | .Xr loader.conf 5 . | |
be871347 SZ |
304 | .Em Y |
305 | is the device unit number. | |
306 | .Bl -tag -width "hw.em.int_throttle_ceil" | |
c08223a6 SW |
307 | .It Va hw.em.int_throttle_ceil |
308 | Hardware interrupt throttling rate. | |
be871347 SZ |
309 | The default value is 6000Hz. |
310 | This tunable also applies to | |
311 | .Nm emx . | |
312 | .Nm emx | |
313 | has a per device tunable | |
314 | .Va hw.emxY.int_throttle_ceil , | |
315 | which serves the same purpose. | |
7bc27c52 SW |
316 | .It Va hw.em.rxd |
317 | Number of receive descriptors allocated by the driver. | |
be871347 | 318 | The default value is 512. |
7bc27c52 SW |
319 | The 82542 and 82543-based adapters can handle up to 256 descriptors, |
320 | while others can have up to 4096. | |
be871347 SZ |
321 | This tunable also applies to |
322 | .Nm emx . | |
323 | .Nm emx | |
324 | has a per device tunable | |
325 | .Va hw.emxY.rxd , | |
326 | which serves the same purpose. | |
7bc27c52 SW |
327 | .It Va hw.em.txd |
328 | Number of transmit descriptors allocated by the driver. | |
be871347 | 329 | The default value is 512. |
7bc27c52 SW |
330 | The 82542 and 82543-based adapters can handle up to 256 descriptors, |
331 | while others can have up to 4096. | |
be871347 SZ |
332 | This tunable also applies to |
333 | .Nm emx . | |
334 | .Nm emx | |
335 | has a per device tunable | |
336 | .Va hw.emxY.txd , | |
337 | which serves the same purpose. | |
338 | .It Va hw.em.msi.enable Va hw.emY.msi.enable | |
339 | By default, the driver will use MSI if it is supported. | |
340 | This behavior can be turned off by setting these tunable to 0. | |
341 | These tunables also applies to | |
342 | .Nm emx . | |
343 | .It Va hw.emY.msi.cpu | |
344 | If MSI is used, | |
345 | it specifies the MSI's target CPU. | |
346 | This tunable also applies to | |
347 | .Nm emx . | |
348 | .It Va hw.emY.irq.unshared | |
349 | If legacy interrupt is used, | |
350 | by default, | |
351 | the driver assumes the interrupt could be shared. | |
352 | Setting this tunable to 1 allows the driver to | |
353 | perform certain optimization based on the knowledge | |
354 | that the interrupt is not shared. | |
355 | These tunables also applies to | |
356 | .Nm emx . | |
81ac62f7 SZ |
357 | .It Va hw.em.flow_ctrl Va hw.emY.flow_ctrl |
358 | The default flow control settings. | |
359 | Supported values are: | |
360 | rxpause (only enable PAUSE reception), | |
361 | txpause (only enable PAUSE transmission), | |
362 | full (enable PAUSE reception and transmission), | |
363 | none (disable flow control PAUSE operation), | |
364 | force-rxpause (force PAUSE reception), | |
365 | force-txpause (force PAUSE transmission), | |
366 | force-full (forcefully enable PAUSE reception and transmission), | |
367 | force-none (forcefully disable flow control PAUSE operation). | |
fd291c1a | 368 | Default is none. |
81ac62f7 SZ |
369 | These tunables also applies to |
370 | .Nm emx . | |
be871347 SZ |
371 | .It Va hw.emx.rxr Va hw.emxY.rxr |
372 | This tunable specifies the number of reception queues could be enabled. | |
373 | Maximum allowed value for these tunables is 2. | |
374 | Setting these tunables to 0 allows the driver to enable reception | |
375 | queues based on the number of CPUs. | |
376 | The default value is 0. | |
377 | .It Va hw.emx.txr Va hw.emxY.txr | |
378 | These tunables only take effect on 82571 and 82572. | |
379 | This tunable specifies the number of transmission queues could be enabled. | |
380 | Maximum allowed value for these tunables is 2. | |
381 | Setting these tunables to 0 allows the driver to enable transmission | |
382 | queues based on the number of CPUs. | |
383 | The default value is 1. | |
be871347 SZ |
384 | .El |
385 | .Sh MIB Variables | |
386 | A number of per-interface variables are implemented in the | |
26595b18 | 387 | .Va dev.emx. Ns Em Y |
be871347 | 388 | or |
26595b18 | 389 | .Va dev.em. Ns Em Y |
be871347 SZ |
390 | branch of the |
391 | .Xr sysctl 3 | |
392 | MIB. | |
393 | .Bl -tag -width "int_throttle_ceil" | |
394 | .It Va rxd | |
395 | Number of reception descriptors enabled (read-only). | |
396 | Use the tunable | |
397 | .Va hw.em.rxd | |
398 | or | |
399 | .Va hw.emY.rxd | |
400 | to configure it. | |
401 | .It Va txd | |
402 | Number of transmission descriptors enabled (read-only). | |
403 | Use the tunable | |
404 | .Va hw.em.txd | |
405 | or | |
406 | .Va hw.emY.txd | |
407 | to configure it. | |
408 | .It Va int_throttle_ceil | |
409 | See the tunable | |
410 | .Va hw.em.int_throttle_ceil . | |
411 | .It Va int_tx_nsegs | |
19bc33b2 SZ |
412 | This value controls how many transmit descriptors should be consumed |
413 | by the hardware before the hardware generates a transmit interrupt. | |
414 | The default value is 1/16 of the number of transmit descriptors. | |
7bc27c52 | 415 | If |
19bc33b2 SZ |
416 | .Xr polling 4 |
417 | is not used on the hardware and | |
418 | the major part of the transmitted data are bulk data, | |
419 | this value could safely be set to 1/2 of the number of transmit descriptors. | |
be871347 SZ |
420 | .It Va tx_wreg_nsegs |
421 | The number of transmission descriptors should be setup | |
422 | before the hardware register is written. | |
423 | Setting this value too high will have negative effect | |
424 | on transmission timeliness. | |
425 | Setting this value too low will hurt overall transmission due to | |
426 | the frequent hardware register writing. | |
427 | Default value is 8. | |
428 | .It Va rx_ring_cnt | |
f734ea4b | 429 | Number of reception queues enabled (read-only). |
be871347 SZ |
430 | This sysctl only applies to |
431 | .Nm emx . | |
432 | Use the tunable | |
433 | .Va hw.emx.rxr | |
434 | or | |
435 | .Va hw.emxY.rxr | |
436 | to configure it. | |
437 | .It Va tx_ring_cnt | |
f734ea4b | 438 | Number of transmission queues that can be enabled (read-only). |
be871347 SZ |
439 | This sysctl only applies to |
440 | .Nm emx . | |
441 | Use the tunable | |
442 | .Va hw.emx.txr | |
443 | or | |
444 | .Va hw.emxY.txr | |
445 | to configure it. | |
446 | .It Va tx_ring_inuse | |
447 | Number of transmission queues being used (read-only). | |
448 | This sysctl only applies to | |
449 | .Nm emx . | |
7bc27c52 | 450 | .El |
be871347 SZ |
451 | .\".Sh SUPPORT |
452 | .\"For general information and support, | |
453 | .\"go to the Intel support website at: | |
454 | .\".Pa http://support.intel.com . | |
82020495 | 455 | .\".Pp |
be871347 SZ |
456 | .\"If an issue is identified with the released source code on the supported kernel |
457 | .\"with a supported adapter, email the specific information related to the | |
458 | .\"issue to | |
b2a6f486 | 459 | .\".Aq Mt freebsdnic@mailbox.intel.com . |
984263bc MD |
460 | .Sh SEE ALSO |
461 | .Xr arp 4 , | |
8985f72f | 462 | .Xr ifmedia 4 , |
984263bc MD |
463 | .Xr netintro 4 , |
464 | .Xr ng_ether 4 , | |
01fe1724 | 465 | .Xr polling 4 , |
984263bc MD |
466 | .Xr vlan 4 , |
467 | .Xr ifconfig 8 | |
468 | .Sh HISTORY | |
469 | The | |
470 | .Nm | |
471 | device driver first appeared in | |
82020495 SW |
472 | .Fx 4.4 |
473 | and the | |
474 | .Nm emx | |
475 | driver first appeared in | |
476 | .Dx 2.3 . | |
984263bc | 477 | .Sh AUTHORS |
82020495 | 478 | .An -nosplit |
984263bc MD |
479 | The |
480 | .Nm | |
481 | driver was written by | |
b2a6f486 | 482 | .An Intel Corporation Aq Mt freebsdnic@mailbox.intel.com . |
82020495 SW |
483 | .Pp |
484 | The | |
485 | .Nm emx | |
486 | driver was written by | |
487 | .An Sepherosa Ziehau | |
488 | (in parts based on | |
489 | .Tn Intel Ap s ) . |