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**) is a virtual
   8 device that allows using any device supporting hotplug (sudden device removal
   9 and plugging on its bus), without modifying other components relying on such
  10 device (application, other PMDs).
  11
  12 Additionally to the Seamless Hotplug feature, the Fail-safe PMD offers the
  13 ability to redirect operations to secondary devices when the primary has been
  14 removed 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
  21 Features
  22 --------
  23
  24 The Fail-safe PMD only supports a limited set of features. If you plan to use a
  25 device underneath the Fail-safe PMD with a specific feature, this feature must
  26 be supported by the Fail-safe PMD to avoid throwing any error.
  27
  28 A notable exception is the device removal feature. The fail-safe PMD being a
  29 virtual device, it cannot currently be removed in the sense of a specific bus
  30 hotplug, like for PCI for example. It will however enable this feature for its
  31 sub-device automatically, detecting those that are capable and register the
  32 relevant callback for such event.
  33
  34 Check the feature matrix for the complete set of supported features.
  35
  36 Compilation option
  37 ------------------
  38
  39 This 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
  45 Using the Fail-safe PMD from the EAL command line
  46 -------------------------------------------------
  47
  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, up to ``RTE_MAX_ETHPORTS-1``.
  53
  54 A sub-device can be any legal DPDK device, including possibly another fail-safe
  55 instance.
  56
  57 Fail-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
 116 Usage example
 117 ~~~~~~~~~~~~~
 118
 119 This 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
 163 Using the Fail-safe PMD from an application
 164 -------------------------------------------
 165
 166 This driver strives to be as seamless as possible to existing applications, in
 167 order to propose the hotplug functionality in the easiest way possible.
 168
 169 Care must be taken, however, to respect the **ether** API concerning device
 170 access, and in particular, using the ``RTE_ETH_FOREACH_DEV`` macro to iterate
 171 over ethernet devices, instead of directly accessing them or by writing one's
 172 own device iterator.
 173
 174 Plug-in feature
 175 ---------------
 176
 177 A sub-device can be defined without existing on the system when the fail-safe
 178 PMD is initialized. Upon probing this device, the fail-safe PMD will detect its
 179 absence and postpone its use. It will then register for a periodic check on any
 180 missing sub-device.
 181
 182 During this time, the fail-safe PMD can be used normally, configured and told to
 183 emit and receive packets. It will store any applied configuration, and try to
 184 apply it upon the probing of its missing sub-device. After this configuration
 185 pass, the new sub-device will be synchronized with other sub-devices, i.e. be
 186 started if the fail-safe PMD has been started by the user before.
 187
 188 Plug-out feature
 189 ----------------
 190
 191 A sub-device supporting the device removal event can be removed from its bus at
 192 any time. The fail-safe PMD will register a callback for such event and react
 193 accordingly. It will try to safely stop, close and uninit the sub-device having
 194 emitted this event, allowing it to free its eventual resources.
 195
 196 Fail-safe glossary
 197 ------------------
 198
 199 Fallback device : Secondary device
 200     The fail-safe will fail-over onto this device when the preferred device is
 201     absent.
 202
 203 Preferred 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
 209 Upkeep 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
 214 Slave
 215     In the context of the fail-safe PMD, synonymous to sub-device.
 216
 217 Sub-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.