Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/133803/?format=api
{ "id": 133803, "url": "https://patches.dpdk.org/api/patches/133803/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/patch/20231103040202.2849-6-dave@youngcopy.com/", "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": "<20231103040202.2849-6-dave@youngcopy.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20231103040202.2849-6-dave@youngcopy.com", "date": "2023-11-03T04:01:51", "name": "[v3,5/7] Section 5: Appendix", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "f471e12fa16bddc78d88eed1f4da7f6653b038e2", "submitter": { "id": 3122, "url": "https://patches.dpdk.org/api/people/3122/?format=api", "name": "Dave Young", "email": "dave@youngcopy.com" }, "delegate": { "id": 1, "url": "https://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "https://patches.dpdk.org/project/dpdk/patch/20231103040202.2849-6-dave@youngcopy.com/mbox/", "series": [ { "id": 30128, "url": "https://patches.dpdk.org/api/series/30128/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/list/?series=30128", "date": "2023-11-03T04:01:46", "name": "docs: getting started guide consolidation", "version": 3, "mbox": "https://patches.dpdk.org/series/30128/mbox/" } ], "comments": "https://patches.dpdk.org/api/patches/133803/comments/", "check": "warning", "checks": "https://patches.dpdk.org/api/patches/133803/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 6926C43274;\n\tFri, 3 Nov 2023 05:03:00 +0100 (CET)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 625B842DC3;\n\tFri, 3 Nov 2023 05:02:28 +0100 (CET)", "from mail-yb1-f176.google.com (mail-yb1-f176.google.com\n [209.85.219.176])\n by mails.dpdk.org (Postfix) with ESMTP id 25A4640265\n for <dev@dpdk.org>; Fri, 3 Nov 2023 05:02:25 +0100 (CET)", "by mail-yb1-f176.google.com with SMTP id\n 3f1490d57ef6-da34f90f6e3so417998276.0\n for <dev@dpdk.org>; Thu, 02 Nov 2023 21:02:25 -0700 (PDT)", "from localhost.localdomain\n ([2600:1700:20c0:a560:c076:581e:323d:c06e])\n by smtp.gmail.com with ESMTPSA id\n x64-20020a817c43000000b0059b1f6d1959sm493958ywc.101.2023.11.02.21.02.23\n (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n Thu, 02 Nov 2023 21:02:23 -0700 (PDT)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1698984144;\n x=1699588944;\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=g5ZtCG/8bPQDFKgDw4WTwkpSDegAxVEqQCkogrr0iZM=;\n b=hP2mlnHMzYOLwlmjuTAafhxs7IMf9obw1S6qAmbN/cSnuqdlNzL5VuCwj2vt/oz0Ac\n Lp0cF4oVED3zzz6/0p+VDwC6pA+dNINo0qnXUoHK0H/YsklqDq+NW40DWjMOqZDNtFH4\n oX88yaxuCAUgkwFJV2OWz8nqMaNXBoJ63a0X5Qw8dih5uDdc9z0W5C4wx0zNuDHTxz1F\n NVzKfm0VBEUocucAvBXVkf1aLIg9t+cJBzTD8gXBmmKayyVj74hfT3iOSRfAeRde43PT\n ywfMCHIgG9sS6MQ5LVk02YcUZxo11XUrC71iJAD4lIZSWZEEBXu/m646lGhtSRJAY25I\n 16Kw==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20230601; t=1698984144; x=1699588944;\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=g5ZtCG/8bPQDFKgDw4WTwkpSDegAxVEqQCkogrr0iZM=;\n b=G/5t3AokV4YN3FkdakZYA+nJuQddP5gQTMwzzqyw4V1mhO89Ie0q59W5yhlLgNGxTO\n fafcS3odHWzuQc9JZws7gIwAQbp5qB/wiI5857B2ywosBE5PJIAABAa32gwq8G22cpt1\n DWO21bWJhvu1j33cW/wGWfFaZ4AMdqjIDo3AloFxhNnsC8LRuMIxVFsn2d2YtQevuY4o\n HOh2YhifQ2f8KsAwd6JOKSoUpQkOJ5PMGMk5zXv6XcWtUbv5peADiQqlkqWRgi9BFLVQ\n 0aBeM1d0njw8lLT8n9zkQovOck3yvuoJP3eTi288//3R4+KJBkOKrDzSnDSWk8qxmr5K\n 15jA==", "X-Gm-Message-State": "AOJu0YyTU0TFzcYbSeSwXGvN2AKMIB2UmcHKeAF34mITcui16EBEUBwY\n FVRJE5qIoRJPrXHbuIl1kNWozJxyVLebBTUUJnU=", "X-Google-Smtp-Source": "\n AGHT+IHcuo4AkNzKssegQI//Z1tOT3ACZi9hN96eBUL/j3/VdVxBz8vyCVXXrbMrFJ+HC64jOm7Rcg==", "X-Received": "by 2002:a05:690c:4803:b0:5b3:1c41:733f with SMTP id\n hc3-20020a05690c480300b005b31c41733fmr10237007ywb.5.1698984143873;\n Thu, 02 Nov 2023 21:02:23 -0700 (PDT)", "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 v3 5/7] Section 5: Appendix", "Date": "Fri, 3 Nov 2023 00:01:51 -0400", "Message-ID": "<20231103040202.2849-6-dave@youngcopy.com>", "X-Mailer": "git-send-email 2.41.0.windows.1", "In-Reply-To": "<20231103040202.2849-1-dave@youngcopy.com>", "References": "<20231103040202.2849-1-dave@youngcopy.com>", "MIME-Version": "1.0", "Content-Type": "text/plain; charset=y", "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": "---\n .../appendix/cross_compile_dpdk.rst | 37 +++\n .../appendix/dpdk_meson_build_options.rst | 57 ++++\n .../getting_started_guide/appendix/index.rst | 17 +\n .../running_dpdk_apps_without_root.rst | 36 +++\n .../appendix/vfio_advanced.rst | 295 ++++++++++++++++++\n 5 files changed, 442 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/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/index.rst b/doc/guides/getting_started_guide/appendix/index.rst\nnew file mode 100644\nindex 0000000000..23bb1fcf78\n--- /dev/null\n+++ b/doc/guides/getting_started_guide/appendix/index.rst\n@@ -0,0 +1,17 @@\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+ running_dpdk_apps_without_root\n+ vfio_advanced\n+ cross_compile_dpdk\n\\ No newline at end of file\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..9f214bbdc8\n--- /dev/null\n+++ b/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst\n@@ -0,0 +1,36 @@\n+.. SPDX-License-Identifier: BSD-3-Clause\n+ Copyright(c) 2010-2025 Intel Corporation.\n+\n+.. _running_dpdk_apps_without_root:\n+\n+Running DPDK Applications Without Root Privileges\n+=================================================\n+\n+Although applications using the DPDK use network ports and other hardware resources\n+directly, with a number of small permission adjustments, \n+it is possible to run these applications as a user other than “root”. \n+To do so, the ownership, or permissions, on the following file system objects should be\n+adjusted so the user account being used to run the DPDK application has\n+access to them:\n+\n+Linux\n+-----\n+\n+1. **Create a DPDK User Group**: Create a new user group for DPDK and add the desired user to this group.\n+\n+2. **Set Up Hugepages**: Configure hugepages for the user.\n+\n+3. **Bind the NIC to a User-Space Driver**: Use the DPDK tool ``dpdk-devbind.py`` to bind the NIC to a user-space driver like ``vfio-pci`` or ``igb_uio``.\n+\n+4. **Set Permissions for UIO/VFIO Devices**: Change the ownership and permissions of the UIO or VFIO devices to allow access by the DPDK user group.\n+\n+5. **Run the DPDK Application**: Run the desired DPDK application as the user who has been added to the DPDK group.\n+\n+FreeBSD\n+-------\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``\n+\n+\n+Refer to the `DPDK Release Notes <https://doc.dpdk.org/guides/rel_notes/index.html>`_ for supported applications.\n\\ No newline at end of file\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..1cdb138eb7\n--- /dev/null\n+++ b/doc/guides/getting_started_guide/appendix/vfio_advanced.rst\n@@ -0,0 +1,295 @@\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+\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+\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+\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\\ No newline at end of file\n", "prefixes": [ "v3", "5/7" ] }