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 September 4, 2013 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 and I218 65Ethernet 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 and I218 Ethernet controller chips 75that additionally supports Receive Side Scaling (RSS, 2 reception queues). 76By default, 77the 78.Nm emx 79driver will try enabling 2 reception queues 80if there are multiple CPUs on the system. 81For 82571 and 82572, 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. 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. 106.Pp 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 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. 116The maximum MTU size for Jumbo Frames is 16114. 117.Pp 118This driver version supports VLANs. 119The 120.Nm 121and 122.Nm emx 123drivers support the following media types: 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. 146.It Cm 1000baseT 147Sets 1000Mbps operation. 148Only 149.Cm full-duplex 150mode is supported at this speed. 151.El 152.Pp 153The 154.Nm 155and 156.Nm emx 157drivers support the following media options: 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 . 176.Pp 177The 178.Nm 179and 180.Nm emx 181drivers support 182.Xr polling 4 . 183.Sh HARDWARE 184The 185.Nm 186driver supports Gigabit Ethernet adapters based on the Intel 18782540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, 82546EB, 18882546GB, 82547, 82571, 82572, 82573, 82574, I217 and I218 189controller chips: 190.Pp 191.Bl -bullet -compact 192.It 193Intel 82540EM Gigabit Ethernet Controller 194.It 195Intel 82540EP Gigabit Ethernet Controller 196.It 197Intel 82543GC Gigabit Ethernet Controller 198.It 199Intel 82544 Gigabit Ethernet Controller 200.It 201Intel 82544EI Gigabit Ethernet Controller 202.It 203Intel 82545GM Gigabit Ethernet Controller 204.It 205Intel 82546EB Gigabit Ethernet Controller 206.It 207Intel 82547EI Gigabit Ethernet Controller 208.It 209Intel 82547GI Gigabit Ethernet Controller 210.It 211Intel 82567 Gigabit Ethernet Controller 212.It 213Intel 82571EB Gigabit Ethernet Controller 214.It 215Intel 82572EI Gigabit Ethernet Controller 216.It 217Intel 82573E Gigabit Ethernet Controller 218.It 219Intel 82573L Gigabit Ethernet Controller 220.It 221Intel 82573V Gigabit Ethernet Controller 222.It 223Intel 82574 Gigabit Ethernet Controller 224.It 225Intel 82578 Gigabit Ethernet PHY 226.It 227Intel 82579 Gigabit Ethernet Controller 228.It 229Intel Ethernet Connection I217-LM 230.It 231Intel Ethernet Connection I217-V 232.It 233Intel Ethernet Connection I218-LM 234.It 235Intel Ethernet Connection I218-V 236.It 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 273Intel PRO/1000 XT Server Adapter 274.El 275.Pp 276The 277.Nm emx 278driver supports Gigabit Ethernet adapters based on the Intel 27982571, 82572, 82573, 82574, I217 and I218 controller chips. 280.Sh TUNABLES 281Tunables can be set at the 282.Xr loader 8 283prompt before booting the kernel or stored in 284.Xr loader.conf 5 . 285.Em Y 286is the device unit number. 287.Bl -tag -width "hw.em.int_throttle_ceil" 288.It Va hw.em.int_throttle_ceil 289Hardware interrupt throttling rate. 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. 297.It Va hw.em.rxd 298Number of receive descriptors allocated by the driver. 299The default value is 512. 300The 82542 and 82543-based adapters can handle up to 256 descriptors, 301while others can have up to 4096. 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. 308.It Va hw.em.txd 309Number of transmit descriptors allocated by the driver. 310The default value is 512. 311The 82542 and 82543-based adapters can handle up to 256 descriptors, 312while others can have up to 4096. 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 367.Va hw.emx Ns Em Y 368or 369.Va hw.em Ns Em Y 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 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. 395If 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. 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 409Number of reception queues enabled (read-only). 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 418Number of transmission queues that can be enabled (read-only). 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 . 446.El 447.\".Sh SUPPORT 448.\"For general information and support, 449.\"go to the Intel support website at: 450.\".Pa http://support.intel.com . 451.\".Pp 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 455.\".Aq Mt freebsdnic@mailbox.intel.com . 456.Sh SEE ALSO 457.Xr arp 4 , 458.Xr ifmedia 4 , 459.Xr netintro 4 , 460.Xr ng_ether 4 , 461.Xr polling 4 , 462.Xr vlan 4 , 463.Xr ifconfig 8 464.Sh HISTORY 465The 466.Nm 467device driver first appeared in 468.Fx 4.4 469and the 470.Nm emx 471driver first appeared in 472.Dx 2.3 . 473.Sh AUTHORS 474.An -nosplit 475The 476.Nm 477driver was written by 478.An Intel Corporation Aq Mt freebsdnic@mailbox.intel.com . 479.Pp 480The 481.Nm emx 482driver was written by 483.An Sepherosa Ziehau 484(in parts based on 485.Tn Intel Ap s ) . 486