[dpdk-dev] [PATCH v1 0/2] failsafe: improve documentation

[dpdk-dev] [PATCH v1 0/2] failsafe: improve documentation

[Gaetan Rivet]

The fail-safe documentation is subpar. It can be improved (1), and an
error is present from the beginning (2).

Gaetan Rivet (2):
  doc/failsafe: improve fail-safe documentation
  doc/failsafe: fix incorrect statement regarding number of sub-device

 doc/guides/nics/fail_safe.rst | 109 +++++++++++++++++++++-------------
 1 file changed, 67 insertions(+), 42 deletions(-)

-- 
2.25.0

[dpdk-dev] [PATCH v1 1/2] doc/failsafe: improve fail-safe documentation

[Gaetan Rivet]

Reading the fail-safe doc with a few years added, a few phrasing
choices are ambiguous or confusing.

Signed-off-by: Gaetan Rivet <grive@u256.net>
---
 doc/guides/nics/fail_safe.rst | 107 +++++++++++++++++++++-------------
 1 file changed, 66 insertions(+), 41 deletions(-)

diff --git a/doc/guides/nics/fail_safe.rst b/doc/guides/nics/fail_safe.rst
index 6c02d7ef6..3ce2f8bee 100644
--- a/doc/guides/nics/fail_safe.rst
+++ b/doc/guides/nics/fail_safe.rst
@@ -4,13 +4,14 @@
 Fail-safe poll mode driver library
 ==================================
 
-The Fail-safe poll mode driver library (**librte_pmd_failsafe**) is a virtual
-device that allows using any device supporting hotplug (sudden device removal
-and plugging on its bus), without modifying other components relying on such
-device (application, other PMDs).
+The Fail-safe poll mode driver library (**librte_pmd_failsafe**) implements a
+virtual device that allows using device supporting hotplug, without modifying
+other components relying on such device (application, other PMDs).
+In this context, hotplug support is meant as plugging or removing a device
+from its bus suddenly.
 
 Additionally to the Seamless Hotplug feature, the Fail-safe PMD offers the
-ability to redirect operations to secondary devices when the primary has been
+ability to redirect operations to a secondary device when the primary has been
 removed from the system.
 
 .. note::
@@ -23,24 +24,23 @@ Features
 
 The Fail-safe PMD only supports a limited set of features. If you plan to use a
 device underneath the Fail-safe PMD with a specific feature, this feature must
-be supported by the Fail-safe PMD to avoid throwing any error.
+also be supported by the Fail-safe PMD.
 
-A notable exception is the device removal feature. The fail-safe PMD being a
-virtual device, it cannot currently be removed in the sense of a specific bus
-hotplug, like for PCI for example. It will however enable this feature for its
-sub-device automatically, detecting those that are capable and register the
-relevant callback for such event.
+A notable exception is the device removal feature. The fail-safe PMD is not
+meant to be removed itself, unlike its sub-devices which should support it.
+If a sub-device supports hotplugging, the fail-safe PMD will enable its use
+automatically by detecting capable devices and registering the relevant handler.
 
 Check the feature matrix for the complete set of supported features.
 
 Compilation option
 ------------------
 
-This option can be modified in the ``$RTE_TARGET/build/.config`` file.
+Available options within the ``$RTE_TARGET/build/.config`` file:
 
 - ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` (default **y**)
 
-  Toggle compiling librte_pmd_failsafe.
+  This option enables or disables compiling librte_pmd_failsafe.
 
 Using the Fail-safe PMD from the EAL command line
 -------------------------------------------------
@@ -51,8 +51,7 @@ must start with the *net_failsafe* prefix, followed by numbers or letters. This
 name must be unique for each device. Each fail-safe instance must have at least one
 sub-device, up to ``RTE_MAX_ETHPORTS-1``.
 
-A sub-device can be any legal DPDK device, including possibly another fail-safe
-instance.
+A sub-device can be any DPDK device, including possibly another fail-safe device.
 
 Fail-safe command line parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -60,20 +59,23 @@ Fail-safe command line parameters
 - **dev(<iface>)** parameter
 
   This parameter allows the user to define a sub-device. The ``<iface>`` part of
-  this parameter must be a valid device definition. It could be the argument
-  provided to any ``-w`` device specification or the argument that would be
-  given to a ``--vdev`` parameter (including a fail-safe).
-  Enclosing the device definition within parenthesis here allows using
+  this parameter must be a valid device definition. It follows the same format
+  provided to any ``-w`` or ``--vdev`` options.
+
+  Enclosing the device definition within parentheses here allows using
   additional sub-device parameters if need be. They will be passed on to the
   sub-device.
 
 .. note::
 
-   In case of whitelist sub-device probed by EAL, fail-safe PMD will take the device
-   as is, which means that EAL device options are taken in this case.
-   When trying to use a PCI device automatically probed in blacklist mode,
-   the syntax for the fail-safe must be with the full PCI id:
-   Domain:Bus:Device.Function. See the usage example section.
+   In case where the sub-device is also used as a whitelist device, using ``-w``
+   on the EAL command line, the fail-safe PMD will use the device with the
+   options provided to the EAL instead of its own parameters.
+
+   When trying to use a PCI device automatically probed by the blacklist mode,
+   the name for the fail-safe sub-device must be the full PCI id:
+   Domain:Bus:Device.Function, *i.e.* ``00:00:00.0`` instead of ``00:00.0``,
+   as the second form is historically accepted by the DPDK.
 
 - **exec(<shell command>)** parameter
 
@@ -81,9 +83,9 @@ Fail-safe command line parameters
   execute and define a sub-device.
   It is done within a regular shell context.
   The first line of its output is read by the fail-safe PMD and otherwise
-  interpreted as if passed by the regular **dev** parameter.
+  interpreted as if passed to a **dev** parameter.
   Any other line is discarded.
-  If the command fail or output an incorrect string, the sub-device is not
+  If the command fails or output an incorrect string, the sub-device is not
   initialized.
   All commas within the ``shell command`` are replaced by spaces before
   executing the command. This helps using scripts to specify devices.
@@ -105,13 +107,13 @@ Fail-safe command line parameters
   address of the first of its sub-device to be successfully probed and use it as
   its default MAC address, trying to set it to all of its other sub-devices.
   If no sub-device was successfully probed at initialization, then a random MAC
-  address is generated, that will be subsequently applied to all sub-device once
+  address is generated, that will be subsequently applied to all sub-devices once
   they are probed.
 
 - **hotplug_poll** parameter [UINT64] (default **2000**)
 
   This parameter allows the user to configure the amount of time in milliseconds
-  between two slave upkeep round.
+  between two sub-device upkeep round.
 
 Usage example
 ~~~~~~~~~~~~~
@@ -121,8 +123,8 @@ This section shows some example of using **testpmd** with a fail-safe PMD.
 #. To build a PMD and configure DPDK, refer to the document
    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`.
 
-#. Start testpmd. The slave device should be blacklisted from normal EAL
-   operations to avoid probing it twice when in PCI blacklist mode.
+#. Start testpmd. The sub-device ``84:00.0`` should be blacklisted from normal EAL
+   operations to avoid probing it twice, as the PCI bus is in blacklist mode.
 
    .. code-block:: console
 
@@ -130,7 +132,7 @@ This section shows some example of using **testpmd** with a fail-safe PMD.
          --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' \
          -b 84:00.0 -b 00:04.0 -- -i
 
-   If the slave device being used is not blacklisted, it will be probed by the
+   If the sub-device ``84:00.0`` is not blacklisted, it will be probed by the
    EAL first. When the fail-safe then tries to initialize it the probe operation
    fails.
 
@@ -148,7 +150,7 @@ This section shows some example of using **testpmd** with a fail-safe PMD.
 
    .. code-block:: console
 
-      $RTE_TARGET/build/app/testpmd -c 0xff -n 4 --no-pci \
+      $RTE_TARGET/build/app/testpmd -c 0xff -n 4 -w ff:ff.f \
          --vdev='net_failsafe0,exec(echo 84:00.0)' -- -i
 
 #. Start testpmd, automatically probing the device 84:00.0 and using it with
@@ -171,6 +173,20 @@ access, and in particular, using the ``RTE_ETH_FOREACH_DEV`` macro to iterate
 over ethernet devices, instead of directly accessing them or by writing one's
 own device iterator.
 
+   .. code-block:: C
+
+      unsigned int i;
+
+      /* VALID iteration over eth-dev. */
+      RTE_ETH_FOREACH_DEV(i) {
+              [...]
+      }
+
+      /* INVALID iteration over eth-dev. */
+      for (i = 0; i < RTE_MAX_ETHPORTS; i++) {
+              [...]
+      }
+
 Plug-in feature
 ---------------
 
@@ -180,10 +196,14 @@ absence and postpone its use. It will then register for a periodic check on any
 missing sub-device.
 
 During this time, the fail-safe PMD can be used normally, configured and told to
-emit and receive packets. It will store any applied configuration, and try to
-apply it upon the probing of its missing sub-device. After this configuration
-pass, the new sub-device will be synchronized with other sub-devices, i.e. be
-started if the fail-safe PMD has been started by the user before.
+emit and receive packets. It will store any applied configuration but will fail
+to emit anything, returning ``0`` from its TX function. Any unsent packet must
+be freed.
+
+Upon the probing of its missing sub-device, the current stored configuration
+will be applied. After this configuration pass, the new sub-device will be
+synchronized with other sub-devices, i.e. be started if the fail-safe PMD has
+been started by the user before.
 
 Plug-out feature
 ----------------
@@ -196,20 +216,25 @@ emitted this event, allowing it to free its eventual resources.
 Fail-safe glossary
 ------------------
 
-Fallback device : Secondary device
+Fallback device
+    Also called **Secondary device**.
+
     The fail-safe will fail-over onto this device when the preferred device is
     absent.
 
-Preferred device : Primary device
+Preferred device
+    Also called **Primary device**.
+
     The first declared sub-device in the fail-safe parameters.
     When this device is plugged, it is always used as emitting device.
     It is the main sub-device and is used as target for configuration
     operations if there is any ambiguity.
 
 Upkeep round
-    Periodical process when slaves are serviced. Each devices having a state
-    different to that of the fail-safe device itself, is synchronized with it.
-    Additionally, each slave having the remove flag set are cleaned-up.
+    Periodical event during which sub-devices are serviced. Each devices having a state
+    different to that of the fail-safe device itself, is synchronized with it
+    (brought down or up accordingly). Additionally, any sub-device marked for
+    removal is cleaned-up.
 
 Slave
     In the context of the fail-safe PMD, synonymous to sub-device.
-- 
2.25.0

[dpdk-dev] [PATCH v1 2/2] doc/failsafe: fix incorrect statement regarding number of sub-device

[Gaetan Rivet]

Supporting more than 2 sub-device is a remnant from earlier fail-safe
design, that was never actually published.

Fixes: a46f8d584eb8 ("net/failsafe: add fail-safe PMD")
Cc: stable@dpdk.org

Signed-off-by: Gaetan Rivet <grive@u256.net>
---
 doc/guides/nics/fail_safe.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/guides/nics/fail_safe.rst b/doc/guides/nics/fail_safe.rst
index 3ce2f8bee..b4a92f663 100644
--- a/doc/guides/nics/fail_safe.rst
+++ b/doc/guides/nics/fail_safe.rst
@@ -49,7 +49,7 @@ The Fail-safe PMD can be used like most other DPDK virtual devices, by passing a
 ``--vdev`` parameter to the EAL when starting the application. The device name
 must start with the *net_failsafe* prefix, followed by numbers or letters. This
 name must be unique for each device. Each fail-safe instance must have at least one
-sub-device, up to ``RTE_MAX_ETHPORTS-1``.
+sub-device, and at most two.
 
 A sub-device can be any DPDK device, including possibly another fail-safe device.
 
-- 
2.25.0

Re: [dpdk-dev] [PATCH v1 1/2] doc/failsafe: improve fail-safe documentation

[Ferruh Yigit]

On 2/22/2020 12:14 AM, Gaetan Rivet wrote:
> Reading the fail-safe doc with a few years added, a few phrasing
> choices are ambiguous or confusing.
> 
> Signed-off-by: Gaetan Rivet <grive@u256.net>

cc'ed Marco & John for documentation (structure & language) perspective review.

Re: [dpdk-dev] [PATCH v1 1/2] doc/failsafe: improve fail-safe documentation

[Kovacevic, Marko]

Acked-by: Marko Kovacevic <marko.kovacevic@intel.com>

Re: [dpdk-dev] [PATCH v1 1/2] doc/failsafe: improve fail-safe documentation

[Ferruh Yigit]

On 2/22/2020 12:14 AM, Gaetan Rivet wrote:
> Reading the fail-safe doc with a few years added, a few phrasing
> choices are ambiguous or confusing.
> 
> Signed-off-by: Gaetan Rivet <grive@u256.net>
>
> Acked-by: Marko Kovacevic <marko.kovacevic@intel.com>
>

Series applied to dpdk-next-net/master, thanks.