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 December 17, 2017
  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 .It Cm rxpause
 188 Enable flow control PAUSE reception.
 189 This is only supported by
 190 .Cm autoselect
 191 and
 192 .Cm full-duplex
 193 mode.
 194 .It Cm txpause
 195 Enable flow control PAUSE transmission.
 196 This is only supported by
 197 .Cm autoselect
 198 and
 199 .Cm full-duplex
 200 mode.
 201 .It Cm forcepause
 202 Force flow control PAUSE operation as configured by
 203 .Cm rxpause
 204 and
 205 .Cm txpause
 206 media options.
 207 .El
 208 .Pp
 209 Only use
 210 .Cm mediaopt
 211 to set the driver to
 212 .Cm full-duplex .
 213 If
 214 .Cm mediaopt
 215 is not specified, the driver defaults to
 216 .Cm half-duplex .
 217 .Pp
 218 For more information on configuring this device, see
 219 .Xr ifconfig 8 .
 220 The
 221 .Nm
 222 driver supports
 223 .Xr polling 4 .
 224 .Sh HARDWARE
 225 The
 226 .Nm
 227 driver supports Gigabit Ethernet adapters based on the Intel
 228 82575,
 229 82576,
 230 82580,
 231 I210,
 232 I211,
 233 I350 and I354
 234 controller chips:
 235 .Pp
 236 .Bl -bullet -compact
 237 .It
 238 Intel 82575EB Gigabit Ethernet Controller
 239 .It
 240 Intel 82576EB Gigabit Ethernet Controller
 241 .It
 242 Intel 82576NS Gigabit Ethernet Controller
 243 .It
 244 Intel 82580EB Gigabit Ethernet Controller
 245 .It
 246 Intel Ethernet Controller I350-AM2
 247 .It
 248 Intel Ethernet Controller I350-AM4
 249 .It
 250 Intel Ethernet Controller I350-BT2
 251 .It
 252 Intel Ethernet Controller I210-AS
 253 .It
 254 Intel Ethernet Controller I210-AT
 255 .It
 256 Intel Ethernet Controller I210-CS
 257 .It
 258 Intel Ethernet Controller I210-IS
 259 .It
 260 Intel Ethernet Controller I210-IT
 261 .It
 262 Intel Ethernet Controller I211-AT
 263 .It
 264 Intel Ethernet Server Adapter I210-T1
 265 .It
 266 Intel Ethernet Server Adapter I340-F4
 267 .It
 268 Intel Ethernet Server Adapter I340-T4
 269 .It
 270 Intel Ethernet Server Adapter I350-F2
 271 .It
 272 Intel Ethernet Server Adapter I350-F4
 273 .It
 274 Intel Ethernet Server Adapter I350-T2
 275 .It
 276 Intel Ethernet Server Adapter I350-T4
 277 .It
 278 Intel Gigabit EF Dual Port Server Adapter
 279 .It
 280 Intel Gigabit ET Dual Port Server Adapter
 281 .It
 282 Intel Gigabit ET Quad Port Server Adapter
 283 .It
 284 Intel Gigabit ET2 Quad Port Server Adapter
 285 .It
 286 Intel Gigabit VT Quad Port Server Adapter
 287 .El
 288 .Sh TUNABLES
 289 Tunables can be set at the
 290 .Xr loader 8
 291 prompt before booting the kernel or stored in
 292 .Xr loader.conf 5 .
 293 .Em X
 294 is the device unit number.
 295 .Bl -tag -width ".Va hw.igbX.irq.unshared"
 296 .It Va hw.igb.rxd Va hw.igbX.rxd
 297 Number of receive descriptors allocated by the driver.
 298 The default value is 512.
 299 The minimum is 256,
 300 and the maximum is 4096.
 301 .It Va hw.igb.txd Va hw.igbX.txd
 302 Number of transmit descriptors allocated by the driver.
 303 The default value is 1024.
 304 The minimum is 256,
 305 and the maximum is 4096.
 306 .It Va hw.igb.rxr Va hw.igbX.rxr
 307 This tunable specifies the number of reception queues could be enabled.
 308 Maximum allowed value for these tunables is device specific
 309 and it must be power of 2 aligned.
 310 Setting these tunables to 0 allows the driver to make
 311 as many reception queues ready-for-use as allowed by the number of CPUs.
 312 .It Va hw.igb.txr Va hw.igbX.txr
 313 This tunable specifies the number of transmission queues could be enabled.
 314 Maximum allowed value for these tunables is device specific
 315 and it must be power of 2 aligned.
 316 Setting these tunables to 0 allows the driver to make
 317 as many transmission queues ready-for-use as allowed by the number of CPUs.
 318 .It Va hw.igb.msix.enable Va hw.igbX.msix.enable
 319 By default,
 320 the driver will use MSI-X if it is supported.
 321 This behaviour can be turned off by setting this tunable to 0.
 322 .It Va hw.igb.msi.enable Va hw.igbX.msi.enable
 323 If MSI-X is disabled and MSI is supported,
 324 the driver will use MSI.
 325 This behavior can be turned off by setting this tunable to 0.
 326 .It Va hw.igbX.msi.cpu
 327 If MSI is used,
 328 it specifies the MSI's target CPU.
 329 .It Va hw.igbX.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 perform certain
 334 optimization based on the knowledge that the interrupt is not shared.
 335 .It Va hw.igb.flow_ctrl Va hw.igbX.flow_ctrl
 336 The default flow control settings.
 337 Supported values are:
 338 rxpause (only enable PAUSE reception),
 339 txpause (only enable PAUSE transmission),
 340 full (enable PAUSE reception and transmission),
 341 none (disable flow control PAUSE operation),
 342 force-rxpause (force PAUSE reception),
 343 force-txpause (force PAUSE transmission),
 344 force-full (forcefully enable PAUSE reception and transmission),
 345 force-none (forcefully disable flow control PAUSE operation).
 346 Default is none.
 347 .El
 348 .Sh MIB Variables
 349 A number of per-interface variables are implemented in the
 350 .Va dev.igb. Ns Em X
 351 branch of the
 352 .Xr sysctl 3
 353 MIB.
 354 .Bl -tag -width "rxtx_intr_rate"
 355 .It Va rxr
 356 Number of reception queues could be enabled (read-only).
 357 Use the tunable
 358 .Va hw.igb.rxr
 359 or
 360 .Va hw.igbX.rxr
 361 to configure it.
 362 .It Va rxr_inuse
 363 Number of reception queues being used (read-only).
 364 .It Va txr
 365 Number of transmission queues could be enabled (read-only).
 366 Use the tunable
 367 .Va hw.igb.txr
 368 or
 369 .Va hw.igbX.txr
 370 to configure it.
 371 .It Va txr_inuse
 372 Number of transmission queues being used (read-only).
 373 .It Va rxd
 374 Number of descriptors per reception queue (read-only).
 375 Use the tunable
 376 .Va hw.igb.rxd
 377 or
 378 .Va hw.igbX.rxd
 379 to configure it.
 380 .It Va txd
 381 Number of descriptors per transmission queue (read-only).
 382 Use the tunable
 383 .Va hw.igb.txd
 384 or
 385 .Va hw.igbX.txd
 386 to configure it.
 387 .It Va rxtx_intr_rate
 388 If MSI or legacy interrupt is used,
 389 this sysctl controls the highest possible frequency
 390 that interrupt could be generated by the device.
 391 If MSI-X is used,
 392 this sysctl controls the highest possible frequency
 393 that interrupt could be generated by the MSI-X vectors,
 394 which aggregate transmission queue and reception queue procecssing.
 395 It is 6000 by default (~150us).
 396 .It Va rx_intr_rate
 397 If MSI-X is used,
 398 this sysctl controls the highest possible frequency
 399 that interrupt could be generated by the MSI-X vectors,
 400 which only process reception queue.
 401 It is 6000 by default (~150us).
 402 .It Va tx_intr_rate
 403 If MSI-X is used,
 404 this sysctl controls the highest possible frequency
 405 that interrupt could be generated by the MSI-X vectors,
 406 which only process transmission queue.
 407 It is 4000 by default (250us).
 408 .It Va sts_intr_rate
 409 If MSI-X is used,
 410 this sysctl controls the highest possible frequency
 411 that interrupt could be generated by the MSI-X vectors,
 412 which only process chip status changes.
 413 It is 6000 by default (~150us).
 414 .It Va tx_intr_nsegs
 415 Transmission interrupt is asked to be generated upon every
 416 .Va tx_intr_nsegs
 417 transmission descritors having been setup.
 418 The default value is 1/16 of the number of transmission descriptors per queue.
 419 .It Va tx_wreg_nsegs
 420 The number of transmission descriptors should be setup
 421 before the hardware register is written.
 422 Setting this value too high will have negative effect
 423 on transmission timeliness.
 424 Setting this value too low will hurt overall transmission performance
 425 due to the frequent hardware register writing.
 426 The default value is 8.
 427 .It Va rx_wreg_nsegs
 428 The number of reception descriptors should be setup
 429 before the hardware register is written.
 430 Setting this value too high will make device drop incoming packets.
 431 Setting this value too low will hurt overall reception performance
 432 due to the frequent hardware register writing.
 433 The default value is 32.
 434 .El
 435 .\".Sh SUPPORT
 436 .\"For general information and support,
 437 .\"go to the Intel support website at:
 438 .\".Pa http://support.intel.com .
 439 .\".Pp
 440 .\"If an issue is identified with the released source code on the supported kernel
 441 .\"with a supported adapter, email the specific information related to the
 442 .\"issue to
 443 .\".Aq Mt freebsdnic@mailbox.intel.com .
 444 .Sh SEE ALSO
 445 .Xr altq 4 ,
 446 .Xr arp 4 ,
 447 .Xr ifmedia 4 ,
 448 .Xr netintro 4 ,
 449 .Xr ng_ether 4 ,
 450 .Xr polling 4 ,
 451 .Xr vlan 4 ,
 452 .Xr ifconfig 8
 453 .Sh HISTORY
 454 The
 455 .Nm
 456 device driver first appeared in
 457 .Fx 7.1 .
 458 .Sh AUTHORS
 459 The
 460 .Nm
 461 driver was written by
 462 .An Intel Corporation Aq Mt freebsdnic@mailbox.intel.com .