share/man/man4/em.4

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