1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright 2017 6WIND S.A. 3 4Fail-safe poll mode driver library 5================================== 6 7The Fail-safe poll mode driver library (**librte_net_failsafe**) implements a 8virtual device that allows using device supporting hotplug, without modifying 9other components relying on such device (application, other PMDs). 10In this context, hotplug support is meant as plugging or removing a device 11from its bus suddenly. 12 13Additionally to the Seamless Hotplug feature, the Fail-safe PMD offers the 14ability to redirect operations to a secondary device when the primary has been 15removed from the system. 16 17 18Features 19-------- 20 21The Fail-safe PMD only supports a limited set of features. If you plan to use a 22device underneath the Fail-safe PMD with a specific feature, this feature must 23also be supported by the Fail-safe PMD. 24 25A notable exception is the device removal feature. The fail-safe PMD is not 26meant to be removed itself, unlike its sub-devices which should support it. 27If a sub-device supports hotplugging, the fail-safe PMD will enable its use 28automatically by detecting capable devices and registering the relevant handler. 29 30Check the feature matrix for the complete set of supported features. 31 32 33Using the Fail-safe PMD from the EAL command line 34------------------------------------------------- 35 36The Fail-safe PMD can be used like most other DPDK virtual devices, by passing a 37``--vdev`` parameter to the EAL when starting the application. The device name 38must start with the *net_failsafe* prefix, followed by numbers or letters. This 39name must be unique for each device. Each fail-safe instance must have at least one 40sub-device, and at most two. 41 42A sub-device can be any DPDK device, including possibly another fail-safe device. 43 44Fail-safe command line parameters 45~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 46 47- **dev(<iface>)** parameter 48 49 This parameter allows the user to define a sub-device. The ``<iface>`` part of 50 this parameter must be a valid device definition. It follows the same format 51 provided to any ``-a`` or ``--vdev`` options. 52 53 Enclosing the device definition within parentheses here allows using 54 additional sub-device parameters if need be. They will be passed on to the 55 sub-device. 56 57.. note:: 58 59 In case where the sub-device is also used as an allowed device, using ``-a`` 60 on the EAL command line, the fail-safe PMD will use the device with the 61 options provided to the EAL instead of its own parameters. 62 63 When trying to use a PCI device automatically probed by the command line, 64 the name for the fail-safe sub-device must be the full PCI id: 65 Domain:Bus:Device.Function, *i.e.* ``00:00:00.0`` instead of ``00:00.0``, 66 as the second form is historically accepted by the DPDK. 67 68- **exec(<shell command>)** parameter 69 70 This parameter allows the user to provide a command to the fail-safe PMD to 71 execute and define a sub-device. 72 It is done within a regular shell context. 73 The first line of its output is read by the fail-safe PMD and otherwise 74 interpreted as if passed to a **dev** parameter. 75 Any other line is discarded. 76 If the command fails or output an incorrect string, the sub-device is not 77 initialized. 78 All commas within the ``shell command`` are replaced by spaces before 79 executing the command. This helps using scripts to specify devices. 80 81- **fd(<file descriptor number>)** parameter 82 83 This parameter reads a device definition from an arbitrary file descriptor 84 number in ``<iface>`` format as described above. 85 86 The file descriptor is read in non-blocking mode and is never closed in 87 order to take only the last line into account (unlike ``exec()``) at every 88 probe attempt. 89 90- **mac** parameter [MAC address] 91 92 This parameter allows the user to set a default MAC address to the fail-safe 93 and all of its sub-devices. 94 If no default mac address is provided, the fail-safe PMD will read the MAC 95 address of the first of its sub-device to be successfully probed and use it as 96 its default MAC address, trying to set it to all of its other sub-devices. 97 If no sub-device was successfully probed at initialization, then a random MAC 98 address is generated, that will be subsequently applied to all sub-devices once 99 they are probed. 100 101- **hotplug_poll** parameter [UINT64] (default **2000**) 102 103 This parameter allows the user to configure the amount of time in milliseconds 104 between two sub-device upkeep round. 105 106Usage example 107~~~~~~~~~~~~~ 108 109This section shows some example of using **testpmd** with a fail-safe PMD. 110 111#. To build a PMD and configure DPDK, refer to the document 112 :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`. 113 114#. Start testpmd. The sub-device ``84:00.0`` should be blocked from normal EAL 115 operations to avoid probing it twice, as the PCI bus is in blocklist mode. 116 117 .. code-block:: console 118 119 ./<build_dir>/app/dpdk-testpmd -c 0xff -n 4 \ 120 --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' \ 121 -b 84:00.0 -b 00:04.0 -- -i 122 123 If the sub-device ``84:00.0`` is not blocked, it will be probed by the 124 EAL first. When the fail-safe then tries to initialize it the probe operation 125 fails. 126 127 Note that PCI blocklist mode is the default PCI operating mode. 128 129#. Alternatively, it can be used alongside any other device in allow mode. 130 131 .. code-block:: console 132 133 ./<build_dir>/app/dpdk-testpmd -c 0xff -n 4 \ 134 --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' \ 135 -a 81:00.0 -- -i 136 137#. Start testpmd using a flexible device definition 138 139 .. code-block:: console 140 141 ./<build_dir>/app/dpdk-testpmd -c 0xff -n 4 -a ff:ff.f \ 142 --vdev='net_failsafe0,exec(echo 84:00.0)' -- -i 143 144#. Start testpmd, automatically probing the device 84:00.0 and using it with 145 the fail-safe. 146 147 .. code-block:: console 148 149 ./<build_dir>/app/dpdk-testpmd -c 0xff -n 4 \ 150 --vdev 'net_failsafe0,dev(0000:84:00.0),dev(net_ring0)' -- -i 151 152 153Using the Fail-safe PMD from an application 154------------------------------------------- 155 156This driver strives to be as seamless as possible to existing applications, in 157order to propose the hotplug functionality in the easiest way possible. 158 159Care must be taken, however, to respect the **ether** API concerning device 160access, and in particular, using the ``RTE_ETH_FOREACH_DEV`` macro to iterate 161over ethernet devices, instead of directly accessing them or by writing one's 162own device iterator. 163 164 .. code-block:: C 165 166 unsigned int i; 167 168 /* VALID iteration over eth-dev. */ 169 RTE_ETH_FOREACH_DEV(i) { 170 [...] 171 } 172 173 /* INVALID iteration over eth-dev. */ 174 for (i = 0; i < RTE_MAX_ETHPORTS; i++) { 175 [...] 176 } 177 178Plug-in feature 179--------------- 180 181A sub-device can be defined without existing on the system when the fail-safe 182PMD is initialized. Upon probing this device, the fail-safe PMD will detect its 183absence and postpone its use. It will then register for a periodic check on any 184missing sub-device. 185 186During this time, the fail-safe PMD can be used normally, configured and told to 187emit and receive packets. It will store any applied configuration but will fail 188to emit anything, returning ``0`` from its TX function. Any unsent packet must 189be freed. 190 191Upon the probing of its missing sub-device, the current stored configuration 192will be applied. After this configuration pass, the new sub-device will be 193synchronized with other sub-devices, i.e. be started if the fail-safe PMD has 194been started by the user before. 195 196Plug-out feature 197---------------- 198 199A sub-device supporting the device removal event can be removed from its bus at 200any time. The fail-safe PMD will register a callback for such event and react 201accordingly. It will try to safely stop, close and uninit the sub-device having 202emitted this event, allowing it to free its eventual resources. 203 204Fail-safe glossary 205------------------ 206 207Fallback device 208 Also called **Secondary device**. 209 210 The fail-safe will fail-over onto this device when the preferred device is 211 absent. 212 213Preferred device 214 Also called **Primary device**. 215 216 The first declared sub-device in the fail-safe parameters. 217 When this device is plugged, it is always used as emitting device. 218 It is the main sub-device and is used as target for configuration 219 operations if there is any ambiguity. 220 221Upkeep round 222 Periodical event during which sub-devices are serviced. Each devices having a state 223 different to that of the fail-safe device itself, is synchronized with it 224 (brought down or up accordingly). Additionally, any sub-device marked for 225 removal is cleaned-up. 226 227Slave 228 In the context of the fail-safe PMD, synonymous to sub-device. 229 230Sub-device 231 A device being utilized by the fail-safe PMD. 232 This is another PMD running underneath the fail-safe PMD. 233 Any sub-device can disappear at any time. The fail-safe will ensure 234 that the device removal happens gracefully. 235