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
additional sub-device parameters if need be. They will be passed on to the
sub-device.
+- **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.
+
- **mac** parameter [MAC address]
This parameter allows the user to set a default MAC address to the fail-safe
--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
+
Using the Fail-safe PMD from an application
-------------------------------------------
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
------------------
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.