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