X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fnics%2Ffail_safe.rst;h=ae9f08ec8d1d5f20c234b401dad08a7503c7ff72;hb=6be6690127744bb294005bfcf539508b3d5f389e;hp=c20696e7ff51b3b61bf88d8f8a15415a2261ae5e;hpb=a46f8d584eb88feb2a05ca3459d4a00b7d7654aa;p=dpdk.git diff --git a/doc/guides/nics/fail_safe.rst b/doc/guides/nics/fail_safe.rst index c20696e7ff..ae9f08ec8d 100644 --- a/doc/guides/nics/fail_safe.rst +++ b/doc/guides/nics/fail_safe.rst @@ -1,66 +1,34 @@ -.. BSD LICENSE +.. SPDX-License-Identifier: BSD-3-Clause Copyright 2017 6WIND S.A. - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of 6WIND S.A. nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - Fail-safe poll mode driver library ================================== -The Fail-safe poll mode driver library (**librte_pmd_failsafe**) is a virtual -device that allows using any device supporting hotplug (sudden device removal -and plugging on its bus), without modifying other components relying on such -device (application, other PMDs). +The Fail-safe poll mode driver library (**librte_net_failsafe**) implements a +virtual device that allows using device supporting hotplug, without modifying +other components relying on such device (application, other PMDs). +In this context, hotplug support is meant as plugging or removing a device +from its bus suddenly. Additionally to the Seamless Hotplug feature, the Fail-safe PMD offers the -ability to redirect operations to secondary devices when the primary has been +ability to redirect operations to a secondary device when the primary has been removed from the system. -.. note:: - - The library is enabled by default. You can enable it or disable it manually - by setting the ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` configuration option. Features -------- The Fail-safe PMD only supports a limited set of features. If you plan to use a device underneath the Fail-safe PMD with a specific feature, this feature must -be supported by the Fail-safe PMD to avoid throwing any error. +also be supported by the Fail-safe PMD. -Check the feature matrix for the complete set of supported features. - -Compilation option ------------------- +A notable exception is the device removal feature. The fail-safe PMD is not +meant to be removed itself, unlike its sub-devices which should support it. +If a sub-device supports hotplugging, the fail-safe PMD will enable its use +automatically by detecting capable devices and registering the relevant handler. -This option can be modified in the ``$RTE_TARGET/build/.config`` file. - -- ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` (default **y**) +Check the feature matrix for the complete set of supported features. - Toggle compiling librte_pmd_failsafe. Using the Fail-safe PMD from the EAL command line ------------------------------------------------- @@ -69,10 +37,9 @@ The Fail-safe PMD can be used like most other DPDK virtual devices, by passing a ``--vdev`` parameter to the EAL when starting the application. The device name must start with the *net_failsafe* prefix, followed by numbers or letters. This name must be unique for each device. Each fail-safe instance must have at least one -sub-device, up to ``RTE_MAX_ETHPORTS-1``. +sub-device, and at most two. -A sub-device can be any legal DPDK device, including possibly another fail-safe -instance. +A sub-device can be any DPDK device, including possibly another fail-safe device. Fail-safe command line parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -80,13 +47,46 @@ Fail-safe command line parameters - **dev()** parameter This parameter allows the user to define a sub-device. The ```` part of - this parameter must be a valid device definition. It could be the argument - provided to any ``-w`` device specification or the argument that would be - given to a ``--vdev`` parameter (including a fail-safe). - Enclosing the device definition within parenthesis here allows using + this parameter must be a valid device definition. It follows the same format + provided to any ``-a`` or ``--vdev`` options. + + Enclosing the device definition within parentheses here allows using additional sub-device parameters if need be. They will be passed on to the sub-device. +.. note:: + + In case where the sub-device is also used as an allowed device, using ``-a`` + on the EAL command line, the fail-safe PMD will use the device with the + options provided to the EAL instead of its own parameters. + + When trying to use a PCI device automatically probed by the command line, + the name for the fail-safe sub-device must be the full PCI id: + Domain:Bus:Device.Function, *i.e.* ``00:00:00.0`` instead of ``00:00.0``, + as the second form is historically accepted by the DPDK. + +- **exec()** parameter + + This parameter allows the user to provide a command to the fail-safe PMD to + execute and define a sub-device. + It is done within a regular shell context. + The first line of its output is read by the fail-safe PMD and otherwise + interpreted as if passed to a **dev** parameter. + Any other line is discarded. + If the command fails or output an incorrect string, the sub-device is not + initialized. + All commas within the ``shell command`` are replaced by spaces before + executing the command. This helps using scripts to specify devices. + +- **fd()** parameter + + This parameter reads a device definition from an arbitrary file descriptor + number in ```` format as described above. + + The file descriptor is read in non-blocking mode and is never closed in + order to take only the last line into account (unlike ``exec()``) at every + probe attempt. + - **mac** parameter [MAC address] This parameter allows the user to set a default MAC address to the fail-safe @@ -95,9 +95,14 @@ Fail-safe command line parameters address of the first of its sub-device to be successfully probed and use it as its default MAC address, trying to set it to all of its other sub-devices. If no sub-device was successfully probed at initialization, then a random MAC - address is generated, that will be subsequently applied to all sub-device once + address is generated, that will be subsequently applied to all sub-devices once they are probed. +- **hotplug_poll** parameter [UINT64] (default **2000**) + + This parameter allows the user to configure the amount of time in milliseconds + between two sub-device upkeep round. + Usage example ~~~~~~~~~~~~~ @@ -106,28 +111,44 @@ This section shows some example of using **testpmd** with a fail-safe PMD. #. To build a PMD and configure DPDK, refer to the document :ref:`compiling and testing a PMD for a NIC `. -#. Start testpmd. The slave device should be blacklisted from normal EAL - operations to avoid probing it twice when in PCI blacklist mode. +#. Start testpmd. The sub-device ``84:00.0`` should be blocked from normal EAL + operations to avoid probing it twice, as the PCI bus is in blocklist mode. .. code-block:: console - $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \ - --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' + .//app/dpdk-testpmd -c 0xff -n 4 \ + --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' \ -b 84:00.0 -b 00:04.0 -- -i - If the slave device being used is not blacklisted, it will be probed by the + If the sub-device ``84:00.0`` is not blocked, it will be probed by the EAL first. When the fail-safe then tries to initialize it the probe operation fails. - Note that PCI blacklist mode is the default PCI operating mode. + Note that PCI blocklist mode is the default PCI operating mode. + +#. Alternatively, it can be used alongside any other device in allow mode. -#. Alternatively, it can be used alongside any other device in whitelist mode. + .. code-block:: console + + .//app/dpdk-testpmd -c 0xff -n 4 \ + --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' \ + -a 81:00.0 -- -i + +#. Start testpmd using a flexible device definition .. code-block:: console - $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \ - --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' - -w 81:00.0 -- -i + .//app/dpdk-testpmd -c 0xff -n 4 -a ff:ff.f \ + --vdev='net_failsafe0,exec(echo 84:00.0)' -- -i + +#. Start testpmd, automatically probing the device 84:00.0 and using it with + the fail-safe. + + .. code-block:: console + + .//app/dpdk-testpmd -c 0xff -n 4 \ + --vdev 'net_failsafe0,dev(0000:84:00.0),dev(net_ring0)' -- -i + Using the Fail-safe PMD from an application ------------------------------------------- @@ -140,19 +161,69 @@ access, and in particular, using the ``RTE_ETH_FOREACH_DEV`` macro to iterate over ethernet devices, instead of directly accessing them or by writing one's own device iterator. + .. code-block:: C + + unsigned int i; + + /* VALID iteration over eth-dev. */ + RTE_ETH_FOREACH_DEV(i) { + [...] + } + + /* INVALID iteration over eth-dev. */ + for (i = 0; i < RTE_MAX_ETHPORTS; i++) { + [...] + } + +Plug-in feature +--------------- + +A sub-device can be defined without existing on the system when the fail-safe +PMD is initialized. Upon probing this device, the fail-safe PMD will detect its +absence and postpone its use. It will then register for a periodic check on any +missing sub-device. + +During this time, the fail-safe PMD can be used normally, configured and told to +emit and receive packets. It will store any applied configuration but will fail +to emit anything, returning ``0`` from its TX function. Any unsent packet must +be freed. + +Upon the probing of its missing sub-device, the current stored configuration +will be applied. After this configuration pass, the new sub-device will be +synchronized with other sub-devices, i.e. be started if the fail-safe PMD has +been started by the user before. + +Plug-out feature +---------------- + +A sub-device supporting the device removal event can be removed from its bus at +any time. The fail-safe PMD will register a callback for such event and react +accordingly. It will try to safely stop, close and uninit the sub-device having +emitted this event, allowing it to free its eventual resources. + Fail-safe glossary ------------------ -Fallback device : Secondary device +Fallback device + Also called **Secondary device**. + The fail-safe will fail-over onto this device when the preferred device is absent. -Preferred device : Primary device +Preferred device + Also called **Primary device**. + The first declared sub-device in the fail-safe parameters. When this device is plugged, it is always used as emitting device. It is the main sub-device and is used as target for configuration operations if there is any ambiguity. +Upkeep round + Periodical event during which sub-devices are serviced. Each devices having a state + different to that of the fail-safe device itself, is synchronized with it + (brought down or up accordingly). Additionally, any sub-device marked for + removal is cleaned-up. + Slave In the context of the fail-safe PMD, synonymous to sub-device.