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 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
  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, and 82574 controller chips:
 193 .Pp
 194 .Bl -bullet -compact
 195 .It
 196 Intel PRO/1000 CT Network Connection (82547)
 197 .It
 198 Intel PRO/1000 F Server Adapter (82543)
 199 .It
 200 Intel PRO/1000 Gigabit Server Adapter (82542)
 201 .It
 202 Intel PRO/1000 GT Desktop Adapter (82541PI)
 203 .It
 204 Intel PRO/1000 MF Dual Port Server Adapter (82546)
 205 .It
 206 Intel PRO/1000 MF Server Adapter (82545)
 207 .It
 208 Intel PRO/1000 MF Server Adapter (LX) (82545)
 209 .It
 210 Intel PRO/1000 MT Desktop Adapter (82540)
 211 .It
 212 Intel PRO/1000 MT Desktop Adapter (82541)
 213 .It
 214 Intel PRO/1000 MT Dual Port Server Adapter (82546)
 215 .It
 216 Intel PRO/1000 MT Quad Port Server Adapter (82546EB)
 217 .It
 218 Intel PRO/1000 MT Server Adapter (82545)
 219 .It
 220 Intel PRO/1000 PF Dual Port Server Adapter (82571)
 221 .It
 222 Intel PRO/1000 PF Quad Port Server Adapter (82571)
 223 .It
 224 Intel PRO/1000 PF Server Adapter (82572)
 225 .It
 226 Intel PRO/1000 PT Desktop Adapter (82572)
 227 .It
 228 Intel PRO/1000 PT Dual Port Server Adapter (82571)
 229 .It
 230 Intel PRO/1000 PT Quad Port Server Adapter (82571)
 231 .It
 232 Intel PRO/1000 PT Server Adapter (82572)
 233 .It
 234 Intel PRO/1000 T Desktop Adapter (82544)
 235 .It
 236 Intel PRO/1000 T Server Adapter (82543)
 237 .It
 238 Intel PRO/1000 XF Server Adapter (82544)
 239 .It
 240 Intel PRO/1000 XT Server Adapter (82544)
 241 .El
 242 .Pp
 243 The
 244 .Nm emx
 245 driver supports Gigabit Ethernet adapters based on the Intel
 246 82571, 82572, 82573, and 82574 controller chips.
 247 .Sh TUNABLES
 248 Tunables can be set at the
 249 .Xr loader 8
 250 prompt before booting the kernel or stored in
 251 .Xr loader.conf 5 .
 252 .Em Y
 253 is the device unit number.
 254 .Bl -tag -width "hw.em.int_throttle_ceil"
 255 .It Va hw.em.int_throttle_ceil
 256 Hardware interrupt throttling rate.
 257 The default value is 6000Hz.
 258 This tunable also applies to
 259 .Nm emx .
 260 .Nm emx
 261 has a per device tunable
 262 .Va hw.emxY.int_throttle_ceil ,
 263 which serves the same purpose.
 264 .It Va hw.em.rxd
 265 Number of receive descriptors allocated by the driver.
 266 The default value is 512.
 267 The 82542 and 82543-based adapters can handle up to 256 descriptors,
 268 while others can have up to 4096.
 269 This tunable also applies to
 270 .Nm emx .
 271 .Nm emx
 272 has a per device tunable
 273 .Va hw.emxY.rxd ,
 274 which serves the same purpose.
 275 .It Va hw.em.txd
 276 Number of transmit descriptors allocated by the driver.
 277 The default value is 512.
 278 The 82542 and 82543-based adapters can handle up to 256 descriptors,
 279 while others can have up to 4096.
 280 This tunable also applies to
 281 .Nm emx .
 282 .Nm emx
 283 has a per device tunable
 284 .Va hw.emxY.txd ,
 285 which serves the same purpose.
 286 .It Va hw.em.msi.enable Va hw.emY.msi.enable
 287 By default, the driver will use MSI if it is supported.
 288 This behavior can be turned off by setting these tunable to 0.
 289 These tunables also applies to
 290 .Nm emx .
 291 .It Va hw.emY.msi.cpu
 292 If MSI is used,
 293 it specifies the MSI's target CPU.
 294 This tunable also applies to
 295 .Nm emx .
 296 .It Va hw.emY.irq.unshared
 297 If legacy interrupt is used,
 298 by default,
 299 the driver assumes the interrupt could be shared.
 300 Setting this tunable to 1 allows the driver to
 301 perform certain optimization based on the knowledge
 302 that the interrupt is not shared.
 303 These tunables also applies to
 304 .Nm emx .
 305 .It Va hw.emx.rxr Va hw.emxY.rxr
 306 This tunable specifies the number of reception queues could be enabled.
 307 Maximum allowed value for these tunables is 2.
 308 Setting these tunables to 0 allows the driver to enable reception
 309 queues based on the number of CPUs.
 310 The default value is 0.
 311 .It Va hw.emx.txr Va hw.emxY.txr
 312 These tunables only take effect on 82571 and 82572.
 313 This tunable specifies the number of transmission queues could be enabled.
 314 Maximum allowed value for these tunables is 2.
 315 Setting these tunables to 0 allows the driver to enable transmission
 316 queues based on the number of CPUs.
 317 The default value is 1.
 318 .It Va hw.emxY.npoll.rxoff
 319 This tunable specifies the leading target CPU for reception queues
 320 .Xr polling 4
 321 processing.
 322 The value specificed must be aligned to the number of reception queues enabled
 323 and must be less than the power of 2 number of CPUs.
 324 .It Va hw.emxY.npoll.rxoff
 325 This tunable specifies the leading target CPU for transmission queues
 326 .Xr polling 4
 327 processing.
 328 The value specificed must be aligned to the number of transmission queues
 329 enabled
 330 and must be less than the power of 2 number of CPUs.
 331 .El
 332 .Sh MIB Variables
 333 A number of per-interface variables are implemented in the
 334 .Va hw.emx Ns Em Y
 335 or
 336 .Va hw.em Ns Em Y
 337 branch of the
 338 .Xr sysctl 3
 339 MIB.
 340 .Bl -tag -width "int_throttle_ceil"
 341 .It Va rxd
 342 Number of reception descriptors enabled (read-only).
 343 Use the tunable
 344 .Va hw.em.rxd
 345 or
 346 .Va hw.emY.rxd
 347 to configure it.
 348 .It Va txd
 349 Number of transmission descriptors enabled (read-only).
 350 Use the tunable
 351 .Va hw.em.txd
 352 or
 353 .Va hw.emY.txd
 354 to configure it.
 355 .It Va int_throttle_ceil
 356 See the tunable
 357 .Va hw.em.int_throttle_ceil .
 358 .It Va int_tx_nsegs
 359 This value controls how many transmit descriptors should be consumed
 360 by the hardware before the hardware generates a transmit interrupt.
 361 The default value is 1/16 of the number of transmit descriptors.
 362 If
 363 .Xr polling 4
 364 is not used on the hardware and
 365 the major part of the transmitted data are bulk data,
 366 this value could safely be set to 1/2 of the number of transmit descriptors.
 367 .It Va tx_wreg_nsegs
 368 The number of transmission descriptors should be setup
 369 before the hardware register is written.
 370 Setting this value too high will have negative effect
 371 on transmission timeliness.
 372 Setting this value too low will hurt overall transmission due to
 373 the frequent hardware register writing.
 374 Default value is 8.
 375 .It Va rx_ring_cnt
 376 Number of reception queues enableed (read-only).
 377 This sysctl only applies to
 378 .Nm emx .
 379 Use the tunable
 380 .Va hw.emx.rxr
 381 or
 382 .Va hw.emxY.rxr
 383 to configure it.
 384 .It Va tx_ring_cnt
 385 Number of transmission queues that cound be enableed (read-only).
 386 This sysctl only applies to
 387 .Nm emx .
 388 Use the tunable
 389 .Va hw.emx.txr
 390 or
 391 .Va hw.emxY.txr
 392 to configure it.
 393 .It Va tx_ring_inuse
 394 Number of transmission queues being used (read-only).
 395 This sysctl only applies to
 396 .Nm emx .
 397 .It Va npoll_rxoff
 398 See the tunable
 399 .Va hw.emxY.npoll.rxoff .
 400 The set value will take effect the next time
 401 .Xr polling 4
 402 is enabled on the device.
 403 This sysctl only applies to
 404 .Nm emx .
 405 .It Va npoll_txoff
 406 See the tunable
 407 .Va hw.emxY.npoll.txoff .
 408 The set value will take effect the next time
 409 .Xr polling 4
 410 is enabled on the device.
 411 This 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
 432 The
 433 .Nm
 434 device driver first appeared in
 435 .Fx 4.4
 436 and the
 437 .Nm emx
 438 driver first appeared in
 439 .Dx 2.3 .
 440 .Sh AUTHORS
 441 .An -nosplit
 442 The
 443 .Nm
 444 driver was written by
 445 .An Intel Corporation Aq Mt freebsdnic@mailbox.intel.com .
 446 .Pp
 447 The
 448 .Nm emx
 449 driver was written by
 450 .An Sepherosa Ziehau
 451 (in parts based on
 452 .Tn Intel Ap s ) .