Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/65992/?format=api
{ "id": 65992, "url": "https://patches.dpdk.org/api/patches/65992/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/patch/d9516604296a6db77987895950a9b47cebe13b90.1582330416.git.grive@u256.net/", "project": { "id": 1, "url": "https://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<d9516604296a6db77987895950a9b47cebe13b90.1582330416.git.grive@u256.net>", "list_archive_url": "https://inbox.dpdk.org/dev/d9516604296a6db77987895950a9b47cebe13b90.1582330416.git.grive@u256.net", "date": "2020-02-22T00:14:39", "name": "[v1,1/2] doc/failsafe: improve fail-safe documentation", "commit_ref": null, "pull_url": null, "state": "accepted", "archived": true, "hash": "de1b4e10c4c2fb3bf2bdf084ea7353d91204fc86", "submitter": { "id": 1560, "url": "https://patches.dpdk.org/api/people/1560/?format=api", "name": "Gaëtan Rivet", "email": "grive@u256.net" }, "delegate": { "id": 319, "url": "https://patches.dpdk.org/api/users/319/?format=api", "username": "fyigit", "first_name": "Ferruh", "last_name": "Yigit", "email": "ferruh.yigit@amd.com" }, "mbox": "https://patches.dpdk.org/project/dpdk/patch/d9516604296a6db77987895950a9b47cebe13b90.1582330416.git.grive@u256.net/mbox/", "series": [ { "id": 8652, "url": "https://patches.dpdk.org/api/series/8652/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/list/?series=8652", "date": "2020-02-22T00:14:38", "name": "failsafe: improve documentation", "version": 1, "mbox": "https://patches.dpdk.org/series/8652/mbox/" } ], "comments": "https://patches.dpdk.org/api/patches/65992/comments/", "check": "success", "checks": "https://patches.dpdk.org/api/patches/65992/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@inbox.dpdk.org", "Delivered-To": "patchwork@inbox.dpdk.org", "Received": [ "from dpdk.org (dpdk.org [92.243.14.124])\n\tby inbox.dpdk.org (Postfix) with ESMTP id 09314A0558;\n\tSat, 22 Feb 2020 01:14:59 +0100 (CET)", "from [92.243.14.124] (localhost [127.0.0.1])\n\tby dpdk.org (Postfix) with ESMTP id EC2711BFC8;\n\tSat, 22 Feb 2020 01:14:53 +0100 (CET)", "from relay10.mail.gandi.net (relay10.mail.gandi.net\n [217.70.178.230])\n by dpdk.org (Postfix) with ESMTP id 354B81BFBE\n for <dev@dpdk.org>; Sat, 22 Feb 2020 01:14:53 +0100 (CET)", "from inocybe.home (lfbn-idf2-1-1446-67.w92-169.abo.wanadoo.fr\n [92.169.247.67]) (Authenticated sender: grive@u256.net)\n by relay10.mail.gandi.net (Postfix) with ESMTPSA id A4B5024000B\n for <dev@dpdk.org>; Sat, 22 Feb 2020 00:14:50 +0000 (UTC)" ], "From": "Gaetan Rivet <grive@u256.net>", "To": "dev@dpdk.org", "Date": "Sat, 22 Feb 2020 01:14:39 +0100", "Message-Id": "\n <d9516604296a6db77987895950a9b47cebe13b90.1582330416.git.grive@u256.net>", "X-Mailer": "git-send-email 2.25.0", "In-Reply-To": "<cover.1582330416.git.grive@u256.net>", "References": "<cover.1582330416.git.grive@u256.net>", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "Subject": "[dpdk-dev] [PATCH v1 1/2] doc/failsafe: improve fail-safe\n\tdocumentation", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.15", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://mails.dpdk.org/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "Reading the fail-safe doc with a few years added, a few phrasing\nchoices are ambiguous or confusing.\n\nSigned-off-by: Gaetan Rivet <grive@u256.net>\n---\n doc/guides/nics/fail_safe.rst | 107 +++++++++++++++++++++-------------\n 1 file changed, 66 insertions(+), 41 deletions(-)", "diff": "diff --git a/doc/guides/nics/fail_safe.rst b/doc/guides/nics/fail_safe.rst\nindex 6c02d7ef6..3ce2f8bee 100644\n--- a/doc/guides/nics/fail_safe.rst\n+++ b/doc/guides/nics/fail_safe.rst\n@@ -4,13 +4,14 @@\n Fail-safe poll mode driver library\n ==================================\n \n-The Fail-safe poll mode driver library (**librte_pmd_failsafe**) is a virtual\n-device that allows using any device supporting hotplug (sudden device removal\n-and plugging on its bus), without modifying other components relying on such\n-device (application, other PMDs).\n+The Fail-safe poll mode driver library (**librte_pmd_failsafe**) implements a\n+virtual device that allows using device supporting hotplug, without modifying\n+other components relying on such device (application, other PMDs).\n+In this context, hotplug support is meant as plugging or removing a device\n+from its bus suddenly.\n \n Additionally to the Seamless Hotplug feature, the Fail-safe PMD offers the\n-ability to redirect operations to secondary devices when the primary has been\n+ability to redirect operations to a secondary device when the primary has been\n removed from the system.\n \n .. note::\n@@ -23,24 +24,23 @@ Features\n \n The Fail-safe PMD only supports a limited set of features. If you plan to use a\n device underneath the Fail-safe PMD with a specific feature, this feature must\n-be supported by the Fail-safe PMD to avoid throwing any error.\n+also be supported by the Fail-safe PMD.\n \n-A notable exception is the device removal feature. The fail-safe PMD being a\n-virtual device, it cannot currently be removed in the sense of a specific bus\n-hotplug, like for PCI for example. It will however enable this feature for its\n-sub-device automatically, detecting those that are capable and register the\n-relevant callback for such event.\n+A notable exception is the device removal feature. The fail-safe PMD is not\n+meant to be removed itself, unlike its sub-devices which should support it.\n+If a sub-device supports hotplugging, the fail-safe PMD will enable its use\n+automatically by detecting capable devices and registering the relevant handler.\n \n Check the feature matrix for the complete set of supported features.\n \n Compilation option\n ------------------\n \n-This option can be modified in the ``$RTE_TARGET/build/.config`` file.\n+Available options within the ``$RTE_TARGET/build/.config`` file:\n \n - ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` (default **y**)\n \n- Toggle compiling librte_pmd_failsafe.\n+ This option enables or disables compiling librte_pmd_failsafe.\n \n Using the Fail-safe PMD from the EAL command line\n -------------------------------------------------\n@@ -51,8 +51,7 @@ must start with the *net_failsafe* prefix, followed by numbers or letters. This\n name must be unique for each device. Each fail-safe instance must have at least one\n sub-device, up to ``RTE_MAX_ETHPORTS-1``.\n \n-A sub-device can be any legal DPDK device, including possibly another fail-safe\n-instance.\n+A sub-device can be any DPDK device, including possibly another fail-safe device.\n \n Fail-safe command line parameters\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n@@ -60,20 +59,23 @@ Fail-safe command line parameters\n - **dev(<iface>)** parameter\n \n This parameter allows the user to define a sub-device. The ``<iface>`` part of\n- this parameter must be a valid device definition. It could be the argument\n- provided to any ``-w`` device specification or the argument that would be\n- given to a ``--vdev`` parameter (including a fail-safe).\n- Enclosing the device definition within parenthesis here allows using\n+ this parameter must be a valid device definition. It follows the same format\n+ provided to any ``-w`` or ``--vdev`` options.\n+\n+ Enclosing the device definition within parentheses here allows using\n additional sub-device parameters if need be. They will be passed on to the\n sub-device.\n \n .. note::\n \n- In case of whitelist sub-device probed by EAL, fail-safe PMD will take the device\n- as is, which means that EAL device options are taken in this case.\n- When trying to use a PCI device automatically probed in blacklist mode,\n- the syntax for the fail-safe must be with the full PCI id:\n- Domain:Bus:Device.Function. See the usage example section.\n+ In case where the sub-device is also used as a whitelist device, using ``-w``\n+ on the EAL command line, the fail-safe PMD will use the device with the\n+ options provided to the EAL instead of its own parameters.\n+\n+ When trying to use a PCI device automatically probed by the blacklist mode,\n+ the name for the fail-safe sub-device must be the full PCI id:\n+ Domain:Bus:Device.Function, *i.e.* ``00:00:00.0`` instead of ``00:00.0``,\n+ as the second form is historically accepted by the DPDK.\n \n - **exec(<shell command>)** parameter\n \n@@ -81,9 +83,9 @@ Fail-safe command line parameters\n execute and define a sub-device.\n It is done within a regular shell context.\n The first line of its output is read by the fail-safe PMD and otherwise\n- interpreted as if passed by the regular **dev** parameter.\n+ interpreted as if passed to a **dev** parameter.\n Any other line is discarded.\n- If the command fail or output an incorrect string, the sub-device is not\n+ If the command fails or output an incorrect string, the sub-device is not\n initialized.\n All commas within the ``shell command`` are replaced by spaces before\n executing the command. This helps using scripts to specify devices.\n@@ -105,13 +107,13 @@ Fail-safe command line parameters\n address of the first of its sub-device to be successfully probed and use it as\n its default MAC address, trying to set it to all of its other sub-devices.\n If no sub-device was successfully probed at initialization, then a random MAC\n- address is generated, that will be subsequently applied to all sub-device once\n+ address is generated, that will be subsequently applied to all sub-devices once\n they are probed.\n \n - **hotplug_poll** parameter [UINT64] (default **2000**)\n \n This parameter allows the user to configure the amount of time in milliseconds\n- between two slave upkeep round.\n+ between two sub-device upkeep round.\n \n Usage example\n ~~~~~~~~~~~~~\n@@ -121,8 +123,8 @@ This section shows some example of using **testpmd** with a fail-safe PMD.\n #. To build a PMD and configure DPDK, refer to the document\n :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`.\n \n-#. Start testpmd. The slave device should be blacklisted from normal EAL\n- operations to avoid probing it twice when in PCI blacklist mode.\n+#. Start testpmd. The sub-device ``84:00.0`` should be blacklisted from normal EAL\n+ operations to avoid probing it twice, as the PCI bus is in blacklist mode.\n \n .. code-block:: console\n \n@@ -130,7 +132,7 @@ This section shows some example of using **testpmd** with a fail-safe PMD.\n --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' \\\n -b 84:00.0 -b 00:04.0 -- -i\n \n- If the slave device being used is not blacklisted, it will be probed by the\n+ If the sub-device ``84:00.0`` is not blacklisted, it will be probed by the\n EAL first. When the fail-safe then tries to initialize it the probe operation\n fails.\n \n@@ -148,7 +150,7 @@ This section shows some example of using **testpmd** with a fail-safe PMD.\n \n .. code-block:: console\n \n- $RTE_TARGET/build/app/testpmd -c 0xff -n 4 --no-pci \\\n+ $RTE_TARGET/build/app/testpmd -c 0xff -n 4 -w ff:ff.f \\\n --vdev='net_failsafe0,exec(echo 84:00.0)' -- -i\n \n #. Start testpmd, automatically probing the device 84:00.0 and using it with\n@@ -171,6 +173,20 @@ access, and in particular, using the ``RTE_ETH_FOREACH_DEV`` macro to iterate\n over ethernet devices, instead of directly accessing them or by writing one's\n own device iterator.\n \n+ .. code-block:: C\n+\n+ unsigned int i;\n+\n+ /* VALID iteration over eth-dev. */\n+ RTE_ETH_FOREACH_DEV(i) {\n+ [...]\n+ }\n+\n+ /* INVALID iteration over eth-dev. */\n+ for (i = 0; i < RTE_MAX_ETHPORTS; i++) {\n+ [...]\n+ }\n+\n Plug-in feature\n ---------------\n \n@@ -180,10 +196,14 @@ absence and postpone its use. It will then register for a periodic check on any\n missing sub-device.\n \n During this time, the fail-safe PMD can be used normally, configured and told to\n-emit and receive packets. It will store any applied configuration, and try to\n-apply it upon the probing of its missing sub-device. After this configuration\n-pass, the new sub-device will be synchronized with other sub-devices, i.e. be\n-started if the fail-safe PMD has been started by the user before.\n+emit and receive packets. It will store any applied configuration but will fail\n+to emit anything, returning ``0`` from its TX function. Any unsent packet must\n+be freed.\n+\n+Upon the probing of its missing sub-device, the current stored configuration\n+will be applied. After this configuration pass, the new sub-device will be\n+synchronized with other sub-devices, i.e. be started if the fail-safe PMD has\n+been started by the user before.\n \n Plug-out feature\n ----------------\n@@ -196,20 +216,25 @@ emitted this event, allowing it to free its eventual resources.\n Fail-safe glossary\n ------------------\n \n-Fallback device : Secondary device\n+Fallback device\n+ Also called **Secondary device**.\n+\n The fail-safe will fail-over onto this device when the preferred device is\n absent.\n \n-Preferred device : Primary device\n+Preferred device\n+ Also called **Primary device**.\n+\n The first declared sub-device in the fail-safe parameters.\n When this device is plugged, it is always used as emitting device.\n It is the main sub-device and is used as target for configuration\n operations if there is any ambiguity.\n \n Upkeep round\n- Periodical process when slaves are serviced. Each devices having a state\n- different to that of the fail-safe device itself, is synchronized with it.\n- Additionally, each slave having the remove flag set are cleaned-up.\n+ Periodical event during which sub-devices are serviced. Each devices having a state\n+ different to that of the fail-safe device itself, is synchronized with it\n+ (brought down or up accordingly). Additionally, any sub-device marked for\n+ removal is cleaned-up.\n \n Slave\n In the context of the fail-safe PMD, synonymous to sub-device.\n", "prefixes": [ "v1", "1/2" ] }