[PATCH 1/2] igb.txt: Add igb documentation

[PATCH 1/2] igb.txt: Add igb documentation

[Jeff Kirsher]

Add documentation for the igb networking driver.

Signed-off-by: Jeff Kirsher <jeffrey.t.kirsher@intel.com>
Tested-by: Jeff Pieper <jeffrey.e.pieper@intel.com>
---

 Documentation/networking/igb.txt |  134 ++++++++++++++++++++++++++++++++++++++
 1 files changed, 134 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/networking/igb.txt

diff --git a/Documentation/networking/igb.txt b/Documentation/networking/igb.txt
new file mode 100644
index 0000000..975023a
--- /dev/null
+++ b/Documentation/networking/igb.txt
@@ -0,0 +1,134 @@
+Linux* Base Driver for Intel(R) Network Connection
+==================================================
+
+Intel Gigabit Linux driver.
+Copyright(c) 1999 - 2010 Intel Corporation.
+
+Contents
+========
+
+- Identifying Your Adapter
+- Additional Configurations
+- Support
+
+Identifying Your Adapter
+========================
+
+This driver supports all 82575, 82576 and 82580-based Intel (R) gigabit network
+connections.
+
+For specific information on how to identify your adapter, go to the Adapter &
+Driver ID Guide at:
+
+    http://support.intel.com/support/go/network/adapter/idguide.htm
+
+Command Line Parameters
+=======================
+
+The default value for each parameter is generally the recommended setting,
+unless otherwise noted.
+ 
+max_vfs
+-------
+Valid Range:   0-7
+Default Value: 0
+
+This parameter adds support for SR-IOV.  It causes the driver to spawn up to 
+max_vfs worth of virtual function.  
+
+Additional Configurations
+=========================
+
+  Jumbo Frames
+  ------------
+  Jumbo Frames support is enabled by changing the MTU to a value larger than
+  the default of 1500.  Use the ifconfig command to increase the MTU size.
+  For example:
+
+       ifconfig eth<x> mtu 9000 up
+
+  This setting is not saved across reboots.  
+
+  Notes:
+
+  - The maximum MTU setting for Jumbo Frames is 9216.  This value coincides
+    with the maximum Jumbo Frames size of 9234 bytes.
+
+  - Using Jumbo Frames at 10 or 100 Mbps may result in poor performance or
+    loss of link.
+
+  Ethtool
+  -------
+  The driver utilizes the ethtool interface for driver configuration and
+  diagnostics, as well as displaying statistical information.  Ethtool
+  version 3.0 or later is required for this functionality, although we 
+  strongly recommend downloading the latest version at:
+
+  http://sourceforge.net/projects/gkernel.
+
+  Enabling Wake on LAN* (WoL)
+  ---------------------------
+  WoL is configured through the Ethtool* utility. 
+
+  For instructions on enabling WoL with Ethtool, refer to the Ethtool man page.
+
+  WoL will be enabled on the system during the next shut down or reboot.
+  For this driver version, in order to enable WoL, the igb driver must be
+  loaded when shutting down or rebooting the system.
+
+  Wake On LAN is only supported on port A of multi-port adapters.
+
+  Wake On LAN is not supported for the Intel(R) Gigabit VT Quad Port Server 
+  Adapter.
+
+  Multiqueue
+  ----------
+  In this mode, a separate MSI-X vector is allocated for each queue and one
+  for "other" interrupts such as link status change and errors.  All 
+  interrupts are throttled via interrupt moderation.  Interrupt moderation 
+  must be used to avoid interrupt storms while the driver is processing one 
+  interrupt.  The moderation value should be at least as large as the expected
+  time for the driver to process an interrupt. Multiqueue is off by default.
+
+  REQUIREMENTS: MSI-X support is required for Multiqueue. If MSI-X is not 
+  found, the system will fallback to MSI or to Legacy interrupts.
+
+  LRO
+  ---
+  Large Receive Offload (LRO) is a technique for increasing inbound throughput
+  of high-bandwidth network connections by reducing CPU overhead. It works by
+  aggregating multiple incoming packets from a single stream into a larger 
+  buffer before they are passed higher up the networking stack, thus reducing
+  the number of packets that have to be processed. LRO combines multiple 
+  Ethernet frames into a single receive in the stack, thereby potentially 
+  decreasing CPU utilization for receives.
+
+  NOTE: LRO requires 2.6.24 or later kernel version. You also need to have
+  inet_lro enabled via either the CONFIG_INET_LRO or CONFIG_INET_LRO_MODULE 
+  kernel config option. Additionally, if CONFIG_INET_LRO_MODULE is used, the
+  inet_lro module needs to be loaded before the igb driver.
+
+  You can verify that the driver is using LRO by looking at these counters in 
+  Ethtool:
+
+  lro_aggregated - count of total packets that were combined
+  lro_flushed - counts the number of packets flushed out of LRO
+  lro_no_desc - counts the number of times an LRO descriptor was not available 
+  for the LRO packet
+
+  NOTE: IPv6 and UDP are not supported by LRO.
+
+Support
+=======
+
+For general information, go to the Intel support website at:
+
+    www.intel.com/support/
+
+or the Intel Wired Networking project hosted by Sourceforge at:
+
+    http://sourceforge.net/projects/e1000
+
+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 e1000-devel@lists.sf.net

[PATCH 2/2] igbvf.txt: Add igbvf Documentation

[Jeff Kirsher]

Adds documentation for the igbvf (igb virtual function driver).

Signed-off-by: Jeff Kirsher <jeffrey.t.kirsher@intel.com>
Tested-by: Jeff Pieper <jeffrey.e.pieper@intel.com>
---

 Documentation/networking/igbvf.txt |   82 ++++++++++++++++++++++++++++++++++++
 1 files changed, 82 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/networking/igbvf.txt

diff --git a/Documentation/networking/igbvf.txt b/Documentation/networking/igbvf.txt
new file mode 100644
index 0000000..06bf4bf
--- /dev/null
+++ b/Documentation/networking/igbvf.txt
@@ -0,0 +1,82 @@
+Linux* Base Driver for Intel(R) Network Connection
+==================================================
+
+Intel Gigabit Linux driver.
+Copyright(c) 1999 - 2010 Intel Corporation.
+
+Contents
+========
+
+- Identifying Your Adapter
+- Additional Configurations
+- Support
+
+This file describes the igbvf Linux* Base Driver for Intel Network Connection.  
+
+The igbvf driver supports 82576-based virtual function devices that can only 
+be activated on kernels that support SR-IOV. SR-IOV requires the correct 
+platform and OS support. 
+
+The igbvf driver requires the igb driver, version 2.0 or later. The igbvf 
+driver supports virtual functions generated by the igb driver with a max_vfs 
+value of 1 or greater. For more information on the max_vfs parameter refer 
+to the README included with the igb driver.
+
+The guest OS loading the igbvf driver must support MSI-X interrupts.
+
+This driver is only supported as a loadable module at this time.  Intel is
+not supplying patches against the kernel source to allow for static linking
+of the driver.  For questions related to hardware requirements, refer to the
+documentation supplied with your Intel Gigabit adapter.  All hardware
+requirements listed apply to use with Linux.
+
+Instructions on updating ethtool can be found in the section "Additional
+Configurations" later in this document.
+
+VLANs: There is a limit of a total of 32 shared VLANs to 1 or more VFs.
+
+Identifying Your Adapter
+========================
+
+The igbvf driver supports 82576-based virtual function devices that can only 
+be activated on kernels that support SR-IOV.
+
+For more information on how to identify your adapter, go to the Adapter &
+Driver ID Guide at:
+
+    http://support.intel.com/support/go/network/adapter/idguide.htm
+
+For the latest Intel network drivers for Linux, refer to the following
+website.  In the search field, enter your adapter name or type, or use the
+networking link on the left to search for your adapter:
+
+    http://downloadcenter.intel.com/scripts-df-external/Support_Intel.aspx
+
+Additional Configurations
+=========================
+
+  Ethtool
+  -------
+  The driver utilizes the ethtool interface for driver configuration and
+  diagnostics, as well as displaying statistical information.  Ethtool
+  version 3.0 or later is required for this functionality, although we 
+  strongly recommend downloading the latest version at:
+
+  http://sourceforge.net/projects/gkernel.
+
+Support
+=======
+
+For general information, go to the Intel support website at:
+
+    http://support.intel.com
+
+or the Intel Wired Networking project hosted by Sourceforge at:
+
+    http://sourceforge.net/projects/e1000
+
+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 e1000-devel@lists.sf.net
+
+

Re: [PATCH 2/2] igbvf.txt: Add igbvf Documentation

[David Miller]

From: Jeff Kirsher <jeffrey.t.kirsher@intel.com>
Date: Tue, 03 Aug 2010 17:16:17 -0700

> Adds documentation for the igbvf (igb virtual function driver).
> 
> Signed-off-by: Jeff Kirsher <jeffrey.t.kirsher@intel.com>
> Tested-by: Jeff Pieper <jeffrey.e.pieper@intel.com>

Tons of trailing whitespace, GIT nearly craps itself when I try
to apply this.

Please fix this, and also submit the fixed up 1/1 ixgbe.txt doc patch
and even more importantly the ixgbe FCOE build fix you promised I'd
have two nights ago :-)

Thanks.

Re: [PATCH 2/2] igbvf.txt: Add igbvf Documentation

[Jeff Kirsher]

On Sat, Aug 7, 2010 at 23:01, David Miller <davem@davemloft.net> wrote:
> From: Jeff Kirsher <jeffrey.t.kirsher@intel.com>
> Date: Tue, 03 Aug 2010 17:16:17 -0700
>
>> Adds documentation for the igbvf (igb virtual function driver).
>>
>> Signed-off-by: Jeff Kirsher <jeffrey.t.kirsher@intel.com>
>> Tested-by: Jeff Pieper <jeffrey.e.pieper@intel.com>
>
> Tons of trailing whitespace, GIT nearly craps itself when I try
> to apply this.
>
> Please fix this, and also submit the fixed up 1/1 ixgbe.txt doc patch
> and even more importantly the ixgbe FCOE build fix you promised I'd
> have two nights ago :-)
>
> Thanks.
> --

I will get you everything tonight, sorry about not getting the ixgbe
FCOE build fix when I said I would.  I was expecting better internet
connectivity than what I had the last couple of days.

-- 
Cheers,
Jeff

Re: [PATCH 1/2] igb.txt: Add igb documentation

[Joe Perches]

On Tue, 2010-08-03 at 17:15 -0700, Jeff Kirsher wrote:
> Add documentation for the igb networking driver.

It'd be nice if you could scare up
register level ipw-2xxx docs.

Re: [PATCH 1/2] igb.txt: Add igb documentation

[Jeff Kirsher]

On Tue, Aug 3, 2010 at 17:39, Joe Perches <joe@perches.com> wrote:
> On Tue, 2010-08-03 at 17:15 -0700, Jeff Kirsher wrote:
>> Add documentation for the igb networking driver.
>
> It'd be nice if you could scare up
> register level ipw-2xxx docs.
>
>
> --

That would be wireless, and I am with Wired LAN.  Although Joe, I will
see what I can come up with, but I cannot promise anything... :)

-- 
Cheers,
Jeff

Re: [PATCH 1/2] igb.txt: Add igb documentation

[Ben Hutchings]

On Tue, 2010-08-03 at 17:15 -0700, Jeff Kirsher wrote:
[...]
> +  Jumbo Frames
> +  ------------
> +  Jumbo Frames support is enabled by changing the MTU to a value larger than
> +  the default of 1500.  Use the ifconfig command to increase the MTU size.
> +  For example:
> +
> +       ifconfig eth<x> mtu 9000 up
> +
> +  This setting is not saved across reboots.  

Not igb-specific.

[...]
> +  Ethtool
> +  -------
> +  The driver utilizes the ethtool interface for driver configuration and
> +  diagnostics, as well as displaying statistical information.  Ethtool
> +  version 3.0 or later is required for this functionality, although we 
> +  strongly recommend downloading the latest version at:
> +
> +  http://sourceforge.net/projects/gkernel.

Not igb-specific, and seriously - 3.0?

> +  Enabling Wake on LAN* (WoL)
> +  ---------------------------
> +  WoL is configured through the Ethtool* utility. 

Not igb-specific.

[...]
> +  LRO
> +  ---
> +  Large Receive Offload (LRO) is a technique for increasing inbound throughput
> +  of high-bandwidth network connections by reducing CPU overhead. It works by
> +  aggregating multiple incoming packets from a single stream into a larger 
> +  buffer before they are passed higher up the networking stack, thus reducing
> +  the number of packets that have to be processed. LRO combines multiple 
> +  Ethernet frames into a single receive in the stack, thereby potentially 
> +  decreasing CPU utilization for receives.

Not igb-specific.

> +  NOTE: LRO requires 2.6.24 or later kernel version.
[...]

Which is irrelevant to an in-tree driver.

Ben.

-- 
Ben Hutchings, Senior Software Engineer, Solarflare Communications
Not speaking for my employer; that's the marketing department's job.
They asked us to note that Solarflare product names are trademarked.

Re: [PATCH 1/2] igb.txt: Add igb documentation

[Jeff Kirsher]

0On Tue, Aug 3, 2010 at 19:34, Ben Hutchings <bhutchings@solarflare.com> wrote:
> On Tue, 2010-08-03 at 17:15 -0700, Jeff Kirsher wrote:
> [...]
>> +  Jumbo Frames
>> +  ------------
>> +  Jumbo Frames support is enabled by changing the MTU to a value larger than
>> +  the default of 1500.  Use the ifconfig command to increase the MTU size.
>> +  For example:
>> +
>> +       ifconfig eth<x> mtu 9000 up
>> +
>> +  This setting is not saved across reboots.
>
> Not igb-specific.
>
> [...]
>> +  Ethtool
>> +  -------
>> +  The driver utilizes the ethtool interface for driver configuration and
>> +  diagnostics, as well as displaying statistical information.  Ethtool
>> +  version 3.0 or later is required for this functionality, although we
>> +  strongly recommend downloading the latest version at:
>> +
>> +  http://sourceforge.net/projects/gkernel.
>
> Not igb-specific, and seriously - 3.0?
>
>> +  Enabling Wake on LAN* (WoL)
>> +  ---------------------------
>> +  WoL is configured through the Ethtool* utility.
>
> Not igb-specific.
>
> [...]
>> +  LRO
>> +  ---
>> +  Large Receive Offload (LRO) is a technique for increasing inbound throughput
>> +  of high-bandwidth network connections by reducing CPU overhead. It works by
>> +  aggregating multiple incoming packets from a single stream into a larger
>> +  buffer before they are passed higher up the networking stack, thus reducing
>> +  the number of packets that have to be processed. LRO combines multiple
>> +  Ethernet frames into a single receive in the stack, thereby potentially
>> +  decreasing CPU utilization for receives.
>
> Not igb-specific.
>
>> +  NOTE: LRO requires 2.6.24 or later kernel version.
> [...]
>
> Which is irrelevant to an in-tree driver.
>
> Ben.
>
> --
> Ben Hutchings, Senior Software Engineer, Solarflare Communications
> Not speaking for my employer; that's the marketing department's job.
> They asked us to note that Solarflare product names are trademarked.
>

Thanks for the review Ben.

I am fine and agree with removing the reference to Ethtool version 3.0
and reference to LRO requiring 2.6.24 kernel.  Sorry we did not catch
the earlier...

As far as the 4 sections you noted as not being igb-specific, while
these sections are not specific to the driver, I see them as useful to
users trying to find more information on the driver and how to
configure it.  IMHO more documentation is more useful that too little,
as long as you are not adding bloat to the documentation which makes
it difficult to find what you are looking for.

If I am in minority here, I fine with removing the non-igb specific
sections as well.

-- 
Cheers,
Jeff