From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 09314A0558; Sat, 22 Feb 2020 01:14:59 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id EC2711BFC8; Sat, 22 Feb 2020 01:14:53 +0100 (CET) Received: from relay10.mail.gandi.net (relay10.mail.gandi.net [217.70.178.230]) by dpdk.org (Postfix) with ESMTP id 354B81BFBE for ; Sat, 22 Feb 2020 01:14:53 +0100 (CET) Received: from inocybe.home (lfbn-idf2-1-1446-67.w92-169.abo.wanadoo.fr [92.169.247.67]) (Authenticated sender: grive@u256.net) by relay10.mail.gandi.net (Postfix) with ESMTPSA id A4B5024000B for ; Sat, 22 Feb 2020 00:14:50 +0000 (UTC) From: Gaetan Rivet To: dev@dpdk.org Date: Sat, 22 Feb 2020 01:14:39 +0100 Message-Id: X-Mailer: git-send-email 2.25.0 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v1 1/2] doc/failsafe: improve fail-safe documentation X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Reading the fail-safe doc with a few years added, a few phrasing choices are ambiguous or confusing. Signed-off-by: Gaetan Rivet --- doc/guides/nics/fail_safe.rst | 107 +++++++++++++++++++++------------- 1 file changed, 66 insertions(+), 41 deletions(-) diff --git a/doc/guides/nics/fail_safe.rst b/doc/guides/nics/fail_safe.rst index 6c02d7ef6..3ce2f8bee 100644 --- a/doc/guides/nics/fail_safe.rst +++ b/doc/guides/nics/fail_safe.rst @@ -4,13 +4,14 @@ 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_pmd_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:: @@ -23,24 +24,23 @@ 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. -A notable exception is the device removal feature. The fail-safe PMD being a -virtual device, it cannot currently be removed in the sense of a specific bus -hotplug, like for PCI for example. It will however enable this feature for its -sub-device automatically, detecting those that are capable and register the -relevant callback for such event. +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. Check the feature matrix for the complete set of supported features. Compilation option ------------------ -This option can be modified in the ``$RTE_TARGET/build/.config`` file. +Available options within the ``$RTE_TARGET/build/.config`` file: - ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` (default **y**) - Toggle compiling librte_pmd_failsafe. + This option enables or disables compiling librte_pmd_failsafe. Using the Fail-safe PMD from the EAL command line ------------------------------------------------- @@ -51,8 +51,7 @@ 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``. -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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -60,20 +59,23 @@ 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 ``-w`` 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 of whitelist sub-device probed by EAL, fail-safe PMD will take the device - as is, which means that EAL device options are taken in this case. - When trying to use a PCI device automatically probed in blacklist mode, - the syntax for the fail-safe must be with the full PCI id: - Domain:Bus:Device.Function. See the usage example section. + In case where the sub-device is also used as a whitelist device, using ``-w`` + 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 blacklist mode, + 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 @@ -81,9 +83,9 @@ Fail-safe command line parameters 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 by the regular **dev** parameter. + interpreted as if passed to a **dev** parameter. Any other line is discarded. - If the command fail or output an incorrect string, the sub-device is not + 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. @@ -105,13 +107,13 @@ 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 slave upkeep round. + between two sub-device upkeep round. Usage example ~~~~~~~~~~~~~ @@ -121,8 +123,8 @@ 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 blacklisted from normal EAL + operations to avoid probing it twice, as the PCI bus is in blacklist mode. .. code-block:: console @@ -130,7 +132,7 @@ This section shows some example of using **testpmd** with a fail-safe PMD. --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 blacklisted, it will be probed by the EAL first. When the fail-safe then tries to initialize it the probe operation fails. @@ -148,7 +150,7 @@ This section shows some example of using **testpmd** with a fail-safe PMD. .. code-block:: console - $RTE_TARGET/build/app/testpmd -c 0xff -n 4 --no-pci \ + $RTE_TARGET/build/app/testpmd -c 0xff -n 4 -w 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 @@ -171,6 +173,20 @@ 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 --------------- @@ -180,10 +196,14 @@ 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, and try to -apply it upon the probing of its missing sub-device. 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. +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 ---------------- @@ -196,20 +216,25 @@ 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 process when slaves are serviced. Each devices having a state - different to that of the fail-safe device itself, is synchronized with it. - Additionally, each slave having the remove flag set are cleaned-up. + 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. -- 2.25.0