[PATCH 0/3] improve documentation iavf driver

[PATCH 0/3] improve documentation iavf driver

[Bruce Richardson]

Some small cleanups and reformatting of the iavf driver documentation
to make it easier to read. Also add an additional note on large VF
support.

Bruce Richardson (3):
  doc/nics: improve structure of Intel VF section
  doc/nics: rework notes for iavf use
  doc/nics: document how to create large VFs for iavf

 doc/guides/nics/intel_vf.rst | 83 +++++++++++++++++++++++-------------
 1 file changed, 53 insertions(+), 30 deletions(-)

--
2.43.0

[PATCH 1/3] doc/nics: improve structure of Intel VF section

[Bruce Richardson]

The Intel VF section in the NIC guide document had descriptions of the
various drivers at a very deep level of the document hierarchy. Improve
the structure of the doc by giving those per-driver subsections their
own top-level section. Also create a new top-level section for details
of hypervisor use of VFs.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/nics/intel_vf.rst | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/doc/guides/nics/intel_vf.rst b/doc/guides/nics/intel_vf.rst
index 4780ee7add..2b0eebcafe 100644
--- a/doc/guides/nics/intel_vf.rst
+++ b/doc/guides/nics/intel_vf.rst
@@ -68,8 +68,12 @@ and the Physical Function operates on the global resources on behalf of the Virt
 For this out-of-band communication, an SR-IOV enabled NIC provides a memory buffer for each Virtual Function,
 which is called a "Mailbox".
 
+Intel SR-IOV drivers
+--------------------
+
+
 Intel® Ethernet Adaptive Virtual Function
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Adaptive Virtual Function (IAVF) is a SR-IOV Virtual Function with the same device id (8086:1889) on different Intel Ethernet Controller.
 IAVF Driver is VF driver which supports for all future Intel devices without requiring a VM update. And since this happens to be an adaptive VF driver,
 every new drop of the VF driver would add more and more advanced features that can be turned on in the VM if the underlying HW device supports those
@@ -126,7 +130,7 @@ For more detail on SR-IOV, please refer to the following documents:
     * ``offload``: Check for use of an unsupported offload flag.
 
 The PCIE host-interface of Intel Ethernet Switch FM10000 Series VF infrastructure
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In a virtualized environment, the programmer can enable a maximum of *64 Virtual Functions (VF)*
 globally per PCIE host-interface of the Intel Ethernet Switch FM10000 Series device.
@@ -157,7 +161,7 @@ However:
     The above is an important consideration to take into account when targeting specific packets to a selected port.
 
 Intel® X710/XL710 Gigabit Ethernet Controller VF Infrastructure
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In a virtualized environment, the programmer can enable a maximum of *128 Virtual Functions (VF)*
 globally per Intel® X710/XL710 Gigabit Ethernet Controller NIC device.
@@ -196,7 +200,7 @@ However:
     one transmit queue. The default number of queue pairs per VF is 4, and can be 16 in maximum.
 
 Intel® 82599 10 Gigabit Ethernet Controller VF Infrastructure
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The programmer can enable a maximum of *63 Virtual Functions* and there must be *one Physical Function* per Intel® 82599
 10 Gigabit Ethernet Controller NIC port.
@@ -271,7 +275,7 @@ However:
     The above is an important consideration to take into account when targeting specific packets to a selected port.
 
 Intel® 82576 Gigabit Ethernet Controller and Intel® Ethernet Controller I350 Family VF Infrastructure
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In a virtualized environment, an Intel® 82576 Gigabit Ethernet Controller serves up to eight virtual machines (VMs).
 The controller has 16 TX and 16 RX queues.
@@ -316,6 +320,10 @@ However:
 
     The above is an important consideration to take into account when targeting specific packets to a selected port.
 
+
+Hypervisor Use of VFs
+---------------------
+
 Validated Hypervisors
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -341,7 +349,7 @@ For supported kernel versions, refer to the *DPDK Release Notes*.
 .. _intel_vf_kvm:
 
 Setting Up a KVM Virtual Machine Monitor
-----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following describes a target environment:
 
-- 
2.43.0

[PATCH 2/3] doc/nics: rework notes for iavf use

[Bruce Richardson]

When describing the iavf driver, there was a lot of text in a single
note block which could be clarified by splitting it up into separate
sections and appropriate bulletted lists.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/nics/intel_vf.rst | 60 +++++++++++++++++++++---------------
 1 file changed, 35 insertions(+), 25 deletions(-)

diff --git a/doc/guides/nics/intel_vf.rst b/doc/guides/nics/intel_vf.rst
index 2b0eebcafe..708cb85417 100644
--- a/doc/guides/nics/intel_vf.rst
+++ b/doc/guides/nics/intel_vf.rst
@@ -88,36 +88,26 @@ For more detail on SR-IOV, please refer to the following documents:
 
 *   `Intel® IAVF HAS <https://www.intel.com/content/dam/www/public/us/en/documents/product-specifications/ethernet-adaptive-virtual-function-hardware-spec.pdf>`_
 
-.. note::
-
-    To use DPDK IAVF PMD on Intel® 700 Series Ethernet Controller, the device id (0x1889) need to specified during device
-    assignment in hypervisor. Take qemu for example, the device assignment should carry the IAVF device id (0x1889) like
-    ``-device vfio-pci,x-pci-device-id=0x1889,host=03:0a.0``.
-
-    When IAVF is backed by an Intel® E810 device, the "Protocol Extraction" feature which is supported by ice PMD is also
-    available for IAVF PMD. The same devargs with the same parameters can be applied to IAVF PMD, for detail please reference
-    the section ``Protocol extraction for per queue`` of ice.rst.
-
-    Quanta size configuration is also supported when IAVF is backed by an Intel® E810 device by setting ``devargs``
-    parameter ``quanta_size`` like ``-a 18:00.0,quanta_size=2048``. The default value is 1024, and quanta size should be
-    set as the product of 64 in legacy host interface mode.
-
-    When IAVF is backed by an Intel® E810 device or an Intel® 700 Series Ethernet device, the reset watchdog is enabled
-    when link state changes to down. The default period is 2000us, defined by ``IAVF_DEV_WATCHDOG_PERIOD``.
-    Set ``devargs`` parameter ``watchdog_period`` to adjust the watchdog period in microseconds, or set it to 0 to disable the watchdog,
+IAVF PMD parameters
+^^^^^^^^^^^^^^^^^^^
+
+``watchdog_period``
+    The reset watchdog is enabled when link state changes to down.
+    The default period is 2000us, defined by ``IAVF_DEV_WATCHDOG_PERIOD``.
+    Set ``devargs`` parameter ``watchdog_period`` to adjust the watchdog period in microseconds,
+    or set it to 0 to disable the watchdog,
     for example, ``-a 18:01.0,watchdog_period=5000`` or ``-a 18:01.0,watchdog_period=0``.
 
-    Enable VF auto-reset by setting the devargs parameter like ``-a 18:01.0,auto_reset=1``
-    when IAVF is backed by an Intel\ |reg| E810 device
-    or an Intel\ |reg| 700 Series Ethernet device.
+``auto_reset``
+    Enable VF auto-reset by setting the devargs parameter,
+    for example ``-a 18:01.0,auto_reset=1``,
 
+``no-poll-on-link-down``
     Stop polling Rx/Tx hardware queue when link is down
-    by setting the ``devargs`` parameter like ``-a 18:01.0,no-poll-on-link-down=1``
-    when IAVF is backed by an Intel\ |reg| E810 device or an Intel\ |reg| 700 Series Ethernet device.
+    by setting the ``devargs`` parameter like ``-a 18:01.0,no-poll-on-link-down=1``.
 
-    Similarly, when IAVF is backed by an Intel\ |reg| E810 device
-    or an Intel\ |reg| 700 Series Ethernet device,
-    set the ``devargs`` parameter ``mbuf_check`` to enable Tx diagnostics.
+``mbuf_check``
+    Set the ``devargs`` parameter ``mbuf_check`` to enable Tx diagnostics.
     For example, ``-a 18:01.0,mbuf_check=<case>`` or ``-a 18:01.0,mbuf_check=[<case1>,<case2>...]``.
     Thereafter, ``rte_eth_xstats_get()`` can be used to get the error counts,
     which are collected in ``tx_mbuf_error_packets`` xstats.
@@ -129,6 +119,26 @@ For more detail on SR-IOV, please refer to the following documents:
     * ``segment``: Check number of mbuf segments does not exceed HW limits.
     * ``offload``: Check for use of an unsupported offload flag.
 
+
+HW-Specific Notes For IAVF
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Intel\ |reg| 700 Series Ethernet devices:
+
+* To use DPDK IAVF PMD the device id (0x1889) need to specified during device assignment in hypervisor.
+  For example, on qemu, the device assignment should carry the IAVF device id (0x1889) like
+  ``-device vfio-pci,x-pci-device-id=0x1889,host=03:0a.0``.
+
+Intel\ |reg| E800 Series Ethernet devices:
+
+* the "Protocol Extraction" feature which is supported by ice PMD is also available for IAVF PMD. The same devargs with the same parameters can be applied to IAVF PMD.
+  for Detail please reference the section ``Protocol extraction for per queue`` of ice.rst.
+
+* Quanta size configuration is supported by setting ``devargs`` parameter ``quanta_size``,
+  for example: ``-a 18:00.0,quanta_size=2048``.
+  The default value is 1024, and quanta size should be set as the product of 64 in legacy host interface mode.
+
+
 The PCIE host-interface of Intel Ethernet Switch FM10000 Series VF infrastructure
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.43.0

[PATCH 3/3] doc/nics: document how to create large VFs for iavf

[Bruce Richardson]

Document the additional step necessary to create large VFs for iavf when
using ice kernel driver v1.13.7 or later.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/nics/intel_vf.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/doc/guides/nics/intel_vf.rst b/doc/guides/nics/intel_vf.rst
index 708cb85417..eb939df41a 100644
--- a/doc/guides/nics/intel_vf.rst
+++ b/doc/guides/nics/intel_vf.rst
@@ -138,6 +138,11 @@ Intel\ |reg| E800 Series Ethernet devices:
   for example: ``-a 18:00.0,quanta_size=2048``.
   The default value is 1024, and quanta size should be set as the product of 64 in legacy host interface mode.
 
+* When using the Intel out-of-tree "ice" PF/kernel driver v1.13.7 or later,
+  to create VFs with >16 queues (aka. "large VFs"),
+  it is necessary to change the rss_lut_vf_addr setting in sysfs from the default of 64 to 512.
+  This can be done using the following command for the first VF on an interface:
+  ``echo 512 > /sys/class/net/<PF interface>/device/virtfn0/rss_lut_vf_attr``
 
 The PCIE host-interface of Intel Ethernet Switch FM10000 Series VF infrastructure
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.43.0