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 May 26, 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 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 none. 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.El 391.Sh MIB Variables 392A number of per-interface variables are implemented in the 393.Va dev.emx. Ns Em Y 394or 395.Va dev.em. Ns Em Y 396branch of the 397.Xr sysctl 3 398MIB. 399.Bl -tag -width "int_throttle_ceil" 400.It Va rxd 401Number of reception descriptors enabled (read-only). 402Use the tunable 403.Va hw.em.rxd 404or 405.Va hw.emY.rxd 406to configure it. 407.It Va txd 408Number of transmission descriptors enabled (read-only). 409Use the tunable 410.Va hw.em.txd 411or 412.Va hw.emY.txd 413to configure it. 414.It Va int_throttle_ceil 415See the tunable 416.Va hw.em.int_throttle_ceil . 417.It Va int_tx_nsegs 418This value controls how many transmit descriptors should be consumed 419by the hardware before the hardware generates a transmit interrupt. 420The default value is 1/16 of the number of transmit descriptors. 421If 422.Xr polling 4 423is not used on the hardware and 424the major part of the transmitted data are bulk data, 425this value could safely be set to 1/2 of the number of transmit descriptors. 426.It Va tx_wreg_nsegs 427The number of transmission descriptors should be setup 428before the hardware register is written. 429Setting this value too high will have negative effect 430on transmission timeliness. 431Setting this value too low will hurt overall transmission due to 432the frequent hardware register writing. 433Default value is 8. 434.It Va rx_ring_cnt 435Number of reception queues enabled (read-only). 436This sysctl only applies to 437.Nm emx . 438Use the tunable 439.Va hw.emx.rxr 440or 441.Va hw.emxY.rxr 442to configure it. 443.It Va tx_ring_cnt 444Number of transmission queues that can be enabled (read-only). 445This sysctl only applies to 446.Nm emx . 447Use the tunable 448.Va hw.emx.txr 449or 450.Va hw.emxY.txr 451to configure it. 452.It Va tx_ring_inuse 453Number of transmission queues being used (read-only). 454This sysctl only applies to 455.Nm emx . 456.El 457.\".Sh SUPPORT 458.\"For general information and support, 459.\"go to the Intel support website at: 460.\".Pa http://support.intel.com . 461.\".Pp 462.\"If an issue is identified with the released source code on the supported kernel 463.\"with a supported adapter, email the specific information related to the 464.\"issue to 465.\".Aq Mt freebsdnic@mailbox.intel.com . 466.Sh SEE ALSO 467.Xr arp 4 , 468.Xr ifmedia 4 , 469.Xr netintro 4 , 470.Xr ng_ether 4 , 471.Xr polling 4 , 472.Xr vlan 4 , 473.Xr ifconfig 8 474.Sh HISTORY 475The 476.Nm 477device driver first appeared in 478.Fx 4.4 479and the 480.Nm emx 481driver first appeared in 482.Dx 2.3 . 483.Sh AUTHORS 484.An -nosplit 485The 486.Nm 487driver was written by 488.An Intel Corporation Aq Mt freebsdnic@mailbox.intel.com . 489.Pp 490The 491.Nm emx 492driver was written by 493.An Sepherosa Ziehau 494(in parts based on 495.Tn Intel Ap s ) . 496