From patchwork Fri Nov 3 04:01:47 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 133799 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 A0A5943274; Fri, 3 Nov 2023 05:02:26 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 4F69740DF5; Fri, 3 Nov 2023 05:02:22 +0100 (CET) Received: from mail-yw1-f182.google.com (mail-yw1-f182.google.com [209.85.128.182]) by mails.dpdk.org (Postfix) with ESMTP id 1F84B4021E for ; Fri, 3 Nov 2023 05:02:21 +0100 (CET) Received: by mail-yw1-f182.google.com with SMTP id 00721157ae682-5b4e3284e68so2690107b3.1 for ; Thu, 02 Nov 2023 21:02:21 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1698984139; x=1699588939; 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=yFBTvZcAzKyzh9+QV/9xdwbVNKknh6k434Z5wlWKCo8=; b=p8YFq1D7qYcD4sPDTdMcsLcPMs2K8X2LCAl7Bc2HfmcwzgMFYPOKIMCULrh+hfPJco 4vyQM2Y38EZA1U8qcDtWcZmB0mQvoURq9BHZZsmUPZpwynIR7ew+2pail9NUAB645AS4 JvIagJcD3NSHo2wDLFjRZdwPm1l8Bw9UtYrNvtmP04cHD7dTvySHeVqhIaOpVt2Zwgsu zKQSHodk0+vkWXiZ3jgIJrqTy43dWUuiJY/9GmvCZWL0gbnzj/s/0VpjrQnokKP6JOPW nb4paaOZEVt2B8+bBw/kDpAkB5rZnvDl61LwT7oh0s34C0L8dBaWz2B/3p6I4DRHRqXf jdnA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1698984139; x=1699588939; 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=yFBTvZcAzKyzh9+QV/9xdwbVNKknh6k434Z5wlWKCo8=; b=SeqlJfcfHgsE1+vm2L/s7nflUhgKAZA2H7VeUje8XX9RB2wHspZVq2Meq0uruk0fcN L/1MlnttcModofHKm+9ioSd1D34zaZ10vxNACnwE6RBe18o/sZ7LfSAdFNTaMq5UpOhP YekXZQvaHw9nLIdJR3v29Chb/o1OUH9EuOpnWgtq+HDVWCe0e9/IBURu5ISXXQGF0YvA d/BIwbvPEaL2nOHcs/ch95eLnJYAPNnsBgPGHDUmtQaAriewGKqVkatO5CYZU9srv8UP 1vgL6d3M1YKbHGd1TVXQhmNtzp2VvKtmzJ8wAwj3mmr0SFR4NbgWLa3kmcyOvpW070yw GwDg== X-Gm-Message-State: AOJu0Yx8HtMew5swMVeJ4tAKSpq5SOg2pyGpVnKJXcqW5cwtMjARpTow PF2oJsPOxiZLkRURDpIiwpL12tGA0XZhDamKAXQ= X-Google-Smtp-Source: AGHT+IH+rzQzyEdKvui3UsssFrjOPS+5ERGaN3zYa60uv35TKiFeWZa9YQvfv0SLH+M2OlBQERnUig== X-Received: by 2002:a05:690c:450c:b0:5af:778e:d53b with SMTP id gt12-20020a05690c450c00b005af778ed53bmr16703696ywb.0.1698984139099; Thu, 02 Nov 2023 21:02:19 -0700 (PDT) Received: from localhost.localdomain ([2600:1700:20c0:a560:c076:581e:323d:c06e]) by smtp.gmail.com with ESMTPSA id x64-20020a817c43000000b0059b1f6d1959sm493958ywc.101.2023.11.02.21.02.18 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 02 Nov 2023 21:02:18 -0700 (PDT) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young Subject: [PATCH v3 1/7] Section 1: Introduction Date: Fri, 3 Nov 2023 00:01:47 -0400 Message-ID: <20231103040202.2849-2-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20231103040202.2849-1-dave@youngcopy.com> References: <20231103040202.2849-1-dave@youngcopy.com> MIME-Version: 1.0 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 Edited copy to be simpler based on feedback. --- doc/guides/getting_started_guide/intro.rst | 13 +++++++++++++ 1 file changed, 13 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..538b3bacec --- /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 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. \ No newline at end of file From patchwork Fri Nov 3 04:01:48 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 133800 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 4853F43274; Fri, 3 Nov 2023 05:02:33 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 76742427E0; Fri, 3 Nov 2023 05:02:24 +0100 (CET) Received: from mail-yb1-f171.google.com (mail-yb1-f171.google.com [209.85.219.171]) by mails.dpdk.org (Postfix) with ESMTP id DB5A840EDC for ; Fri, 3 Nov 2023 05:02:22 +0100 (CET) Received: by mail-yb1-f171.google.com with SMTP id 3f1490d57ef6-d9fdc712b8fso411004276.1 for ; Thu, 02 Nov 2023 21:02:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1698984141; x=1699588941; 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=T0s5PJymRqJSHAfx7IZl3Fx9/NsUdw56W3yoatr8kUM=; b=Nr2dJ12XhlKnpIvhvQyUQQSCU1Q/kUTCcCW1uV9L9i1j8n6NtxRuryAUjaegv5amQh OH1K3b2iQp55/cdJAEj6/Ufny4FLmiVAX/f6JGPC6iJoKbePr/TyA9hp79SA8YJm1Ihy 4SFfOPeyV9Hi/ouSuljtvXlkbyV8GduLqs0pInLFynf4eLqpgsnGZOebuPDAbIbT8DEd FLyTRjkfyPHlVGWwxESfL+fnMMyMPX3x4MsiREhX7r6v7lGM7nzz5Fd0o4ynkMv6ciC0 mbcmZK1s0mx1/1lMD3uX5vh4zekk9hddR+Y5mq+XnH2+lZNZu+4vbk8SDQ5iIGwlXiNe +1hA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1698984141; x=1699588941; 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=T0s5PJymRqJSHAfx7IZl3Fx9/NsUdw56W3yoatr8kUM=; b=uaXKyWgcYFv/Vq6oJyNySgqqSVc1ykY2Gk3ZFSNc1XndIY0V9O6Jjnh1NB6P3siorp qZuTacnQVMSPYAv1P0IZf3cbvX72g8o3BvRtG3kdBW0VsIH7krPrBrgndyluuiD/NXN5 U1pz2n0PrvkaejYwKO/Kbjee53LLzadvRx7uZBRo7iwZh0gcYg3Hg27d8zIxIxbaBREh a5GBn14BMMtFH3f6PARCGQ76O/6HCrGxy8P6QvoPV0HDcas7oKOPJItxw3dA6U8VpD01 CwuORp4p8srBWfrcYqtf6lA090RsvGtUFEMatj4FeqjlCpClSZnkwAh+a2Cx+ZtSEaIR BmRA== X-Gm-Message-State: AOJu0Yw1OZ0kXWJg3wEMZcQXSd1uhpvCEnCkk9g11UCA4ow8MJnrAZRF ZdpzRe0b0qOwnTs8Pi26uouynedlgfnDyFOTi0U= X-Google-Smtp-Source: AGHT+IHjeyRqgTJR6qC82XJXu3ueFtYBCMSAZpk2Q3utzItwrDTORQNxbPKEubOu0i8rNzoK6uv69w== X-Received: by 2002:a05:690c:4803:b0:5b3:1c41:733f with SMTP id hc3-20020a05690c480300b005b31c41733fmr10236897ywb.5.1698984141089; Thu, 02 Nov 2023 21:02:21 -0700 (PDT) Received: from localhost.localdomain ([2600:1700:20c0:a560:c076:581e:323d:c06e]) by smtp.gmail.com with ESMTPSA id x64-20020a817c43000000b0059b1f6d1959sm493958ywc.101.2023.11.02.21.02.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 02 Nov 2023 21:02:19 -0700 (PDT) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young Subject: [PATCH v3 2/7] Section 2: Install and Build DPDK Date: Fri, 3 Nov 2023 00:01:48 -0400 Message-ID: <20231103040202.2849-3-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20231103040202.2849-1-dave@youngcopy.com> References: <20231103040202.2849-1-dave@youngcopy.com> MIME-Version: 1.0 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 Section 2: Install and Build DPDK - Updated based on feedback; Merged windows_install_build.rst into building_from_sources.rst; Updated Meson 0.57.x to be required for Windows. --- .../building_from_sources.rst | 174 ++++++++++++++++++ .../install_and_build/index.rst | 14 ++ .../installing_prebuilt_packages.rst | 54 ++++++ 3 files changed, 242 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..fd7e2e9b30 --- /dev/null +++ b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst @@ -0,0 +1,174 @@ +.. 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 Linux, FreeBSD, and Windows. 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 +^^^^^ + +Common Tools for All Distributions: + +.. code-block:: bash + + sudo apt install gcc pkg-config python3 meson ninja pyelftools + +Alpine + +.. code-block:: bash + + sudo apk add alpine-sdk bsd-compat-headers + +Debian, Ubuntu, and derivatives + +.. code-block:: bash + + sudo apt install build-essential + +Fedora and RedHat Enterprise Linux RHEL + +.. code-block:: bash + + sudo dnf groupinstall "Development Tools" + +openSUSE + +.. code-block:: bash + + sudo zypper install -t pattern devel_basis python3-pyelftools + +FreeBSD +^^^^^^^ + +Common Tools for FreeBSD: + +.. code-block:: bash + + pkg install gcc 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. + +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. +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-.tar.xz + tar -xvf dpdk-.tar.xz + cd dpdk- + +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- + +Building DPDK +------------- + +Linux and FreeBSD +^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + meson build + ninja -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`. \ No newline at end of file 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 Fri Nov 3 04:01:49 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 133802 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 B1D7243274; Fri, 3 Nov 2023 05:02:52 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 2589B42DBB; Fri, 3 Nov 2023 05:02:27 +0100 (CET) Received: from mail-yw1-f175.google.com (mail-yw1-f175.google.com [209.85.128.175]) by mails.dpdk.org (Postfix) with ESMTP id C914E40265 for ; Fri, 3 Nov 2023 05:02:24 +0100 (CET) Received: by mail-yw1-f175.google.com with SMTP id 00721157ae682-5b4e3284e68so2690217b3.1 for ; Thu, 02 Nov 2023 21:02:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1698984143; x=1699588943; 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=Roj71ag7umjzgm1B3X7B2kllVR+d5CGQuCFAUNYuBeiYIW0h7MUb0yTI83VZbjsP3Y 1v/EH23G5+WzpQ0AcrWP2CexS6CM7Os1R/fSJzBl1EuYAge/BTWqXOZ/568spbe/c5qR xr7+Z0HDhL5PcLMNNLtfpbhVHQgyzwKCgt033h8xgzs93pnESD+1pHZiLlE03Dq8H4BQ weY5f5dYSWBhzJOp9SiIHVQFnvaFOkJrDMXi4cljMRinPY+6LzGWfUJbbu0/2NW0AJlG WyWOu9qCGOhFfkXzt9sToQeZIswKwpdzokOCZTMUkisn3wm2KpxKNDQy0vGmbJdf4mmI i+4w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1698984143; x=1699588943; 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=uu8y9DRedwKh14zdFhsbUwrJHFo3VAuO5wkSSnWBKsOpmxOIPXqpX82w0kT7RafZZ3 yI7pmok/MdhA7IcWLW77V3rMLa6yaPGwJgbu/UM1AX9qehtwyCsTlrzQl5AEABSLtJzm oNBbX2RLd+vcwh0J7YPP7Eguq2VGhM+9ztqyr49AVCLtqKHjre8lqzm7OnNJNPupEz7W nn079aafLVUO3flwTIu9mD4eYzTio9Ci3zyipWtgk32Ven/+YMoyh7J+av/zjnYm8QV2 zZ/zSJ6PUUQkoVaVmbItCKUlXGcBxeOZMr+J6Mbaf0KVAJOSbHPMcymgrWRW26Y4du5v aEbw== X-Gm-Message-State: AOJu0YxQvdexU7oUhc9hhMnp3P84si4qIIPbfs9rjbjP8S1CcDjcII+R Z4wEEUZR+PVLDk1pFL4KnrW/0L9CsHvUsgCgeJU= X-Google-Smtp-Source: AGHT+IE8HNfOgJUgGCRDJW5G0U+D/ysAZ3ztsII/yYmLOnUv/ZBeeARDDkWKwqNsmJ7oN9Hdyd595A== X-Received: by 2002:a81:7909:0:b0:5a7:b972:a5bd with SMTP id u9-20020a817909000000b005a7b972a5bdmr14111790ywc.3.1698984141772; Thu, 02 Nov 2023 21:02:21 -0700 (PDT) Received: from localhost.localdomain ([2600:1700:20c0:a560:c076:581e:323d:c06e]) by smtp.gmail.com with ESMTPSA id x64-20020a817c43000000b0059b1f6d1959sm493958ywc.101.2023.11.02.21.02.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 02 Nov 2023 21:02:21 -0700 (PDT) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young Subject: [PATCH v3 3/7] Section 3: Setting up a System to Run DPDK Applications Date: Fri, 3 Nov 2023 00:01:49 -0400 Message-ID: <20231103040202.2849-4-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20231103040202.2849-1-dave@youngcopy.com> References: <20231103040202.2849-1-dave@youngcopy.com> MIME-Version: 1.0 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 Fri Nov 3 04:01:50 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 133801 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 9CDF043274; Fri, 3 Nov 2023 05:02:43 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id EDE3B42D9F; Fri, 3 Nov 2023 05:02:25 +0100 (CET) Received: from mail-yb1-f169.google.com (mail-yb1-f169.google.com [209.85.219.169]) by mails.dpdk.org (Postfix) with ESMTP id DF8C8427DD for ; Fri, 3 Nov 2023 05:02:23 +0100 (CET) Received: by mail-yb1-f169.google.com with SMTP id 3f1490d57ef6-d9b720b5398so278851276.0 for ; Thu, 02 Nov 2023 21:02:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1698984143; x=1699588943; 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=eQ+FWDCbZluINf+PPUwXJAoLw9mx7J4X/p4M8EVIZ/ASGDl18ppg35VdCdxYhbdnnL dK5J/MLa9hWsLvQWnLod2ZpsEmbeD4fWcGUhsAO1nYUNmR0EP8vUe2/LsDK3gwvxmf7F end2LGcPkEMaFkTyNbwgtq4qL0mUaod7+uV8ZZH3z7yRTCxutW01FhzHxhYrNp3WixuJ UPS17TOmfC90OrMvA1DtnGTAfuADYwapn/03P3GrRpbWgipaIo9mF5UXsi0hSSjv9yMH 8eTNhJ3yOXG+gjGRjhL7f0rjebcD0leiPkNxDFEqyQu7ffCfPeZhPbPpC7r+cy7j43BX 59Mg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1698984143; x=1699588943; 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=Y8M069p/LwVRkvI1KUyD3pm3ZZ1s9xjuYt8bmPYL5gmcbp0QQm7Hf7+12YgS7amAlt NcabcYtaWFkFmtNhzEuXfBgHp3fdRqepWgOPEdLelegGB1ajCafgvm4/om4bJBg/EP/R 1XmelrYMKsD67LRGOLs9CdpFiu0O/z9R7eS6dVrLk81ulGOZ6qsU+2K/RaWGuiinZUbX ZiL+IaYycYLMnKxY39jzkrkZIC0vScFxE8Apk1fHXR2HiaHuzp329w14y/Pe7PKaSjAu CRGMZg/YcdEDQo2ghArGRZcjGJq9VnwO88N9qesI6kBc1NTFkVro1qLkKW4ZNPyj2uHG ICgA== X-Gm-Message-State: AOJu0YzS7Md53McJ9h+nmAO92LOIocPeeXu1GjJHylJ2FMMfe8Z7Xiuo f8u3C19xQ6P+At5M5OVKM+HR9CY3c9uehxvSCnQ= X-Google-Smtp-Source: AGHT+IG9K+HIhgdQ/z/q+TytXSqZmGRH8EnyPydU3krxmOY9p91w7bDW0wGpHfYiiH4zjdC7Hy0fDQ== X-Received: by 2002:a05:690c:23c4:b0:5af:a690:e47f with SMTP id do4-20020a05690c23c400b005afa690e47fmr17421898ywb.5.1698984142857; Thu, 02 Nov 2023 21:02:22 -0700 (PDT) Received: from localhost.localdomain ([2600:1700:20c0:a560:c076:581e:323d:c06e]) by smtp.gmail.com with ESMTPSA id x64-20020a817c43000000b0059b1f6d1959sm493958ywc.101.2023.11.02.21.02.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 02 Nov 2023 21:02:22 -0700 (PDT) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young Subject: [PATCH v3 4/7] Section 4: Running Applications Date: Fri, 3 Nov 2023 00:01:50 -0400 Message-ID: <20231103040202.2849-5-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20231103040202.2849-1-dave@youngcopy.com> References: <20231103040202.2849-1-dave@youngcopy.com> MIME-Version: 1.0 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 Fri Nov 3 04:01:51 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 133803 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 6926C43274; Fri, 3 Nov 2023 05:03:00 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 625B842DC3; Fri, 3 Nov 2023 05:02:28 +0100 (CET) Received: from mail-yb1-f176.google.com (mail-yb1-f176.google.com [209.85.219.176]) by mails.dpdk.org (Postfix) with ESMTP id 25A4640265 for ; Fri, 3 Nov 2023 05:02:25 +0100 (CET) Received: by mail-yb1-f176.google.com with SMTP id 3f1490d57ef6-da34f90f6e3so417998276.0 for ; Thu, 02 Nov 2023 21:02:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1698984144; x=1699588944; 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=hP2mlnHMzYOLwlmjuTAafhxs7IMf9obw1S6qAmbN/cSnuqdlNzL5VuCwj2vt/oz0Ac Lp0cF4oVED3zzz6/0p+VDwC6pA+dNINo0qnXUoHK0H/YsklqDq+NW40DWjMOqZDNtFH4 oX88yaxuCAUgkwFJV2OWz8nqMaNXBoJ63a0X5Qw8dih5uDdc9z0W5C4wx0zNuDHTxz1F NVzKfm0VBEUocucAvBXVkf1aLIg9t+cJBzTD8gXBmmKayyVj74hfT3iOSRfAeRde43PT ywfMCHIgG9sS6MQ5LVk02YcUZxo11XUrC71iJAD4lIZSWZEEBXu/m646lGhtSRJAY25I 16Kw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1698984144; x=1699588944; 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=G/5t3AokV4YN3FkdakZYA+nJuQddP5gQTMwzzqyw4V1mhO89Ie0q59W5yhlLgNGxTO fafcS3odHWzuQc9JZws7gIwAQbp5qB/wiI5857B2ywosBE5PJIAABAa32gwq8G22cpt1 DWO21bWJhvu1j33cW/wGWfFaZ4AMdqjIDo3AloFxhNnsC8LRuMIxVFsn2d2YtQevuY4o HOh2YhifQ2f8KsAwd6JOKSoUpQkOJ5PMGMk5zXv6XcWtUbv5peADiQqlkqWRgi9BFLVQ 0aBeM1d0njw8lLT8n9zkQovOck3yvuoJP3eTi288//3R4+KJBkOKrDzSnDSWk8qxmr5K 15jA== X-Gm-Message-State: AOJu0YyTU0TFzcYbSeSwXGvN2AKMIB2UmcHKeAF34mITcui16EBEUBwY FVRJE5qIoRJPrXHbuIl1kNWozJxyVLebBTUUJnU= X-Google-Smtp-Source: AGHT+IHcuo4AkNzKssegQI//Z1tOT3ACZi9hN96eBUL/j3/VdVxBz8vyCVXXrbMrFJ+HC64jOm7Rcg== X-Received: by 2002:a05:690c:4803:b0:5b3:1c41:733f with SMTP id hc3-20020a05690c480300b005b31c41733fmr10237007ywb.5.1698984143873; Thu, 02 Nov 2023 21:02:23 -0700 (PDT) Received: from localhost.localdomain ([2600:1700:20c0:a560:c076:581e:323d:c06e]) by smtp.gmail.com with ESMTPSA id x64-20020a817c43000000b0059b1f6d1959sm493958ywc.101.2023.11.02.21.02.23 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 02 Nov 2023 21:02:23 -0700 (PDT) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young Subject: [PATCH v3 5/7] Section 5: Appendix Date: Fri, 3 Nov 2023 00:01:51 -0400 Message-ID: <20231103040202.2849-6-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20231103040202.2849-1-dave@youngcopy.com> References: <20231103040202.2849-1-dave@youngcopy.com> MIME-Version: 1.0 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 Fri Nov 3 04:01:52 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 133804 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 9066843274; Fri, 3 Nov 2023 05:03:10 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id ED33B42D9A; Fri, 3 Nov 2023 05:02:29 +0100 (CET) Received: from mail-yb1-f180.google.com (mail-yb1-f180.google.com [209.85.219.180]) by mails.dpdk.org (Postfix) with ESMTP id 63D0542DBB for ; Fri, 3 Nov 2023 05:02:26 +0100 (CET) Received: by mail-yb1-f180.google.com with SMTP id 3f1490d57ef6-d9fdc712b8fso411021276.1 for ; Thu, 02 Nov 2023 21:02:26 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1698984145; x=1699588945; 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=Iq8Tzy/xxeELD24QoVg49jg2s4gCTDtLBnpYJXaBu8w=; b=qxFjZxnRAOm4ddZUD4Mhg7jFvVQ+KNvS4FiCWUsTbv/JI6XWoWFu+KxSOfkNpCUvoR pLDqdbD/rsPYJzNrEjmHDWpEtqso1KGSOBV5j9PIPlQyinObLSV2fmlRXKr6exE+QNLJ WqmWhRvmd58VtSMfBypYJwnrAcNKtDxO6B/6aAwXjK5gxjSpd/OYmlm+3wHw+H+7pwGe 8zj4t1SwTwAEZy1C3FM1jfHTYCZdfH+9s2EUd/ZxBQgQ1ClfhvhohSaSSufn7Dgv93K0 qsBE3SX/Ir/xEFuYFXlFScF4M8OmFkRjVn+WvuCT+oJX/JxCnLRIUi4Doujo8+8/zHWJ 4Q1Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1698984145; x=1699588945; 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=Iq8Tzy/xxeELD24QoVg49jg2s4gCTDtLBnpYJXaBu8w=; b=lqoI90gjD+1eEpir9tOOOWB2hE1yft3nV4EIL6BHmmi46lyoi3XcR49vhfoGJBbCAE WrVvImvxWoYFpUokdp9DipTgGVOhRGjBHpAjaSn7ySSu+eNdEySC68eNDuDSEV5A9/t+ e6aoRORP3c1EUtWgR/cWYSMyhpHppcWYoY2nlMevRCmA3WeOir4IUE4xigTpbCvNC/gD xMU7mdHZkX1uWxadeHhfTD+zh/Vmemeao0oKA2vYHFcVuv3apmxsbtcUduGCgfHaMiVd MsJCeIrlKbrthHkFRRRAXLwkLohiq1oUdXu2/7VK7VAzzKP8NbQj/Lg24EqDjyI++HJ/ 2xUA== X-Gm-Message-State: AOJu0YybhS5aWEYXYYp8hUR9bOfZBVYsSwrjRFDGlUqD3+Evl8JtdASn uoIn66zrXeuRLlqAuDIPy8wJYLNVIL6G1p51jpI= X-Google-Smtp-Source: AGHT+IGV23RnX8z49rMXu4BX1+AUGiry5VWqTVSpgzdUKGxbHCbdHs++kICpMG1b9CbDFz4IS4ZlyQ== X-Received: by 2002:a05:690c:4502:b0:5a7:ba54:5127 with SMTP id gt2-20020a05690c450200b005a7ba545127mr13499235ywb.3.1698984145098; Thu, 02 Nov 2023 21:02:25 -0700 (PDT) Received: from localhost.localdomain ([2600:1700:20c0:a560:c076:581e:323d:c06e]) by smtp.gmail.com with ESMTPSA id x64-20020a817c43000000b0059b1f6d1959sm493958ywc.101.2023.11.02.21.02.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 02 Nov 2023 21:02:24 -0700 (PDT) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young Subject: [PATCH v3 6/7] Added link to Getting Started Guide in index.rst Date: Fri, 3 Nov 2023 00:01:52 -0400 Message-ID: <20231103040202.2849-7-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20231103040202.2849-1-dave@youngcopy.com> References: <20231103040202.2849-1-dave@youngcopy.com> MIME-Version: 1.0 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/index.rst | 1 + 1 file changed, 1 insertion(+) 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 Fri Nov 3 04:01:53 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 133805 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 C6B5143274; Fri, 3 Nov 2023 05:03:17 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 30A9A42DC5; Fri, 3 Nov 2023 05:02:31 +0100 (CET) Received: from mail-yb1-f182.google.com (mail-yb1-f182.google.com [209.85.219.182]) by mails.dpdk.org (Postfix) with ESMTP id BA3E342DC3 for ; Fri, 3 Nov 2023 05:02:27 +0100 (CET) Received: by mail-yb1-f182.google.com with SMTP id 3f1490d57ef6-da326fc942aso371599276.1 for ; Thu, 02 Nov 2023 21:02:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1698984146; x=1699588946; 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=13xL9Ij2mAmDEUMAkgPZx8NYXwSSG88lMPPXJfxlKmibV8phCU2DjFhYooE8pUIcsL IQXc0hznvRdhSwC4eZHjFyjGDc+0e1CNPIL4Tw16n6VH1+FnCWZAjatLMWzaFg+0pkUZ R1ZEZfjBr42NqE/tLuG60KDYDDW0pCqSeAHpH3b6i2jdA8kVUCqWo7WvNaMiFJaXfol3 x4jvaMuKyEBmA+4eY6yqthRpnf49u9HmMB6x8Wpya/I0o4VK0PDYo+rSGBsCgnrj5oZt qwTNpF/HCOJzWLojG6tBLwvTYbTofeYwk8rlyPPhDT33X2k8Jjje0ir2JD5XAJjSt0Bh +XCg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1698984146; x=1699588946; 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=dpu1VsMWrHaMpJZx1ob0SAajhqeIsxX1zs7Z/sS08DffubuEcKxLaHYkqd9i2SuqP9 g84UEwnS2FFkXAgpHSCYgV3NGRKGaCtPE3v8mxjKwPkiI6BTiAB6XvSII98WB+ddtf4s tkFX+XPXYLGetf+M1k2d9xS9DOGFC7Tnz03Jqy/x96uGZ7xBrRg3krKYUHt4TO6lL4Ou I3PRG2II1CvVJf20RUbSf0MDq7bcM2/22fCfh51AdgX0d4MxreSH/yOzlo4EYS17d8zV 7VHfWwirrGqm2e7TPFpd8cPBg1xYCz+BI6u5sQvtq41j1nr18dZKKlMfJo6Zou7Kn+2u /k1g== X-Gm-Message-State: AOJu0YzZjusYFLMEqCqTrM2mko1sHkUckOGpuuf3YZDoMcndKpqP5PG8 OExAdBjBiQnPD1ssIYs/TcTKVNwpFQRkJTluxr4= X-Google-Smtp-Source: AGHT+IEwMZx+CsGUF19nWyH4nVjpGh6fju05M43oxkPhIVUKcx3PaWcMHerGbIJ4cARJX94t6zkfbw== X-Received: by 2002:a05:690c:eca:b0:5a7:da7e:effa with SMTP id cs10-20020a05690c0eca00b005a7da7eeffamr16775794ywb.5.1698984146370; Thu, 02 Nov 2023 21:02:26 -0700 (PDT) Received: from localhost.localdomain ([2600:1700:20c0:a560:c076:581e:323d:c06e]) by smtp.gmail.com with ESMTPSA id x64-20020a817c43000000b0059b1f6d1959sm493958ywc.101.2023.11.02.21.02.25 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 02 Nov 2023 21:02:25 -0700 (PDT) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young Subject: [PATCH v3 7/7] Section 6: Glossary Date: Fri, 3 Nov 2023 00:01:53 -0400 Message-ID: <20231103040202.2849-8-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20231103040202.2849-1-dave@youngcopy.com> References: <20231103040202.2849-1-dave@youngcopy.com> MIME-Version: 1.0 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