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