doc/guides/nics/fail_safe.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright 2017 6WIND S.A.
   3
   4 Fail-safe poll mode driver library
   5 ==================================
   6
   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.
  12
  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.
  16
  17
  18 Features
  19 --------
  20
  21 The Fail-safe PMD only supports a limited set of features. If you plan to use a
  22 device underneath the Fail-safe PMD with a specific feature, this feature must
  23 also be supported by the Fail-safe PMD.
  24
  25 A notable exception is the device removal feature. The fail-safe PMD is not
  26 meant to be removed itself, unlike its sub-devices which should support it.
  27 If a sub-device supports hotplugging, the fail-safe PMD will enable its use
  28 automatically by detecting capable devices and registering the relevant handler.
  29
  30 Check the feature matrix for the complete set of supported features.
  31
  32
  33 Using the Fail-safe PMD from the EAL command line
  34 -------------------------------------------------
  35
  36 The 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
  38 must start with the *net_failsafe* prefix, followed by numbers or letters. This
  39 name must be unique for each device. Each fail-safe instance must have at least one
  40 sub-device, and at most two.
  41
  42 A sub-device can be any DPDK device, including possibly another fail-safe device.
  43
  44 Fail-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 ``-w`` 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 a whitelist device, using ``-w``
  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 blacklist mode,
  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
 106 Usage example
 107 ~~~~~~~~~~~~~
 108
 109 This 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 blacklisted from normal EAL
 115    operations to avoid probing it twice, as the PCI bus is in blacklist 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 blacklisted, 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 blacklist mode is the default PCI operating mode.
 128
 129 #. Alternatively, it can be used alongside any other device in whitelist 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          -w 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 -w 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
 153 Using the Fail-safe PMD from an application
 154 -------------------------------------------
 155
 156 This driver strives to be as seamless as possible to existing applications, in
 157 order to propose the hotplug functionality in the easiest way possible.
 158
 159 Care must be taken, however, to respect the **ether** API concerning device
 160 access, and in particular, using the ``RTE_ETH_FOREACH_DEV`` macro to iterate
 161 over ethernet devices, instead of directly accessing them or by writing one's
 162 own 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
 178 Plug-in feature
 179 ---------------
 180
 181 A sub-device can be defined without existing on the system when the fail-safe
 182 PMD is initialized. Upon probing this device, the fail-safe PMD will detect its
 183 absence and postpone its use. It will then register for a periodic check on any
 184 missing sub-device.
 185
 186 During this time, the fail-safe PMD can be used normally, configured and told to
 187 emit and receive packets. It will store any applied configuration but will fail
 188 to emit anything, returning ``0`` from its TX function. Any unsent packet must
 189 be freed.
 190
 191 Upon the probing of its missing sub-device, the current stored configuration
 192 will be applied. After this configuration pass, the new sub-device will be
 193 synchronized with other sub-devices, i.e. be started if the fail-safe PMD has
 194 been started by the user before.
 195
 196 Plug-out feature
 197 ----------------
 198
 199 A sub-device supporting the device removal event can be removed from its bus at
 200 any time. The fail-safe PMD will register a callback for such event and react
 201 accordingly. It will try to safely stop, close and uninit the sub-device having
 202 emitted this event, allowing it to free its eventual resources.
 203
 204 Fail-safe glossary
 205 ------------------
 206
 207 Fallback 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
 213 Preferred 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
 221 Upkeep 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
 227 Slave
 228     In the context of the fail-safe PMD, synonymous to sub-device.
 229
 230 Sub-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.