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 December 17, 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 82544EI Gigabit Ethernet Controller
 221 .It
 222 Intel 82544GC Gigabit Ethernet Controller
 223 .It
 224 Intel 82545GM Gigabit Ethernet Controller
 225 .It
 226 Intel 82546EB Gigabit Ethernet Controller
 227 .It
 228 Intel 82547GI Gigabit Ethernet Controller
 229 .It
 230 Intel 82567 Gigabit Ethernet Controller
 231 .It
 232 Intel 82571EB Gigabit Ethernet Controller
 233 .It
 234 Intel 82572EI Gigabit Ethernet Controller
 235 .It
 236 Intel 82573E Gigabit Ethernet Controller
 237 .It
 238 Intel 82573L Gigabit Ethernet Controller
 239 .It
 240 Intel 82573V Gigabit Ethernet Controller
 241 .It
 242 Intel 82574IT Gigabit Ethernet Controller
 243 .It
 244 Intel 82574L Gigabit Ethernet Controller
 245 .It
 246 Intel 82578DC Gigabit Ethernet PHY
 247 .It
 248 Intel 82578DM Gigabit Ethernet PHY
 249 .It
 250 Intel 82579LM Gigabit Ethernet PHY
 251 .It
 252 Intel 82579V Gigabit Ethernet PHY
 253 .It
 254 Intel Ethernet Connection I217-LM
 255 .It
 256 Intel Ethernet Connection I217-V
 257 .It
 258 Intel Ethernet Connection I218-LM
 259 .It
 260 Intel Ethernet Connection I218-V
 261 .It
 262 Intel Ethernet Connection I219-LM
 263 .It
 264 Intel Ethernet Connection I219-V
 265 .It
 266 Intel Gigabit CT Desktop Adapter
 267 .It
 268 Intel PRO/1000 F Server Adapter
 269 .It
 270 Intel PRO/1000 MF Dual Port Server Adapter
 271 .It
 272 Intel PRO/1000 MF Server Adapter
 273 .It
 274 Intel PRO/1000 MF Server Adapter (LX)
 275 .It
 276 Intel PRO/1000 MT Dual Port Server Adapter
 277 .It
 278 Intel PRO/1000 MT Quad Port Server Adapter
 279 .It
 280 Intel PRO/1000 PF Dual Port Server Adapter
 281 .It
 282 Intel PRO/1000 PT Dual Port Server Adapter
 283 .It
 284 Intel PRO/1000 PT Quad Port Low Profile Server Adapter
 285 .It
 286 Intel PRO/1000 PT Quad Port Server Adapter
 287 .It
 288 Intel PRO/1000 T Server Adapter
 289 .It
 290 Intel PRO/1000 XT Low Profile Server Adapter
 291 .It
 292 Intel PRO/1000 XT Server Adapter
 293 .El
 294 .Pp
 295 The
 296 .Nm emx
 297 driver supports Gigabit Ethernet adapters based on the Intel
 298 82571, 82572, 82573, 82574, I217, I218 and I219 controller chips.
 299 .Sh TUNABLES
 300 Tunables can be set at the
 301 .Xr loader 8
 302 prompt before booting the kernel or stored in
 303 .Xr loader.conf 5 .
 304 .Em Y
 305 is the device unit number.
 306 .Bl -tag -width "hw.em.int_throttle_ceil"
 307 .It Va hw.em.int_throttle_ceil
 308 Hardware interrupt throttling rate.
 309 The default value is 6000Hz.
 310 This tunable also applies to
 311 .Nm emx .
 312 .Nm emx
 313 has a per device tunable
 314 .Va hw.emxY.int_throttle_ceil ,
 315 which serves the same purpose.
 316 .It Va hw.em.rxd
 317 Number of receive descriptors allocated by the driver.
 318 The default value is 512.
 319 The 82542 and 82543-based adapters can handle up to 256 descriptors,
 320 while others can have up to 4096.
 321 This tunable also applies to
 322 .Nm emx .
 323 .Nm emx
 324 has a per device tunable
 325 .Va hw.emxY.rxd ,
 326 which serves the same purpose.
 327 .It Va hw.em.txd
 328 Number of transmit descriptors allocated by the driver.
 329 The default value is 512.
 330 The 82542 and 82543-based adapters can handle up to 256 descriptors,
 331 while others can have up to 4096.
 332 This tunable also applies to
 333 .Nm emx .
 334 .Nm emx
 335 has a per device tunable
 336 .Va hw.emxY.txd ,
 337 which serves the same purpose.
 338 .It Va hw.em.msi.enable Va hw.emY.msi.enable
 339 By default, the driver will use MSI if it is supported.
 340 This behavior can be turned off by setting these tunable to 0.
 341 These tunables also applies to
 342 .Nm emx .
 343 .It Va hw.emY.msi.cpu
 344 If MSI is used,
 345 it specifies the MSI's target CPU.
 346 This tunable also applies to
 347 .Nm emx .
 348 .It Va hw.emY.irq.unshared
 349 If legacy interrupt is used,
 350 by default,
 351 the driver assumes the interrupt could be shared.
 352 Setting this tunable to 1 allows the driver to
 353 perform certain optimization based on the knowledge
 354 that the interrupt is not shared.
 355 These tunables also applies to
 356 .Nm emx .
 357 .It Va hw.em.flow_ctrl Va hw.emY.flow_ctrl
 358 The default flow control settings.
 359 Supported values are:
 360 rxpause (only enable PAUSE reception),
 361 txpause (only enable PAUSE transmission),
 362 full (enable PAUSE reception and transmission),
 363 none (disable flow control PAUSE operation),
 364 force-rxpause (force PAUSE reception),
 365 force-txpause (force PAUSE transmission),
 366 force-full (forcefully enable PAUSE reception and transmission),
 367 force-none (forcefully disable flow control PAUSE operation).
 368 Default is none.
 369 These tunables also applies to
 370 .Nm emx .
 371 .It Va hw.emx.rxr Va hw.emxY.rxr
 372 This tunable specifies the number of reception queues could be enabled.
 373 Maximum allowed value for these tunables is 2.
 374 Setting these tunables to 0 allows the driver to enable reception
 375 queues based on the number of CPUs.
 376 The default value is 0.
 377 .It Va hw.emx.txr Va hw.emxY.txr
 378 These tunables only take effect on 82571 and 82572.
 379 This tunable specifies the number of transmission queues could be enabled.
 380 Maximum allowed value for these tunables is 2.
 381 Setting these tunables to 0 allows the driver to enable transmission
 382 queues based on the number of CPUs.
 383 The default value is 1.
 384 .El
 385 .Sh MIB Variables
 386 A number of per-interface variables are implemented in the
 387 .Va dev.emx. Ns Em Y
 388 or
 389 .Va dev.em. Ns Em Y
 390 branch of the
 391 .Xr sysctl 3
 392 MIB.
 393 .Bl -tag -width "int_throttle_ceil"
 394 .It Va rxd
 395 Number of reception descriptors enabled (read-only).
 396 Use the tunable
 397 .Va hw.em.rxd
 398 or
 399 .Va hw.emY.rxd
 400 to configure it.
 401 .It Va txd
 402 Number of transmission descriptors enabled (read-only).
 403 Use the tunable
 404 .Va hw.em.txd
 405 or
 406 .Va hw.emY.txd
 407 to configure it.
 408 .It Va int_throttle_ceil
 409 See the tunable
 410 .Va hw.em.int_throttle_ceil .
 411 .It Va int_tx_nsegs
 412 This value controls how many transmit descriptors should be consumed
 413 by the hardware before the hardware generates a transmit interrupt.
 414 The default value is 1/16 of the number of transmit descriptors.
 415 If
 416 .Xr polling 4
 417 is not used on the hardware and
 418 the major part of the transmitted data are bulk data,
 419 this value could safely be set to 1/2 of the number of transmit descriptors.
 420 .It Va tx_wreg_nsegs
 421 The number of transmission descriptors should be setup
 422 before the hardware register is written.
 423 Setting this value too high will have negative effect
 424 on transmission timeliness.
 425 Setting this value too low will hurt overall transmission due to
 426 the frequent hardware register writing.
 427 Default value is 8.
 428 .It Va rx_ring_cnt
 429 Number of reception queues enabled (read-only).
 430 This sysctl only applies to
 431 .Nm emx .
 432 Use the tunable
 433 .Va hw.emx.rxr
 434 or
 435 .Va hw.emxY.rxr
 436 to configure it.
 437 .It Va tx_ring_cnt
 438 Number of transmission queues that can be enabled (read-only).
 439 This sysctl only applies to
 440 .Nm emx .
 441 Use the tunable
 442 .Va hw.emx.txr
 443 or
 444 .Va hw.emxY.txr
 445 to configure it.
 446 .It Va tx_ring_inuse
 447 Number of transmission queues being used (read-only).
 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 ) .