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