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>
Fail-safe poll mode driver library
==================================
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
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::
removed from the system.
.. note::
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
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
------------------
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**)
- ``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
-------------------------------------------------
Using the Fail-safe PMD from the EAL command line
-------------------------------------------------
name must be unique for each device. Each fail-safe instance must have at least one
sub-device, up to ``RTE_MAX_ETHPORTS-1``.
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Fail-safe command line parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- **dev(<iface>)** parameter
This parameter allows the user to define a sub-device. The ``<iface>`` part of
- **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::
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
- **exec(<shell command>)** parameter
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
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.
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.
initialized.
All commas within the ``shell command`` are replaced by spaces before
executing the command. This helps using scripts to specify devices.
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 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
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
~~~~~~~~~~~~~
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>`.
#. 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.
--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
--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.
EAL first. When the fail-safe then tries to initialize it the probe operation
fails.
- $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
--vdev='net_failsafe0,exec(echo 84:00.0)' -- -i
#. Start testpmd, automatically probing the device 84:00.0 and using it with
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.
+ .. 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
---------------
Plug-in feature
---------------
missing sub-device.
During this time, the fail-safe PMD can be used normally, configured and told to
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
----------------
Plug-out feature
----------------
Fail-safe glossary
------------------
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.
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
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.
Slave
In the context of the fail-safe PMD, synonymous to sub-device.
git.droids-corp.org / dpdk.git / commitdiff