Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/134546/?format=api
{ "id": 134546, "url": "http://patches.dpdk.org/api/patches/134546/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20231123012633.2005-6-dave@youngcopy.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": "<20231123012633.2005-6-dave@youngcopy.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20231123012633.2005-6-dave@youngcopy.com", "date": "2023-11-23T01:26:26", "name": "[v4,5/6] Section 5: Appendix", "commit_ref": null, "pull_url": null, "state": "new", "archived": false, "hash": "a47b27ed38742403a7eee79a2284350cc147b299", "submitter": { "id": 3122, "url": "http://patches.dpdk.org/api/people/3122/?format=api", "name": "Dave Young", "email": "dave@youngcopy.com" }, "delegate": { "id": 1, "url": "http://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "http://patches.dpdk.org/project/dpdk/patch/20231123012633.2005-6-dave@youngcopy.com/mbox/", "series": [ { "id": 30365, "url": "http://patches.dpdk.org/api/series/30365/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=30365", "date": "2023-11-23T01:26:21", "name": "docs: getting started guide consolidation", "version": 4, "mbox": "http://patches.dpdk.org/series/30365/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/134546/comments/", "check": "warning", "checks": "http://patches.dpdk.org/api/patches/134546/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 475054339F;\n\tThu, 23 Nov 2023 02:27:33 +0100 (CET)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id A076A42EE4;\n\tThu, 23 Nov 2023 02:27:11 +0100 (CET)", "from mail-oo1-f49.google.com (mail-oo1-f49.google.com\n [209.85.161.49]) by mails.dpdk.org (Postfix) with ESMTP id A719742D7F\n for <dev@dpdk.org>; Thu, 23 Nov 2023 02:27:02 +0100 (CET)", "by mail-oo1-f49.google.com with SMTP id\n 006d021491bc7-587af6285c0so57793eaf.1\n for <dev@dpdk.org>; Wed, 22 Nov 2023 17:27:02 -0800 (PST)", "from localhost.localdomain\n ([2600:1700:20c0:a560:40f7:d2c:d53a:d071])\n by smtp.gmail.com with ESMTPSA id\n j184-20020a0dc7c1000000b005a815346d95sm89832ywd.71.2023.11.22.17.26.59\n (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n Wed, 22 Nov 2023 17:26:59 -0800 (PST)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1700702821;\n x=1701307621;\n darn=dpdk.org;\n h=content-transfer-encoding:mime-version:references:in-reply-to\n :message-id:date:subject:cc:to:from:from:to:cc:subject:date\n :message-id:reply-to;\n bh=pyuxstBfbLf4VelbhrwBQ/D2st8c3XcQOqoGXEgOwE8=;\n b=uwE5apTWREIxjx4UJQ7wzmgee7iLW9KsDpzs2ghYwlVd6edq7uiOldQh8uKPjQHWRd\n dRMIY9AZdXjWVti9SZ/txVXb2gPAA0DDdRaX7tNdF88Lk+IYOy6T2fOweTvHiP9zspf+\n 7Hh+b2GR7w16JzUnMOdAOgqYywzyO6MCzCzIwkAylSr2ovq0fjYJG28tqrVEIFo8Dgad\n WNOBfUzTeyb553WYN3JeLtbFQxxyzJm50/LG3qqsgdqWbN28/VLVa4to1a4QyOUqDgfA\n a+E8CVVV7y95FxKM2rsoa3Ez+SOcVYwVsjndiBdRN0p4YSC/5GNVd5Fg/Un3py5FtUHE\n r5Cg==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20230601; t=1700702821; x=1701307621;\n h=content-transfer-encoding:mime-version:references:in-reply-to\n :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc\n :subject:date:message-id:reply-to;\n bh=pyuxstBfbLf4VelbhrwBQ/D2st8c3XcQOqoGXEgOwE8=;\n b=kTaxZ/Lo/zuw9F/FSCJL/iGzG83n1szzaKSq62/MvXjQyYaQEcVJ4MUiTQhZMIbvvg\n oMI3cXfS6f4NDBor3JovoLTZfGrLkt1PoKsljhB1ZF5xyyOat3cyNw76bAfAqCWROc+0\n ZJ96iDegcwpWEODT2yNkMmmrn8fUnNWwP7HwjvdY6vG73R2qbwV7g5e2fjJO9QUPlMRx\n dj+NCcY15lXh3bCQ6+zTXsc5lt1v3fGdT8q1/trAzX0OR0DUGQW1wATSPBV6wsKxhJNW\n vb3dz1yPsEUk2xk9SFokHQpJLyNXsTJ2nbNLY2R0E+JD/fGicgAF+pItq6VOEsUYM1sz\n ToRA==", "X-Gm-Message-State": "AOJu0YyQQ4WW3DGI3bfrKvCrOs0DD4vkt4x+537JCoS5taq1SRYqtqpd\n krT0qasqr/PT3eP9ndwHK02ARZLjeEPicM4ba8Y=", "X-Google-Smtp-Source": "\n AGHT+IHusCHkQSUQ4ee9cGBuXJX/iHyvp5sYRaujE4plvFTfXNZe7AuZR7kMC8Yv1kAQxovcfgFjWg==", "X-Received": "by 2002:a05:6358:7e14:b0:16d:e922:ffdc with SMTP id\n o20-20020a0563587e1400b0016de922ffdcmr3938762rwm.1.1700702820811;\n Wed, 22 Nov 2023 17:27:00 -0800 (PST)", "From": "David Young <dave@youngcopy.com>", "To": "dev@dpdk.org", "Cc": "Bruce Richardson <bruce.richardson@intel.com>,\n Aaron Conole <aconole@redhat.com>, David Young <dave@youngcopy.com>", "Subject": "[PATCH v4 5/6] Section 5: Appendix", "Date": "Wed, 22 Nov 2023 20:26:26 -0500", "Message-ID": "<20231123012633.2005-6-dave@youngcopy.com>", "X-Mailer": "git-send-email 2.41.0.windows.1", "In-Reply-To": "<20231123012633.2005-1-dave@youngcopy.com>", "References": "<20231103040202.2849-1-dave@youngcopy.com>\n <20231123012633.2005-1-dave@youngcopy.com>", "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": "Added new guide on hugepages for different architectures\n\nAdded hugepages_different_architectures to index\n\n-Content Streamlining: Removed initial detailed instructions on setting up DPDK\nfor non-root users.\nEmphasized that running DPDK as non-root on Linux requires IOMMU support through vfio.\n-Linux Section Updates: Simplified the section to focus on:\nAdjusting permissions for VFIO entries in /dev and hugepage mount directories.\nRunning DPDK applications as a user in the DPDK group.\n-FreeBSD Section Updates:\nStreamlined content to specify adjusting permissions for:\nUserspace-io device files in /dev, such as /dev/uio0, /dev/uio1, etc.\nThe userspace contiguous memory device: /dev/contigmem.\n-Removed Sections: Detailed steps for creating user groups, binding NICs,\nand setting up hugepages were removed.\n-Overall Impact: The page now focuses more on the prerequisites for\nrunning DPDK applications without root privileges, specifically for Linux and FreeBSD,\nwith less emphasis on detailed procedural steps.\n\n-Added a reference tag `.. _vfio_platform:` at the start of the VFIO Platform section.\n-Inserted a reference tag `.. _bifurcated_driver:` at the beginning of the Bifurcated Driver section.\n-Appended a reference tag `.. _uio:` to the UIO section.\n---\n .../appendix/cross_compile_dpdk.rst | 37 +++\n .../appendix/dpdk_meson_build_options.rst | 57 ++++\n .../hugepages_different_architectures.rst | 56 ++++\n .../getting_started_guide/appendix/index.rst | 18 ++\n .../running_dpdk_apps_without_root.rst | 24 ++\n .../appendix/vfio_advanced.rst | 301 ++++++++++++++++++\n 6 files changed, 493 insertions(+)\n create mode 100644 doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst\n create mode 100644 doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst\n create mode 100644 doc/guides/getting_started_guide/appendix/hugepages_different_architectures.rst\n create mode 100644 doc/guides/getting_started_guide/appendix/index.rst\n create mode 100644 doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst\n create mode 100644 doc/guides/getting_started_guide/appendix/vfio_advanced.rst", "diff": "diff --git a/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst b/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst\nnew file mode 100644\nindex 0000000000..3e4efe23a4\n--- /dev/null\n+++ b/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst\n@@ -0,0 +1,37 @@\n+.. SPDX-License-Identifier: BSD-3-Clause\n+ Copyright(c) 2010-2025 Intel Corporation.\n+\n+.. _cross_compile_dpdk:\n+\n+Cross-compiling DPDK for Different Architectures on Linux\n+=========================================================\n+\n+Cross-compiling DPDK for different architectures follows a similar process. Here are the general steps:\n+\n+1. **Get Compiler and Libraries**: Obtain the cross-compiler toolchain and any required libraries specific to the target architecture.\n+\n+2. **Build Using Cross-File**: Use Meson to set up the build with a cross-file specific to the target architecture, and then build with Ninja.\n+\n+Prerequisites\n+-------------\n+\n+- NUMA Library (if required)\n+- Meson and Ninja\n+- pkg-config for the target architecture\n+- Specific GNU or LLVM/Clang toolchain for the target architecture\n+\n+Cross-Compiling DPDK\n+--------------------\n+\n+1. **Set Up the Cross Toolchain**: Download and extract the toolchain for the target architecture. Add it to the PATH.\n+\n+2. **Compile Any Required Libraries**: Compile libraries like NUMA if required.\n+\n+3. **Cross-Compile DPDK with Meson**:\n+\n+ .. code-block:: bash\n+\n+ meson setup cross-build --cross-file <target_machine_configuration>\n+ ninja -C cross-build\n+\n+Refer to the specific sections for ARM64, LoongArch, and RISC-V for detailed instructions and architecture-specific considerations.\n\\ No newline at end of file\ndiff --git a/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst b/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst\nnew file mode 100644\nindex 0000000000..6669f98371\n--- /dev/null\n+++ b/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst\n@@ -0,0 +1,57 @@\n+.. SPDX-License-Identifier: BSD-3-Clause\n+ Copyright(c) 2010-2025 Intel Corporation.\n+\n+.. _dpdk_meson_build_options:\n+\n+DPDK Meson Build Configuration Options\n+======================================\n+\n+DPDK provides a number of build configuration options that can be adjusted using the Meson build system. These options can be listed by running ``meson configure`` inside a configured build\n+folder.\n+\n+Changing the Build Type\n+-----------------------\n+\n+To change the build type from the default \"release\" to a regular \"debug\" build,\n+you can either:\n+\n+- Pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially.\n+- Run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run.\n+\n+Platform Options\n+----------------\n+\n+The \"platform\" option specifies a set of configuration parameters that will be used. \n+The valid values are:\n+\n+- ``-Dplatform=native`` will tailor the configuration to the build machine.\n+- ``-Dplatform=generic`` will use configuration that works on all machines of the same architecture as the build machine.\n+- ``-Dplatform=<SoC>`` will use configuration optimized for a particular SoC.\n+\n+Consult the \"socs\" dictionary in ``config/arm/meson.build`` to see which SoCs are supported.\n+\n+Overriding Platform Parameters\n+------------------------------\n+\n+The values determined by the platform parameter may be overwritten. For example,\n+to set the ``max_lcores`` value to 256, you can either:\n+\n+- Pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially.\n+- Run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run.\n+\n+Building Sample Applications\n+----------------------------\n+\n+Some of the DPDK sample applications in the examples directory can be automatically built as\n+part of a meson build. To do so, pass a comma-separated list of the examples to build to the\n+``-Dexamples`` meson option as below::\n+\n+ meson setup -Dexamples=l2fwd,l3fwd build\n+\n+There is also a special value \"all\" to request that all example applications whose dependencies\n+are met on the current system are built. When ``-Dexamples=all`` is set as a meson option,\n+meson will check each example application to see if it can be built, and add all which can be\n+built to the list of tasks in the ninja build configuration file.\n+\n+For a complete list of options, run ``meson configure`` inside your configured build\n+folder.\n\\ No newline at end of file\ndiff --git a/doc/guides/getting_started_guide/appendix/hugepages_different_architectures.rst b/doc/guides/getting_started_guide/appendix/hugepages_different_architectures.rst\nnew file mode 100644\nindex 0000000000..a93904fc49\n--- /dev/null\n+++ b/doc/guides/getting_started_guide/appendix/hugepages_different_architectures.rst\n@@ -0,0 +1,56 @@\n+.. SPDX-License-Identifier: BSD-3-Clause\n+ Copyright(c) 2010-2025 Intel Corporation.\n+\n+.. _hugepages_different_architectures:\n+\n+Hugepages Configuration for Multiple Architectures\n+==================================================\n+\n+This section outlines the steps for configuring hugepages of various sizes on different architectures, an important aspect for optimizing DPDK performance.\n+\n+Hugepages on x86 Architecture\n+-----------------------------\n+\n+**2MB and 1G Hugepages**\n+\n+- *2MB hugepages* are commonly used on x86.\n+- *1G hugepages* can improve performance for large-memory applications.\n+\n+**Configuring 1G Hugepages**\n+\n+.. code-block:: bash\n+\n+ # Example GRUB configuration for 1G hugepages\n+ GRUB_CMDLINE_LINUX=\"default_hugepagesz=1G hugepagesz=1G hugepages=4\"\n+\n+Update GRUB and reboot after making these changes.\n+\n+Hugepages on ARM Architecture\n+-----------------------------\n+\n+ARM supports a range of hugepage sizes, such as 64KB, 512KB, and 2MB.\n+\n+**Example Configuration**\n+\n+.. code-block:: bash\n+\n+ # Setting 2MB hugepages on ARM\n+ echo N > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages\n+\n+Replace 'N' with the number of pages needed.\n+\n+Other Architectures\n+-------------------\n+\n+Refer to architecture-specific documentation for hugepage configurations on platforms like PowerPC or MIPS.\n+\n+Boot-Time Reservation of Hugepages\n+----------------------------------\n+\n+Boot-time reservation is essential for large hugepage sizes. Modify the boot loader, such as GRUB, for this purpose:\n+\n+.. code-block:: bash\n+\n+ GRUB_CMDLINE_LINUX=\"hugepagesz=2M hugepages=512\"\n+\n+Regenerate the GRUB config and reboot your system.\ndiff --git a/doc/guides/getting_started_guide/appendix/index.rst b/doc/guides/getting_started_guide/appendix/index.rst\nnew file mode 100644\nindex 0000000000..b92e3afb5a\n--- /dev/null\n+++ b/doc/guides/getting_started_guide/appendix/index.rst\n@@ -0,0 +1,18 @@\n+.. SPDX-License-Identifier: BSD-3-Clause\n+ Copyright(c) 2010-2025 Intel Corporation.\n+\n+.. _appendix:\n+\n+Appendix\n+========\n+\n+This section covers specific guides related to DPDK.\n+\n+.. toctree::\n+ :maxdepth: 2\n+\n+ dpdk_meson_build_options\n+ hugepages_different_architectures\n+ running_dpdk_apps_without_root\n+ vfio_advanced\n+ cross_compile_dpdk\ndiff --git a/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst b/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst\nnew file mode 100644\nindex 0000000000..50cead324e\n--- /dev/null\n+++ b/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst\n@@ -0,0 +1,24 @@\n+.. _running_dpdk_apps_without_root:\n+\n+Running DPDK Applications Without Root Privileges\n+=================================================\n+\n+It's important to note that running DPDK as non-root on Linux requires IOMMU support through vfio.\n+\n+Linux\n+-----\n+To run DPDK applications without root privileges on Linux, follow these steps:\n+\n+1. **Adjust Permissions for Specific Files and Directories**:\n+\n+ - VFIO entries in ``/dev``, such as ``/dev/vfio/<id>``, where ``<id>`` is the VFIO group to which a device used by DPDK belongs.\n+ - The hugepage mount directory, typically ``/dev/hugepages``, or any alternative mount point configured by the user, e.g., ``/mnt/huge``, ``/mnt/huge_1G``.\n+\n+2. **Run the DPDK Application**: Execute the desired DPDK application as the user who has been added to the DPDK group.\n+\n+FreeBSD\n+-------\n+Adjust the permissions of the following files to run DPDK applications as a non-root user:\n+\n+- The userspace-io device files in ``/dev``, for example, ``/dev/uio0``, ``/dev/uio1``, and so on.\n+- The userspace contiguous memory device: ``/dev/contigmem``.\ndiff --git a/doc/guides/getting_started_guide/appendix/vfio_advanced.rst b/doc/guides/getting_started_guide/appendix/vfio_advanced.rst\nnew file mode 100644\nindex 0000000000..35d9e783bf\n--- /dev/null\n+++ b/doc/guides/getting_started_guide/appendix/vfio_advanced.rst\n@@ -0,0 +1,301 @@\n+.. SPDX-License-Identifier: BSD-3-Clause\n+ Copyright(c) 2010-2025 Intel Corporation.\n+\n+.. _vfio_advanced:\n+\n+.. |reg| unicode:: U+000AE\n+\n+VFIO Advanced\n+=============\n+\n+\n+.. contents:: Table of Contents\n+ :local:\n+\n+.. _vfio_no_iommu_mode:\n+\n+VFIO no-IOMMU mode\n+------------------\n+\n+If there is no IOMMU available on the system, VFIO can still be used,\n+but it has to be loaded with an additional module parameter:\n+\n+.. code-block:: console\n+\n+ modprobe vfio enable_unsafe_noiommu_mode=1\n+\n+Alternatively, one can also enable this option in an already loaded kernel module:\n+\n+.. code-block:: console\n+\n+ echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode\n+\n+After that, VFIO can be used with hardware devices as usual.\n+\n+.. note::\n+\n+ It may be required to unload all VFIO related-modules before probing\n+ the module again with ``enable_unsafe_noiommu_mode=1`` parameter.\n+\n+.. warning::\n+\n+ Since no-IOMMU mode forgoes IOMMU protection, it is inherently unsafe.\n+ That said, it does make it possible for the user\n+ to keep the degree of device access and programming that VFIO has,\n+ in situations where IOMMU is not available.\n+\n+VFIO Memory Mapping Limits\n+--------------------------\n+\n+For DMA mapping of either external memory or hugepages, VFIO interface is used.\n+VFIO does not support partial unmap of once mapped memory. Hence DPDK's memory is\n+mapped in hugepage granularity or system page granularity. Number of DMA\n+mappings is limited by kernel with user locked memory limit of a process (rlimit)\n+for system/hugepage memory. Another per-container overall limit applicable both\n+for external memory and system memory was added in kernel 5.1 defined by\n+VFIO module parameter ``dma_entry_limit`` with a default value of 64K.\n+When application is out of DMA entries, these limits need to be adjusted to\n+increase the allowed limit.\n+\n+Creating Virtual Functions using vfio-pci\n+-----------------------------------------\n+\n+Since Linux version 5.7,\n+the ``vfio-pci`` module supports the creation of virtual functions.\n+After the PF is bound to ``vfio-pci`` module,\n+the user can create the VFs using the ``sysfs`` interface,\n+and these VFs will be bound to ``vfio-pci`` module automatically.\n+\n+When the PF is bound to ``vfio-pci``,\n+by default it will have a randomly generated VF token.\n+For security reasons, this token is write only,\n+so the user cannot read it from the kernel directly.\n+To access the VFs, the user needs to create a new token,\n+and use it to initialize both VF and PF devices.\n+The tokens are in UUID format,\n+so any UUID generation tool can be used to create a new token.\n+\n+This VF token can be passed to DPDK by using EAL parameter ``--vfio-vf-token``.\n+The token will be used for all PF and VF ports within the application.\n+\n+#. Generate the VF token by uuid command\n+\n+ .. code-block:: console\n+\n+ 14d63f20-8445-11ea-8900-1f9ce7d5650d\n+\n+#. Load the ``vfio-pci`` module with ``enable_sriov`` parameter set\n+\n+ .. code-block:: console\n+\n+ sudo modprobe vfio-pci enable_sriov=1\n+\n+ Alternatively, pass the ``enable_sriov`` parameter through the ``sysfs`` if the module is already loaded or is built-in:\n+\n+ .. code-block:: console\n+\n+ echo 1 | sudo tee /sys/module/vfio_pci/parameters/enable_sriov\n+\n+#. Bind the PCI devices to ``vfio-pci`` driver\n+\n+ .. code-block:: console\n+\n+ ./usertools/dpdk-devbind.py -b vfio-pci 0000:86:00.0\n+\n+#. Create the desired number of VF devices\n+\n+ .. code-block:: console\n+\n+ echo 2 > /sys/bus/pci/devices/0000:86:00.0/sriov_numvfs\n+\n+#. Start the DPDK application that will manage the PF device\n+\n+ .. code-block:: console\n+\n+ <build_dir>/app/dpdk-testpmd -l 22-25 -n 4 -a 86:00.0 \\\n+ --vfio-vf-token=14d63f20-8445-11ea-8900-1f9ce7d5650d --file-prefix=pf -- -i\n+\n+#. Start the DPDK application that will manage the VF device\n+\n+ .. code-block:: console\n+\n+ <build_dir>/app/dpdk-testpmd -l 26-29 -n 4 -a 86:02.0 \\\n+ --vfio-vf-token=14d63f20-8445-11ea-8900-1f9ce7d5650d --file-prefix=vf0 -- -i\n+\n+.. note::\n+\n+ Linux versions earlier than version 5.7 do not support the creation of\n+ virtual functions within the VFIO framework.\n+\n+Troubleshooting VFIO\n+--------------------\n+\n+In certain situations, using ``dpdk-devbind.py`` script\n+to bind a device to VFIO driver may fail.\n+The first place to check is the kernel messages:\n+\n+.. code-block:: console\n+\n+ dmesg | tail\n+ ...\n+ [ 1297.875090] vfio-pci: probe of 0000:31:00.0 failed with error -22\n+ ...\n+\n+In most cases, the ``error -22`` indicates that the VFIO subsystem\n+could not be enabled because there is no IOMMU support.\n+\n+To check whether the kernel has been booted with correct parameters,\n+one can check the kernel command-line:\n+\n+.. code-block:: console\n+\n+ cat /proc/cmdline\n+\n+Please refer to earlier sections on how to configure kernel parameters\n+correctly for your system.\n+\n+If the kernel is configured correctly, one also has to make sure that\n+the BIOS configuration has virtualization features (such as Intel\\ |reg| VT-d).\n+There is no standard way to check if the platform is configured correctly,\n+so please check with your platform documentation to see if it has such features,\n+and how to enable them.\n+\n+In certain distributions, default kernel configuration is such that\n+the no-IOMMU mode is disabled altogether at compile time.\n+This can be checked in the boot configuration of your system:\n+\n+.. code-block:: console\n+\n+ cat /boot/config-$(uname -r) | grep NOIOMMU\n+ # CONFIG_VFIO_NOIOMMU is not set\n+\n+If ``CONFIG_VFIO_NOIOMMU`` is not enabled in the kernel configuration,\n+VFIO driver will not support the no-IOMMU mode,\n+and other alternatives (such as UIO drivers) will have to be used.\n+\n+.. _vfio_platform:\n+\n+VFIO Platform\n+-------------\n+\n+VFIO Platform is a kernel driver that extends capabilities of VFIO\n+by adding support for platform devices that reside behind an IOMMU.\n+Linux usually learns about platform devices directly from device tree\n+during boot-up phase,\n+unlike for example, PCI devices which have necessary information built-in.\n+\n+To make use of VFIO platform, the ``vfio-platform`` module must be loaded first:\n+\n+.. code-block:: console\n+\n+ sudo modprobe vfio-platform\n+\n+.. note::\n+\n+ By default ``vfio-platform`` assumes that platform device has dedicated reset driver.\n+ If such driver is missing or device does not require one,\n+ this option can be turned off by setting ``reset_required=0`` module parameter.\n+\n+Afterwards platform device needs to be bound to ``vfio-platform``.\n+This is standard procedure requiring two steps.\n+First ``driver_override``, which is available inside platform device directory,\n+needs to be set to ``vfio-platform``:\n+\n+.. code-block:: console\n+\n+ sudo echo vfio-platform > /sys/bus/platform/devices/DEV/driver_override\n+\n+Next ``DEV`` device must be bound to ``vfio-platform`` driver:\n+\n+.. code-block:: console\n+\n+ sudo echo DEV > /sys/bus/platform/drivers/vfio-platform/bind\n+\n+On application startup, DPDK platform bus driver scans ``/sys/bus/platform/devices``\n+searching for devices that have ``driver`` symbolic link\n+pointing to ``vfio-platform`` driver.\n+Finally, scanned devices are matched against available PMDs.\n+Matching is successful if either PMD name or PMD alias matches kernel driver name\n+or PMD name matches platform device name, all in that order.\n+\n+VFIO Platform depends on ARM/ARM64 and is usually enabled on distributions\n+running on these systems.\n+Consult your distributions documentation to make sure that is the case.\n+\n+.. _bifurcated_driver:\n+\n+Bifurcated Driver\n+-----------------\n+\n+PMDs which use the bifurcated driver co-exists with the device kernel driver.\n+On such model the NIC is controlled by the kernel, while the data\n+path is performed by the PMD directly on top of the device.\n+\n+Such model has the following benefits:\n+\n+ - It is secure and robust, as the memory management and isolation\n+ is done by the kernel.\n+ - It enables the user to use legacy linux tools such as ``ethtool`` or\n+ ``ifconfig`` while running DPDK application on the same network ports.\n+ - It enables the DPDK application to filter only part of the traffic,\n+ while the rest will be directed and handled by the kernel driver.\n+ The flow bifurcation is performed by the NIC hardware.\n+ As an example, using :ref:`flow_isolated_mode` allows to choose\n+ strictly what is received in DPDK.\n+\n+More about the bifurcated driver can be found in\n+NVIDIA `bifurcated PMD\n+<https://www.dpdk.org/wp-content/uploads/sites/35/2016/10/Day02-Session04-RonyEfraim-Userspace2016.pdf>`_ presentation.\n+\n+.. _uio:\n+\n+UIO\n+---\n+\n+.. warning::\n+\n+ Using UIO drivers is inherently unsafe due to this method lacking IOMMU protection,\n+ and can only be done by root user.\n+\n+In situations where using VFIO is not an option, there are alternative drivers one can\n+use.\n+In many cases, the standard ``uio_pci_generic`` module included in the Linux kernel\n+can be used as a substitute for VFIO. This module can be loaded using the command:\n+\n+.. code-block:: console\n+\n+ sudo modprobe uio_pci_generic\n+\n+.. note::\n+\n+ ``uio_pci_generic`` module doesn't support the creation of virtual functions.\n+\n+As an alternative to the ``uio_pci_generic``, there is the ``igb_uio`` module\n+which can be found in the repository `dpdk-kmods <http://git.dpdk.org/dpdk-kmods>`_.\n+It can be loaded as shown below:\n+\n+.. code-block:: console\n+\n+ sudo modprobe uio\n+ sudo insmod igb_uio.ko\n+\n+.. note::\n+\n+ For some devices which lack support for legacy interrupts, e.g. virtual function\n+ (VF) devices, the ``igb_uio`` module may be needed in place of ``uio_pci_generic``.\n+\n+.. note::\n+\n+ If UEFI secure boot is enabled,\n+ the Linux kernel may disallow the use of UIO on the system.\n+ Therefore, devices for use by DPDK should be bound to the ``vfio-pci`` kernel module\n+ rather than any UIO-based module.\n+ For more details see :ref:`linux_gsg_binding_kernel` below.\n+\n+.. note::\n+\n+ If the devices used for DPDK are bound to a UIO-based kernel module,\n+ please make sure that the IOMMU is disabled or is in passthrough mode.\n+ One can add ``intel_iommu=off`` or ``amd_iommu=off`` or ``intel_iommu=on iommu=pt``\n+ in GRUB command line on x86_64 systems,\n+ or add ``iommu.passthrough=1`` on aarch64 systems.\n", "prefixes": [ "v4", "5/6" ] }