-.. BSD LICENSE
+.. SPDX-License-Identifier: BSD-3-Clause
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
==================================
-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_net_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::
-
- The library is enabled by default. You can enable it or disable it manually
- by setting the ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` configuration option.
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.
-
-Check the feature matrix for the complete set of supported features.
-
-Compilation option
-------------------
+also be supported by the Fail-safe PMD.
-This option can be modified in the ``$RTE_TARGET/build/.config`` file.
+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.
-- ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` (default **y**)
+Check the feature matrix for the complete set of supported features.
- Toggle compiling librte_pmd_failsafe.
Using the Fail-safe PMD from the EAL command line
-------------------------------------------------
``--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 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- **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 ``-a`` 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 where the sub-device is also used as an allowed device, using ``-a``
+ 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 command line,
+ 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
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.
+ 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.
+- **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
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
~~~~~~~~~~~~~
#. 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 blocked from normal EAL
+ operations to avoid probing it twice, as the PCI bus is in blocklist mode.
.. 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)'
+ ./<build_dir>/app/dpdk-testpmd -c 0xff -n 4 \
+ --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 blocked, it will be probed by the
EAL first. When the fail-safe then tries to initialize it the probe operation
fails.
- Note that PCI blacklist mode is the default PCI operating mode.
+ Note that PCI blocklist mode is the default PCI operating mode.
-#. Alternatively, it can be used alongside any other device in whitelist mode.
+#. Alternatively, it can be used alongside any other device in allow mode.
.. 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)'
- -w 81:00.0 -- -i
+ ./<build_dir>/app/dpdk-testpmd -c 0xff -n 4 \
+ --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' \
+ -a 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 \
+ ./<build_dir>/app/dpdk-testpmd -c 0xff -n 4 -a 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
+ the fail-safe.
+
+ .. code-block:: console
+
+ ./<build_dir>/app/dpdk-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
-------------------------------------------
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
---------------
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
+----------------
+
+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
------------------
-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.
+ 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.