net/failsafe: add probed device capture

[dpdk.git] / doc / guides / nics / fail_safe.rst

diff --git a/doc/guides/nics/fail_safe.rst b/doc/guides/nics/fail_safe.rst
index 0005892..3f72b59 100644 (file)
--- a/doc/guides/nics/fail_safe.rst
+++ b/doc/guides/nics/fail_safe.rst
@@ -51,6 +51,12 @@ 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.
 
+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.
+
 Check the feature matrix for the complete set of supported features.
 
 Compilation option
@@ -87,6 +93,36 @@ Fail-safe command line parameters
   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.
+
+- **exec(<shell command>)** parameter
+
+  This parameter allows the user to provide a command to the fail-safe PMD to
+  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.
+  Any other line is discarded.
+  If the command fail 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.
+
+- **fd(<file descriptor number>)** parameter
+
+  This parameter reads a device definition from an arbitrary file descriptor
+  number in ``<iface>`` format as described above.
+
+  The file descriptor is read in non-blocking mode and is never closed in
+  order to take only the last line into account (unlike ``exec()``) at every
+  probe attempt.
+
 - **mac** parameter [MAC address]
 
   This parameter allows the user to set a default MAC address to the fail-safe
@@ -117,7 +153,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 \
-         --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)'
+         --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
@@ -131,9 +167,25 @@ 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 \
-         --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)'
+         --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' \
          -w 81:00.0 -- -i
 
+#. Start testpmd using a flexible device definition
+
+   .. code-block:: console
+
+      $RTE_TARGET/build/app/testpmd -c 0xff -n 4 --no-pci \
+         --vdev='net_failsafe0,exec(echo 84:00.0)' -- -i
+
+#. Start testpmd, automatically probing the device 84:00.0 and using it with
+   the fail-safe.
+ 
+   .. code-block:: console
+ 
+      $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \
+         --vdev 'net_failsafe0,dev(0000:84:00.0),dev(net_ring0)' -- -i
+
+
 Using the Fail-safe PMD from an application
 -------------------------------------------
 
@@ -159,6 +211,14 @@ 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.
 
+Plug-out feature
+----------------
+
+A sub-device supporting the device removal event can be removed from its bus at
+any time. The fail-safe PMD will register a callback for such event and react
+accordingly. It will try to safely stop, close and uninit the sub-device having
+emitted this event, allowing it to free its eventual resources.
+
 Fail-safe glossary
 ------------------
 
@@ -175,6 +235,7 @@ Preferred device : Primary device
 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.
 
 Slave
     In the context of the fail-safe PMD, synonymous to sub-device.