-.. 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
==================================
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.
+.. 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
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
~~~~~~~~~~~~~
.. 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
.. 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
-------------------------------------------
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
------------------
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.
git.droids-corp.org / dpdk.git / blobdiff