doc/guides/nics/fail_safe.rst

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