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 Check the feature matrix for the complete set of supported features.
  55
  56 Compilation option
  57 ------------------
  58
  59 This option can be modified in the ``$RTE_TARGET/build/.config`` file.
  60
  61 - ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` (default **y**)
  62
  63   Toggle compiling librte_pmd_failsafe.
  64
  65 Using the Fail-safe PMD from the EAL command line
  66 -------------------------------------------------
  67
  68 The Fail-safe PMD can be used like most other DPDK virtual devices, by passing a
  69 ``--vdev`` parameter to the EAL when starting the application. The device name
  70 must start with the *net_failsafe* prefix, followed by numbers or letters. This
  71 name must be unique for each device. Each fail-safe instance must have at least one
  72 sub-device, up to ``RTE_MAX_ETHPORTS-1``.
  73
  74 A sub-device can be any legal DPDK device, including possibly another fail-safe
  75 instance.
  76
  77 Fail-safe command line parameters
  78 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  79
  80 - **dev(<iface>)** parameter
  81
  82   This parameter allows the user to define a sub-device. The ``<iface>`` part of
  83   this parameter must be a valid device definition. It could be the argument
  84   provided to any ``-w`` device specification or the argument that would be
  85   given to a ``--vdev`` parameter (including a fail-safe).
  86   Enclosing the device definition within parenthesis here allows using
  87   additional sub-device parameters if need be. They will be passed on to the
  88   sub-device.
  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-device once
  99   they are probed.
 100
 101 Usage example
 102 ~~~~~~~~~~~~~
 103
 104 This section shows some example of using **testpmd** with a fail-safe PMD.
 105
 106 #. To build a PMD and configure DPDK, refer to the document
 107    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`.
 108
 109 #. Start testpmd. The slave device should be blacklisted from normal EAL
 110    operations to avoid probing it twice when in PCI blacklist mode.
 111
 112    .. code-block:: console
 113
 114       $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \
 115          --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)'
 116          -b 84:00.0 -b 00:04.0 -- -i
 117
 118    If the slave device being used is not blacklisted, it will be probed by the
 119    EAL first. When the fail-safe then tries to initialize it the probe operation
 120    fails.
 121
 122    Note that PCI blacklist mode is the default PCI operating mode.
 123
 124 #. Alternatively, it can be used alongside any other device in whitelist mode.
 125
 126    .. code-block:: console
 127
 128       $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \
 129          --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)'
 130          -w 81:00.0 -- -i
 131
 132 Using the Fail-safe PMD from an application
 133 -------------------------------------------
 134
 135 This driver strives to be as seamless as possible to existing applications, in
 136 order to propose the hotplug functionality in the easiest way possible.
 137
 138 Care must be taken, however, to respect the **ether** API concerning device
 139 access, and in particular, using the ``RTE_ETH_FOREACH_DEV`` macro to iterate
 140 over ethernet devices, instead of directly accessing them or by writing one's
 141 own device iterator.
 142
 143 Fail-safe glossary
 144 ------------------
 145
 146 Fallback device : Secondary device
 147     The fail-safe will fail-over onto this device when the preferred device is
 148     absent.
 149
 150 Preferred device : Primary device
 151     The first declared sub-device in the fail-safe parameters.
 152     When this device is plugged, it is always used as emitting device.
 153     It is the main sub-device and is used as target for configuration
 154     operations if there is any ambiguity.
 155
 156 Slave
 157     In the context of the fail-safe PMD, synonymous to sub-device.
 158
 159 Sub-device
 160     A device being utilized by the fail-safe PMD.
 161     This is another PMD running underneath the fail-safe PMD.
 162     Any sub-device can disappear at any time. The fail-safe will ensure
 163     that the device removal happens gracefully.