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 December 17, 2017 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 82544EI Gigabit Ethernet Controller 221.It 222Intel 82544GC Gigabit Ethernet Controller 223.It 224Intel 82545GM Gigabit Ethernet Controller 225.It 226Intel 82546EB Gigabit Ethernet Controller 227.It 228Intel 82547GI Gigabit Ethernet Controller 229.It 230Intel 82567 Gigabit Ethernet Controller 231.It 232Intel 82571EB Gigabit Ethernet Controller 233.It 234Intel 82572EI Gigabit Ethernet Controller 235.It 236Intel 82573E Gigabit Ethernet Controller 237.It 238Intel 82573L Gigabit Ethernet Controller 239.It 240Intel 82573V Gigabit Ethernet Controller 241.It 242Intel 82574IT Gigabit Ethernet Controller 243.It 244Intel 82574L Gigabit Ethernet Controller 245.It 246Intel 82578DC Gigabit Ethernet PHY 247.It 248Intel 82578DM Gigabit Ethernet PHY 249.It 250Intel 82579LM Gigabit Ethernet PHY 251.It 252Intel 82579V Gigabit Ethernet PHY 253.It 254Intel Ethernet Connection I217-LM 255.It 256Intel Ethernet Connection I217-V 257.It 258Intel Ethernet Connection I218-LM 259.It 260Intel Ethernet Connection I218-V 261.It 262Intel Ethernet Connection I219-LM 263.It 264Intel Ethernet Connection I219-V 265.It 266Intel Gigabit CT Desktop Adapter 267.It 268Intel PRO/1000 F Server Adapter 269.It 270Intel PRO/1000 MF Dual Port Server Adapter 271.It 272Intel PRO/1000 MF Server Adapter 273.It 274Intel PRO/1000 MF Server Adapter (LX) 275.It 276Intel PRO/1000 MT Dual Port Server Adapter 277.It 278Intel PRO/1000 MT Quad Port Server Adapter 279.It 280Intel PRO/1000 PF Dual Port Server Adapter 281.It 282Intel PRO/1000 PT Dual Port Server Adapter 283.It 284Intel PRO/1000 PT Quad Port Low Profile Server Adapter 285.It 286Intel PRO/1000 PT Quad Port Server Adapter 287.It 288Intel PRO/1000 T Server Adapter 289.It 290Intel PRO/1000 XT Low Profile Server Adapter 291.It 292Intel PRO/1000 XT Server Adapter 293.El 294.Pp 295The 296.Nm emx 297driver supports Gigabit Ethernet adapters based on the Intel 29882571, 82572, 82573, 82574, I217, I218 and I219 controller chips. 299.Sh TUNABLES 300Tunables can be set at the 301.Xr loader 8 302prompt before booting the kernel or stored in 303.Xr loader.conf 5 . 304.Em Y 305is the device unit number. 306.Bl -tag -width "hw.em.int_throttle_ceil" 307.It Va hw.em.int_throttle_ceil 308Hardware interrupt throttling rate. 309The default value is 6000Hz. 310This tunable also applies to 311.Nm emx . 312.Nm emx 313has a per device tunable 314.Va hw.emxY.int_throttle_ceil , 315which serves the same purpose. 316.It Va hw.em.rxd 317Number of receive descriptors allocated by the driver. 318The default value is 512. 319The 82542 and 82543-based adapters can handle up to 256 descriptors, 320while others can have up to 4096. 321This tunable also applies to 322.Nm emx . 323.Nm emx 324has a per device tunable 325.Va hw.emxY.rxd , 326which serves the same purpose. 327.It Va hw.em.txd 328Number of transmit descriptors allocated by the driver. 329The default value is 512. 330The 82542 and 82543-based adapters can handle up to 256 descriptors, 331while others can have up to 4096. 332This tunable also applies to 333.Nm emx . 334.Nm emx 335has a per device tunable 336.Va hw.emxY.txd , 337which serves the same purpose. 338.It Va hw.em.msi.enable Va hw.emY.msi.enable 339By default, the driver will use MSI if it is supported. 340This behavior can be turned off by setting these tunable to 0. 341These tunables also applies to 342.Nm emx . 343.It Va hw.emY.msi.cpu 344If MSI is used, 345it specifies the MSI's target CPU. 346This tunable also applies to 347.Nm emx . 348.It Va hw.emY.irq.unshared 349If legacy interrupt is used, 350by default, 351the driver assumes the interrupt could be shared. 352Setting this tunable to 1 allows the driver to 353perform certain optimization based on the knowledge 354that the interrupt is not shared. 355These tunables also applies to 356.Nm emx . 357.It Va hw.em.flow_ctrl Va hw.emY.flow_ctrl 358The default flow control settings. 359Supported values are: 360rxpause (only enable PAUSE reception), 361txpause (only enable PAUSE transmission), 362full (enable PAUSE reception and transmission), 363none (disable flow control PAUSE operation), 364force-rxpause (force PAUSE reception), 365force-txpause (force PAUSE transmission), 366force-full (forcefully enable PAUSE reception and transmission), 367force-none (forcefully disable flow control PAUSE operation). 368Default is none. 369These tunables also applies to 370.Nm emx . 371.It Va hw.emx.rxr Va hw.emxY.rxr 372This tunable specifies the number of reception queues could be enabled. 373Maximum allowed value for these tunables is 2. 374Setting these tunables to 0 allows the driver to enable reception 375queues based on the number of CPUs. 376The default value is 0. 377.It Va hw.emx.txr Va hw.emxY.txr 378These tunables only take effect on 82571 and 82572. 379This tunable specifies the number of transmission queues could be enabled. 380Maximum allowed value for these tunables is 2. 381Setting these tunables to 0 allows the driver to enable transmission 382queues based on the number of CPUs. 383The default value is 1. 384.El 385.Sh MIB Variables 386A number of per-interface variables are implemented in the 387.Va dev.emx. Ns Em Y 388or 389.Va dev.em. Ns Em Y 390branch of the 391.Xr sysctl 3 392MIB. 393.Bl -tag -width "int_throttle_ceil" 394.It Va rxd 395Number of reception descriptors enabled (read-only). 396Use the tunable 397.Va hw.em.rxd 398or 399.Va hw.emY.rxd 400to configure it. 401.It Va txd 402Number of transmission descriptors enabled (read-only). 403Use the tunable 404.Va hw.em.txd 405or 406.Va hw.emY.txd 407to configure it. 408.It Va int_throttle_ceil 409See the tunable 410.Va hw.em.int_throttle_ceil . 411.It Va int_tx_nsegs 412This value controls how many transmit descriptors should be consumed 413by the hardware before the hardware generates a transmit interrupt. 414The default value is 1/16 of the number of transmit descriptors. 415If 416.Xr polling 4 417is not used on the hardware and 418the major part of the transmitted data are bulk data, 419this value could safely be set to 1/2 of the number of transmit descriptors. 420.It Va tx_wreg_nsegs 421The number of transmission descriptors should be setup 422before the hardware register is written. 423Setting this value too high will have negative effect 424on transmission timeliness. 425Setting this value too low will hurt overall transmission due to 426the frequent hardware register writing. 427Default value is 8. 428.It Va rx_ring_cnt 429Number of reception queues enabled (read-only). 430This sysctl only applies to 431.Nm emx . 432Use the tunable 433.Va hw.emx.rxr 434or 435.Va hw.emxY.rxr 436to configure it. 437.It Va tx_ring_cnt 438Number of transmission queues that can be enabled (read-only). 439This sysctl only applies to 440.Nm emx . 441Use the tunable 442.Va hw.emx.txr 443or 444.Va hw.emxY.txr 445to configure it. 446.It Va tx_ring_inuse 447Number of transmission queues being used (read-only). 448This sysctl only applies to 449.Nm emx . 450.El 451.\".Sh SUPPORT 452.\"For general information and support, 453.\"go to the Intel support website at: 454.\".Pa http://support.intel.com . 455.\".Pp 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 459.\".Aq Mt freebsdnic@mailbox.intel.com . 460.Sh SEE ALSO 461.Xr arp 4 , 462.Xr ifmedia 4 , 463.Xr netintro 4 , 464.Xr ng_ether 4 , 465.Xr polling 4 , 466.Xr vlan 4 , 467.Xr ifconfig 8 468.Sh HISTORY 469The 470.Nm 471device driver first appeared in 472.Fx 4.4 473and the 474.Nm emx 475driver first appeared in 476.Dx 2.3 . 477.Sh AUTHORS 478.An -nosplit 479The 480.Nm 481driver was written by 482.An Intel Corporation Aq Mt freebsdnic@mailbox.intel.com . 483.Pp 484The 485.Nm emx 486driver was written by 487.An Sepherosa Ziehau 488(in parts based on 489.Tn Intel Ap s ) . 490