share/man/man4/igb.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/igb.4,v 1.2 2010/05/14 20:11:30 marius Exp $
  33 .\"
  34 .Dd September 3, 2013
  35 .Dt IGB 4
  36 .Os
  37 .Sh NAME
  38 .Nm igb
  39 .Nd "Intel(R) PRO/1000 PCI Express Gigabit Ethernet adapter driver"
  40 .Sh SYNOPSIS
  41 To compile this driver into the kernel,
  42 place the following line in your
  43 kernel configuration file:
  44 .Bd -ragged -offset indent
  45 .Cd "device ig_hal"
  46 .Cd "device igb"
  47 .Ed
  48 .Pp
  49 Alternatively, to load the driver as a
  50 module at boot time, place the following line in
  51 .Xr loader.conf 5 :
  52 .Bd -literal -offset indent
  53 ig_hal_load="YES"
  54 if_igb_load="YES"
  55 .Ed
  56 .Sh DESCRIPTION
  57 The
  58 .Nm
  59 driver provides support for PCI Express Gigabit Ethernet adapters based on
  60 the Intel
  61 82575,
  62 82576,
  63 82580,
  64 I210,
  65 I211,
  66 I350 and I354
  67 Ethernet controller chips.
  68 The
  69 .Nm
  70 driver supports:
  71 .Pp
  72 .Bl -item -offset indent -compact
  73 .It
  74 Transmit/Receive checksum offload for IP/UDP/TCP.
  75 .\"Jumbo Frames.
  76 .It
  77 Interrupt moderation
  78 .It
  79 TCP segmentation offload (TSO)
  80 .It
  81 Receive side scaling (RSS)
  82 .It
  83 Multiple tranmission queues
  84 .It
  85 Multiple vector MSI-X
  86 .It
  87 VLAN tag stripping and inserting
  88 .El
  89 .Pp
  90 If
  91 .Xr polling 4
  92 or MSI-X is used,
  93 by default,
  94 the
  95 .Nm
  96 driver will try enabling as many reception queues and transmission queues
  97 as are allowed by the number of CPUs in the system.
  98 .Pp
  99 If multiple transmission queues are used,
 100 the round-robin arbitration is performed among the transmission queues.
 101 It should be noted that
 102 if both TSO and multiple transmission queues are used,
 103 for 82575, the round-robin arbitration between transmission queues is done
 104 at the TSO packet boundary;
 105 for the reset of the hardware, the round-robin arbitration
 106 between transmission queues is done at the TCP segment boundary after
 107 the hardware segmentation is performed.
 108 .Pp
 109 82575 supports 4 reception queues and 4 transmission queues.
 110 MSI-X is not enabled due to hardware errata.
 111 Under MSI or legacy interrupt mode,
 112 2 reception queues are enabled for hardware RSS hash
 113 and only 1 transmission queue is enable.
 114 .Pp
 115 82576 supports 16 reception queues and 16 transmission queues.
 116 MSI-X is enable by default.
 117 However,
 118 due to the number of MSI-X vectors is 10,
 119 at most 8 reception queues and 8 transmission queues will be enabled
 120 under MSI-X mode.
 121 When
 122 .Xr polling 4
 123 is enabled on the devices,
 124 at most 16 reception queues and 16 transmission queues will be enabled.
 125 .Pp
 126 82580,
 127 I350 and I354 support 8 reception queues and 8 transmission queues.
 128 MSI-X is enabled by default.
 129 .Pp
 130 I210 supports 4 reception queues and 4 transmission queues.
 131 MSI-X is enabled by default.
 132 .Pp
 133 I211 supports 2 reception queues and 2 transmission queues.
 134 MSI-X is enabled by default.
 135 .Pp
 136 .\"For questions related to hardware requirements, refer to the
 137 .\"documentation supplied with your Intel PRO/1000 adapter.
 138 .\"All hardware requirements listed apply to use with
 139 .\".Dx .
 140 .\".Pp
 141 .\"Support for Jumbo Frames is provided via the interface MTU setting.
 142 .\"Selecting an MTU larger than 1500 bytes with the
 143 .\".Xr ifconfig 8
 144 .\"utility configures the adapter to receive and transmit Jumbo Frames.
 145 .\"The maximum MTU size for Jumbo Frames is 9216.
 146 .\".Pp
 147 The
 148 .Nm
 149 driver supports the following media types:
 150 .Bl -tag -width ".Cm 10baseT/UTP"
 151 .It Cm autoselect
 152 Enables auto-negotiation for speed and duplex.
 153 .It Cm 10baseT/UTP
 154 Sets 10Mbps operation.
 155 Use the
 156 .Cm mediaopt
 157 option to select
 158 .Cm full-duplex
 159 mode.
 160 .It Cm 100baseTX
 161 Sets 100Mbps operation.
 162 Use the
 163 .Cm mediaopt
 164 option to select
 165 .Cm full-duplex
 166 mode.
 167 .It Cm 1000baseSX
 168 Sets 1000Mbps operation.
 169 Only
 170 .Cm full-duplex
 171 mode is supported at this speed.
 172 .It Cm 1000baseT
 173 Sets 1000Mbps operation.
 174 Only
 175 .Cm full-duplex
 176 mode is supported at this speed.
 177 .El
 178 .Pp
 179 The
 180 .Nm
 181 driver supports the following media options:
 182 .Bl -tag -width ".Cm full-duplex"
 183 .It Cm full-duplex
 184 Forces full-duplex operation
 185 .It Cm half-duplex
 186 Forces half-duplex operation.
 187 .El
 188 .Pp
 189 Only use
 190 .Cm mediaopt
 191 to set the driver to
 192 .Cm full-duplex .
 193 If
 194 .Cm mediaopt
 195 is not specified, the driver defaults to
 196 .Cm half-duplex .
 197 .Pp
 198 For more information on configuring this device, see
 199 .Xr ifconfig 8 .
 200 The
 201 .Nm
 202 driver supports
 203 .Xr polling 4 .
 204 .Sh HARDWARE
 205 The
 206 .Nm
 207 driver supports Gigabit Ethernet adapters based on the Intel
 208 82575,
 209 82576,
 210 82580,
 211 I210,
 212 I211,
 213 I350 and I354
 214 controller chips:
 215 .Pp
 216 .Bl -bullet -compact
 217 .It
 218 Intel 82575EB Gigabit Ethernet Controller
 219 .It
 220 Intel 82576 Gigabit Ethernet Controller
 221 .It
 222 Intel 82580EB Gigabit Ethernet Controller
 223 .It
 224 Intel Ethernet Controller I210 Series
 225 .It
 226 Intel Ethernet Controller I211 Series
 227 .It
 228 Intel Ethernet Controller I350
 229 .It
 230 Intel Ethernet Controller I354
 231 .It
 232 Intel Ethernet Server Adapter I210-T1
 233 .It
 234 Intel Ethernet Server Adapter I340-F4
 235 .It
 236 Intel Ethernet Server Adapter I340-T4
 237 .It
 238 Intel Ethernet Server Adapter I350-F2
 239 .It
 240 Intel Ethernet Server Adapter I350-F4
 241 .It
 242 Intel Ethernet Server Adapter I350-T2
 243 .It
 244 Intel Ethernet Server Adapter I350-T4
 245 .It
 246 Intel Gigabit EF Dual Port Server Adapter
 247 .It
 248 Intel Gigabit ET Dual Port Server Adapter
 249 .It
 250 Intel Gigabit ET Quad Port Server Adapter
 251 .It
 252 Intel Gigabit ET2 Quad Port Server Adapter
 253 .It
 254 Intel Gigabit VT Quad Port Server Adapter
 255 .El
 256 .Sh TUNABLES
 257 Tunables can be set at the
 258 .Xr loader 8
 259 prompt before booting the kernel or stored in
 260 .Xr loader.conf 5 .
 261 .Em X
 262 is the device unit number.
 263 .Bl -tag -width ".Va hw.igbX.irq.unshared"
 264 .It Va hw.igb.rxd Va hw.igbX.rxd
 265 Number of receive descriptors allocated by the driver.
 266 The default value is 512.
 267 The minimum is 256,
 268 and the maximum is 4096.
 269 .It Va hw.igb.txd Va hw.igbX.txd
 270 Number of transmit descriptors allocated by the driver.
 271 The default value is 1024.
 272 The minimum is 256,
 273 and the maximum is 4096.
 274 .It Va hw.igb.rxr Va hw.igbX.rxr
 275 This tunable specifies the number of reception queues could be enabled.
 276 Maximum allowed value for these tunables is device specific
 277 and it must be power of 2 aligned.
 278 Setting these tunables to 0 allows the driver to make
 279 as many reception queues ready-for-use as allowed by the number of CPUs.
 280 .It Va hw.igb.txr Va hw.igbX.txr
 281 This tunable specifies the number of transmission queues could be enabled.
 282 Maximum allowed value for these tunables is device specific
 283 and it must be power of 2 aligned.
 284 Setting these tunables to 0 allows the driver to make
 285 as many transmission queues ready-for-use as allowed by the number of CPUs.
 286 .It Va hw.igb.msix.enable Va hw.igbX.msix.enable
 287 By default,
 288 the driver will use MSI-X if it is supported.
 289 This behaviour can be turned off by setting this tunable to 0.
 290 .It Va hw.igbX.msix.off
 291 If MSI-X is used
 292 and the number of MSI-X vectors is not enough to
 293 put transmission queue processing and reception queue processing
 294 onto independent MSI-X vector,
 295 this tunable specifies the leading target CPU for
 296 transmission and reception queues processing.
 297 The value specificed must be aligned to the maximum of
 298 the number of reception queues
 299 and the number of transmission queues enabled,
 300 and must be less than the power of 2 number of CPUs.
 301 .It Va hw.igbX.msix.rxoff
 302 If MSI-X is used
 303 and the number of MSI-X vectors is enough to
 304 put transmission queue processing and reception queue processing
 305 onto independent MSI-X vector,
 306 this tunable specifies the leading target CPU for reception queues processing.
 307 The value specificed must be aligned to the number of reception queues enabled
 308 and must be less than the power of 2 number of CPUs.
 309 .It Va hw.igbX.msix.txoff
 310 If MSI-X is used
 311 and the number of MSI-X vectors is enough to
 312 put transmission queue processing and reception queue processing
 313 onto independent MSI-X vector,
 314 this tunable specifies the leading target CPU
 315 for transmission queues processing.
 316 The value specificed must be aligned to
 317 the number of transmission queues enabled
 318 and must be less than the power of 2 number of CPUs.
 319 .It Va hw.igb.msi.enable Va hw.igbX.msi.enable
 320 If MSI-X is disabled and MSI is supported,
 321 the driver will use MSI.
 322 This behavior can be turned off by setting this tunable to 0.
 323 .It Va hw.igbX.msi.cpu
 324 If MSI is used,
 325 it specifies the MSI's target CPU.
 326 .It Va hw.igbX.irq.unshared
 327 If legacy interrupt is used,
 328 by default,
 329 the driver assumes the interrupt could be shared.
 330 Setting this tunable to 1 allows the driver to perform certain
 331 optimization based on the knowledge that the interrupt is not shared.
 332 .It Va hw.igbX.npoll.txoff
 333 This tunable specifies the leading target CPU for
 334 transmission queue
 335 .Xr polling 4
 336 processing.
 337 The value specificed must be aligned to the number of transmission queues
 338 enabled and must be less than the power of 2 number of CPUs.
 339 .It Va hw.igbX.npoll.rxoff
 340 This tunable specifies the leading target CPU for
 341 reception queue
 342 .Xr polling 4
 343 processing.
 344 The value specificed must be aligned to the number of reception queues
 345 enabled and must be less than the power of 2 number of CPUs.
 346 .El
 347 .Sh MIB Variables
 348 A number of per-interface variables are implemented in the
 349 .Va hw.igb Ns Em X
 350 branch of the
 351 .Xr sysctl 3
 352 MIB.
 353 .Bl -tag -width "tx_intr_nsegs"
 354 .It Va rxr
 355 Number of reception queues could be enabled (read-only).
 356 Use the tunable
 357 .Va hw.igb.rxr
 358 or
 359 .Va hw.igbX.rxr
 360 to configure it.
 361 .It Va rxr_inuse
 362 Number of reception queues being used (read-only).
 363 .It Va txr
 364 Number of transmission queues could be enabled (read-only).
 365 Use the tunable
 366 .Va hw.igb.txr
 367 or
 368 .Va hw.igbX.txr
 369 to configure it.
 370 .It Va txr_inuse
 371 Number of transmission queues being used (read-only).
 372 .It Va rxd
 373 Number of descriptors per reception queue (read-only).
 374 Use the tunable
 375 .Va hw.igb.rxd
 376 or
 377 .Va hw.igbX.rxd
 378 to configure it.
 379 .It Va txd
 380 Number of descriptors per transmission queue (read-only).
 381 Use the tunable
 382 .Va hw.igb.txd
 383 or
 384 .Va hw.igbX.txd
 385 to configure it.
 386 .It Va intr_rate
 387 If MSI or legacy interrupt is used,
 388 this sysctl controls the highest possible frequency
 389 that interrupt could be generated by the device.
 390 It is 6000 by default (~150us).
 391 .It Va msixY_rate
 392 If MSI-X is used,
 393 this sysctl controls the highest possible frequency
 394 that interrupt could be generated by the
 395 .Em Y
 396 MSI-X vector.
 397 For reception processing only MSI-X vector,
 398 the default value is 6000 (~150us).
 399 For transmission processing only MSI-X vector,
 400 the default value is 4000 (250us).
 401 For MSI-X vector which handles both reception and transmission,
 402 the default value is 6000 (~150us).
 403 .It Va tx_intr_nsegs
 404 Transmission interrupt is asked to be generated upon every
 405 .Va tx_intr_nsegs
 406 transmission descritors having been setup.
 407 The default value is 1/16 of the number of transmission descriptors per queue.
 408 .It Va tx_wreg_nsegs
 409 The number of transmission descriptors should be setup
 410 before the hardware register is written.
 411 Setting this value too high will have negative effect
 412 on transmission timeliness.
 413 Setting this value too low will hurt overall transmission performance
 414 due to the frequent hardware register writing.
 415 The default value is 8.
 416 .It Va rx_wreg_nsegs
 417 The number of reception descriptors should be setup
 418 before the hardware register is written.
 419 Setting this value too high will make device drop incoming packets.
 420 Setting this value too low will hurt overall reception performance
 421 due to the frequent hardware register writing.
 422 The default value is 32.
 423 .It Va npoll_rxoff
 424 See the tunable
 425 .Va hw.igbX.npoll.rxoff .
 426 The set value will take effect the next time
 427 .Xr polling 4
 428 is enabled on the device.
 429 .It Va npoll_txoff
 430 See the tunable
 431 .Va hw.igbX.npoll.txoff .
 432 The set value will take effect the next time
 433 .Xr polling 4
 434 is enabled on the device.
 435 .El
 436 .\".Sh SUPPORT
 437 .\"For general information and support,
 438 .\"go to the Intel support website at:
 439 .\".Pa http://support.intel.com .
 440 .\".Pp
 441 .\"If an issue is identified with the released source code on the supported kernel
 442 .\"with a supported adapter, email the specific information related to the
 443 .\"issue to
 444 .\".Aq Mt freebsdnic@mailbox.intel.com .
 445 .Sh SEE ALSO
 446 .Xr altq 4 ,
 447 .Xr arp 4 ,
 448 .Xr ifmedia 4 ,
 449 .Xr netintro 4 ,
 450 .Xr ng_ether 4 ,
 451 .Xr polling 4 ,
 452 .Xr vlan 4 ,
 453 .Xr ifconfig 8
 454 .Sh HISTORY
 455 The
 456 .Nm
 457 device driver first appeared in
 458 .Fx 7.1 .
 459 .Sh AUTHORS
 460 The
 461 .Nm
 462 driver was written by
 463 .An Intel Corporation Aq Mt freebsdnic@mailbox.intel.com .