From patchwork Wed Sep 20 15:48:05 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 131744 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 EEFF8425F1; Wed, 20 Sep 2023 17:49:50 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id DD05540ED0; Wed, 20 Sep 2023 17:49:50 +0200 (CEST) Received: from mail-yw1-f171.google.com (mail-yw1-f171.google.com [209.85.128.171]) by mails.dpdk.org (Postfix) with ESMTP id C22AD40041 for ; Wed, 20 Sep 2023 17:49:49 +0200 (CEST) Received: by mail-yw1-f171.google.com with SMTP id 00721157ae682-59be81cf0d8so7215097b3.0 for ; Wed, 20 Sep 2023 08:49:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1695224989; x=1695829789; 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=d2sKinRyp66552QdkzzeXnd35I9jXsMdA+AR/5vPsqQ=; b=pOI8HDjz0bv/T2BKu1vjNDW809oFbpXsKRBcKNjKNuJ0/5buWa+qlHUL122ezGUNSL e0ph27gBmzc4tvVS+fPq3zQGNfKSqqBHlYNQ7re31BRkQYAn2ZKMC+PcVsRVkYt2Cu26 Bbin0zdfSMbCxA1nuEPB+zJPHQUJxsPe62o8UcuROJ6lAIfPE9n1hE2JxloIESdHT5z6 nerOvogVhK0lPx0juNXBMOMYLZdjvme5aHo3OBQbgDIWrtMBEluorarVM4eZQZJlSrR3 MQxp69BUyFtgxsIICHRKBvpOUSfy4ehS9VHEBnKodnPj1WvXD7ndzv4nPsHaQr1Wfs9K +tOg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695224989; x=1695829789; 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=d2sKinRyp66552QdkzzeXnd35I9jXsMdA+AR/5vPsqQ=; b=sjm0wDxVls+PjwEmUkLnjrIJBc3s0Bmg1ywk5iMWK5bxkuFwJ34y9AsX2ssWS3tMVa /09Dmh64I6OscpIF50vxSdtSg/GrDq4FU/cPSBHC6TE5JBglF3tbVoWCLBQyTnZmjYHq Rxovp6TJv7AwzKtHPzJS+3viFxGVKUH6ooTgtWCiEsmlso1so/h8FEK816mYPCKCYv/x qujQ189Mc70cd4qRdLCQidClNeMWXDomV/9rH8D3/MzcQK1auQmBH7P/XypMF95lL8pR hgGlfGnizHvZ+2T8s8eRKUbolsUbCZTtebQr75koty7zEGVjgaaAkQoJtijv7lhbK5Ri qbDg== X-Gm-Message-State: AOJu0Yz0UEbXjuAgsUSeshBr/9I2WZlqOAybTYnAye6UnVaWCLbi5fC9 duq1q9ke2znTtJMeakMlao4h+po+AHPQo1zB8SE= X-Google-Smtp-Source: AGHT+IH+yMsToe9WzuVzJthTOpgtpftZ6Tq/brJTcH6p+n/I4gNV+f9fD9FPYkHBkrUjFhEjOWcX/g== X-Received: by 2002:a0d:dfc5:0:b0:583:adc6:10b8 with SMTP id i188-20020a0ddfc5000000b00583adc610b8mr2453870ywe.3.1695224988796; Wed, 20 Sep 2023 08:49:48 -0700 (PDT) Received: from localhost.localdomain ([2600:1700:20c0:a560:1d8e:3ea8:ad75:14a1]) by smtp.gmail.com with ESMTPSA id r2-20020a818102000000b0059a34cfa2a5sm3806348ywf.67.2023.09.20.08.49.48 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 20 Sep 2023 08:49:48 -0700 (PDT) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , David Young Subject: [PATCH 1/6] Section 1: Introduction Date: Wed, 20 Sep 2023 11:48:05 -0400 Message-ID: <20230920154817.617-2-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20230920154817.617-1-dave@youngcopy.com> References: <20230920154817.617-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 --- doc/guides/getting_started_guide/intro.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 doc/guides/getting_started_guide/intro.rst diff --git a/doc/guides/getting_started_guide/intro.rst b/doc/guides/getting_started_guide/intro.rst new file mode 100644 index 0000000000..88bdd48849 --- /dev/null +++ b/doc/guides/getting_started_guide/intro.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. + +Introduction +============ + +Welcome to the unified 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 for each operating system where necessary. +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. + +We hope this guide serves as a valuable resource as you explore the powerful +capabilities of DPDK. \ No newline at end of file From patchwork Wed Sep 20 15:48:06 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 131745 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 4E9EE425F1; Wed, 20 Sep 2023 17:49:55 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 0EE2F410E3; Wed, 20 Sep 2023 17:49:53 +0200 (CEST) Received: from mail-yw1-f174.google.com (mail-yw1-f174.google.com [209.85.128.174]) by mails.dpdk.org (Postfix) with ESMTP id E485940ED2 for ; Wed, 20 Sep 2023 17:49:50 +0200 (CEST) Received: by mail-yw1-f174.google.com with SMTP id 00721157ae682-59be81cf0d8so7215127b3.0 for ; Wed, 20 Sep 2023 08:49:50 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1695224990; x=1695829790; 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=KK9VyI49layBKZYhNrRz+kEOLivwLK4sFFqNWsOqpYk=; b=WaotOTKZTGIeMjpiU2X43HtyQeObsCw91nKVcGXN+o2+tI3MiKJW+wiOInEbolOGyL R7+Is/Mf4ga+SMggyP1xAkcHPUiKD2TMnD3asAnFhZK8x16qes54VFdkj/rLSnXqgvtA mLJwLm6xNM2ZVvBgm6Ed3ymEUEpILI02C6y7ckBV/dZEc+X6TT7FRb68aNHJPMjlqw5f xP1nGlmFZrIT1srGcAbtS1jruTjNSEHM+7mh8sym6fcyCNY5H6+BDIBJ59DFgmD6OKOF FxVCMR9KoFAzFqVjSolohgGkaGUWaEmWB8s7LOjg/C/2Y21D/y2UC7So9LPncKoxS3RB OKJw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695224990; x=1695829790; 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=KK9VyI49layBKZYhNrRz+kEOLivwLK4sFFqNWsOqpYk=; b=TQyA7n0ydgA5sts3IhpVD9Haxyrys6M+bsFUDfMnpfdcF+6+NE2wzYu/Ll1DtmhkUs Kkw+q/BSD/wcawnM3PvdaH4G6uNhfXIQIeTWGskw26V/gRYjOq0U+plD34IaqnBBZ5ol TQCke5JANk/Tp9ONLrumRAhOON4ipalj0mK6J+OSPfG/cXiSR726jvIO+QcoWs0Ch8mt qKB9HJBAM+ROqRdDYy5EhgUp1cjochq4BW9SMNfujLBqITzxMlmzX10Dy0ss9cxdtQiC A0WE7YMcJxL69cfBH+ETfKkco0ECE9YOVbw2BYuSv8R3Yf3xwU2xVB5SccCyQbjCrzOf UZKQ== X-Gm-Message-State: AOJu0Yw8vOJWv96/P2lgGnrr39xjFCC803m/3UkKb8NvxGupAXY6bIma Vp2SndJNaI61u0t0C/AVNZWNxmenW5IAormysG8= X-Google-Smtp-Source: AGHT+IEKHVU9mgXe9fXMecY0oFmrxCKcoUXGUIXwb/8Ztpo6m5LcpbKX9cWXkwalFzkMZ+duneN+5Q== X-Received: by 2002:a0d:dfc5:0:b0:583:adc6:10b8 with SMTP id i188-20020a0ddfc5000000b00583adc610b8mr2453906ywe.3.1695224989791; Wed, 20 Sep 2023 08:49:49 -0700 (PDT) Received: from localhost.localdomain ([2600:1700:20c0:a560:1d8e:3ea8:ad75:14a1]) by smtp.gmail.com with ESMTPSA id r2-20020a818102000000b0059a34cfa2a5sm3806348ywf.67.2023.09.20.08.49.48 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 20 Sep 2023 08:49:49 -0700 (PDT) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , David Young Subject: [PATCH 2/6] Section 2: Install and Build DPDK Date: Wed, 20 Sep 2023 11:48:06 -0400 Message-ID: <20230920154817.617-3-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20230920154817.617-1-dave@youngcopy.com> References: <20230920154817.617-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 --- .../building_from_sources.rst | 108 ++++++++++++++++++ .../install_and_build/index.rst | 15 +++ .../installing_prebuilt_packages.rst | 54 +++++++++ .../windows_install_build.rst | 93 +++++++++++++++ 4 files changed, 270 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 create mode 100644 doc/guides/getting_started_guide/install_and_build/windows_install_build.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..e4ee8e436d --- /dev/null +++ b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst @@ -0,0 +1,108 @@ +.. 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 on both +Linux and FreeBSD platforms. 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.53.2+) and ``ninja`` +- ``pyelftools`` (version 0.22+) + +Here's how to install them: + +Linux +^^^^^ + +Alpine + +.. code-block:: bash + + sudo apk add alpine-sdk bsd-compat-headers + pip install meson ninja + +Debian and Ubuntu and derivatives + +.. code-block:: bash + + sudo apt install build-essential + pip install meson ninja + +Fedora and RedHat Enterprise Linux RHEL + +.. code-block:: bash + + sudo dnf groupinstall "Development Tools" + pip install meson ninja + +openSUSE + +.. code-block:: bash + + sudo zypper install -t pattern devel_basis python3-pyelftools + pip install meson ninja + +FreeBSD +^^^^^^^ + +FreeBSD (as root) + +.. code-block:: bash + + pkg install meson pkgconf py38-pyelftools + +Note: If you're using FreeBSD, you'll also need kernel sources. Make sure they're included during the FreeBSD installation. + +Getting the DPDK Source +----------------------- + +Download the DPDK source code from the official repository +``https://fast.dpdk.org/rel/``. + +Use ``wget`` to grab the DPDK version:: + + wget https://fast.dpdk.org/rel/dpdk-.tar.xz + +Extract the downloaded archive: + +.. code-block:: bash + + tar -xvf dpdk-.tar.gz + +Navigate to the DPDK directory: + +.. code-block:: bash + + cd dpdk- + +Building DPDK +------------- + +Configure the build based on your needs, hardware, and environment. +This might include setting specific flags or options. For example: “meson setup -Dbuildtype=debugoptimized build”. Then compile using “ninja” and install using “meson install”. + +.. code-block:: bash + + ninja -C build + cd build + sudo ninja install + ldconfig + +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..f4d8740fb6 --- /dev/null +++ b/doc/guides/getting_started_guide/install_and_build/index.rst @@ -0,0 +1,15 @@ +.. 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 + windows_install_build \ 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 diff --git a/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst b/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst new file mode 100644 index 0000000000..ea0e131766 --- /dev/null +++ b/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2015 Intel Corporation. + +.. _windows_install_build: + +Windows DPDK Build +================== + +Before you begin the process of building DPDK on Windows, +make sure your system meets all the necessary requirements as outlined below. + +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. + +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. + +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. +Recommended version is either Meson 0.57.0 (baseline) or the latest release. + +Install the Backend +------------------- + +If using Ninja, download and install the backend from the +`Ninja website `_ or install along with the meson build +system. + +Once you have verified that your system meets these requirements, +you can proceed with the following steps to build DPDK. + +Build the Code +-------------- + +The build environment is setup to build the EAL and the helloworld example by default. +To compile the examples, the flag -Dexamples is required. + +**Option 1. Native Build on Windows** + +When using Clang-LLVM, specifying the compiler might be required to complete the meson +command:: + + set CC=clang + +When using MinGW-w64, it is sufficient to have toolchain executables in PATH:: + + set PATH=C:\MinGW\mingw64\bin;%PATH% + +To compile the examples:: + + cd C:\Users\me\dpdk + meson -Dexamples=helloworld build + ninja -C build + +**Option 2. Cross-Compile with MinGW-w64** + +The cross-file option must be specified for Meson. +Depending on the distribution, paths in this file may need adjustments:: + + meson --cross-file config/x86/cross-mingw -Dexamples=helloworld build + ninja -C build \ No newline at end of file From patchwork Wed Sep 20 15:48:07 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 131746 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 85138425F1; Wed, 20 Sep 2023 17:50:05 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 7026C42D2A; Wed, 20 Sep 2023 17:49:54 +0200 (CEST) Received: from mail-yb1-f179.google.com (mail-yb1-f179.google.com [209.85.219.179]) by mails.dpdk.org (Postfix) with ESMTP id 4EC5240F35 for ; Wed, 20 Sep 2023 17:49:52 +0200 (CEST) Received: by mail-yb1-f179.google.com with SMTP id 3f1490d57ef6-d8207f87163so480276.1 for ; Wed, 20 Sep 2023 08:49:52 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1695224991; x=1695829791; 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=TvECvViEB9WLpJo0E7w5lRllV05LoKXuyslTDeSqEE8=; b=ZnsPqrEg40FbOV/6FftZ3/zceiaQIhgVU8oTqKqQEKKTgV1BICWwQU8Bw00Po5ZFly /EUUflg7cQ3Giyi3G3xI9Wo9upBWFXLtAgDB4Xn4qnx6YUdCJBDM4dXbizNV0GFbV2u2 NnpCXhkGrHQo33zS4VbluPfAUaeU0pbaygh0Zs8BD5pLIxja3fa97KFOHCpwDuiJF0ml CELPvh/hnttprltTBJ/WQ2zP/BG1T98mdLtgVcGHSH4cQUwN79ic/fLE5Nbs6g6ao6XV 9oNaVki5w9grlwhqWtFKuVO5yPwqc0uBh1DjXCx43mjkVhqTEwyduukwYUQtH3/viFDW 6pag== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695224991; x=1695829791; 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=TvECvViEB9WLpJo0E7w5lRllV05LoKXuyslTDeSqEE8=; b=NZk5u33WEYwfxP6rCSwlH72B/KkaX4uR/qdqhsggzRoK7R+8kOBVPOCqtrxwbl6nl9 hgSRpSjxPGeyVhvfO9qboR9o92EDtI54UR12+FTJ7ha91beClmdn2S+s6tIkpMN6X1jw XqdE+dTCFic4dEd6sNwS44vAb4214bvcMLnFv51PlWOSuo+1TXgpqEVXQCS0tBFNbE1W NGusUih39qjrqrmOApUQ1lqPq9ReUDu2v7UEG4EbQ7Hj8NmJ5ACPtMeRT7vwwTBIxWGb oVHAz76Vy7k6T0RnvX+F+lb7Ma0Ap2Ha59worZhry7gJmCdU28tO/9OQI9WYExw6uU5i u4Tg== X-Gm-Message-State: AOJu0Yx1pJnAiakncKHhJYqoU55IkQzLh8Fbod/bPFE462a7SEhVi8h7 VvbThjsQyhM1sOigDv0dk2PlHUq87MpZxRH4754= X-Google-Smtp-Source: AGHT+IEe3YKXtzxHbXEt/mP8pD3ijFtBRCMKZVrOCT51k3FCN4621kNpPoeBdAOtu1GOsVJyr3TU7w== X-Received: by 2002:a0d:d755:0:b0:565:a2eb:3436 with SMTP id z82-20020a0dd755000000b00565a2eb3436mr2608156ywd.1.1695224990928; Wed, 20 Sep 2023 08:49:50 -0700 (PDT) Received: from localhost.localdomain ([2600:1700:20c0:a560:1d8e:3ea8:ad75:14a1]) by smtp.gmail.com with ESMTPSA id r2-20020a818102000000b0059a34cfa2a5sm3806348ywf.67.2023.09.20.08.49.50 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 20 Sep 2023 08:49:50 -0700 (PDT) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , David Young Subject: [PATCH 3/6] Section 3: Setting up a System to Run DPDK Applications Date: Wed, 20 Sep 2023 11:48:07 -0400 Message-ID: <20230920154817.617-4-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20230920154817.617-1-dave@youngcopy.com> References: <20230920154817.617-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/system_setup.rst | 195 ++++++++++++++++++ 1 file changed, 195 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..fa9d249ec7 --- /dev/null +++ b/doc/guides/getting_started_guide/system_setup.rst @@ -0,0 +1,195 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _memory_setup: + +.. |reg| unicode:: U+000AE + +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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For Linux, DPDK requires hugepages be reserved for its use on the system. To check if hugepages are are 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. Most distributions make hugepages available via `/dev/hugepages`, so this step may not be necessary. If you need to manually mount the hugepages filesystem, 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 + +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 and Unbinding Network Ports to/from VFIO-PCI Module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To bind or unbind network ports to/from the `vfio-pci` module on Linux, follow these steps: + +Replace ```` with the appropriate module identifier. + +**Unbind from current module**: + If a device is bound to a kernel driver, unbind it: + + .. code-block:: bash + + sudo dpdk-devbind.py -u + +**Bind to vfio-pci module**: + Bind the device to the `vfio-pci` module: + + .. code-block:: bash + + sudo dpdk-devbind.py -b vfio-pci + +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 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 + +Device Setup: Loading the DPDK nic_uio Module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After :ref:`loading_contigmem_module` on FreeBSD, the ``nic_uio`` module must also be loaded into the running kernel prior to running any DPDK application, e.g. using:: + + cd /boot/modules + kldload nic_uio + +By default, the ``nic_uio`` module will take ownership of network ports if they are +recognized DPDK devices and are not owned by another module. +However, since the FreeBSD kernel includes support, either built-in, +or via a separate driver module, for most network card devices, +it is likely that the ports to be used are already bound to a driver other than +``nic_uio``. + +To re-bind the ports to the `nic_uio` module upon loading, use the following command:: + + kenv hw.nic_uio.bdfs="b:d:f,b:d:f,..." + +Where a comma-separated list of selectors is set, the list must not contain any +whitespace. + +The variable can also be specified during boot by placing the following into +``/boot/loader.conf``, before the previously-described ``nic_uio_load`` line:: + + hw.nic_uio.bdfs="2:0:0,2:0:1" + nic_uio_load="YES" + +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. \ No newline at end of file From patchwork Wed Sep 20 15:48:08 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 131747 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 294EA425F1; Wed, 20 Sep 2023 17:50:13 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 7E21F42D3F; Wed, 20 Sep 2023 17:49:56 +0200 (CEST) Received: from mail-yw1-f176.google.com (mail-yw1-f176.google.com [209.85.128.176]) by mails.dpdk.org (Postfix) with ESMTP id 55D20410FB for ; Wed, 20 Sep 2023 17:49:53 +0200 (CEST) Received: by mail-yw1-f176.google.com with SMTP id 00721157ae682-595024603bdso11534407b3.0 for ; Wed, 20 Sep 2023 08:49:53 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1695224992; x=1695829792; 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=Bm9ffjKjsNWcdWqgJ8iok658Jzs1afGMjmnGDkkXeyurL10ioP5Rs0/hfWfxT1Me5C GY/iI1BJAkPSfln660s8kuE3XObVnE9bAUotu6cE3KYeqREgr+CZp8A9TgZAYEZuYF1V 4EHsQI6oWCvuSKv67c6EOMWBRlsEPduL6clAgV6tGZWO4i9H9YkjopdoV0rc+JxCstUD nR6T1gLargf8JeDxuXdcwymFYkMU8LI2BLkLUydXdMUK74JEAu1+/B9rhxsE2yMa5GDf JM80akLQejlzQfuMZthFltNvIojjUaU5ogFQJJHY8kjLi8c22mkgtHv5lBgKrvbQY2+d QW8g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695224992; x=1695829792; 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=MDxhhJ8xDAOdYOMulQ+Wt/2sVZbBmNzZUyJfx/Cfdpchx0UR2fe5m03FK1XZtdOM5K ukk/pfRRp8iteF1N8QnL8yElMCs0SGAi8L1njJXfe7pyY1vk++zbcKMeidaNf8bp0noL nmyjmgWB/DOPJWpWOIRBLk+mem7jOAGuIJx2xp+KrIJS/tY+WqfXcVX2HbPuRBWEZSpd APiAFjO1xHLpJyUa+j04n37o5H5uzYuP8p77+LXKn622oKxxnVTexDBVRjhfreYj5JzG oFzhmPJzEF7Fh7VKwj0B5RxkVBCXP/z3cOv3qbSYyL2DaARZc41ArGZZEypdpyIiDwas X28g== X-Gm-Message-State: AOJu0YycbUGw30lr208GaRRWnrTDZdZpjuLtkoHEJSHVUoPYyo79lk0F tfXABwOuvUMePqgiFqmhFMGjFz9lvFUcs0tvA7M= X-Google-Smtp-Source: AGHT+IF5JhalA+1AidOYwvzfMzK3ZXrARccQYhDwR7jL5vUeJkznQG4NU5ZTBbi8ei4yFKWthvu0nA== X-Received: by 2002:a0d:d805:0:b0:59b:e90f:8df8 with SMTP id a5-20020a0dd805000000b0059be90f8df8mr2580875ywe.4.1695224992385; Wed, 20 Sep 2023 08:49:52 -0700 (PDT) Received: from localhost.localdomain ([2600:1700:20c0:a560:1d8e:3ea8:ad75:14a1]) by smtp.gmail.com with ESMTPSA id r2-20020a818102000000b0059a34cfa2a5sm3806348ywf.67.2023.09.20.08.49.51 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 20 Sep 2023 08:49:51 -0700 (PDT) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , David Young Subject: [PATCH 4/6] Section 4: Running Applications Date: Wed, 20 Sep 2023 11:48:08 -0400 Message-ID: <20230920154817.617-5-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20230920154817.617-1-dave@youngcopy.com> References: <20230920154817.617-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 Wed Sep 20 15:48:09 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 131748 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 E30A0425F1; Wed, 20 Sep 2023 17:50:21 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 95F9D42DA1; Wed, 20 Sep 2023 17:49:57 +0200 (CEST) Received: from mail-yw1-f178.google.com (mail-yw1-f178.google.com [209.85.128.178]) by mails.dpdk.org (Postfix) with ESMTP id B549D42D3F for ; Wed, 20 Sep 2023 17:49:54 +0200 (CEST) Received: by mail-yw1-f178.google.com with SMTP id 00721157ae682-59c06cf1614so9308577b3.1 for ; Wed, 20 Sep 2023 08:49:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1695224994; x=1695829794; 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=g5ZtCG/8bPQDFKgDw4WTwkpSDegAxVEqQCkogrr0iZM=; b=ba4qnzxODxUV4Qqh7rTVeUa7GnLWrKmOEP5TeNu4b2zNYYgRZNJBlHDtd3UdZyus9K VU1w/ndiBPJ5y6YEbVLWoqg2WGbAdPPwc0hGEhYNvSsdSyy5A90ZgEYWCuHCL2BgY0o3 Bdy7SpcHDUnrzlijQQeq4XupFJuovkzWRlWipDv+0hjy9b/+GImcz2QC2yeBuuasBGxq QSorzCDI4H48N0/+p/JMD7iCNPY0MWUvlXDmRIUkcSAGot5PQJAAHCRW3mOgqANj1IeK vBMC/8jYP9faZ5N5beh/iMgVJa5WZ4l4aW5v/k11MAkm8ofCJeYMnJh3qAxKQrZaAesK Crjg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695224994; x=1695829794; 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=g5ZtCG/8bPQDFKgDw4WTwkpSDegAxVEqQCkogrr0iZM=; b=ZvlTEQcfusycy6z9LovG+/qrrwW5oIlO09WEsc2pd1TeW11joE2ctA1nJ6feDaUQaQ bkD6A1j7jgL9AI+RbbRITvOHUkWc5fCPuzHbLF11SoZSo2GvDBth5JHH1qlozgFyWgFd B15IyzKPLXk8k/Dhj7vChrRllXfHC/gRVU70GTTmZ1selLTmz/y3+YNpnXZQj1TLV/bk HNuM+YVRWRDkZSpjK/fmcq1uTXdGevnpw789mFMH3pISUDCrjFe4hq4F5bwAfLRdxZnP m8EI1B0FcetOipv3s6yMydWp9S/uJwtYLEI5qVK5wsdl2UK+KbtZktRa+weiPMrAmlny vQzg== X-Gm-Message-State: AOJu0YxrQ9rNsFtkqiYmAzajKo0Zpqxnye5oI7Fqo/LVYSCsApb4TyKT ZudutB9h+gyPCuxOam2pOy7SnxBzr71oj/EI+14= X-Google-Smtp-Source: AGHT+IEmnYbqmHDCRwJea95yRZ6UfNU6WssvYeEtYyb8iaPX47EoP9kS/pLJjZrF/5pOC1EY7CXvkw== X-Received: by 2002:a0d:e2c9:0:b0:59c:cb8:ac2e with SMTP id l192-20020a0de2c9000000b0059c0cb8ac2emr2366529ywe.1.1695224993576; Wed, 20 Sep 2023 08:49:53 -0700 (PDT) Received: from localhost.localdomain ([2600:1700:20c0:a560:1d8e:3ea8:ad75:14a1]) by smtp.gmail.com with ESMTPSA id r2-20020a818102000000b0059a34cfa2a5sm3806348ywf.67.2023.09.20.08.49.52 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 20 Sep 2023 08:49:53 -0700 (PDT) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , David Young Subject: [PATCH 5/6] Section 5: Appendix Date: Wed, 20 Sep 2023 11:48:09 -0400 Message-ID: <20230920154817.617-6-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20230920154817.617-1-dave@youngcopy.com> References: <20230920154817.617-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 --- .../appendix/cross_compile_dpdk.rst | 37 +++ .../appendix/dpdk_meson_build_options.rst | 57 ++++ .../getting_started_guide/appendix/index.rst | 17 + .../running_dpdk_apps_without_root.rst | 36 +++ .../appendix/vfio_advanced.rst | 295 ++++++++++++++++++ 5 files changed, 442 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/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/index.rst b/doc/guides/getting_started_guide/appendix/index.rst new file mode 100644 index 0000000000..23bb1fcf78 --- /dev/null +++ b/doc/guides/getting_started_guide/appendix/index.rst @@ -0,0 +1,17 @@ +.. 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 + running_dpdk_apps_without_root + vfio_advanced + cross_compile_dpdk \ No newline at end of file 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..9f214bbdc8 --- /dev/null +++ b/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst @@ -0,0 +1,36 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _running_dpdk_apps_without_root: + +Running DPDK Applications Without Root Privileges +================================================= + +Although applications using the DPDK use network ports and other hardware resources +directly, with a number of small permission adjustments, +it is possible to run these applications as a user other than “root”. +To do so, the ownership, or permissions, on the following file system objects should be +adjusted so the user account being used to run the DPDK application has +access to them: + +Linux +----- + +1. **Create a DPDK User Group**: Create a new user group for DPDK and add the desired user to this group. + +2. **Set Up Hugepages**: Configure hugepages for the user. + +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``. + +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. + +5. **Run the DPDK Application**: Run the desired DPDK application as the user who has been added to the DPDK group. + +FreeBSD +------- + +- The userspace-io device files in ``/dev``, for example, ``/dev/uio0``, ``/dev/uio1``, and so on +- The userspace contiguous memory device: ``/dev/contigmem`` + + +Refer to the `DPDK Release Notes `_ for supported applications. \ No newline at end of file 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..1cdb138eb7 --- /dev/null +++ b/doc/guides/getting_started_guide/appendix/vfio_advanced.rst @@ -0,0 +1,295 @@ +.. 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 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 +----------------- + +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 +--- + +.. 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. \ No newline at end of file From patchwork Wed Sep 20 15:48:10 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 131749 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 68CA2425F1; Wed, 20 Sep 2023 17:50:29 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A2C5C42DC3; Wed, 20 Sep 2023 17:49:58 +0200 (CEST) Received: from mail-yw1-f169.google.com (mail-yw1-f169.google.com [209.85.128.169]) by mails.dpdk.org (Postfix) with ESMTP id BDDC142D3F for ; Wed, 20 Sep 2023 17:49:55 +0200 (CEST) Received: by mail-yw1-f169.google.com with SMTP id 00721157ae682-597f4b5a5c7so14120357b3.1 for ; Wed, 20 Sep 2023 08:49:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1695224995; x=1695829795; 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=FIxH2IrCHJ+f4m1b9dmta5p7Xd8Ss76TKZE6TtkalGE=; b=fxaM636ETV3wvfFfyYphiM0ZxS8G5jlBhUbe8+PHji7rLUk/6jLSz4PfjJyO2RcvQI PTFkyy3JMqIYEp5ZG6/JwXRSH2mCpq6yKFTf8hNZhjNsv9nQprcB6LtqOCXsKY+j27wP bk8Wx52jZvs0Euj0uaUWxKWKy6BuhzHGIv5uVre7CU0M5fBgnwM2tVnRnsd8CUJrFpqq zaG9Z2KZQ/14oRY/x9TKLWXGIMpdIbICNplpGuqy4qGdLEmUyjeYLtqItj6RJpEXutsF VKQC4GHpiPzPI3gGQpY6p/gTLqliBMWyisvVLwBqcahEPo2RoftNAo4hWOJPKu7Lv226 PRRQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695224995; x=1695829795; 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=FIxH2IrCHJ+f4m1b9dmta5p7Xd8Ss76TKZE6TtkalGE=; b=v8WYXnMwKaTfTOruUgdKfq90Vl7sHhv+StTsxb+JRxCKz3k+E7F/nH+JoI3gNytUTE Es2PvMx3tf1A7QeZ5X0LNFAgXxWncqy0lMcg9Io78X5LUMFVV+B5Xf3ScV3SkrRTBsc6 rBhHuztJxz0jxnuxTY+ZPkDuo38QwNnwG+sodjZaNz0IovF2pGA7i0UUYg0m9J9SLKwW nAKhTJIN1D9cJbApx+P9jCMNj/FkksgC3R26rlirve4AucFmRta48SAVblYAi7jGZIpR hEc2RKFZdT0YbsjFObx1+z08lw5Gz/Ng8I5FrYGFcHK6zNHwaQ+20bH3M/1peuPxqVjz 8BcA== X-Gm-Message-State: AOJu0Yx1jQqAEh330KDMoNZIEaH8schepxvmaeNH6Mqmbi9T2t8kRPSH U2yvXZ6QXoOTCe64XF9HsrD9MSKoZQrTn2mXzJI= X-Google-Smtp-Source: AGHT+IGs8qM1TQGoLkeBsGUKrxBbfPT10V8mq6adxQkfTpImO+ObIoOqoFLQUUvz58OucWmqvoZ7SQ== X-Received: by 2002:a0d:d4cb:0:b0:59b:eedc:43da with SMTP id w194-20020a0dd4cb000000b0059beedc43damr2778440ywd.3.1695224994807; Wed, 20 Sep 2023 08:49:54 -0700 (PDT) Received: from localhost.localdomain ([2600:1700:20c0:a560:1d8e:3ea8:ad75:14a1]) by smtp.gmail.com with ESMTPSA id r2-20020a818102000000b0059a34cfa2a5sm3806348ywf.67.2023.09.20.08.49.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 20 Sep 2023 08:49:53 -0700 (PDT) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , David Young Subject: [PATCH 6/6] Section 6: Glossary Date: Wed, 20 Sep 2023 11:48:10 -0400 Message-ID: <20230920154817.617-7-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20230920154817.617-1-dave@youngcopy.com> References: <20230920154817.617-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 --- doc/guides/getting_started_guide/glossary.rst | 75 +++++++++++++++++++ 1 file changed, 75 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..7fcfe16f38 --- /dev/null +++ b/doc/guides/getting_started_guide/glossary.rst @@ -0,0 +1,75 @@ +.. 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. + +**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. + +**Bifurcated Driver** + +A driver model that splits functionality between kernel and userspace, often used in high-performance networking. + +**Clang-LLVM** + +A compiler toolchain that includes the Clang C compiler and LLVM linker, used for building DPDK on Windows. + +**contigmem Module** + +A module in FreeBSD that provides physically contiguous memory allocation used by DPDK. + +**DMA (Direct Memory Access)** + +A feature that allows hardware devices to access the main system memory directly, without involving the CPU. + +**EAL (Environment Abstraction Layer)** + +The layer within DPDK that abstracts environmental specifics and provides a standard programming interface. + +**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. + +**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. + +**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. + +**UIO (Userspace I/O)** + +A Linux kernel module that enables user-space applications to access hardware devices directly. + +**VFIO (Virtual Function I/O)** + +A kernel driver that allows a virtual machine to access physical devices directly, used in DPDK for device assignment. + +**VFIO Platform** + +A framework in Linux that allows exposing direct device access to userspace, in a secure, IOMMU-protected way. \ No newline at end of file