build: fix meson check for binutils 2.30

[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 c20696e..6c02d7e 100644 (file)
--- a/doc/guides/nics/fail_safe.rst
+++ b/doc/guides/nics/fail_safe.rst
@@ -1,32 +1,6 @@
-..  BSD LICENSE
+..  SPDX-License-Identifier: BSD-3-Clause

     Copyright 2017 6WIND S.A.
 
     Copyright 2017 6WIND S.A.
 

-    Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions
-    are met:
-
-    * Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in
-    the documentation and/or other materials provided with the
-    distribution.
-    * Neither the name of 6WIND S.A. nor the names of its
-    contributors may be used to endorse or promote products derived
-    from this software without specific prior written permission.
-
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-

 Fail-safe poll mode driver library
 ==================================
 
 Fail-safe poll mode driver library
 ==================================
 


@@ -51,6 +25,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.
 
 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
 Check the feature matrix for the complete set of supported features.
 
 Compilation option


@@ -87,6 +67,36 @@ Fail-safe command line parameters
   additional sub-device parameters if need be. They will be passed on to the
   sub-device.
 
   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
 - **mac** parameter [MAC address]
 
   This parameter allows the user to set a default MAC address to the fail-safe


@@ -98,6 +108,11 @@ Fail-safe command line parameters
   address is generated, that will be subsequently applied to all sub-device once
   they are probed.
 
   address is generated, that will be subsequently applied to all sub-device 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.
+

 Usage example
 ~~~~~~~~~~~~~
 
 Usage example
 ~~~~~~~~~~~~~
 


@@ -112,7 +127,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 \
    .. 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
          -b 84:00.0 -b 00:04.0 -- -i
 
    If the slave device being used is not blacklisted, it will be probed by the


@@ -126,9 +141,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 \
    .. 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
 
          -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
 -------------------------------------------
 
 Using the Fail-safe PMD from an application
 -------------------------------------------
 


@@ -140,6 +171,28 @@ 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.
 
 over ethernet devices, instead of directly accessing them or by writing one's
 own device iterator.
 

+Plug-in feature
+---------------
+
+A sub-device can be defined without existing on the system when the fail-safe
+PMD is initialized. Upon probing this device, the fail-safe PMD will detect its
+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.
+
+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
 ------------------
 
 Fail-safe glossary
 ------------------
 


@@ -153,6 +206,11 @@ Preferred device : Primary device
     It is the main sub-device and is used as target for configuration
     operations if there is any ambiguity.
 
     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.
+

 Slave
     In the context of the fail-safe PMD, synonymous to sub-device.
 
 Slave
     In the context of the fail-safe PMD, synonymous to sub-device.