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