1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright 2017 6WIND S.A.
4 Fail-safe poll mode driver library
5 ==================================
7 The Fail-safe poll mode driver library (**librte_pmd_failsafe**) implements a
8 virtual device that allows using device supporting hotplug, without modifying
9 other components relying on such device (application, other PMDs).
10 In this context, hotplug support is meant as plugging or removing a device
11 from its bus suddenly.
13 Additionally to the Seamless Hotplug feature, the Fail-safe PMD offers the
14 ability to redirect operations to a secondary device when the primary has been
15 removed from the system.
19 The library is enabled by default. You can enable it or disable it manually
20 by setting the ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` configuration option.
25 The Fail-safe PMD only supports a limited set of features. If you plan to use a
26 device underneath the Fail-safe PMD with a specific feature, this feature must
27 also be supported by the Fail-safe PMD.
29 A notable exception is the device removal feature. The fail-safe PMD is not
30 meant to be removed itself, unlike its sub-devices which should support it.
31 If a sub-device supports hotplugging, the fail-safe PMD will enable its use
32 automatically by detecting capable devices and registering the relevant handler.
34 Check the feature matrix for the complete set of supported features.
39 Available options within the ``$RTE_TARGET/build/.config`` file:
41 - ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` (default **y**)
43 This option enables or disables compiling librte_pmd_failsafe.
45 Using the Fail-safe PMD from the EAL command line
46 -------------------------------------------------
48 The Fail-safe PMD can be used like most other DPDK virtual devices, by passing a
49 ``--vdev`` parameter to the EAL when starting the application. The device name
50 must start with the *net_failsafe* prefix, followed by numbers or letters. This
51 name must be unique for each device. Each fail-safe instance must have at least one
52 sub-device, and at most two.
54 A sub-device can be any DPDK device, including possibly another fail-safe device.
56 Fail-safe command line parameters
57 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
59 - **dev(<iface>)** parameter
61 This parameter allows the user to define a sub-device. The ``<iface>`` part of
62 this parameter must be a valid device definition. It follows the same format
63 provided to any ``-w`` or ``--vdev`` options.
65 Enclosing the device definition within parentheses here allows using
66 additional sub-device parameters if need be. They will be passed on to the
71 In case where the sub-device is also used as a whitelist device, using ``-w``
72 on the EAL command line, the fail-safe PMD will use the device with the
73 options provided to the EAL instead of its own parameters.
75 When trying to use a PCI device automatically probed by the blacklist mode,
76 the name for the fail-safe sub-device must be the full PCI id:
77 Domain:Bus:Device.Function, *i.e.* ``00:00:00.0`` instead of ``00:00.0``,
78 as the second form is historically accepted by the DPDK.
80 - **exec(<shell command>)** parameter
82 This parameter allows the user to provide a command to the fail-safe PMD to
83 execute and define a sub-device.
84 It is done within a regular shell context.
85 The first line of its output is read by the fail-safe PMD and otherwise
86 interpreted as if passed to a **dev** parameter.
87 Any other line is discarded.
88 If the command fails or output an incorrect string, the sub-device is not
90 All commas within the ``shell command`` are replaced by spaces before
91 executing the command. This helps using scripts to specify devices.
93 - **fd(<file descriptor number>)** parameter
95 This parameter reads a device definition from an arbitrary file descriptor
96 number in ``<iface>`` format as described above.
98 The file descriptor is read in non-blocking mode and is never closed in
99 order to take only the last line into account (unlike ``exec()``) at every
102 - **mac** parameter [MAC address]
104 This parameter allows the user to set a default MAC address to the fail-safe
105 and all of its sub-devices.
106 If no default mac address is provided, the fail-safe PMD will read the MAC
107 address of the first of its sub-device to be successfully probed and use it as
108 its default MAC address, trying to set it to all of its other sub-devices.
109 If no sub-device was successfully probed at initialization, then a random MAC
110 address is generated, that will be subsequently applied to all sub-devices once
113 - **hotplug_poll** parameter [UINT64] (default **2000**)
115 This parameter allows the user to configure the amount of time in milliseconds
116 between two sub-device upkeep round.
121 This section shows some example of using **testpmd** with a fail-safe PMD.
123 #. To build a PMD and configure DPDK, refer to the document
124 :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`.
126 #. Start testpmd. The sub-device ``84:00.0`` should be blacklisted from normal EAL
127 operations to avoid probing it twice, as the PCI bus is in blacklist mode.
129 .. code-block:: console
131 $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \
132 --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' \
133 -b 84:00.0 -b 00:04.0 -- -i
135 If the sub-device ``84:00.0`` is not blacklisted, it will be probed by the
136 EAL first. When the fail-safe then tries to initialize it the probe operation
139 Note that PCI blacklist mode is the default PCI operating mode.
141 #. Alternatively, it can be used alongside any other device in whitelist mode.
143 .. code-block:: console
145 $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \
146 --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' \
149 #. Start testpmd using a flexible device definition
151 .. code-block:: console
153 $RTE_TARGET/build/app/testpmd -c 0xff -n 4 -w ff:ff.f \
154 --vdev='net_failsafe0,exec(echo 84:00.0)' -- -i
156 #. Start testpmd, automatically probing the device 84:00.0 and using it with
159 .. code-block:: console
161 $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \
162 --vdev 'net_failsafe0,dev(0000:84:00.0),dev(net_ring0)' -- -i
165 Using the Fail-safe PMD from an application
166 -------------------------------------------
168 This driver strives to be as seamless as possible to existing applications, in
169 order to propose the hotplug functionality in the easiest way possible.
171 Care must be taken, however, to respect the **ether** API concerning device
172 access, and in particular, using the ``RTE_ETH_FOREACH_DEV`` macro to iterate
173 over ethernet devices, instead of directly accessing them or by writing one's
180 /* VALID iteration over eth-dev. */
181 RTE_ETH_FOREACH_DEV(i) {
185 /* INVALID iteration over eth-dev. */
186 for (i = 0; i < RTE_MAX_ETHPORTS; i++) {
193 A sub-device can be defined without existing on the system when the fail-safe
194 PMD is initialized. Upon probing this device, the fail-safe PMD will detect its
195 absence and postpone its use. It will then register for a periodic check on any
198 During this time, the fail-safe PMD can be used normally, configured and told to
199 emit and receive packets. It will store any applied configuration but will fail
200 to emit anything, returning ``0`` from its TX function. Any unsent packet must
203 Upon the probing of its missing sub-device, the current stored configuration
204 will be applied. After this configuration pass, the new sub-device will be
205 synchronized with other sub-devices, i.e. be started if the fail-safe PMD has
206 been started by the user before.
211 A sub-device supporting the device removal event can be removed from its bus at
212 any time. The fail-safe PMD will register a callback for such event and react
213 accordingly. It will try to safely stop, close and uninit the sub-device having
214 emitted this event, allowing it to free its eventual resources.
220 Also called **Secondary device**.
222 The fail-safe will fail-over onto this device when the preferred device is
226 Also called **Primary device**.
228 The first declared sub-device in the fail-safe parameters.
229 When this device is plugged, it is always used as emitting device.
230 It is the main sub-device and is used as target for configuration
231 operations if there is any ambiguity.
234 Periodical event during which sub-devices are serviced. Each devices having a state
235 different to that of the fail-safe device itself, is synchronized with it
236 (brought down or up accordingly). Additionally, any sub-device marked for
237 removal is cleaned-up.
240 In the context of the fail-safe PMD, synonymous to sub-device.
243 A device being utilized by the fail-safe PMD.
244 This is another PMD running underneath the fail-safe PMD.
245 Any sub-device can disappear at any time. The fail-safe will ensure
246 that the device removal happens gracefully.