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 June 23, 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, and 82574 Ethernet 65controller 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 adapters 69based on the 82571, 82572, 82573 and 82574 controller chips. 70.\"For further hardware information, see the 71.\".Pa README 72.\"included with the driver. 73.Pp 74The 75.Nm emx 76is a version of the 77.Nm em 78driver for 82571, 82572, 82573, and 82574 Ethernet controller chips that 79additionally supports Receive Side Scaling (RSS, 2 reception queues). 80By default, 81the 82.Nm emx 83driver will try enabling 2 reception queues 84if there are multiple CPUs on the system. 85For 82571 and 82572, 86the 87.Nm emx 88driver could be configured to enable 2 transmission queues. 89By default, 90the 91.Nm emx 92driver only enables 1 transmission queue, 93since enabling 2 transmission queues will require setting up context 94descriptor for every packets requiring hardware transmission offloading, 95which hurts tiny packet transmission performance. 96However, 97if the workload is mainly bulk data 98or hardware transmission offloading is rarely required, 99extra transmission queue could be enabled to reduce contention on 100transmission path. 1012 transmission queues will only be used when 102.Xr polling 4 103is enabled on the device. 104.Pp 105.\"For questions related to hardware requirements, 106.\"refer to the documentation supplied with your Intel PRO/1000 adapter. 107.\"All hardware requirements listed apply to use with 108.\".Dx . 109.\".Pp 110Support for Jumbo Frames is provided via the interface MTU setting. 111Selecting an MTU larger than 1500 bytes with the 112.Xr ifconfig 8 113utility configures the adapter to receive and transmit Jumbo Frames. 114The maximum MTU size for Jumbo Frames is 16114. 115.Pp 116This driver version supports VLANs. 117The 118.Nm 119and 120.Nm emx 121drivers support the following media types: 122.Bl -tag -width ".Cm 10baseT/UTP" 123.It Cm autoselect 124Enables auto-negotiation for speed and duplex. 125.It Cm 10baseT/UTP 126Sets 10Mbps operation. 127Use the 128.Cm mediaopt 129option to select 130.Cm full-duplex 131mode. 132.It Cm 100baseTX 133Sets 100Mbps operation. 134Use the 135.Cm mediaopt 136option to select 137.Cm full-duplex 138mode. 139.It Cm 1000baseSX 140Sets 1000Mbps operation. 141Only 142.Cm full-duplex 143mode is supported at this speed. 144.It Cm 1000baseT 145Sets 1000Mbps operation. 146Only 147.Cm full-duplex 148mode is supported at this speed. 149.El 150.Pp 151The 152.Nm 153and 154.Nm emx 155drivers support the following media options: 156.Bl -tag -width ".Cm full-duplex" 157.It Cm full-duplex 158Forces full-duplex operation 159.It Cm half-duplex 160Forces half-duplex operation. 161.El 162.Pp 163Only use 164.Cm mediaopt 165to set the driver to 166.Cm full-duplex . 167If 168.Cm mediaopt 169is not specified, the driver defaults to 170.Cm half-duplex . 171.Pp 172For more information on configuring this device, see 173.Xr ifconfig 8 . 174.Pp 175The 176.Nm 177and 178.Nm emx 179drivers support 180.Xr polling 4 . 181.Sh HARDWARE 182The 183.Nm 184driver supports Gigabit Ethernet adapters based on the Intel 18582540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, 82546EB, 18682546GB, 82547, 82571, 82572, 82573, and 82574 controller chips: 187.Pp 188.Bl -bullet -compact 189.It 190Intel PRO/1000 CT Network Connection (82547) 191.It 192Intel PRO/1000 F Server Adapter (82543) 193.It 194Intel PRO/1000 Gigabit Server Adapter (82542) 195.It 196Intel PRO/1000 GT Desktop Adapter (82541PI) 197.It 198Intel PRO/1000 MF Dual Port Server Adapter (82546) 199.It 200Intel PRO/1000 MF Server Adapter (82545) 201.It 202Intel PRO/1000 MF Server Adapter (LX) (82545) 203.It 204Intel PRO/1000 MT Desktop Adapter (82540) 205.It 206Intel PRO/1000 MT Desktop Adapter (82541) 207.It 208Intel PRO/1000 MT Dual Port Server Adapter (82546) 209.It 210Intel PRO/1000 MT Quad Port Server Adapter (82546EB) 211.It 212Intel PRO/1000 MT Server Adapter (82545) 213.It 214Intel PRO/1000 PF Dual Port Server Adapter (82571) 215.It 216Intel PRO/1000 PF Quad Port Server Adapter (82571) 217.It 218Intel PRO/1000 PF Server Adapter (82572) 219.It 220Intel PRO/1000 PT Desktop Adapter (82572) 221.It 222Intel PRO/1000 PT Dual Port Server Adapter (82571) 223.It 224Intel PRO/1000 PT Quad Port Server Adapter (82571) 225.It 226Intel PRO/1000 PT Server Adapter (82572) 227.It 228Intel PRO/1000 T Desktop Adapter (82544) 229.It 230Intel PRO/1000 T Server Adapter (82543) 231.It 232Intel PRO/1000 XF Server Adapter (82544) 233.It 234Intel PRO/1000 XT Server Adapter (82544) 235.El 236.Pp 237The 238.Nm emx 239driver supports Gigabit Ethernet adapters based on the Intel 24082571, 82572, 82573, and 82574 controller chips. 241.Sh TUNABLES 242Tunables can be set at the 243.Xr loader 8 244prompt before booting the kernel or stored in 245.Xr loader.conf 5 . 246.Em Y 247is the device unit number. 248.Bl -tag -width "hw.em.int_throttle_ceil" 249.It Va hw.em.int_throttle_ceil 250Hardware interrupt throttling rate. 251The default value is 6000Hz. 252This tunable also applies to 253.Nm emx . 254.Nm emx 255has a per device tunable 256.Va hw.emxY.int_throttle_ceil , 257which serves the same purpose. 258.It Va hw.em.rxd 259Number of receive descriptors allocated by the driver. 260The default value is 512. 261The 82542 and 82543-based adapters can handle up to 256 descriptors, 262while others can have up to 4096. 263This tunable also applies to 264.Nm emx . 265.Nm emx 266has a per device tunable 267.Va hw.emxY.rxd , 268which serves the same purpose. 269.It Va hw.em.txd 270Number of transmit descriptors allocated by the driver. 271The default value is 512. 272The 82542 and 82543-based adapters can handle up to 256 descriptors, 273while others can have up to 4096. 274This tunable also applies to 275.Nm emx . 276.Nm emx 277has a per device tunable 278.Va hw.emxY.txd , 279which serves the same purpose. 280.It Va hw.em.msi.enable Va hw.emY.msi.enable 281By default, the driver will use MSI if it is supported. 282This behavior can be turned off by setting these tunable to 0. 283These tunables also applies to 284.Nm emx . 285.It Va hw.emY.msi.cpu 286If MSI is used, 287it specifies the MSI's target CPU. 288This tunable also applies to 289.Nm emx . 290.It Va hw.emY.irq.unshared 291If legacy interrupt is used, 292by default, 293the driver assumes the interrupt could be shared. 294Setting this tunable to 1 allows the driver to 295perform certain optimization based on the knowledge 296that the interrupt is not shared. 297These tunables also applies to 298.Nm emx . 299.It Va hw.emx.rxr Va hw.emxY.rxr 300This tunable specifies the number of reception queues could be enabled. 301Maximum allowed value for these tunables is 2. 302Setting these tunables to 0 allows the driver to enable reception 303queues based on the number of CPUs. 304The default value is 0. 305.It Va hw.emx.txr Va hw.emxY.txr 306These tunables only take effect on 82571 and 82572. 307This tunable specifies the number of transmission queues could be enabled. 308Maximum allowed value for these tunables is 2. 309Setting these tunables to 0 allows the driver to enable transmission 310queues based on the number of CPUs. 311The default value is 1. 312.It Va hw.emxY.npoll.rxoff 313This tunable specifies the leading target CPU for reception queues 314.Xr polling 4 315processing. 316The value specificed must be aligned to the number of reception queues enabled 317and must be less than the power of 2 number of CPUs. 318.It Va hw.emxY.npoll.rxoff 319This tunable specifies the leading target CPU for transmission queues 320.Xr polling 4 321processing. 322The value specificed must be aligned to the number of transmission queues 323enabled 324and must be less than the power of 2 number of CPUs. 325.El 326.Sh MIB Variables 327A number of per-interface variables are implemented in the 328.Va hw.emx Ns Em Y 329or 330.Va hw.em Ns Em Y 331branch of the 332.Xr sysctl 3 333MIB. 334.Bl -tag -width "int_throttle_ceil" 335.It Va rxd 336Number of reception descriptors enabled (read-only). 337Use the tunable 338.Va hw.em.rxd 339or 340.Va hw.emY.rxd 341to configure it. 342.It Va txd 343Number of transmission descriptors enabled (read-only). 344Use the tunable 345.Va hw.em.txd 346or 347.Va hw.emY.txd 348to configure it. 349.It Va int_throttle_ceil 350See the tunable 351.Va hw.em.int_throttle_ceil . 352.It Va int_tx_nsegs 353This value controls how many transmit descriptors should be consumed 354by the hardware before the hardware generates a transmit interrupt. 355The default value is 1/16 of the number of transmit descriptors. 356If 357.Xr polling 4 358is not used on the hardware and 359the major part of the transmitted data are bulk data, 360this value could safely be set to 1/2 of the number of transmit descriptors. 361.It Va tx_wreg_nsegs 362The number of transmission descriptors should be setup 363before the hardware register is written. 364Setting this value too high will have negative effect 365on transmission timeliness. 366Setting this value too low will hurt overall transmission due to 367the frequent hardware register writing. 368Default value is 8. 369.It Va rx_ring_cnt 370Number of reception queues enableed (read-only). 371This sysctl only applies to 372.Nm emx . 373Use the tunable 374.Va hw.emx.rxr 375or 376.Va hw.emxY.rxr 377to configure it. 378.It Va tx_ring_cnt 379Number of transmission queues that cound be enableed (read-only). 380This sysctl only applies to 381.Nm emx . 382Use the tunable 383.Va hw.emx.txr 384or 385.Va hw.emxY.txr 386to configure it. 387.It Va tx_ring_inuse 388Number of transmission queues being used (read-only). 389This sysctl only applies to 390.Nm emx . 391.It Va npoll_rxoff 392See the tunable 393.Va hw.emxY.npoll.rxoff . 394The set value will take effect the next time 395.Xr polling 4 396is enabled on the device. 397This sysctl only applies to 398.Nm emx . 399.It Va npoll_txoff 400See the tunable 401.Va hw.emxY.npoll.txoff . 402The set value will take effect the next time 403.Xr polling 4 404is enabled on the device. 405This sysctl only applies to 406.Nm emx . 407.El 408.\".Sh SUPPORT 409.\"For general information and support, 410.\"go to the Intel support website at: 411.\".Pa http://support.intel.com . 412.\".Pp 413.\"If an issue is identified with the released source code on the supported kernel 414.\"with a supported adapter, email the specific information related to the 415.\"issue to 416.\".Aq freebsdnic@mailbox.intel.com . 417.Sh SEE ALSO 418.Xr arp 4 , 419.Xr ifmedia 4 , 420.Xr netintro 4 , 421.Xr ng_ether 4 , 422.Xr polling 4 , 423.Xr vlan 4 , 424.Xr ifconfig 8 425.Sh HISTORY 426The 427.Nm 428device driver first appeared in 429.Fx 4.4 430and the 431.Nm emx 432driver first appeared in 433.Dx 2.3 . 434.Sh AUTHORS 435.An -nosplit 436The 437.Nm 438driver was written by 439.An Intel Corporation Aq freebsdnic@mailbox.intel.com . 440.Pp 441The 442.Nm emx 443driver was written by 444.An Sepherosa Ziehau 445(in parts based on 446.Tn Intel Ap s ) . 447