igb: Update man page
authorSepherosa Ziehau <sephe@dragonflybsd.org>
Fri, 21 Jun 2013 08:58:40 +0000 (16:58 +0800)
committerSepherosa Ziehau <sephe@dragonflybsd.org>
Fri, 21 Jun 2013 08:59:59 +0000 (16:59 +0800)
share/man/man4/igb.4

index cc0a5ea..4fa8799 100644 (file)
@@ -31,7 +31,7 @@
 .\"
 .\" $FreeBSD: src/share/man/man4/igb.4,v 1.2 2010/05/14 20:11:30 marius Exp $
 .\"
-.Dd December 10, 2010
+.Dd June 21, 2013
 .Dt IGB 4
 .Os
 .Sh NAME
@@ -42,6 +42,7 @@ To compile this driver into the kernel,
 place the following line in your
 kernel configuration file:
 .Bd -ragged -offset indent
+.Cd "device ig_hal"
 .Cd "device igb"
 .Ed
 .Pp
@@ -49,35 +50,89 @@ Alternatively, to load the driver as a
 module at boot time, place the following line in
 .Xr loader.conf 5 :
 .Bd -literal -offset indent
+ig_hal_load="YES"
 if_igb_load="YES"
 .Ed
 .Sh DESCRIPTION
 The
 .Nm
-driver provides support for PCI Express Gigabit Ethernet adapters
-based on the Intel 82575 and 82576 Ethernet controller chips.
-The driver supports Transmit/Receive checksum offload and Jumbo
-Frames.
-Furthermore it supports TCP segmentation offload (TSO) on all
-adapters.
-.\"The identification LEDs of the adapters supported by the
-.\".Nm
-.\"driver can be controlled via the
-.\".Xr led 4
-.\"API for localization purposes.
+driver provides support for PCI Express Gigabit Ethernet adapters based on
+the Intel
+82575,
+82576,
+82580,
+I210,
+I211,
+and I350
+Ethernet controller chips.
+The
+.Nm
+driver supports:
 .Pp
-For questions related to hardware requirements, refer to the
-documentation supplied with your Intel PRO/1000 adapter.
-All hardware requirements listed apply to use with
-.Fx .
+.Bl -item -offset indent -compact
+.It
+Transmit/Receive checksum offload for IP/UDP/TCP.
+.\"Jumbo Frames.
+.It
+Interrupt moderation
+.It
+TCP segmentation offload (TSO)
+.It
+Receive side scaling (RSS)
+.It
+Multiple tranmission queues
+.It
+Multiple vector MSI-X
+.It
+VLAN tag stripping and inserting
+.El
 .Pp
-Support for Jumbo Frames is provided via the interface MTU setting.
-Selecting an MTU larger than 1500 bytes with the
-.Xr ifconfig 8
-utility configures the adapter to receive and transmit Jumbo Frames.
-The maximum MTU size for Jumbo Frames is 9216.
+If
+.Xr polling 4
+or MSI-X is used,
+by default,
+the
+.Nm
+driver will try enabling as many reception queues and transmission queues
+as are allowed by the number of CPUs in the system.
+.Pp
+82575 supports 4 reception queues and 4 transmission queues.
+MSI-X is not enabled due to hardware errata.
+Under MSI or legacy interrupt mode,
+2 reception queues are enabled for hardware RSS hash
+and only 1 transmission queue is enable.
+.Pp
+82576 supports 16 reception queues and 16 transmission queues.
+MSI-X is enable by default.
+However,
+due to the number of MSI-X vectors is 10,
+at most 8 reception queues and 8 transmission queues will be enabled
+under MSI-X mode.
+When
+.Xr polling 4
+is enabled on the devices,
+at most 16 reception queues and 16 transmission queues will be enabled.
+.Pp
+82580 and I350 support 8 reception queues and 8 transmission queues.
+MSI-X is enabled by default.
 .Pp
-This driver supports hardware assisted VLANs.
+I210 supports 4 reception queues and 4 transmission queues.
+MSI-X is enabled by default.
+.Pp
+I211 supports 2 reception queues and 2 transmission queues.
+MSI-X is enabled by default.
+.Pp
+.\"For questions related to hardware requirements, refer to the
+.\"documentation supplied with your Intel PRO/1000 adapter.
+.\"All hardware requirements listed apply to use with
+.\".Dx .
+.\".Pp
+.\"Support for Jumbo Frames is provided via the interface MTU setting.
+.\"Selecting an MTU larger than 1500 bytes with the
+.\".Xr ifconfig 8
+.\"utility configures the adapter to receive and transmit Jumbo Frames.
+.\"The maximum MTU size for Jumbo Frames is 9216.
+.\".Pp
 The
 .Nm
 driver supports the following media types:
@@ -103,7 +158,7 @@ Sets 1000Mbps operation.
 Only
 .Cm full-duplex
 mode is supported at this speed.
-.It Cm 1000baseTX
+.It Cm 1000baseT
 Sets 1000Mbps operation.
 Only
 .Cm full-duplex
@@ -131,75 +186,255 @@ is not specified, the driver defaults to
 .Pp
 For more information on configuring this device, see
 .Xr ifconfig 8 .
+The
+.Nm
+driver supports
+.Xr polling 4 .
 .Sh HARDWARE
 The
 .Nm
-driver supports Gigabit Ethernet adapters based on the Intel 82575 and
-82576 controller chips:
+driver supports Gigabit Ethernet adapters based on the Intel
+82575,
+82576,
+82580,
+I210,
+I211,
+and I350
+controller chips:
 .Pp
 .Bl -bullet -compact
 .It
-Intel Gigabit ET Dual Port Server Adapter (82576)
+Intel 82575EB Gigabit Ethernet Controller
+.It
+Intel 82576 Gigabit Ethernet Controller
+.It
+Intel 82580EB Gigabit Ethernet Controller
+.It
+Intel Ethernet Controller I210 Series
+.It
+Intel Ethernet Controller I211 Series
+.It
+Intel Ethernet Controller I350
+.It
+Intel Ethernet Server Adapter I210-T1
+.It
+Intel Ethernet Server Adapter I340-F4
+.It
+Intel Ethernet Server Adapter I340-T4
+.It
+Intel Ethernet Server Adapter I350-F2
+.It
+Intel Ethernet Server Adapter I350-F4
 .It
-Intel Gigabit VT Quad Port Server Adapter (82575)
+Intel Ethernet Server Adapter I350-T2
+.It
+Intel Ethernet Server Adapter I350-T4
+.It
+Intel Gigabit EF Dual Port Server Adapter
+.It
+Intel Gigabit ET Dual Port Server Adapter
+.It
+Intel Gigabit ET Quad Port Server Adapter
+.It
+Intel Gigabit ET2 Quad Port Server Adapter
+.It
+Intel Gigabit VT Quad Port Server Adapter
 .El
-.Sh LOADER TUNABLES
+.Sh TUNABLES
 Tunables can be set at the
 .Xr loader 8
 prompt before booting the kernel or stored in
 .Xr loader.conf 5 .
-.Bl -tag -width indent
-.It Va hw.igb.rxd
+.Em X
+is the device unit number.
+.Bl -tag -width ".Va hw.igbX.irq.unshared"
+.It Va hw.igb.rxd Va hw.igbX.rxd
 Number of receive descriptors allocated by the driver.
-The default value is 256.
-The minimum is 80, and the maximum is 4096.
-.It Va hw.igb.txd
+The default value is 512.
+The minimum is 256,
+and the maximum is 4096.
+.It Va hw.igb.txd Va hw.igbX.txd
 Number of transmit descriptors allocated by the driver.
-The default value is 256.
-The minimum is 80, and the maximum is 4096.
-.It Va hw.igb.enable_aim
-If set to 1, enable Adaptive Interrupt Moderation.
-The default is to enable Adaptive Interrupt Moderation.
+The default value is 1024.
+The minimum is 256,
+and the maximum is 4096.
+.It Va hw.igb.rxr Va hw.igbX.rxr
+This tunable specifies the number of reception queues could be enabled.
+Maximum allowed value for these tunables is device specific
+and it must be power of 2 aligned.
+Setting these tunables to 0 allows the driver to make
+as many reception queues ready-for-use as allowed by the number of CPUs.
+.It Va hw.igb.txr Va hw.igbX.txr
+This tunable specifies the number of transmission queues could be enabled.
+Maximum allowed value for these tunables is device specific
+and it must be power of 2 aligned.
+Setting these tunables to 0 allows the driver to make
+as many transmission queues ready-for-use as allowed by the number of CPUs.
+.It Va hw.igb.msix.enable Va hw.igbX.msix.enable
+By default,
+the driver will use MSI-X if it is supported.
+This behaviour can be turned off by setting this tunable to 0.
+.It Va hw.igbX.msix.off
+If MSI-X is used
+and the number of MSI-X vectors is not enough to
+put transmission queue processing and reception queue processing
+onto independent MSI-X vector,
+this tunable specifies the leading target CPU for
+transmission and reception queues processing.
+The value specificed must be aligned to the maximum of
+the number of reception queues
+and the number of transmission queues enabled,
+and must be less than the power of 2 number of CPUs.
+.It Va hw.igbX.msix.rxoff
+If MSI-X is used
+and the number of MSI-X vectors is enough to
+put transmission queue processing and reception queue processing
+onto independent MSI-X vector,
+this tunable specifies the leading target CPU for reception queues processing.
+The value specificed must be aligned to the number of reception queues enabled
+and must be less than the power of 2 number of CPUs.
+.It Va hw.igbX.msix.txoff
+If MSI-X is used
+and the number of MSI-X vectors is enough to
+put transmission queue processing and reception queue processing
+onto independent MSI-X vector,
+this tunable specifies the leading target CPU
+for transmission queues processing.
+The value specificed must be aligned to
+the number of transmission queues enabled
+and must be less than the power of 2 number of CPUs.
+.It Va hw.igb.msi.enable Va hw.igbX.msi.enable
+If MSI-X is disabled and MSI is supported,
+the driver will use MSI.
+This behavior can be turned off by setting this tunable to 0.
+.It Va hw.igbX.msi.cpu
+If MSI is used,
+it specifies the MSI's target CPU.
+.It Va hw.igbX.irq.unshared
+If legacy interrupt is used,
+by default,
+the driver assumes the interrupt could be shared.
+Setting this tunable to 1 allows the driver to perform certain
+optimization based on the knowledge that the interrupt is not shared.
+.It Va hw.igbX.npoll.txoff
+This tunable specifies the leading target CPU for
+transmission queue
+.Xr polling 4
+processing.
+The value specificed must be aligned to the number of transmission queues
+enabled and must be less than the power of 2 number of CPUs.
+.It Va hw.igbX.npoll.rxoff
+This tunable specifies the leading target CPU for
+reception queue
+.Xr polling 4
+processing.
+The value specificed must be aligned to the number of reception queues
+enabled and must be less than the power of 2 number of CPUs.
 .El
-.Sh DIAGNOSTICS
-.Bl -diag
-.It "igb%d: Unable to allocate bus resource: memory"
-A fatal initialization error has occurred.
-.It "igb%d: Unable to allocate bus resource: interrupt"
-A fatal initialization error has occurred.
-.It "igb%d: watchdog timeout -- resetting"
-The device has stopped responding to the network, or there is a problem with
-the network connection (cable).
+.Sh MIB Variables
+A number of per-interface variables are implemented in the
+.Va hw.igb Ns Em X
+branch of the
+.Xr sysctl 3
+MIB.
+.Bl -tag -width "tx_intr_nsegs"
+.It Va rxr
+Number of reception queues could be enabled (read-only).
+Use the tunable
+.Va hw.igb.rxr
+or
+.Va hw.igbX.rxr
+to configure it.
+.It Va rxr_inuse
+Number of reception queues being used (read-only).
+.It Va txr
+Number of transmission queues could be enabled (read-only).
+Use the tunable
+.Va hw.igb.txr
+or
+.Va hw.igbX.txr
+to configure it.
+.It Va txr_inuse
+Number of transmission queues being used (read-only).
+.It Va rxd
+Number of descriptors per reception queue (read-only).
+Use the tunable
+.Va hw.igb.rxd
+or
+.Va hw.igbX.rxd
+to configure it.
+.It Va txd
+Number of descriptors per transmission queue (read-only).
+Use the tunable
+.Va hw.igb.txd
+or
+.Va hw.igbX.txd
+to configure it.
+.It Va intr_rate
+If MSI or legacy interrupt is used,
+this sysctl controls the highest possible frequency
+that interrupt could be generated by the device.
+It is 6000 by default (~150us).
+.It Va msixY_rate
+If MSI-X is used,
+this sysctl controls the highest possible frequency
+that interrupt could be generated by the
+.Em Y
+MSI-X vector.
+For reception processing only MSI-X vector,
+the default value is 6000 (~150us).
+For transmission processing only MSI-X vector,
+the default value is 4000 (250us).
+For MSI-X vector which handles both reception and transmission,
+the default value is 6000 (~150us).
+.It Va tx_intr_nsegs
+Transmission interrupt is asked to be generated upon every
+.Va tx_intr_nsegs
+transmission descritors having been setup.
+The default value is 1/16 of the number of transmission descriptors per queue.
+.It Va tx_wreg_nsegs
+The number of transmission descriptors should be setup
+before the hardware register is written.
+Setting this value too high will have negative effect
+on transmission timeliness.
+Setting this value too low will hurt overall transmission performance
+due to the frequent hardware register writing.
+The default value is 8.
+.It Va rx_wreg_nsegs
+The number of reception descriptors should be setup
+before the hardware register is written.
+Setting this value too high will make device drop incoming packets.
+Setting this value too low will hurt overall reception performance
+due to the frequent hardware register writing.
+The default value is 32.
+.It Va npoll_rxoff
+See the tunable
+.Va hw.igbX.npoll.rxoff .
+The set value will take effect the next time
+.Xr polling 4
+is enabled on the device.
+.It Va npoll_txoff
+See the tunable
+.Va hw.igbX.npoll.txoff .
+The set value will take effect the next time
+.Xr polling 4
+is enabled on the device.
 .El
-.Sh SUPPORT
-For general information and support,
-go to the Intel support website at:
-.Pa http://support.intel.com .
-.Pp
-If an issue is identified with the released source code on the supported kernel
-with a supported adapter, email the specific information related to the
-issue to
-.Aq freebsdnic@mailbox.intel.com .
-.\".Sh FILES
-.\".Bl -tag -width /dev/led/igb*
-.\".It Pa /dev/led/igb*
-.\"identification LED device nodes
-.\".El
-.\".Sh EXAMPLES
-.\"Make the identification LED of igb0 blink:
-.\".Pp
-.\".Dl "echo f2 > /dev/led/igb0"
-.\".Pp
-.\"Turn the identification LED of igb0 off again:
-.\".Pp
-.\".Dl "echo 0 > /dev/led/igb0"
+.\".Sh SUPPORT
+.\"For general information and support,
+.\"go to the Intel support website at:
+.\".Pa http://support.intel.com .
 .\".Pp
+.\"If an issue is identified with the released source code on the supported kernel
+.\"with a supported adapter, email the specific information related to the
+.\"issue to
+.\".Aq freebsdnic@mailbox.intel.com .
 .Sh SEE ALSO
 .Xr altq 4 ,
 .Xr arp 4 ,
 .Xr em 4 ,
+.Xr emx 4 ,
 .Xr ifmedia 4 ,
-.\".Xr led 4 ,
 .Xr netintro 4 ,
 .Xr ng_ether 4 ,
 .Xr polling 4 ,