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 November 26, 2015 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, 82572, 82574, I217 and I218 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.It Cm rxpause 164Enable flow control PAUSE reception. 165This is only supported by 166.Cm autoselect 167and 168.Cm full-duplex 169mode. 170.It Cm txpause 171Enable flow control PAUSE transmission. 172This is only supported by 173.Cm autoselect 174and 175.Cm full-duplex 176mode. 177.It Cm forcepause 178Force flow control PAUSE operation as configured by 179.Cm rxpause 180and 181.Cm txpause 182media options. 183.El 184.Pp 185Only use 186.Cm mediaopt 187to set the driver to 188.Cm full-duplex . 189If 190.Cm mediaopt 191is not specified, the driver defaults to 192.Cm half-duplex . 193.Pp 194For more information on configuring this device, see 195.Xr ifconfig 8 . 196.Pp 197The 198.Nm 199and 200.Nm emx 201drivers support 202.Xr polling 4 . 203.Sh HARDWARE 204The 205.Nm 206driver supports Gigabit Ethernet adapters based on the Intel 20782540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, 82546EB, 20882546GB, 82547, 82571, 82572, 82573, 82574, I217 and I218 209controller chips: 210.Pp 211.Bl -bullet -compact 212.It 213Intel 82540EM Gigabit Ethernet Controller 214.It 215Intel 82540EP Gigabit Ethernet Controller 216.It 217Intel 82543GC Gigabit Ethernet Controller 218.It 219Intel 82544 Gigabit Ethernet Controller 220.It 221Intel 82544EI Gigabit Ethernet Controller 222.It 223Intel 82545GM Gigabit Ethernet Controller 224.It 225Intel 82546EB Gigabit Ethernet Controller 226.It 227Intel 82547EI Gigabit Ethernet Controller 228.It 229Intel 82547GI Gigabit Ethernet Controller 230.It 231Intel 82567 Gigabit Ethernet Controller 232.It 233Intel 82571EB Gigabit Ethernet Controller 234.It 235Intel 82572EI Gigabit Ethernet Controller 236.It 237Intel 82573E Gigabit Ethernet Controller 238.It 239Intel 82573L Gigabit Ethernet Controller 240.It 241Intel 82573V Gigabit Ethernet Controller 242.It 243Intel 82574 Gigabit Ethernet Controller 244.It 245Intel 82578 Gigabit Ethernet PHY 246.It 247Intel 82579 Gigabit Ethernet Controller 248.It 249Intel Ethernet Connection I217-LM 250.It 251Intel Ethernet Connection I217-V 252.It 253Intel Ethernet Connection I218-LM 254.It 255Intel Ethernet Connection I218-V 256.It 257Intel Gigabit CT Desktop Adapter 258.It 259Intel PRO/1000 F Server Adapter 260.It 261Intel PRO/1000 GT Quad Port Server Adapter 262.It 263Intel PRO/1000 MF Dual Port Server Adapter 264.It 265Intel PRO/1000 MF Server Adapter 266.It 267Intel PRO/1000 MF Server Adapter (LX) 268.It 269Intel PRO/1000 MT Dual Port Server Adapter 270.It 271Intel PRO/1000 MT Quad Port Server Adapter 272.It 273Intel PRO/1000 MT Server Adapter 274.It 275Intel PRO/1000 PF Dual Port Server Adapter 276.It 277Intel PRO/1000 PF Quad Port Server Adapter 278.It 279Intel PRO/1000 PF Server Adapter 280.It 281Intel PRO/1000 PT Dual Port Server Adapter 282.It 283Intel PRO/1000 PT Quad Port Low Profile Server Adapter 284.It 285Intel PRO/1000 PT Quad Port Server Adapter 286.It 287Intel PRO/1000 PT Server Adapter 288.It 289Intel PRO/1000 T Server Adapter 290.It 291Intel PRO/1000 XT Low Profile Server Adapter 292.It 293Intel PRO/1000 XT Server Adapter 294.El 295.Pp 296The 297.Nm emx 298driver supports Gigabit Ethernet adapters based on the Intel 29982571, 82572, 82573, 82574, I217 and I218 controller chips. 300.Sh TUNABLES 301Tunables can be set at the 302.Xr loader 8 303prompt before booting the kernel or stored in 304.Xr loader.conf 5 . 305.Em Y 306is the device unit number. 307.Bl -tag -width "hw.em.int_throttle_ceil" 308.It Va hw.em.int_throttle_ceil 309Hardware interrupt throttling rate. 310The default value is 6000Hz. 311This tunable also applies to 312.Nm emx . 313.Nm emx 314has a per device tunable 315.Va hw.emxY.int_throttle_ceil , 316which serves the same purpose. 317.It Va hw.em.rxd 318Number of receive descriptors allocated by the driver. 319The default value is 512. 320The 82542 and 82543-based adapters can handle up to 256 descriptors, 321while others can have up to 4096. 322This tunable also applies to 323.Nm emx . 324.Nm emx 325has a per device tunable 326.Va hw.emxY.rxd , 327which serves the same purpose. 328.It Va hw.em.txd 329Number of transmit descriptors allocated by the driver. 330The default value is 512. 331The 82542 and 82543-based adapters can handle up to 256 descriptors, 332while others can have up to 4096. 333This tunable also applies to 334.Nm emx . 335.Nm emx 336has a per device tunable 337.Va hw.emxY.txd , 338which serves the same purpose. 339.It Va hw.em.msi.enable Va hw.emY.msi.enable 340By default, the driver will use MSI if it is supported. 341This behavior can be turned off by setting these tunable to 0. 342These tunables also applies to 343.Nm emx . 344.It Va hw.emY.msi.cpu 345If MSI is used, 346it specifies the MSI's target CPU. 347This tunable also applies to 348.Nm emx . 349.It Va hw.emY.irq.unshared 350If legacy interrupt is used, 351by default, 352the driver assumes the interrupt could be shared. 353Setting this tunable to 1 allows the driver to 354perform certain optimization based on the knowledge 355that the interrupt is not shared. 356These tunables also applies to 357.Nm emx . 358.It Va hw.em.flow_ctrl Va hw.emY.flow_ctrl 359The default flow control settings. 360Supported values are: 361rxpause (only enable PAUSE reception), 362txpause (only enable PAUSE transmission), 363full (enable PAUSE reception and transmission), 364none (disable flow control PAUSE operation), 365force-rxpause (force PAUSE reception), 366force-txpause (force PAUSE transmission), 367force-full (forcefully enable PAUSE reception and transmission), 368force-none (forcefully disable flow control PAUSE operation). 369Default is rxpause. 370These tunables also applies to 371.Nm emx . 372.It Va hw.emx.rxr Va hw.emxY.rxr 373This tunable specifies the number of reception queues could be enabled. 374Maximum allowed value for these tunables is 2. 375Setting these tunables to 0 allows the driver to enable reception 376queues based on the number of CPUs. 377The default value is 0. 378.It Va hw.emx.txr Va hw.emxY.txr 379These tunables only take effect on 82571 and 82572. 380This tunable specifies the number of transmission queues could be enabled. 381Maximum allowed value for these tunables is 2. 382Setting these tunables to 0 allows the driver to enable transmission 383queues based on the number of CPUs. 384The default value is 1. 385.It Va hw.emxY.npoll.rxoff 386This tunable specifies the leading target CPU for reception queues 387.Xr polling 4 388processing. 389The value specificed must be aligned to the number of reception queues enabled 390and must be less than the power of 2 number of CPUs. 391.It Va hw.emxY.npoll.rxoff 392This tunable specifies the leading target CPU for transmission queues 393.Xr polling 4 394processing. 395The value specificed must be aligned to the number of transmission queues 396enabled 397and must be less than the power of 2 number of CPUs. 398.El 399.Sh MIB Variables 400A number of per-interface variables are implemented in the 401.Va dev.emx. Ns Em Y 402or 403.Va dev.em. Ns Em Y 404branch of the 405.Xr sysctl 3 406MIB. 407.Bl -tag -width "int_throttle_ceil" 408.It Va rxd 409Number of reception descriptors enabled (read-only). 410Use the tunable 411.Va hw.em.rxd 412or 413.Va hw.emY.rxd 414to configure it. 415.It Va txd 416Number of transmission descriptors enabled (read-only). 417Use the tunable 418.Va hw.em.txd 419or 420.Va hw.emY.txd 421to configure it. 422.It Va int_throttle_ceil 423See the tunable 424.Va hw.em.int_throttle_ceil . 425.It Va int_tx_nsegs 426This value controls how many transmit descriptors should be consumed 427by the hardware before the hardware generates a transmit interrupt. 428The default value is 1/16 of the number of transmit descriptors. 429If 430.Xr polling 4 431is not used on the hardware and 432the major part of the transmitted data are bulk data, 433this value could safely be set to 1/2 of the number of transmit descriptors. 434.It Va tx_wreg_nsegs 435The number of transmission descriptors should be setup 436before the hardware register is written. 437Setting this value too high will have negative effect 438on transmission timeliness. 439Setting this value too low will hurt overall transmission due to 440the frequent hardware register writing. 441Default value is 8. 442.It Va rx_ring_cnt 443Number of reception queues enabled (read-only). 444This sysctl only applies to 445.Nm emx . 446Use the tunable 447.Va hw.emx.rxr 448or 449.Va hw.emxY.rxr 450to configure it. 451.It Va tx_ring_cnt 452Number of transmission queues that can be enabled (read-only). 453This sysctl only applies to 454.Nm emx . 455Use the tunable 456.Va hw.emx.txr 457or 458.Va hw.emxY.txr 459to configure it. 460.It Va tx_ring_inuse 461Number of transmission queues being used (read-only). 462This sysctl only applies to 463.Nm emx . 464.It Va npoll_rxoff 465See the tunable 466.Va hw.emxY.npoll.rxoff . 467The set value will take effect the next time 468.Xr polling 4 469is enabled on the device. 470This sysctl only applies to 471.Nm emx . 472.It Va npoll_txoff 473See the tunable 474.Va hw.emxY.npoll.txoff . 475The set value will take effect the next time 476.Xr polling 4 477is enabled on the device. 478This sysctl only applies to 479.Nm emx . 480.El 481.\".Sh SUPPORT 482.\"For general information and support, 483.\"go to the Intel support website at: 484.\".Pa http://support.intel.com . 485.\".Pp 486.\"If an issue is identified with the released source code on the supported kernel 487.\"with a supported adapter, email the specific information related to the 488.\"issue to 489.\".Aq Mt freebsdnic@mailbox.intel.com . 490.Sh SEE ALSO 491.Xr arp 4 , 492.Xr ifmedia 4 , 493.Xr netintro 4 , 494.Xr ng_ether 4 , 495.Xr polling 4 , 496.Xr vlan 4 , 497.Xr ifconfig 8 498.Sh HISTORY 499The 500.Nm 501device driver first appeared in 502.Fx 4.4 503and the 504.Nm emx 505driver first appeared in 506.Dx 2.3 . 507.Sh AUTHORS 508.An -nosplit 509The 510.Nm 511driver was written by 512.An Intel Corporation Aq Mt freebsdnic@mailbox.intel.com . 513.Pp 514The 515.Nm emx 516driver was written by 517.An Sepherosa Ziehau 518(in parts based on 519.Tn Intel Ap s ) . 520