From patchwork Thu Nov 23 01:26:22 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 134542 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: 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]) by inbox.dpdk.org (Postfix) with ESMTP id E4DD34339F; Thu, 23 Nov 2023 02:27:00 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A2F9B42D55; Thu, 23 Nov 2023 02:27:00 +0100 (CET) Received: from mail-oi1-f173.google.com (mail-oi1-f173.google.com [209.85.167.173]) by mails.dpdk.org (Postfix) with ESMTP id 0162342D55 for ; Thu, 23 Nov 2023 02:26:56 +0100 (CET) Received: by mail-oi1-f173.google.com with SMTP id 5614622812f47-3b83d69c7c9so66097b6e.0 for ; Wed, 22 Nov 2023 17:26:56 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1700702815; x=1701307615; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=6U37Fuwa62g4bJCEmPfVtDjzlWmL3D7/b4zYt/7bxQQ=; b=tjjzjv0/unnUSgQumbpgn9lB5vpU0nkwf9P8KF+wJRNhDCVc3FoPYFQl+3PlQl5VBi p76DZnYfA83P9xSDZJooWUL7DGegeAVia0X4LVWNC33KUUwPkCrs82n+/XYHoqXhnEZ4 4J/+RNBgvJRrN+pobn69K1dTHiF2c3wMJqGRxLmE6lkGRpw6wFN9HHo9VA0Jwcshfu8L f7JIoqeAMWEKaSQ6UdNiHjfFSZwx/pRgc2e2DRqqoi+QWlWWiwvOsbp0JW05YnRoGg7i EdnS+aUzvQc32U/6VbsNL+G8pxAvg54LjZ75vMzCphwowOqD4JdDMxQMANEcNdMZwvLa FSog== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700702815; x=1701307615; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=6U37Fuwa62g4bJCEmPfVtDjzlWmL3D7/b4zYt/7bxQQ=; b=l9N1XnCF4t5zm9ufAPNlpW+5QxkAoZ8UMm+enOu9ZHu6QgybJdCmUn4e8DfnaVsY5Z Phm8Srj6WvRPhoRIjqvp2hvY3Dy2Kp6Fep34squ95oOwUpI807CTUur0tFdfpuFi1cEm hY5xsfCVM3mvvZMUC851bi/ygy6UusqtW8o1heKxl7gB+Iww8JosD6+5bQ2pRx4zTF+B +hvSFLbp6iDqZjVIod4nK/BrSIgMvk4dPDO/DSD7+n/uKjWZ3Iv2Fs5ty6ZVE5QE1D9M yVTYR+82UcSAWzHH20eHyKZwaZMJfisrVd8zDxLc0EeIl9HyMw9+yC/BuuEeHZIZDCy1 YgOA== X-Gm-Message-State: AOJu0YwWS8DKVTjuNl6cIoYL4eBN8jK1iJ/ExiMG3ymwXfmYsxd7KXuZ 0tj2lXN89sh3Oz+q0kr3MfC6dDb3hh0JNINl/Jk= X-Google-Smtp-Source: AGHT+IG2iVoJzkn0BTQ+GtgMRNQzos+Pq0jKQXtCFQbUoEkZ7IZ1IzXIZCZlyIJ2fUDKrr5V9A/QrA== X-Received: by 2002:a05:6358:338b:b0:16b:96fc:650e with SMTP id i11-20020a056358338b00b0016b96fc650emr5004947rwd.3.1700702815136; Wed, 22 Nov 2023 17:26:55 -0800 (PST) Received: from localhost.localdomain ([2600:1700:20c0:a560:40f7:d2c:d53a:d071]) by smtp.gmail.com with ESMTPSA id j184-20020a0dc7c1000000b005a815346d95sm89832ywd.71.2023.11.22.17.26.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 22 Nov 2023 17:26:53 -0800 (PST) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young Subject: [PATCH v4 1/6] Section 1: Introduction Date: Wed, 22 Nov 2023 20:26:22 -0500 Message-ID: <20231123012633.2005-2-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> <20231123012633.2005-1-dave@youngcopy.com> MIME-Version: 1.0 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Added link to Getting Started Guide in index.rst Moved run_apps.rst to GSG index Removed run_apps/index.rst - no longer needed Added run_apps.rst to index -Reformatted the introduction paragraph for better readability. -Clarified that the guide provides basic step-by-step instructions with OS-specific instructions included only where necessary for each operating system. -Emphasized that by the end of this guide, the user should have a solid understanding of how to implement and use DPDK in their networking projects, regardless of the operating system they are using. Moved run_apps into GSG root directory --- doc/guides/getting_started_guide/index.rst | 18 +++ doc/guides/getting_started_guide/intro.rst | 13 ++ doc/guides/getting_started_guide/run_apps.rst | 114 ++++++++++++++++++ doc/guides/index.rst | 1 + 4 files changed, 146 insertions(+) create mode 100644 doc/guides/getting_started_guide/index.rst create mode 100644 doc/guides/getting_started_guide/intro.rst create mode 100644 doc/guides/getting_started_guide/run_apps.rst diff --git a/doc/guides/getting_started_guide/index.rst b/doc/guides/getting_started_guide/index.rst new file mode 100644 index 0000000000..3d7c0eb6ee --- /dev/null +++ b/doc/guides/getting_started_guide/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _getting_started_guide: + +Getting Started Guide +===================== + +.. toctree:: + :maxdepth: 2 + :numbered: + + intro + install_and_build/index + system_setup + run_apps + appendix/index + glossary diff --git a/doc/guides/getting_started_guide/intro.rst b/doc/guides/getting_started_guide/intro.rst new file mode 100644 index 0000000000..3560d705d0 --- /dev/null +++ b/doc/guides/getting_started_guide/intro.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. + +Introduction +============ + +Welcome to the getting started guide for the Data Plane Development Kit (DPDK) covering Linux, +FreeBSD, and Windows. DPDK is a set of libraries and drivers that accelerate packet processing +and allow the user to create high-performance networking applications. + +The guide is structured to provide basic step-by-step instructions with OS-specific instructions included only where necessary for each operating system. +By the end of this guide, you should have a solid understanding of how to implement +and use DPDK in your networking projects, regardless of the operating system you are using. diff --git a/doc/guides/getting_started_guide/run_apps.rst b/doc/guides/getting_started_guide/run_apps.rst new file mode 100644 index 0000000000..d9ef1a6f96 --- /dev/null +++ b/doc/guides/getting_started_guide/run_apps.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _run_apps: + +Running Applications +==================== + +Running Applications on Linux and FreeBSD +----------------------------------------- + +Compiling and Running Sample Applications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To compile a sample application: + +1. Navigate to the application's directory in the DPDK distribution. +2. Execute the ``make`` command on Linux or ``gmake`` on FreeBSD. + +For instance, to compile the ``helloworld`` application: + +:: + + cd examples/helloworld + make # On Linux + gmake # On FreeBSD + +.. note:: + If DPDK is not installed system-wide, + you can compile the examples as part of the DPDK build itself. + If DPDK is not installed system-wide, you can compile the examples as part of the DPDK build + itself. Use the meson build option ``-Dexamples=helloworld`` to compile specific examples + or ``-Dexamples=all`` to compile all examples. + +To run the application, use: + +:: + + ./build/helloworld -l 0-2 + +The ``-l`` option indicates the cores on which the application should run. +This command runs the `helloworld` application on cores 0, 1, and 2. + +Sample Applications Overview +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For a comprehensive list of sample applications and their guides, +refer to the `DPDK Sample Applications User Guides `_. + +EAL Parameters +-------------- + +Every DPDK application is linked with the DPDK target environment’s +Environmental Abstraction Layer (EAL) library. The most essential EAL option is ``-l CORELIST``, which specifies the cores the application should run on. For example: + +- ``-l 1-3`` to run on 3 cores: 1, 2, and 3. +- ``-l 8,16`` to run on 2 cores: 8 and 16. +- ``-l 1-7,9-15`` to run on 14 cores: 1 through 7 and 9 through 15. + +Please refer to the `EAL parameters section ` section for a more comprehensive list of options. + +Running Without Root Privileges +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Refer to :ref:`running_dpdk_apps_without_root`. + +Running Applications on Windows +------------------------------- + +Running DPDK applications on Windows involves a few different steps. +This guide provides detailed instructions on how to run the helloworld example +application, which can be used as a reference for running other DPDK applications. + +Grant Lock Pages in Memory Privilege +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use of hugepages ("large pages" in Windows terminology) requires +``SeLockMemoryPrivilege`` for the user running an application. +This privilege allows the DPDK application to keep data in physical memory, +preventing the system from paging the data to virtual memory. +This can significantly improve the performance of your DPDK applications. + +To grant this privilege: + +1. Open Local Security Policy snap-in, either through Control Panel / Computer Management / Local Security Policy, or by pressing Win+R, typing ``secpol``, and pressing Enter. +2. Open Local Policies / User Rights Assignment / Lock pages in memory. +3. Add desired users or groups to the list of grantees. + +The privilege is applied upon the next logon. If the privilege has been granted to the +current user, a logoff is required before it is available. +More details can be found in the `Large-Page Support in MSDN `_. + +Running the helloworld Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After setting up the drivers, you can run the helloworld example to verify your setup. +Here are the steps: + +1. Navigate to the examples in the build directory:: + + cd C:\\Users\\me\\dpdk\\build\\examples + +2. Run the helloworld application:: + + dpdk-helloworld.exe -l 0-3 + +The output should display a hello message from each core, like this: + +:: + + hello from core 1 + hello from core 3 + hello from core 0 + hello from core 2 diff --git a/doc/guides/index.rst b/doc/guides/index.rst index 244b99624c..51a47d3a51 100644 --- a/doc/guides/index.rst +++ b/doc/guides/index.rst @@ -7,6 +7,7 @@ DPDK documentation .. toctree:: :maxdepth: 1 + getting_started_guide/index linux_gsg/index freebsd_gsg/index windows_gsg/index From patchwork Thu Nov 23 01:26:23 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 134543 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: 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]) by inbox.dpdk.org (Postfix) with ESMTP id 9A7984339F; Thu, 23 Nov 2023 02:27:07 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A4A7542D78; Thu, 23 Nov 2023 02:27:01 +0100 (CET) Received: from mail-yw1-f180.google.com (mail-yw1-f180.google.com [209.85.128.180]) by mails.dpdk.org (Postfix) with ESMTP id 8A8AD42D55 for ; Thu, 23 Nov 2023 02:26:57 +0100 (CET) Received: by mail-yw1-f180.google.com with SMTP id 00721157ae682-5bbfc735572so758887b3.0 for ; Wed, 22 Nov 2023 17:26:57 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1700702816; x=1701307616; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=C1UUsNdXPdQgjdfOSf0ecgxqsoOeMVfdZrRmWPA7nkw=; b=PH1EGJzmBgKk69aczNvjNgB9L80kD5vwqDRCzQBGWbDcWgSmpPR2w2zF3kATxcvajh gR89GtfjiglXWgwREBVWpa6d+yVkBbYTGAE1yCXzlTp3ncN9Nff6WHIUr+UZ7VZ5HRoK PyUzTPitHxVTuWApNY4w+NXKKuC4wlcqEmarNdUyxh9umuX+ex6MuOUrgLQf3VH1B2NC tl4tF60Jk4p2T5YiS/LEMxQ2/mo1Zt2mYCY5z+zqW4q4pecQ5/2hT0Wb3nBEYh5F7nhC cvJHSVi/ba3K648/DJpIW3Gdr6/djL1TdpYCHKUXgXHyaBHzBRNrR1TOMyRDUeazUqi2 6uPw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700702816; x=1701307616; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=C1UUsNdXPdQgjdfOSf0ecgxqsoOeMVfdZrRmWPA7nkw=; b=cGntWECgU7KUvzEIxM/0TtIx09sEGG13hL+foNuZZNe2CfGqxGUJvR3sbeeo++IOOh BJsJtAxo5XJVvIsskHsjzjC4NZqiltcRh8K3i+XqXAfQ1h05s4ZjNxwf7Pn0MHvajrez pixilMiJOUQFlwVXTawGnawCyD4Cs81THJNJv7s7GvtUGebRkcRjD48fHUO8SDXQ1gI+ UseZOKP2q17U88etdIv0RyFV4Ydnjx5uIkO25G8/vVjvHgZCcX09gMEsRxaw6QgNe+rP zaYXvmtreQPuuX/r83+KBC893IU4S5BcQBgFZ5AgdahiMPGvCa/5WrmF0w/frTIiMOj7 /fAw== X-Gm-Message-State: AOJu0YwutXRJ3IGgA1UPPVK66K9yTicbXykZ6K1/TLvXQ0/UsoKDt4r5 LzQtW3i/ZjbGO5ML4I2AbT4BrJ83lAhynTbhM50= X-Google-Smtp-Source: AGHT+IHut0VVWriLBZnfWEJ0HkDluNfqasmJvU8BfKQj54axnPXuwtSjxP2WHyfliMXYp94YFdsa0w== X-Received: by 2002:a05:690c:2c06:b0:5cc:382c:bc78 with SMTP id eo6-20020a05690c2c0600b005cc382cbc78mr2789712ywb.2.1700702815954; Wed, 22 Nov 2023 17:26:55 -0800 (PST) Received: from localhost.localdomain ([2600:1700:20c0:a560:40f7:d2c:d53a:d071]) by smtp.gmail.com with ESMTPSA id j184-20020a0dc7c1000000b005a815346d95sm89832ywd.71.2023.11.22.17.26.55 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 22 Nov 2023 17:26:55 -0800 (PST) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young Subject: [PATCH v4 2/6] Section 2: Install and Build DPDK Date: Wed, 22 Nov 2023 20:26:23 -0500 Message-ID: <20231123012633.2005-3-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> <20231123012633.2005-1-dave@youngcopy.com> MIME-Version: 1.0 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org -Common Tools for All Distributions: The common tools installation instructions for all Linux distributions and FreeBSD have been removed. Instead, the tools are now listed under each specific distribution. -Linux Distributions: The Linux distributions have been restructured to include Alpine, Debian, Ubuntu, Fedora, RedHat Enterprise Linux (RHEL), and openSUSE. Each distribution now has its own section with specific installation commands. -Windows: The Windows section remains largely unchanged, but the instructions for navigating to the directory where the DPDK source code is located have been updated. -Building DPDK: The commands for setting up and compiling with the Meson build system have been updated for both Linux, FreeBSD, and Windows. -Cross-Compilation Instructions: The cross-compilation instructions for different architectures were left unchanged. -Formatting Changes: There are several formatting changes throughout the document, including the addition of notes and changes to the headers for better readability and organization. --- .../building_from_sources.rst | 180 ++++++++++++++++++ .../install_and_build/index.rst | 14 ++ .../installing_prebuilt_packages.rst | 54 ++++++ 3 files changed, 248 insertions(+) create mode 100644 doc/guides/getting_started_guide/install_and_build/building_from_sources.rst create mode 100644 doc/guides/getting_started_guide/install_and_build/index.rst create mode 100644 doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst diff --git a/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst new file mode 100644 index 0000000000..ab54521ac5 --- /dev/null +++ b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst @@ -0,0 +1,180 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _building_from_sources: + +Building and Installing DPDK from Sources +========================================= + +This chapter provides a comprehensive guide for building DPDK from sources. +It covers the necessary steps, prerequisites, and considerations for different architectures and compilers. + +Required Tools +-------------- + +To build DPDK, you'll need the following tools: + +- A C compiler like ``gcc`` (version 5+) or ``clang`` (version 3.6+) +- ``pkg-config`` or ``pkgconf`` +- Python 3.6 or later +- ``meson`` (version 0.57.0) and ``ninja`` +- ``pyelftools`` (version 0.22+) + +Platform-Specific Tool Installation +----------------------------------- + +Linux +^^^^^ + +Alpine +"""""" + +.. code-block:: bash + + sudo apk add alpine-sdk bsd-compat-headers gcc pkg-config python3 meson ninja pyelftools numactl-dev + +Debian, Ubuntu, and derivatives +""""""""""""""""""""""""""""""" + +.. code-block:: bash + + sudo apt install build-essential gcc pkg-config python3 meson ninja pyelftools libnuma-dev + +Fedora and RedHat Enterprise Linux (RHEL) +""""""""""""""""""""""""""""""""""""""""" + +.. code-block:: bash + + sudo dnf groupinstall "Development Tools" + sudo dnf install gcc pkg-config python3 meson ninja python3-pyelftools numactl-devel + +openSUSE +"""""""" + +.. code-block:: bash + + sudo zypper install -t pattern devel_basis + sudo zypper install gcc pkg-config python3 meson ninja python3-pyelftools libnuma-devel + +FreeBSD +^^^^^^^ + +.. code-block:: bash + + pkg install pkgconf python3 meson ninja pyelftools + +.. note:: + + If you're using FreeBSD, make sure kernel sources are included during the FreeBSD installation. + +Windows System Requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Building the DPDK and its applications on Windows requires one of the following +environments: + +- The Clang-LLVM C compiler and Microsoft MSVC linker. +- The MinGW-w64 toolchain (either native or cross). + +The Meson Build system is used to prepare the sources for compilation with the Ninja backend. + +.. _clang_llvm: + +Option 1: Clang-LLVM C Compiler and Microsoft MSVC Linker +""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +1. Install the Compiler: Download and install the Clang compiler from the + `LLVM website `_. + +2. Install the Linker: Download and install the Build Tools for Visual Studio from the + `Microsoft website `_. + When installing build tools, select the “Visual C++ build tools” option and make sure + the Windows SDK is selected. + +.. _mingw_w64_toolchain: + +Option 2: MinGW-w64 Toolchain +"""""""""""""""""""""""""""""" + +1. On Linux (for cross-compilation): Install MinGW-w64 via a package manager. + Version 4.0.4 for Ubuntu 16.04 cannot be used due to a MinGW-w64 bug. + +2. On Windows: Obtain the latest version installer from the + `MinGW-w64 repository `_. + Any thread model (POSIX or Win32) can be chosen, DPDK does not rely on it. + Install to a folder without spaces in its name, like ``C:\MinGW``. + This path is assumed for the rest of this guide. + +Install the Build System +^^^^^^^^^^^^^^^^^^^^^^^^ + +Download and install the build system from the +`Meson website `_. +A good option to choose is the MSI installer for both meson and ninja together. +Required version is Meson 0.57.x (baseline). + +Getting the DPDK Source +----------------------- + +Linux and FreeBSD +^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + wget https://fast.dpdk.org/rel/dpdk-20.11.tar.xz + tar -xJf dpdk-20.11.tar.xz + cd dpdk-20.11 + +Windows +^^^^^^^ + +Download the DPDK source code from `DPDK's official website `_ or clone the repository using a Git client. Extract the downloaded archive, if applicable, and navigate to the DPDK directory. + +Navigate to the directory where the DPDK source code is located: + +.. code-block:: bash + + cd C:\path\to\dpdk-20.11 + +Building DPDK +------------- + +.. note:: + + In all examples below, "build" is used as the name of the build directory. It is not part of the command itself. + +Linux and FreeBSD +^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + meson setup build + meson compile -C build + +Windows +^^^^^^^ + +**Option 1: Using Clang-LLVM** + +.. code-block:: bash + + set CC=clang + meson setup -Dexamples=helloworld build + meson compile -C build + +**Option 2: Using MinGW-w64** + +.. code-block:: bash + + set PATH=C:\MinGW\mingw64\bin;%PATH% + meson setup -Dexamples=helloworld build + meson compile -C build + +.. note:: + + For detailed information on Meson build configuration options specific to DPDK, see :ref:`DPDK Meson Build Configuration Options `. + +Cross-Compilation Instructions for Different Architectures +---------------------------------------------------------- + +For instructions on building DPDK for ARM64, LoongArch, and RISC-V, refer to :ref:`cross_compile_dpdk`. diff --git a/doc/guides/getting_started_guide/install_and_build/index.rst b/doc/guides/getting_started_guide/install_and_build/index.rst new file mode 100644 index 0000000000..48e438282f --- /dev/null +++ b/doc/guides/getting_started_guide/install_and_build/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _install_and_build: + +Install and Build DPDK +====================== + +.. toctree:: + :maxdepth: 2 + + + installing_prebuilt_packages + building_from_sources \ No newline at end of file diff --git a/doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst b/doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst new file mode 100644 index 0000000000..3e395d65f1 --- /dev/null +++ b/doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _installing_prebuilt_packages: + +Installing Pre-built Packages +============================= + +Pre-built packages provide a convenient way to install DPDK without the need to compile +the source code manually. These packages are created and maintained by the DPDK +community or OS vendors and are available for various operating systems and +distributions. + +Available Distributions +----------------------- + +Linux +^^^^^ + +Pre-built DPDK packages are available for several popular Linux distributions, +including but not limited to: + +Alpine + +.. code-block:: bash + + sudo apk add dpdk + +Debian and Ubuntu and derivatives + +.. code-block:: bash + + sudo apt-get install dpdk + +Fedora and RedHat Enterprise Linux RHEL + +.. code-block:: bash + + sudo dnf install dpdk + +openSUSE + +.. code-block:: bash + + sudo zypper install dpdk + +FreeBSD +^^^^^^^ + +To install DPDK on FreeBSD, use the following command: + +.. code-block:: bash + + sudo pkg install dpdk \ No newline at end of file From patchwork Thu Nov 23 01:26:24 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 134544 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: 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]) by inbox.dpdk.org (Postfix) with ESMTP id 31F1C4339F; Thu, 23 Nov 2023 02:27:15 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id C8A1442D83; Thu, 23 Nov 2023 02:27:02 +0100 (CET) Received: from mail-yw1-f171.google.com (mail-yw1-f171.google.com [209.85.128.171]) by mails.dpdk.org (Postfix) with ESMTP id 1B80242D55 for ; Thu, 23 Nov 2023 02:26:59 +0100 (CET) Received: by mail-yw1-f171.google.com with SMTP id 00721157ae682-5bbfc735572so758937b3.0 for ; Wed, 22 Nov 2023 17:26:59 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1700702818; x=1701307618; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=t6Ejlq5Ed4H6/KFzclSb6jvUMXfEA1cxjB5lOfancAk=; b=fsu7uCyyjzns7RjkZPJmS8kag6YJ/fmy063vp6zXckTXKXaIa6HS1xbCmTsSeIVKqv mvu+rUCs6dAwyOFMFBKBpJKsQSac+d3y0OkS439VB8XSBEZ05DqbL9rTzR01C6IClEYQ B2habkO9Up8tQo6H2lrVhO4tO0eQ4cQ/VpXaW/Ne/laUzOQxzcDOGcey+ui9QwgLEaxs rsm4QB/OludDdWcRqVJqpTrTXybnVzLOqg9DoMiGyd6vBBZX4CXZG6lf38w5mdUS4D6c vezqQSZJb3Bz95+gcPZz7Tgk4jM9mXHcm85SSqyJhfbIU9MHe7tcdYaitwvV3plZ22+x GDqg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700702818; x=1701307618; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=t6Ejlq5Ed4H6/KFzclSb6jvUMXfEA1cxjB5lOfancAk=; b=Q2nWwhJjRzrNJCorsPtH3kuJZEpK79i4kNM9Cb56GvbpJF8Wn1tt95s0lJlPKVyr1R gaJTArZKj6iO21Vg3VkzmPsdLQsNBVQqND6VW5l0TyK2330lkBz1Dey84nFe5g0I1TJl I7+jKe9YapM6daimDs0aZdRskYpthJQ9XtGFvKW3fRu9qlCp4LDuXfZcRpH6Epr3IKu5 3Ixbna/KkQ+rfH9kmIVPDUDLNe3oYtqkHJ7hbsfFybmtfXmbNtoz9PUkby/C6NdLeobt E5nQGRlAx2chC1q12tqNDOeLSxfWZo/BrUfnRfhvQIvGZWriVZa8UaNcbm3KBg1mtUpc Rbvg== X-Gm-Message-State: AOJu0Ywc81fG33nsinVQqEMtUqLPJSIW2Sht2ubGPJMeiTLzaUgexsEO axKluQ0ApOatxUJyGvHDs3/uiK7b8n70E/4oyx8= X-Google-Smtp-Source: AGHT+IGe2E3BXppdOTD7S/WE/7m0ghmjiqtgDpeWrjb8Bl37+qBN39WFyjtOomvbTnETmgTKcWLT8g== X-Received: by 2002:a05:690c:a8d:b0:5cc:87d0:7b64 with SMTP id ci13-20020a05690c0a8d00b005cc87d07b64mr2798757ywb.3.1700702817620; Wed, 22 Nov 2023 17:26:57 -0800 (PST) Received: from localhost.localdomain ([2600:1700:20c0:a560:40f7:d2c:d53a:d071]) by smtp.gmail.com with ESMTPSA id j184-20020a0dc7c1000000b005a815346d95sm89832ywd.71.2023.11.22.17.26.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 22 Nov 2023 17:26:56 -0800 (PST) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young Subject: [PATCH v4 3/6] Section 3: Setting up a System to Run DPDK Applications Date: Wed, 22 Nov 2023 20:26:24 -0500 Message-ID: <20231123012633.2005-4-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> <20231123012633.2005-1-dave@youngcopy.com> MIME-Version: 1.0 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Replaced .. |reg| unicode:: U+000AE with .. include:: Added a reference to the section memory_setup_reserving_hugepages -Corrected the sentence “To check if hugepages are are on your system” to “To check if hugepages are reserved on your system” -Updated the instructions for checking if your distribution already provides access to hugepages via /dev/hugepages and how to manually mount the hugepages filesystem if it doesn’t -Added a note about configuring different hugepage sizes, including 1G pages on x86 and various sizes on ARM and other architectures -Added a reference to the section device_setup_vfio -Simplified the instructions for binding network ports to the vfio-pci module on Linux. The new instructions use the dpdk-devbind.py script to automatically unbind the device from its current driver, if necessary, before binding it to vfio-pci. --- .../getting_started_guide/system_setup.rst | 197 ++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 doc/guides/getting_started_guide/system_setup.rst diff --git a/doc/guides/getting_started_guide/system_setup.rst b/doc/guides/getting_started_guide/system_setup.rst new file mode 100644 index 0000000000..d798ad985b --- /dev/null +++ b/doc/guides/getting_started_guide/system_setup.rst @@ -0,0 +1,197 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _memory_setup: + +.. include:: + +Setting up a System to Run DPDK Applications +============================================ + +This section provides step-by-step instructions for setting up your system to run DPDK applications. It covers system configurations for Linux, FreeBSD, and Windows. Each section details the necessary memory and device setups for these operating systems. + +Navigate to the section that corresponds to your operating system to begin the setup process. + +.. contents:: Table of Contents + :local: + +System Setup for Linux +---------------------- + +.. _memory_setup_reserving_hugepages: + +Memory Setup: Reserving Hugepages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For Linux, DPDK requires hugepages be reserved for its use on the system. To check if hugepages are reserved on your system, you can run the following command:: + + grep HugePages_Total /proc/meminfo + +If hugepages are not reserved, you will need to reserve them by following these steps: + +1. Determine the number of hugepages you want to allocate. For example, to allocate 1024 hugepages of 2MB each, you can use the following command:: + + echo 1024 | sudo tee /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages + +2. To make the hugepages configuration persistent across reboots, add the following line to your `/etc/sysctl.conf` file, adjusting the number of hugepages as needed:: + + vm.nr_hugepages = 1024 + +3. Check if your distribution already provides access to hugepages via /dev/hugepages. If it doesn't, you will need to manually mount the hugepages filesystem. To do this, add the following line to your /etc/fstab file:: + + nodev /mnt/huge hugetlbfs defaults 0 0 + + Then, create the mount directory and mount the filesystem:: + + mkdir -p /mnt/huge + mount -a + +.. note:: + For information on configuring different hugepage sizes, including 1G pages on x86 and various sizes on ARM and other architectures, refer to :ref:`Hugepages Configuration for Multiple Architectures `. + +.. _device_setup_vfio: + +Device Setup: VFIO +^^^^^^^^^^^^^^^^^^ + +VFIO is a robust and secure driver that relies on IOMMU protection. +To make use of VFIO on Linux, the ``vfio-pci`` module must be loaded: + +.. code-block:: console + + sudo modprobe vfio-pci + +VFIO kernel is usually present by default in all distributions, +however please consult your distribution's documentation to make sure that is the case. + +To make use of full VFIO functionality, +both kernel and BIOS must support and be configured +to use IO virtualization (such as Intel\ |reg| VT-d). + +.. note:: + + In most cases, specifying "iommu=on" as kernel parameter should be enough to + configure the Linux kernel to use IOMMU. + +For proper operation of VFIO when running DPDK applications as a non-privileged user, +correct permissions should also be set up. +For more information, refer to :ref:`running_dpdk_apps_without_root`. + +Refer to :ref:`vfio_no_iommu_mode` when there is no IOMMU available on the system. + +Binding Network Ports to VFIO-PCI Module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To bind network ports to the `vfio-pci` module on Linux, use the `dpdk-devbind.py` script with the following command. This script will automatically unbind the device from its current driver, if necessary, before binding it to `vfio-pci`. + +.. code-block:: bash + + sudo dpdk-devbind.py -b vfio-pci + +Replace ```` with the PCI device identifier of the network port. For example: + +.. code-block:: bash + + # Example for a network port with PCI ID 01:00.0 + sudo dpdk-devbind.py -b vfio-pci 01:00.0 + +System Setup for FreeBSD +------------------------ + +.. _loading_contigmem_module: + +Memory Setup: Loading the DPDK contigmem Module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To run a DPDK application on FreeBSD, physically contiguous memory is required. In the absence of non-transparent superpages, the included sources for the `contigmem` kernel module provides the ability to present contiguous blocks of memory for the DPDK to use. +The ``contigmem`` module must be loaded into the running kernel before any DPDK application is run. +Once DPDK is installed on the system, the module can be found in the ``/boot/modules`` +directory. + +The amount of physically contiguous memory along with the number of physically +contiguous blocks to be reserved by the module can be set at runtime prior to module +loading using:: + + kenv hw.contigmem.num_buffers=n + kenv hw.contigmem.buffer_size=m + +The kernel environment variables can also be specified during boot by placing the +following in ``/boot/loader.conf``:: + + hw.contigmem.num_buffers=n + hw.contigmem.buffer_size=m + +The variables can be inspected using the following command:: + + sysctl -a hw.contigmem + +The module can then be loaded using ``kldload``:: + + cd /boot/modules + kldload contigmem + +.. _nic_uio_module: + +Device Setup: Loading the DPDK nic_uio Module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After :ref:`loading_contigmem_module` on FreeBSD, the ``nic_uio`` module must be loaded into the running kernel before running any DPDK application. + +**Manual Loading:** + To load the module manually, execute the following command: + + .. code-block:: bash + + cd /boot/modules + kldload nic_uio + +**Automatic Loading at System Startup:** + For the module to be automatically loaded at system startup, add this line to `/boot/loader.conf`: + + .. code-block:: text + + nic_uio_load="YES" + +This configuration step allows the system to automatically load the `nic_uio` module during the boot process. Additionally, to bind specific network ports to the `nic_uio` module, set the `hw.nic_uio.bdfs` variable in the `/boot/loader.conf` file. Use a comma-separated list of PCI device identifiers for the network ports without any whitespace. For example: + +.. code-block:: text + + hw.nic_uio.bdfs="2:0:0,2:0:1" + +Binding and Unbinding Network Ports to/from nic_uio Module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the original driver for a network port has been compiled into the kernel, +it is necessary to reboot FreeBSD to restore the original device binding. +Before doing so, update or remove the ``hw.nic_uio.bdfs`` in ``/boot/loader.conf``. + +If rebinding to a driver that is a loadable module, the network port binding can be +reset without rebooting. To do so, unload both the target kernel module and the +``nic_uio`` module, modify or clear the ``hw.nic_uio.bdfs`` kernel environment +(``kenv``) value, and reload the two drivers - first the original kernel driver, +and then the ``nic_uio`` driver. + +Example commands to perform these steps are shown below:: + + kldunload nic_uio + kldunload + kenv -u hw.nic_uio.bdfs + kldload + kldload nic_uio # optional + +System Setup for Windows +------------------------ + +Memory Setup: Installing Windows Modules +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before running DPDK applications on Windows, certain kernel-mode drivers must be installed. Note that these drivers are not signed, so you'll need to disable signature enforcement. However, be cautious as this can weaken your OS security and is generally not recommended in production environments. + +Device Setup: Install Drivers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To run DPDK applications on Windows, you'll need to install specific kernel-mode drivers: + +- **virt2phys**: This driver is essential for providing access to physical addresses and is mandatory for allocating physically-contiguous memory, which is required by hardware PMDs. Once loaded successfully, this driver will appear in the Device Manager as ``Virtual to physical address translator device`` under the Kernel bypass category. If DPDK cannot communicate with the driver, a warning will be printed during initialization. + +- **NetUIO**: This driver provides access to device hardware resources and is mandatory for all hardware PMDs, except for the mlx5 PMD. Devices supported by NetUIO are listed in ``netuio.inf``. You can extend this list to try running DPDK with new devices. From patchwork Thu Nov 23 01:26:25 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 134545 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: 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]) by inbox.dpdk.org (Postfix) with ESMTP id 2AB1D4339F; Thu, 23 Nov 2023 02:27:25 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 7178D42D89; Thu, 23 Nov 2023 02:27:10 +0100 (CET) Received: from mail-yw1-f170.google.com (mail-yw1-f170.google.com [209.85.128.170]) by mails.dpdk.org (Postfix) with ESMTP id A887142D66 for ; Thu, 23 Nov 2023 02:27:00 +0100 (CET) Received: by mail-yw1-f170.google.com with SMTP id 00721157ae682-5cc933f9219so908917b3.0 for ; Wed, 22 Nov 2023 17:27:00 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1700702819; x=1701307619; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=78Yn5i8ehISscfBlUdClNrI/spv0HhuYxBJLTMBPRx0=; b=gOFFBxmPCVevZN1vs6Gv0JWrPHFeGv5fhDBpGfzRHWq7bKnwQ+7lpzyoWfz3M4JqqF mzbU3BU73Fj6WtNlf179B3WHqYcDvH9NBPai/aFZfvs3lioLDT2eNoLtc+hiGIrKnWAj lv1ldR5vIlGNge7Noq/ZOQR7xefnJjhKjNTNsuZtFprgMy+9d+khTSWb6VSUzQ5Ai7zg OFTqppPEVYpktNDit2KyCpxLHEGHZOcdLg+CL+gdSHAKlx/ImVcz3oucCcu6Ww+ipg1H 5OqGQ6Ik2l37dvoZv0YnHSPcA2qqFp2sZT4BtsmIVEyH4iDfyXn816vbJUcalg04jVNl Fm/w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700702819; x=1701307619; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=78Yn5i8ehISscfBlUdClNrI/spv0HhuYxBJLTMBPRx0=; b=KY6XSLXCc0DWkJDog0ojqd/hJt6sMziQyIGhM5t/KVvxBLU1uGueeJPB5OOuzNYQpW mio1qt/tFWmOVmlSsOPZuBCdojqre7XResFXqeeiONXlj3az0yWZDiK6oN8yZxtfOgWO U784wSXFw5JvVE1i+T7gWO+4VUYNuf+rbjkqGtHzwS1DMX/PjCMF45k8f24zglCLAEsS A4OSVmP8evdsPgHs0LTNGzos530aunxBKKj/RJZEHxxnHPyGLknjW2FDjLUOVQ47j0h9 PwRrNI19vQ3/x2teehOA2nSqRR7G2M9xORaXBgyoGdJKMxCwGJSvwMSZgKTHYJytt3Gg YJFA== X-Gm-Message-State: AOJu0Ywo5oI1cmgJRBlL2zDLMNBVKAT4zaHsNFTFSnyX9VWOkkt8ttA3 crElFH3hi0W4z6vyUdKcQYsUFOdGbBRTOMpBNwc= X-Google-Smtp-Source: AGHT+IG6EfpjrZYV0dXLhooELOB1c8icV7v7QK86Z/rzh/pnXnkExhr1uPSDSQJ3+EKo43gy9c7hVA== X-Received: by 2002:a81:af1c:0:b0:5af:a690:e47f with SMTP id n28-20020a81af1c000000b005afa690e47fmr3149404ywh.5.1700702819198; Wed, 22 Nov 2023 17:26:59 -0800 (PST) Received: from localhost.localdomain ([2600:1700:20c0:a560:40f7:d2c:d53a:d071]) by smtp.gmail.com with ESMTPSA id j184-20020a0dc7c1000000b005a815346d95sm89832ywd.71.2023.11.22.17.26.57 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 22 Nov 2023 17:26:57 -0800 (PST) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young Subject: [PATCH v4 4/6] Section 4: Running Applications Date: Wed, 22 Nov 2023 20:26:25 -0500 Message-ID: <20231123012633.2005-5-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> <20231123012633.2005-1-dave@youngcopy.com> MIME-Version: 1.0 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org --- .../getting_started_guide/run_apps/index.rst | 10 ++ .../run_apps/run_apps.rst | 118 ++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 doc/guides/getting_started_guide/run_apps/index.rst create mode 100644 doc/guides/getting_started_guide/run_apps/run_apps.rst diff --git a/doc/guides/getting_started_guide/run_apps/index.rst b/doc/guides/getting_started_guide/run_apps/index.rst new file mode 100644 index 0000000000..f033cac5f0 --- /dev/null +++ b/doc/guides/getting_started_guide/run_apps/index.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +Running Applications +==================== + +.. toctree:: + :maxdepth: 2 + + run_apps \ No newline at end of file diff --git a/doc/guides/getting_started_guide/run_apps/run_apps.rst b/doc/guides/getting_started_guide/run_apps/run_apps.rst new file mode 100644 index 0000000000..339d4c0a68 --- /dev/null +++ b/doc/guides/getting_started_guide/run_apps/run_apps.rst @@ -0,0 +1,118 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _run_apps: + +Running Applications +==================== + +The following instructions apply to Linux, FreeBSD, and Windows. + +.. contents:: Table of Contents + :local: + +Running Applications on Linux and FreeBSD +----------------------------------------- + +Compiling and Running Sample Applications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To compile a sample application: + +1. Navigate to the application's directory in the DPDK distribution. +2. Execute the ``make`` command on Linux or ``gmake`` on FreeBSD. + +For instance, to compile the ``helloworld`` application: + +:: + + cd examples/helloworld + make # On Linux + gmake # On FreeBSD + +To run the application, use: + +:: + + ./build/helloworld -l 0-2 + +The ``-l`` option indicates the cores on which the application should run. + +Sample Applications Overview +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. **Hello World**: A basic application that prints a "hello world" message. +2. **Basic Forwarding**: A skeleton example of a forwarding application. +3. **Command Line**: Demonstrates the command line interface in DPDK. +4. **Ethtool**: Showcases the Ethtool API in DPDK. + +For a comprehensive list of sample applications and their guides, +refer to the `DPDK Sample Applications User Guides `_. + +EAL Parameters +^^^^^^^^^^^^^^ + +Every DPDK application is linked with the DPDK target environment’s +Environmental Abstraction Layer (EAL) library, which provides generic options. +Some of these options include: + +- ``-c COREMASK`` or ``-l CORELIST``: Specifies the cores to run on. +- ``-n NUM``: Number of memory channels per processor socket. +- ``--socket-mem``: Memory allocation from hugepages on specific sockets. + +For a detailed list of EAL options, +refer to the `EAL parameters section `. + +Running Without Root Privileges +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Refer to :ref:`running_dpdk_apps_without_root`. + +Running Applications on Windows +------------------------------- + +Running DPDK applications on Windows involves a few different steps. +This guide provides detailed instructions on how to run the helloworld example +application, which can be used as a reference for running other DPDK applications. + +Grant Lock Pages in Memory Privilege +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use of hugepages ("large pages" in Windows terminology) requires +``SeLockMemoryPrivilege`` for the user running an application. +This privilege allows the DPDK application to keep data in physical memory, +preventing the system from paging the data to virtual memory. +This can significantly improve the performance of your DPDK applications. + +To grant this privilege: + +1. Open Local Security Policy snap-in, either through Control Panel / Computer Management / Local Security Policy, or by pressing Win+R, typing ``secpol``, and pressing Enter. +2. Open Local Policies / User Rights Assignment / Lock pages in memory. +3. Add desired users or groups to the list of grantees. + +The privilege is applied upon the next logon. If the privilege has been granted to the +current user, a logoff is required before it is available. +More details can be found in the `Large-Page Support in MSDN `_. + +Running the helloworld Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After setting up the drivers, you can run the helloworld example to verify your setup. +Here are the steps: + +1. Navigate to the examples in the build directory:: + + cd C:\\Users\\me\\dpdk\\build\\examples + +2. Run the helloworld application:: + + dpdk-helloworld.exe -l 0-3 + +The output should display a hello message from each core, like this: + +:: + + hello from core 1 + hello from core 3 + hello from core 0 + hello from core 2 From patchwork Thu Nov 23 01:26:26 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 134546 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: 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]) by inbox.dpdk.org (Postfix) with ESMTP id 475054339F; Thu, 23 Nov 2023 02:27:33 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A076A42EE4; Thu, 23 Nov 2023 02:27:11 +0100 (CET) Received: from mail-oo1-f49.google.com (mail-oo1-f49.google.com [209.85.161.49]) by mails.dpdk.org (Postfix) with ESMTP id A719742D7F for ; Thu, 23 Nov 2023 02:27:02 +0100 (CET) Received: by mail-oo1-f49.google.com with SMTP id 006d021491bc7-587af6285c0so57793eaf.1 for ; Wed, 22 Nov 2023 17:27:02 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1700702821; x=1701307621; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=pyuxstBfbLf4VelbhrwBQ/D2st8c3XcQOqoGXEgOwE8=; b=uwE5apTWREIxjx4UJQ7wzmgee7iLW9KsDpzs2ghYwlVd6edq7uiOldQh8uKPjQHWRd dRMIY9AZdXjWVti9SZ/txVXb2gPAA0DDdRaX7tNdF88Lk+IYOy6T2fOweTvHiP9zspf+ 7Hh+b2GR7w16JzUnMOdAOgqYywzyO6MCzCzIwkAylSr2ovq0fjYJG28tqrVEIFo8Dgad WNOBfUzTeyb553WYN3JeLtbFQxxyzJm50/LG3qqsgdqWbN28/VLVa4to1a4QyOUqDgfA a+E8CVVV7y95FxKM2rsoa3Ez+SOcVYwVsjndiBdRN0p4YSC/5GNVd5Fg/Un3py5FtUHE r5Cg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700702821; x=1701307621; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=pyuxstBfbLf4VelbhrwBQ/D2st8c3XcQOqoGXEgOwE8=; b=kTaxZ/Lo/zuw9F/FSCJL/iGzG83n1szzaKSq62/MvXjQyYaQEcVJ4MUiTQhZMIbvvg oMI3cXfS6f4NDBor3JovoLTZfGrLkt1PoKsljhB1ZF5xyyOat3cyNw76bAfAqCWROc+0 ZJ96iDegcwpWEODT2yNkMmmrn8fUnNWwP7HwjvdY6vG73R2qbwV7g5e2fjJO9QUPlMRx dj+NCcY15lXh3bCQ6+zTXsc5lt1v3fGdT8q1/trAzX0OR0DUGQW1wATSPBV6wsKxhJNW vb3dz1yPsEUk2xk9SFokHQpJLyNXsTJ2nbNLY2R0E+JD/fGicgAF+pItq6VOEsUYM1sz ToRA== X-Gm-Message-State: AOJu0YyQQ4WW3DGI3bfrKvCrOs0DD4vkt4x+537JCoS5taq1SRYqtqpd krT0qasqr/PT3eP9ndwHK02ARZLjeEPicM4ba8Y= X-Google-Smtp-Source: AGHT+IHusCHkQSUQ4ee9cGBuXJX/iHyvp5sYRaujE4plvFTfXNZe7AuZR7kMC8Yv1kAQxovcfgFjWg== X-Received: by 2002:a05:6358:7e14:b0:16d:e922:ffdc with SMTP id o20-20020a0563587e1400b0016de922ffdcmr3938762rwm.1.1700702820811; Wed, 22 Nov 2023 17:27:00 -0800 (PST) Received: from localhost.localdomain ([2600:1700:20c0:a560:40f7:d2c:d53a:d071]) by smtp.gmail.com with ESMTPSA id j184-20020a0dc7c1000000b005a815346d95sm89832ywd.71.2023.11.22.17.26.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 22 Nov 2023 17:26:59 -0800 (PST) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young 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> <20231123012633.2005-1-dave@youngcopy.com> MIME-Version: 1.0 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Added new guide on hugepages for different architectures Added hugepages_different_architectures to index -Content Streamlining: Removed initial detailed instructions on setting up DPDK for non-root users. Emphasized that running DPDK as non-root on Linux requires IOMMU support through vfio. -Linux Section Updates: Simplified the section to focus on: Adjusting permissions for VFIO entries in /dev and hugepage mount directories. Running DPDK applications as a user in the DPDK group. -FreeBSD Section Updates: Streamlined content to specify adjusting permissions for: Userspace-io device files in /dev, such as /dev/uio0, /dev/uio1, etc. The userspace contiguous memory device: /dev/contigmem. -Removed Sections: Detailed steps for creating user groups, binding NICs, and setting up hugepages were removed. -Overall Impact: The page now focuses more on the prerequisites for running DPDK applications without root privileges, specifically for Linux and FreeBSD, with less emphasis on detailed procedural steps. -Added a reference tag `.. _vfio_platform:` at the start of the VFIO Platform section. -Inserted a reference tag `.. _bifurcated_driver:` at the beginning of the Bifurcated Driver section. -Appended a reference tag `.. _uio:` to the UIO section. --- .../appendix/cross_compile_dpdk.rst | 37 +++ .../appendix/dpdk_meson_build_options.rst | 57 ++++ .../hugepages_different_architectures.rst | 56 ++++ .../getting_started_guide/appendix/index.rst | 18 ++ .../running_dpdk_apps_without_root.rst | 24 ++ .../appendix/vfio_advanced.rst | 301 ++++++++++++++++++ 6 files changed, 493 insertions(+) create mode 100644 doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst create mode 100644 doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst create mode 100644 doc/guides/getting_started_guide/appendix/hugepages_different_architectures.rst create mode 100644 doc/guides/getting_started_guide/appendix/index.rst create mode 100644 doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst create mode 100644 doc/guides/getting_started_guide/appendix/vfio_advanced.rst diff --git a/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst b/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst new file mode 100644 index 0000000000..3e4efe23a4 --- /dev/null +++ b/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst @@ -0,0 +1,37 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _cross_compile_dpdk: + +Cross-compiling DPDK for Different Architectures on Linux +========================================================= + +Cross-compiling DPDK for different architectures follows a similar process. Here are the general steps: + +1. **Get Compiler and Libraries**: Obtain the cross-compiler toolchain and any required libraries specific to the target architecture. + +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. + +Prerequisites +------------- + +- NUMA Library (if required) +- Meson and Ninja +- pkg-config for the target architecture +- Specific GNU or LLVM/Clang toolchain for the target architecture + +Cross-Compiling DPDK +-------------------- + +1. **Set Up the Cross Toolchain**: Download and extract the toolchain for the target architecture. Add it to the PATH. + +2. **Compile Any Required Libraries**: Compile libraries like NUMA if required. + +3. **Cross-Compile DPDK with Meson**: + + .. code-block:: bash + + meson setup cross-build --cross-file + ninja -C cross-build + +Refer to the specific sections for ARM64, LoongArch, and RISC-V for detailed instructions and architecture-specific considerations. \ No newline at end of file diff --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 new file mode 100644 index 0000000000..6669f98371 --- /dev/null +++ b/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _dpdk_meson_build_options: + +DPDK Meson Build Configuration Options +====================================== + +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 +folder. + +Changing the Build Type +----------------------- + +To change the build type from the default "release" to a regular "debug" build, +you can either: + +- Pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially. +- Run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run. + +Platform Options +---------------- + +The "platform" option specifies a set of configuration parameters that will be used. +The valid values are: + +- ``-Dplatform=native`` will tailor the configuration to the build machine. +- ``-Dplatform=generic`` will use configuration that works on all machines of the same architecture as the build machine. +- ``-Dplatform=`` will use configuration optimized for a particular SoC. + +Consult the "socs" dictionary in ``config/arm/meson.build`` to see which SoCs are supported. + +Overriding Platform Parameters +------------------------------ + +The values determined by the platform parameter may be overwritten. For example, +to set the ``max_lcores`` value to 256, you can either: + +- Pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially. +- Run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run. + +Building Sample Applications +---------------------------- + +Some of the DPDK sample applications in the examples directory can be automatically built as +part of a meson build. To do so, pass a comma-separated list of the examples to build to the +``-Dexamples`` meson option as below:: + + meson setup -Dexamples=l2fwd,l3fwd build + +There is also a special value "all" to request that all example applications whose dependencies +are met on the current system are built. When ``-Dexamples=all`` is set as a meson option, +meson will check each example application to see if it can be built, and add all which can be +built to the list of tasks in the ninja build configuration file. + +For a complete list of options, run ``meson configure`` inside your configured build +folder. \ No newline at end of file diff --git a/doc/guides/getting_started_guide/appendix/hugepages_different_architectures.rst b/doc/guides/getting_started_guide/appendix/hugepages_different_architectures.rst new file mode 100644 index 0000000000..a93904fc49 --- /dev/null +++ b/doc/guides/getting_started_guide/appendix/hugepages_different_architectures.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _hugepages_different_architectures: + +Hugepages Configuration for Multiple Architectures +================================================== + +This section outlines the steps for configuring hugepages of various sizes on different architectures, an important aspect for optimizing DPDK performance. + +Hugepages on x86 Architecture +----------------------------- + +**2MB and 1G Hugepages** + +- *2MB hugepages* are commonly used on x86. +- *1G hugepages* can improve performance for large-memory applications. + +**Configuring 1G Hugepages** + +.. code-block:: bash + + # Example GRUB configuration for 1G hugepages + GRUB_CMDLINE_LINUX="default_hugepagesz=1G hugepagesz=1G hugepages=4" + +Update GRUB and reboot after making these changes. + +Hugepages on ARM Architecture +----------------------------- + +ARM supports a range of hugepage sizes, such as 64KB, 512KB, and 2MB. + +**Example Configuration** + +.. code-block:: bash + + # Setting 2MB hugepages on ARM + echo N > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages + +Replace 'N' with the number of pages needed. + +Other Architectures +------------------- + +Refer to architecture-specific documentation for hugepage configurations on platforms like PowerPC or MIPS. + +Boot-Time Reservation of Hugepages +---------------------------------- + +Boot-time reservation is essential for large hugepage sizes. Modify the boot loader, such as GRUB, for this purpose: + +.. code-block:: bash + + GRUB_CMDLINE_LINUX="hugepagesz=2M hugepages=512" + +Regenerate the GRUB config and reboot your system. diff --git a/doc/guides/getting_started_guide/appendix/index.rst b/doc/guides/getting_started_guide/appendix/index.rst new file mode 100644 index 0000000000..b92e3afb5a --- /dev/null +++ b/doc/guides/getting_started_guide/appendix/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _appendix: + +Appendix +======== + +This section covers specific guides related to DPDK. + +.. toctree:: + :maxdepth: 2 + + dpdk_meson_build_options + hugepages_different_architectures + running_dpdk_apps_without_root + vfio_advanced + cross_compile_dpdk diff --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 new file mode 100644 index 0000000000..50cead324e --- /dev/null +++ b/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst @@ -0,0 +1,24 @@ +.. _running_dpdk_apps_without_root: + +Running DPDK Applications Without Root Privileges +================================================= + +It's important to note that running DPDK as non-root on Linux requires IOMMU support through vfio. + +Linux +----- +To run DPDK applications without root privileges on Linux, follow these steps: + +1. **Adjust Permissions for Specific Files and Directories**: + + - VFIO entries in ``/dev``, such as ``/dev/vfio/``, where ```` is the VFIO group to which a device used by DPDK belongs. + - The hugepage mount directory, typically ``/dev/hugepages``, or any alternative mount point configured by the user, e.g., ``/mnt/huge``, ``/mnt/huge_1G``. + +2. **Run the DPDK Application**: Execute the desired DPDK application as the user who has been added to the DPDK group. + +FreeBSD +------- +Adjust the permissions of the following files to run DPDK applications as a non-root user: + +- The userspace-io device files in ``/dev``, for example, ``/dev/uio0``, ``/dev/uio1``, and so on. +- The userspace contiguous memory device: ``/dev/contigmem``. diff --git a/doc/guides/getting_started_guide/appendix/vfio_advanced.rst b/doc/guides/getting_started_guide/appendix/vfio_advanced.rst new file mode 100644 index 0000000000..35d9e783bf --- /dev/null +++ b/doc/guides/getting_started_guide/appendix/vfio_advanced.rst @@ -0,0 +1,301 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _vfio_advanced: + +.. |reg| unicode:: U+000AE + +VFIO Advanced +============= + + +.. contents:: Table of Contents + :local: + +.. _vfio_no_iommu_mode: + +VFIO no-IOMMU mode +------------------ + +If there is no IOMMU available on the system, VFIO can still be used, +but it has to be loaded with an additional module parameter: + +.. code-block:: console + + modprobe vfio enable_unsafe_noiommu_mode=1 + +Alternatively, one can also enable this option in an already loaded kernel module: + +.. code-block:: console + + echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode + +After that, VFIO can be used with hardware devices as usual. + +.. note:: + + It may be required to unload all VFIO related-modules before probing + the module again with ``enable_unsafe_noiommu_mode=1`` parameter. + +.. warning:: + + Since no-IOMMU mode forgoes IOMMU protection, it is inherently unsafe. + That said, it does make it possible for the user + to keep the degree of device access and programming that VFIO has, + in situations where IOMMU is not available. + +VFIO Memory Mapping Limits +-------------------------- + +For DMA mapping of either external memory or hugepages, VFIO interface is used. +VFIO does not support partial unmap of once mapped memory. Hence DPDK's memory is +mapped in hugepage granularity or system page granularity. Number of DMA +mappings is limited by kernel with user locked memory limit of a process (rlimit) +for system/hugepage memory. Another per-container overall limit applicable both +for external memory and system memory was added in kernel 5.1 defined by +VFIO module parameter ``dma_entry_limit`` with a default value of 64K. +When application is out of DMA entries, these limits need to be adjusted to +increase the allowed limit. + +Creating Virtual Functions using vfio-pci +----------------------------------------- + +Since Linux version 5.7, +the ``vfio-pci`` module supports the creation of virtual functions. +After the PF is bound to ``vfio-pci`` module, +the user can create the VFs using the ``sysfs`` interface, +and these VFs will be bound to ``vfio-pci`` module automatically. + +When the PF is bound to ``vfio-pci``, +by default it will have a randomly generated VF token. +For security reasons, this token is write only, +so the user cannot read it from the kernel directly. +To access the VFs, the user needs to create a new token, +and use it to initialize both VF and PF devices. +The tokens are in UUID format, +so any UUID generation tool can be used to create a new token. + +This VF token can be passed to DPDK by using EAL parameter ``--vfio-vf-token``. +The token will be used for all PF and VF ports within the application. + +#. Generate the VF token by uuid command + + .. code-block:: console + + 14d63f20-8445-11ea-8900-1f9ce7d5650d + +#. Load the ``vfio-pci`` module with ``enable_sriov`` parameter set + + .. code-block:: console + + sudo modprobe vfio-pci enable_sriov=1 + + Alternatively, pass the ``enable_sriov`` parameter through the ``sysfs`` if the module is already loaded or is built-in: + + .. code-block:: console + + echo 1 | sudo tee /sys/module/vfio_pci/parameters/enable_sriov + +#. Bind the PCI devices to ``vfio-pci`` driver + + .. code-block:: console + + ./usertools/dpdk-devbind.py -b vfio-pci 0000:86:00.0 + +#. Create the desired number of VF devices + + .. code-block:: console + + echo 2 > /sys/bus/pci/devices/0000:86:00.0/sriov_numvfs + +#. Start the DPDK application that will manage the PF device + + .. code-block:: console + + /app/dpdk-testpmd -l 22-25 -n 4 -a 86:00.0 \ + --vfio-vf-token=14d63f20-8445-11ea-8900-1f9ce7d5650d --file-prefix=pf -- -i + +#. Start the DPDK application that will manage the VF device + + .. code-block:: console + + /app/dpdk-testpmd -l 26-29 -n 4 -a 86:02.0 \ + --vfio-vf-token=14d63f20-8445-11ea-8900-1f9ce7d5650d --file-prefix=vf0 -- -i + +.. note:: + + Linux versions earlier than version 5.7 do not support the creation of + virtual functions within the VFIO framework. + +Troubleshooting VFIO +-------------------- + +In certain situations, using ``dpdk-devbind.py`` script +to bind a device to VFIO driver may fail. +The first place to check is the kernel messages: + +.. code-block:: console + + dmesg | tail + ... + [ 1297.875090] vfio-pci: probe of 0000:31:00.0 failed with error -22 + ... + +In most cases, the ``error -22`` indicates that the VFIO subsystem +could not be enabled because there is no IOMMU support. + +To check whether the kernel has been booted with correct parameters, +one can check the kernel command-line: + +.. code-block:: console + + cat /proc/cmdline + +Please refer to earlier sections on how to configure kernel parameters +correctly for your system. + +If the kernel is configured correctly, one also has to make sure that +the BIOS configuration has virtualization features (such as Intel\ |reg| VT-d). +There is no standard way to check if the platform is configured correctly, +so please check with your platform documentation to see if it has such features, +and how to enable them. + +In certain distributions, default kernel configuration is such that +the no-IOMMU mode is disabled altogether at compile time. +This can be checked in the boot configuration of your system: + +.. code-block:: console + + cat /boot/config-$(uname -r) | grep NOIOMMU + # CONFIG_VFIO_NOIOMMU is not set + +If ``CONFIG_VFIO_NOIOMMU`` is not enabled in the kernel configuration, +VFIO driver will not support the no-IOMMU mode, +and other alternatives (such as UIO drivers) will have to be used. + +.. _vfio_platform: + +VFIO Platform +------------- + +VFIO Platform is a kernel driver that extends capabilities of VFIO +by adding support for platform devices that reside behind an IOMMU. +Linux usually learns about platform devices directly from device tree +during boot-up phase, +unlike for example, PCI devices which have necessary information built-in. + +To make use of VFIO platform, the ``vfio-platform`` module must be loaded first: + +.. code-block:: console + + sudo modprobe vfio-platform + +.. note:: + + By default ``vfio-platform`` assumes that platform device has dedicated reset driver. + If such driver is missing or device does not require one, + this option can be turned off by setting ``reset_required=0`` module parameter. + +Afterwards platform device needs to be bound to ``vfio-platform``. +This is standard procedure requiring two steps. +First ``driver_override``, which is available inside platform device directory, +needs to be set to ``vfio-platform``: + +.. code-block:: console + + sudo echo vfio-platform > /sys/bus/platform/devices/DEV/driver_override + +Next ``DEV`` device must be bound to ``vfio-platform`` driver: + +.. code-block:: console + + sudo echo DEV > /sys/bus/platform/drivers/vfio-platform/bind + +On application startup, DPDK platform bus driver scans ``/sys/bus/platform/devices`` +searching for devices that have ``driver`` symbolic link +pointing to ``vfio-platform`` driver. +Finally, scanned devices are matched against available PMDs. +Matching is successful if either PMD name or PMD alias matches kernel driver name +or PMD name matches platform device name, all in that order. + +VFIO Platform depends on ARM/ARM64 and is usually enabled on distributions +running on these systems. +Consult your distributions documentation to make sure that is the case. + +.. _bifurcated_driver: + +Bifurcated Driver +----------------- + +PMDs which use the bifurcated driver co-exists with the device kernel driver. +On such model the NIC is controlled by the kernel, while the data +path is performed by the PMD directly on top of the device. + +Such model has the following benefits: + + - It is secure and robust, as the memory management and isolation + is done by the kernel. + - It enables the user to use legacy linux tools such as ``ethtool`` or + ``ifconfig`` while running DPDK application on the same network ports. + - It enables the DPDK application to filter only part of the traffic, + while the rest will be directed and handled by the kernel driver. + The flow bifurcation is performed by the NIC hardware. + As an example, using :ref:`flow_isolated_mode` allows to choose + strictly what is received in DPDK. + +More about the bifurcated driver can be found in +NVIDIA `bifurcated PMD +`_ presentation. + +.. _uio: + +UIO +--- + +.. warning:: + + Using UIO drivers is inherently unsafe due to this method lacking IOMMU protection, + and can only be done by root user. + +In situations where using VFIO is not an option, there are alternative drivers one can +use. +In many cases, the standard ``uio_pci_generic`` module included in the Linux kernel +can be used as a substitute for VFIO. This module can be loaded using the command: + +.. code-block:: console + + sudo modprobe uio_pci_generic + +.. note:: + + ``uio_pci_generic`` module doesn't support the creation of virtual functions. + +As an alternative to the ``uio_pci_generic``, there is the ``igb_uio`` module +which can be found in the repository `dpdk-kmods `_. +It can be loaded as shown below: + +.. code-block:: console + + sudo modprobe uio + sudo insmod igb_uio.ko + +.. note:: + + For some devices which lack support for legacy interrupts, e.g. virtual function + (VF) devices, the ``igb_uio`` module may be needed in place of ``uio_pci_generic``. + +.. note:: + + If UEFI secure boot is enabled, + the Linux kernel may disallow the use of UIO on the system. + Therefore, devices for use by DPDK should be bound to the ``vfio-pci`` kernel module + rather than any UIO-based module. + For more details see :ref:`linux_gsg_binding_kernel` below. + +.. note:: + + If the devices used for DPDK are bound to a UIO-based kernel module, + please make sure that the IOMMU is disabled or is in passthrough mode. + One can add ``intel_iommu=off`` or ``amd_iommu=off`` or ``intel_iommu=on iommu=pt`` + in GRUB command line on x86_64 systems, + or add ``iommu.passthrough=1`` on aarch64 systems. From patchwork Thu Nov 23 01:26:27 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 134547 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: 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]) by inbox.dpdk.org (Postfix) with ESMTP id 824034339F; Thu, 23 Nov 2023 02:27:40 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id C15EC42EE8; Thu, 23 Nov 2023 02:27:12 +0100 (CET) Received: from mail-oo1-f43.google.com (mail-oo1-f43.google.com [209.85.161.43]) by mails.dpdk.org (Postfix) with ESMTP id 21F1040041 for ; Thu, 23 Nov 2023 02:27:03 +0100 (CET) Received: by mail-oo1-f43.google.com with SMTP id 006d021491bc7-582050ce2d8so61350eaf.0 for ; Wed, 22 Nov 2023 17:27:03 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1700702821; x=1701307621; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=NaKMXlXg4ykFm0kZKeVKbTFWUHXM5RVAaPiA6swpqbw=; b=Bda+BJdbMnY2c28zEhkSGN+zGBfJ9LanPdh9cB1VEYRySdk71SKNoyQrJewjdHPOMN lJsGL5Z9/wkheujBIy8D6zYthcR8ruvMLPfPnyUGhYUyiSJUROOQuZmSW8MNR9OzERwQ zZwXRwa5JtAWQ68bETuDI1L3OicTW7a9lP8APIMByK5I51TOpWuCjwUBmpPbESbnE91M zg2GpC+AMAGoLsHQ+eqeSDduXx60By1Ado4pvoHTP1xo9y2ZsXYhpVTzzhn+Ta2Q+id6 jaAUa6qLXS4jcWdo8NHKzewyzNUH7gy0UpzgxcPR2WLy6SKpGjABJuSy5QVSj0TBWUlY /fag== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700702821; x=1701307621; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=NaKMXlXg4ykFm0kZKeVKbTFWUHXM5RVAaPiA6swpqbw=; b=LBGj03gGBbEK3aVzf7yV+8f6BjGQmDFXZmXyw/nzmAufue3NTAKzAiqW9rpFUhtVAW j6rqrNsRVw12ynUPZfdWaoTlMazHIbGv/pC0axINqsvQY/MosZqA281uKMnlEDQcy6+v HhT/kp58exIopBmM1W8d1B+0D42p2fseio+lOYosoMyImxwyXJ4t8nvm2LxgNl+mTsOi tOiwuID9kGo2ZGhJxpyzTkkIBNdnqCYBmX1Kr6gRD31zRegiY5XqqlS/puwrTbY0hLWy eQrlnVvG+V/IOcJnNQib48/qF6yIFk0kThHyMM65hZwbX+lk/wAPC9GKnuKvJzWFUZr/ mZZw== X-Gm-Message-State: AOJu0Yyl/13mspryRB0s9CZ01QoSuYEIinAU4bhiZz+1kC/nb7GS00Lr 5A1/7yjH5VABjnRoOYhSLAwcloU/iSFoRdXqyEo= X-Google-Smtp-Source: AGHT+IFvQ9qmezoy6v/Qu/UtMztFFftp9KIcdUdKrGvJpPaM0FYzcNsLC4nezK6BJHMwRHMXQ0txWA== X-Received: by 2002:a05:6358:71d:b0:16d:abd9:f29e with SMTP id e29-20020a056358071d00b0016dabd9f29emr4253862rwj.2.1700702821594; Wed, 22 Nov 2023 17:27:01 -0800 (PST) Received: from localhost.localdomain ([2600:1700:20c0:a560:40f7:d2c:d53a:d071]) by smtp.gmail.com with ESMTPSA id j184-20020a0dc7c1000000b005a815346d95sm89832ywd.71.2023.11.22.17.27.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 22 Nov 2023 17:27:01 -0800 (PST) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young Subject: [PATCH v4 6/6] Section 6: Glossary Date: Wed, 22 Nov 2023 20:26:27 -0500 Message-ID: <20231123012633.2005-7-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> <20231123012633.2005-1-dave@youngcopy.com> MIME-Version: 1.0 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org -Glossary Introduction Formatting: Refined the introduction's formatting for clarity. -Directive Implementation: Used .. glossary:: directive for structured term definitions. -Term Definitions and Linking: Expanded definitions for terms like BIOS, Bifurcated Driver, Clang-LLVM, etc., with reference tags and links to their respective content pages. Enhanced Navigation: Integrated hyperlinks for each term, directing to detailed information on content pages. --- doc/guides/getting_started_guide/glossary.rst | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 doc/guides/getting_started_guide/glossary.rst diff --git a/doc/guides/getting_started_guide/glossary.rst b/doc/guides/getting_started_guide/glossary.rst new file mode 100644 index 0000000000..29e3f041ba --- /dev/null +++ b/doc/guides/getting_started_guide/glossary.rst @@ -0,0 +1,78 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +Glossary +======== + +This glossary provides definitions for key terms and concepts used within DPDK. Understanding +these terms will help in comprehending the functionality and architecture of DPDK. + +.. glossary:: + + BIOS (Basic Input/Output System) + + The firmware used to perform hardware initialization during the booting process and to provide runtime services for operating systems and programs. + + :ref:`Bifurcated Driver ` + + A driver model that splits functionality between kernel and userspace, often used in high-performance networking. + + :ref:`Clang-LLVM ` + + A compiler toolchain that includes the Clang C compiler and LLVM linker, used for building DPDK on Windows. + + :ref:`contigmem Module ` + + A module in FreeBSD that provides physically contiguous memory allocation used by DPDK. + + :ref:`DMA (Direct Memory Access) ` + + A feature that allows hardware devices to access the main system memory directly, without involving the CPU. + + :ref:`EAL (Environment Abstraction Layer) ` + + The layer within DPDK that abstracts environmental specifics and provides a standard programming interface. + + :ref:`hugepages ` + + Large memory pages used by the operating system to manage memory more efficiently, especially in high-performance applications like DPDK. + + IOMMU (Input-Output Memory Management Unit) + + A hardware component that translates device-visible virtual addresses to physical addresses, providing memory protection and isolation. + + :ref:`MinGW-w64 Toolchain ` + + A development environment for creating Windows applications, used as an option for compiling DPDK on Windows. + + NIC (Network Interface Card) + + A hardware component that connects a computer to a network. + + :ref:`nic_uio Module ` + + A UIO driver for network devices in FreeBSD, used by DPDK. + + NUMA (Non-Uniform Memory Access) + + A computer memory design used in multiprocessing where the memory access time depends on the memory location relative to the processor. + + PMD (POLL Mode Driver) + + A type of driver in DPDK that continuously polls for events rather than relying on interrupts, often used for high-performance networking. + + SoC (System on a Chip) + + An integrated circuit that integrates all components of a computer or other electronic system into a single chip. + + :ref:`UIO (Userspace I/O) ` + + A Linux kernel module that enables user-space applications to access hardware devices directly. + + :ref:`VFIO (Virtual Function I/O) ` + + A kernel driver that allows a virtual machine to access physical devices directly, used in DPDK for device assignment. + + :ref:`VFIO Platform ` + + A framework in Linux that allows exposing direct device access to userspace, in a secure, IOMMU-protected way.