Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/114036/?format=api
{ "id": 114036, "url": "http://patches.dpdk.org/api/patches/114036/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20220718151446.882555-1-shibin.koikkara.reeny@intel.com/", "project": { "id": 1, "url": "http://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": "<20220718151446.882555-1-shibin.koikkara.reeny@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20220718151446.882555-1-shibin.koikkara.reeny@intel.com", "date": "2022-07-18T15:14:46", "name": "net/af_xdp: improve documentation", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "57b98b0bde70214e534460402bdc45bd13402325", "submitter": { "id": 2540, "url": "http://patches.dpdk.org/api/people/2540/?format=api", "name": "Koikkara Reeny, Shibin", "email": "shibin.koikkara.reeny@intel.com" }, "delegate": { "id": 3961, "url": "http://patches.dpdk.org/api/users/3961/?format=api", "username": "arybchenko", "first_name": "Andrew", "last_name": "Rybchenko", "email": "andrew.rybchenko@oktetlabs.ru" }, "mbox": "http://patches.dpdk.org/project/dpdk/patch/20220718151446.882555-1-shibin.koikkara.reeny@intel.com/mbox/", "series": [ { "id": 24022, "url": "http://patches.dpdk.org/api/series/24022/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=24022", "date": "2022-07-18T15:14:46", "name": "net/af_xdp: improve documentation", "version": 1, "mbox": "http://patches.dpdk.org/series/24022/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/114036/comments/", "check": "warning", "checks": "http://patches.dpdk.org/api/patches/114036/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 mails.dpdk.org (mails.dpdk.org [217.70.189.124])\n\tby inbox.dpdk.org (Postfix) with ESMTP id E4F40A0032;\n\tMon, 18 Jul 2022 17:14:51 +0200 (CEST)", "from [217.70.189.124] (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 82FCA40698;\n\tMon, 18 Jul 2022 17:14:51 +0200 (CEST)", "from mga12.intel.com (mga12.intel.com [192.55.52.136])\n by mails.dpdk.org (Postfix) with ESMTP id 9617740041\n for <dev@dpdk.org>; Mon, 18 Jul 2022 17:14:49 +0200 (CEST)", "from fmsmga003.fm.intel.com ([10.253.24.29])\n by fmsmga106.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;\n 18 Jul 2022 08:14:48 -0700", "from silpixa00401350.ir.intel.com (HELO silpixav00401350..)\n ([10.55.128.131])\n by FMSMGA003.fm.intel.com with ESMTP; 18 Jul 2022 08:14:47 -0700" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple;\n d=intel.com; i=@intel.com; q=dns/txt; s=Intel;\n t=1658157289; x=1689693289;\n h=from:to:cc:subject:date:message-id:mime-version:\n content-transfer-encoding;\n bh=K+B3jGc3BHonxY77VIxhlfEf2unY2RIb9s+33eE64P0=;\n b=QBy/KkFyHBuiFbZVeKoWaN57liR2M6kTJxJ0zlKaCccgdboVwUQwFdwt\n ZO+2zgm9ln7NQHDZxor4//GAOKNyquMCkkWxNzZiJsXQmundfsnUvVkEe\n o0EQa/NFRWwy+MarmYMHZW3NDvxisz8y7feuC0zcBhuw6Qdjkym+xJEef\n itM8KuDmuryhYpS8fXMKOtmGqmLh80bbk4tIJM8gwEx+jTudFiL04la5t\n xqjpz531TpPqzLq141UYYqICLcUyDJWbrQpyVgX82LNFGNbzEs1ynHrF1\n /AjTLbIWRrp0fO2MxbzrtKbyc38VFlSQ+vnqlxLco8k/kZxKQ+RQMpAzk g==;", "X-IronPort-AV": [ "E=McAfee;i=\"6400,9594,10412\"; a=\"266029772\"", "E=Sophos;i=\"5.92,281,1650956400\"; d=\"scan'208\";a=\"266029772\"", "E=Sophos;i=\"5.92,281,1650956400\"; d=\"scan'208\";a=\"686774476\"" ], "X-ExtLoop1": "1", "From": "Shibin Koikkara Reeny <shibin.koikkara.reeny@intel.com>", "To": "dev@dpdk.org", "Cc": "ciara.loftus@intel.com,\n\tqi.z.zhang@intel.com", "Subject": "[PATCH] net/af_xdp: improve documentation", "Date": "Mon, 18 Jul 2022 15:14:46 +0000", "Message-Id": "<20220718151446.882555-1-shibin.koikkara.reeny@intel.com>", "X-Mailer": "git-send-email 2.34.1", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.29", "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" }, "content": "From: Ciara Loftus <ciara.loftus@intel.com>\n\nInstead of a one-liner describing each vdev argument, add a description\nand example for each. Move the information describing preferred busy\npolling from the \"Limitations\" section to the \"Options\" section where it\nis better placed. Also make general grammer improvements.\n\nSigned-off-by: Ciara Loftus <ciara.loftus@intel.com>\n---\n doc/guides/nics/af_xdp.rst | 204 ++++++++++++++++++++++---------------\n 1 file changed, 123 insertions(+), 81 deletions(-)", "diff": "diff --git a/doc/guides/nics/af_xdp.rst b/doc/guides/nics/af_xdp.rst\nindex d42e0f1f79..c99f750b44 100644\n--- a/doc/guides/nics/af_xdp.rst\n+++ b/doc/guides/nics/af_xdp.rst\n@@ -5,79 +5,153 @@ AF_XDP Poll Mode Driver\n ==========================\n \n AF_XDP is an address family that is optimized for high performance\n-packet processing. AF_XDP sockets enable the possibility for XDP program to\n+packet processing. AF_XDP sockets enable the possibility for an XDP program to\n redirect packets to a memory buffer in userspace.\n \n-For the full details behind AF_XDP socket, you can refer to\n-`AF_XDP documentation in the Kernel\n+Further information about AF_XDP can be found in the\n+`AF_XDP kernel documentation\n <https://www.kernel.org/doc/Documentation/networking/af_xdp.rst>`_.\n \n This Linux-specific PMD creates the AF_XDP socket and binds it to a\n-specific netdev queue, it allows a DPDK application to send and receive raw\n-packets through the socket which would bypass the kernel network stack.\n-Current implementation only supports single queue, multi-queues feature will\n-be added later.\n-\n-AF_XDP PMD enables need_wakeup flag by default if it is supported. This\n-need_wakeup feature is used to support executing application and driver on the\n-same core efficiently. This feature not only has a large positive performance\n-impact for the one core case, but also does not degrade 2 core performance and\n-actually improves it for Tx heavy workloads.\n-\n-Options\n--------\n-\n-The following options can be provided to set up an af_xdp port in DPDK.\n-\n-* ``iface`` - name of the Kernel interface to attach to (required);\n-* ``start_queue`` - starting netdev queue id (optional, default 0);\n-* ``queue_count`` - total netdev queue number (optional, default 1);\n-* ``shared_umem`` - PMD will attempt to share UMEM with others (optional,\n- default 0);\n-* ``xdp_prog`` - path to custom xdp program (optional, default none);\n-* ``busy_budget`` - busy polling budget (optional, default 64);\n-* ``force_copy`` - PMD will force AF_XDP socket into copy mode (optional,\n- default 0);\n+specific netdev queue. The DPDK application can then send and receive raw\n+packets through the socket which bypass the kernel network stack.\n \n Prerequisites\n -------------\n \n-This is a Linux-specific PMD, thus the following prerequisites apply:\n-\n-* A Linux Kernel (version > v4.18) with XDP sockets configuration enabled;\n-* Both libxdp >=v1.2.2 and libbpf libraries installed, or, libbpf <=v0.6.0\n+* A Linux Kernel (version >= v4.18) with the XDP sockets configuration option\n+ enabled (CONFIG_XDP_SOCKETS=y).\n+* Both libxdp (>= v1.2.2) and libbpf (any version) libraries installed, or\n+ alternatively just the libbpf library <= v0.6.0.\n+* The pkg-config package should be installed on the system as it is used to\n+ discover the libbpf and libxdp libraries and determine their versions are\n+ sufficient.\n * If using libxdp, it requires an environment variable called\n LIBXDP_OBJECT_PATH to be set to the location of where libxdp placed its bpf\n object files. This is usually in /usr/local/lib/bpf or /usr/local/lib64/bpf.\n-* A Kernel bound interface to attach to;\n-* For need_wakeup feature, it requires kernel version later than v5.3-rc1;\n-* For PMD zero copy, it requires kernel version later than v5.4-rc1;\n-* For shared_umem, it requires kernel version v5.10 or later and libbpf version\n- v0.2.0 or later.\n-* For 32-bit OS, a kernel with version 5.4 or later is required.\n-* For busy polling, kernel version v5.11 or later is required.\n+* A Kernel bound interface to attach to.\n+* The need_wakeup feature requires kernel version >= v5.4.\n+* The PMD zero copy feature requires kernel version >= v5.4.\n+* The shared UMEM feature requires kernel version >= v5.10 and libbpf version\n+ v0.2.0 or later. The LINUX_VERSION_CODE defined in the version.h kernel\n+ header is used to determine the kernel version at compile time.\n+* A kernel with version 5.4 or later is required for 32-bit OS.\n+* The busy polling feature requires kernel version >= v5.11.\n+\n \n-Set up an af_xdp interface\n------------------------------\n+Options\n+-------\n \n-The following example will set up an af_xdp interface in DPDK:\n+iface\n+~~~~~\n+\n+The ``iface`` option is the only required option. It is the name of the Kernel\n+interface to attach to.\n \n .. code-block:: console\n \n --vdev net_af_xdp,iface=ens786f1\n \n-If 'start_queue' is not specified in the vdev arguments,\n-the socket will by default be created on Rx queue 0.\n-To ensure traffic lands on this queue,\n-one can use flow steering if the network card supports it.\n-Or, a simpler way is to reduce the number of configured queues\n-for the device which will ensure that all traffic will land on queue 0\n-and thus reach the socket:\n+The socket will by default be created on Rx queue 0. To ensure traffic lands on\n+this queue, one can use flow steering if the network card supports it. Or, a\n+simpler way is to reduce the number of configured queues for the device to just\n+a single queue which will ensure that all traffic will land on that queue (queue\n+1) and thus reach the socket. This can be configured using ethtool:\n \n .. code-block:: console\n \n ethtool -L ens786f1 combined 1\n \n+start_queue\n+~~~~~~~~~~~\n+\n+To create a socket on another queue, first configure the netdev with multiple\n+queues, for example 2, like so:\n+\n+.. code-block:: console\n+\n+ ethtool -L ens786f1 combined 2\n+\n+Then, create the socket on one of those queues, for example queue 1:\n+\n+.. code-block:: console\n+\n+ --vdev net_af_xdp,iface=ens786f1,start_queue=1\n+\n+queue_count\n+~~~~~~~~~~~\n+\n+To create a PMD with sockets on multiple queues, use the queue_count arg. The\n+following example creates sockets on queues 0 and 1:\n+\n+.. code-block:: console\n+\n+ --vdev net_af_xdp,iface=ens786f1,queue_count=2\n+\n+shared_umem\n+~~~~~~~~~~~\n+\n+The shared UMEM feature allows for two sockets to share UMEM and can be\n+configured like so:\n+\n+.. code-block:: console\n+\n+ --vdev net_af_xdp0,iface=ens786f1,shared_umem=1 \\\n+ --vdev net_af_xdp1,iface=ens786f2,shared_umem=1\n+\n+xdp_prog\n+~~~~~~~~\n+\n+The xdp_prog argument allows for the user to provide a path to a custom XDP\n+program which should be used in place of the default libbpf/libxdp program which\n+simply redirects packets to the sockets. For example:\n+\n+.. code-block:: console\n+\n+ --vdev net_af_xdp,iface=ens786f1,xdp_prog=/path/to/prog.o\n+\n+busy_budget\n+~~~~~~~~~~~\n+\n+The busy polling feature aims to improve single-core performance for AF_XDP\n+sockets under heavy load. It is enabled by default if the detected kernel\n+version is sufficient ie. >= v5.11. The busy_budget arg sets the busy-polling\n+NAPI budget which is the number of packets the kernel will attempt to process in\n+the netdev's NAPI context. It can be configured like so:\n+\n+.. code-block:: console\n+\n+ --vdev net_af_xdp,iface=ens786f1,busy_budget=32\n+\n+To disable busy polling, simply set the busy_budget to 0:\n+\n+.. code-block:: console\n+\n+ --vdev net_af_xdp,iface=ens786f1,busy_budget=0\n+\n+It is also strongly recommended to set the following for optimal performance\n+when using the busy polling feature:\n+\n+.. code-block:: console\n+\n+ echo 2 | sudo tee /sys/class/net/ens786f1/napi_defer_hard_irqs\n+ echo 200000 | sudo tee /sys/class/net/ens786f1/gro_flush_timeout\n+\n+The above defers interrupts for interface ens786f1 and instead schedules its\n+NAPI context from a watchdog timer instead of from softirqs. More information\n+on this feature can be found at [1].\n+\n+force_copy\n+~~~~~~~~~~\n+\n+The force_copy argument allows the user to force the socket to use copy mode\n+instead of zero copy mode (if available).\n+\n+.. code-block:: console\n+\n+ --vdev net_af_xdp,iface=ens786f1,force_copy=1\n+\n+\n Limitations\n -----------\n \n@@ -126,38 +200,6 @@ Limitations\n --vdev net_af_xdp0,iface=ens786f1,shared_umem=1 \\\n --vdev net_af_xdp1,iface=ens786f2,shared_umem=1 \\\n \n-- **Preferred Busy Polling**\n-\n- The SO_PREFER_BUSY_POLL socket option was introduced in kernel v5.11. It can\n- deliver a performance improvement for sockets with heavy traffic loads and\n- can significantly improve single-core performance in this context.\n-\n- The feature is enabled by default in the AF_XDP PMD. To disable it, set the\n- 'busy_budget' vdevarg to zero:\n-\n- .. code-block:: console\n-\n- --vdev net_af_xdp0,iface=ens786f1,busy_budget=0\n-\n- The default 'busy_budget' is 64 and it represents the number of packets the\n- kernel will attempt to process in the netdev's NAPI context. You can change\n- the value for example to 256 like so:\n-\n- .. code-block:: console\n-\n- --vdev net_af_xdp0,iface=ens786f1,busy_budget=256\n-\n- It is also strongly recommended to set the following for optimal performance:\n-\n- .. code-block:: console\n-\n- echo 2 | sudo tee /sys/class/net/ens786f1/napi_defer_hard_irqs\n- echo 200000 | sudo tee /sys/class/net/ens786f1/gro_flush_timeout\n-\n- The above defers interrupts for interface ens786f1 and instead schedules its\n- NAPI context from a watchdog timer instead of from softirqs. More information\n- on this feature can be found at [1].\n-\n - **Secondary Processes**\n \n Rx and Tx are not supported for secondary processes due to memory mapping of\n", "prefixes": [] }