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