2 Copyright 2017 6WIND S.A.
4 Redistribution and use in source and binary forms, with or without
5 modification, are permitted provided that the following conditions
8 * Redistributions of source code must retain the above copyright
9 notice, this list of conditions and the following disclaimer.
10 * Redistributions in binary form must reproduce the above copyright
11 notice, this list of conditions and the following disclaimer in
12 the documentation and/or other materials provided with the
14 * Neither the name of 6WIND S.A. nor the names of its
15 contributors may be used to endorse or promote products derived
16 from this software without specific prior written permission.
18 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 Fail-safe poll mode driver library
31 ==================================
33 The Fail-safe poll mode driver library (**librte_pmd_failsafe**) is a virtual
34 device that allows using any device supporting hotplug (sudden device removal
35 and plugging on its bus), without modifying other components relying on such
36 device (application, other PMDs).
38 Additionally to the Seamless Hotplug feature, the Fail-safe PMD offers the
39 ability to redirect operations to secondary devices when the primary has been
40 removed from the system.
44 The library is enabled by default. You can enable it or disable it manually
45 by setting the ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` configuration option.
50 The Fail-safe PMD only supports a limited set of features. If you plan to use a
51 device underneath the Fail-safe PMD with a specific feature, this feature must
52 be supported by the Fail-safe PMD to avoid throwing any error.
54 Check the feature matrix for the complete set of supported features.
59 This option can be modified in the ``$RTE_TARGET/build/.config`` file.
61 - ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` (default **y**)
63 Toggle compiling librte_pmd_failsafe.
65 Using the Fail-safe PMD from the EAL command line
66 -------------------------------------------------
68 The Fail-safe PMD can be used like most other DPDK virtual devices, by passing a
69 ``--vdev`` parameter to the EAL when starting the application. The device name
70 must start with the *net_failsafe* prefix, followed by numbers or letters. This
71 name must be unique for each device. Each fail-safe instance must have at least one
72 sub-device, up to ``RTE_MAX_ETHPORTS-1``.
74 A sub-device can be any legal DPDK device, including possibly another fail-safe
77 Fail-safe command line parameters
78 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80 - **dev(<iface>)** parameter
82 This parameter allows the user to define a sub-device. The ``<iface>`` part of
83 this parameter must be a valid device definition. It could be the argument
84 provided to any ``-w`` device specification or the argument that would be
85 given to a ``--vdev`` parameter (including a fail-safe).
86 Enclosing the device definition within parenthesis here allows using
87 additional sub-device parameters if need be. They will be passed on to the
90 - **exec(<shell command>)** parameter
92 This parameter allows the user to provide a command to the fail-safe PMD to
93 execute and define a sub-device.
94 It is done within a regular shell context.
95 The first line of its output is read by the fail-safe PMD and otherwise
96 interpreted as if passed by the regular **dev** parameter.
97 Any other line is discarded.
98 If the command fail or output an incorrect string, the sub-device is not
100 All commas within the ``shell command`` are replaced by spaces before
101 executing the command. This helps using scripts to specify devices.
103 - **mac** parameter [MAC address]
105 This parameter allows the user to set a default MAC address to the fail-safe
106 and all of its sub-devices.
107 If no default mac address is provided, the fail-safe PMD will read the MAC
108 address of the first of its sub-device to be successfully probed and use it as
109 its default MAC address, trying to set it to all of its other sub-devices.
110 If no sub-device was successfully probed at initialization, then a random MAC
111 address is generated, that will be subsequently applied to all sub-device once
114 - **hotplug_poll** parameter [UINT64] (default **2000**)
116 This parameter allows the user to configure the amount of time in milliseconds
117 between two slave upkeep round.
122 This section shows some example of using **testpmd** with a fail-safe PMD.
124 #. To build a PMD and configure DPDK, refer to the document
125 :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`.
127 #. Start testpmd. The slave device should be blacklisted from normal EAL
128 operations to avoid probing it twice when in PCI blacklist mode.
130 .. code-block:: console
132 $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \
133 --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)'
134 -b 84:00.0 -b 00:04.0 -- -i
136 If the slave device being used is not blacklisted, it will be probed by the
137 EAL first. When the fail-safe then tries to initialize it the probe operation
140 Note that PCI blacklist mode is the default PCI operating mode.
142 #. Alternatively, it can be used alongside any other device in whitelist mode.
144 .. code-block:: console
146 $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \
147 --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)'
150 #. Start testpmd using a flexible device definition
152 .. code-block:: console
154 $RTE_TARGET/build/app/testpmd -c 0xff -n 4 --no-pci \
155 --vdev='net_failsafe0,exec(echo 84:00.0)' -- -i
157 Using the Fail-safe PMD from an application
158 -------------------------------------------
160 This driver strives to be as seamless as possible to existing applications, in
161 order to propose the hotplug functionality in the easiest way possible.
163 Care must be taken, however, to respect the **ether** API concerning device
164 access, and in particular, using the ``RTE_ETH_FOREACH_DEV`` macro to iterate
165 over ethernet devices, instead of directly accessing them or by writing one's
171 A sub-device can be defined without existing on the system when the fail-safe
172 PMD is initialized. Upon probing this device, the fail-safe PMD will detect its
173 absence and postpone its use. It will then register for a periodic check on any
176 During this time, the fail-safe PMD can be used normally, configured and told to
177 emit and receive packets. It will store any applied configuration, and try to
178 apply it upon the probing of its missing sub-device. After this configuration
179 pass, the new sub-device will be synchronized with other sub-devices, i.e. be
180 started if the fail-safe PMD has been started by the user before.
185 Fallback device : Secondary device
186 The fail-safe will fail-over onto this device when the preferred device is
189 Preferred device : Primary device
190 The first declared sub-device in the fail-safe parameters.
191 When this device is plugged, it is always used as emitting device.
192 It is the main sub-device and is used as target for configuration
193 operations if there is any ambiguity.
196 Periodical process when slaves are serviced. Each devices having a state
197 different to that of the fail-safe device itself, is synchronized with it.
200 In the context of the fail-safe PMD, synonymous to sub-device.
203 A device being utilized by the fail-safe PMD.
204 This is another PMD running underneath the fail-safe PMD.
205 Any sub-device can disappear at any time. The fail-safe will ensure
206 that the device removal happens gracefully.