From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id E4DD34339F; Thu, 23 Nov 2023 02:27:00 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A2F9B42D55; Thu, 23 Nov 2023 02:27:00 +0100 (CET) Received: from mail-oi1-f173.google.com (mail-oi1-f173.google.com [209.85.167.173]) by mails.dpdk.org (Postfix) with ESMTP id 0162342D55 for ; Thu, 23 Nov 2023 02:26:56 +0100 (CET) Received: by mail-oi1-f173.google.com with SMTP id 5614622812f47-3b83d69c7c9so66097b6e.0 for ; Wed, 22 Nov 2023 17:26:56 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1700702815; x=1701307615; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=6U37Fuwa62g4bJCEmPfVtDjzlWmL3D7/b4zYt/7bxQQ=; b=tjjzjv0/unnUSgQumbpgn9lB5vpU0nkwf9P8KF+wJRNhDCVc3FoPYFQl+3PlQl5VBi p76DZnYfA83P9xSDZJooWUL7DGegeAVia0X4LVWNC33KUUwPkCrs82n+/XYHoqXhnEZ4 4J/+RNBgvJRrN+pobn69K1dTHiF2c3wMJqGRxLmE6lkGRpw6wFN9HHo9VA0Jwcshfu8L f7JIoqeAMWEKaSQ6UdNiHjfFSZwx/pRgc2e2DRqqoi+QWlWWiwvOsbp0JW05YnRoGg7i EdnS+aUzvQc32U/6VbsNL+G8pxAvg54LjZ75vMzCphwowOqD4JdDMxQMANEcNdMZwvLa FSog== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700702815; x=1701307615; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=6U37Fuwa62g4bJCEmPfVtDjzlWmL3D7/b4zYt/7bxQQ=; b=l9N1XnCF4t5zm9ufAPNlpW+5QxkAoZ8UMm+enOu9ZHu6QgybJdCmUn4e8DfnaVsY5Z Phm8Srj6WvRPhoRIjqvp2hvY3Dy2Kp6Fep34squ95oOwUpI807CTUur0tFdfpuFi1cEm hY5xsfCVM3mvvZMUC851bi/ygy6UusqtW8o1heKxl7gB+Iww8JosD6+5bQ2pRx4zTF+B +hvSFLbp6iDqZjVIod4nK/BrSIgMvk4dPDO/DSD7+n/uKjWZ3Iv2Fs5ty6ZVE5QE1D9M yVTYR+82UcSAWzHH20eHyKZwaZMJfisrVd8zDxLc0EeIl9HyMw9+yC/BuuEeHZIZDCy1 YgOA== X-Gm-Message-State: AOJu0YwWS8DKVTjuNl6cIoYL4eBN8jK1iJ/ExiMG3ymwXfmYsxd7KXuZ 0tj2lXN89sh3Oz+q0kr3MfC6dDb3hh0JNINl/Jk= X-Google-Smtp-Source: AGHT+IG2iVoJzkn0BTQ+GtgMRNQzos+Pq0jKQXtCFQbUoEkZ7IZ1IzXIZCZlyIJ2fUDKrr5V9A/QrA== X-Received: by 2002:a05:6358:338b:b0:16b:96fc:650e with SMTP id i11-20020a056358338b00b0016b96fc650emr5004947rwd.3.1700702815136; Wed, 22 Nov 2023 17:26:55 -0800 (PST) Received: from localhost.localdomain ([2600:1700:20c0:a560:40f7:d2c:d53a:d071]) by smtp.gmail.com with ESMTPSA id j184-20020a0dc7c1000000b005a815346d95sm89832ywd.71.2023.11.22.17.26.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 22 Nov 2023 17:26:53 -0800 (PST) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young Subject: [PATCH v4 1/6] Section 1: Introduction Date: Wed, 22 Nov 2023 20:26:22 -0500 Message-ID: <20231123012633.2005-2-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20231123012633.2005-1-dave@youngcopy.com> References: <20231103040202.2849-1-dave@youngcopy.com> <20231123012633.2005-1-dave@youngcopy.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Added link to Getting Started Guide in index.rst Moved run_apps.rst to GSG index Removed run_apps/index.rst - no longer needed Added run_apps.rst to index -Reformatted the introduction paragraph for better readability. -Clarified that the guide provides basic step-by-step instructions with OS-specific instructions included only where necessary for each operating system. -Emphasized that by the end of this guide, the user should have a solid understanding of how to implement and use DPDK in their networking projects, regardless of the operating system they are using. Moved run_apps into GSG root directory --- doc/guides/getting_started_guide/index.rst | 18 +++ doc/guides/getting_started_guide/intro.rst | 13 ++ doc/guides/getting_started_guide/run_apps.rst | 114 ++++++++++++++++++ doc/guides/index.rst | 1 + 4 files changed, 146 insertions(+) create mode 100644 doc/guides/getting_started_guide/index.rst create mode 100644 doc/guides/getting_started_guide/intro.rst create mode 100644 doc/guides/getting_started_guide/run_apps.rst diff --git a/doc/guides/getting_started_guide/index.rst b/doc/guides/getting_started_guide/index.rst new file mode 100644 index 0000000000..3d7c0eb6ee --- /dev/null +++ b/doc/guides/getting_started_guide/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _getting_started_guide: + +Getting Started Guide +===================== + +.. toctree:: + :maxdepth: 2 + :numbered: + + intro + install_and_build/index + system_setup + run_apps + appendix/index + glossary diff --git a/doc/guides/getting_started_guide/intro.rst b/doc/guides/getting_started_guide/intro.rst new file mode 100644 index 0000000000..3560d705d0 --- /dev/null +++ b/doc/guides/getting_started_guide/intro.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. + +Introduction +============ + +Welcome to the getting started guide for the Data Plane Development Kit (DPDK) covering Linux, +FreeBSD, and Windows. DPDK is a set of libraries and drivers that accelerate packet processing +and allow the user to create high-performance networking applications. + +The guide is structured to provide basic step-by-step instructions with OS-specific instructions included only where necessary for each operating system. +By the end of this guide, you should have a solid understanding of how to implement +and use DPDK in your networking projects, regardless of the operating system you are using. diff --git a/doc/guides/getting_started_guide/run_apps.rst b/doc/guides/getting_started_guide/run_apps.rst new file mode 100644 index 0000000000..d9ef1a6f96 --- /dev/null +++ b/doc/guides/getting_started_guide/run_apps.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _run_apps: + +Running Applications +==================== + +Running Applications on Linux and FreeBSD +----------------------------------------- + +Compiling and Running Sample Applications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To compile a sample application: + +1. Navigate to the application's directory in the DPDK distribution. +2. Execute the ``make`` command on Linux or ``gmake`` on FreeBSD. + +For instance, to compile the ``helloworld`` application: + +:: + + cd examples/helloworld + make # On Linux + gmake # On FreeBSD + +.. note:: + If DPDK is not installed system-wide, + you can compile the examples as part of the DPDK build itself. + If DPDK is not installed system-wide, you can compile the examples as part of the DPDK build + itself. Use the meson build option ``-Dexamples=helloworld`` to compile specific examples + or ``-Dexamples=all`` to compile all examples. + +To run the application, use: + +:: + + ./build/helloworld -l 0-2 + +The ``-l`` option indicates the cores on which the application should run. +This command runs the `helloworld` application on cores 0, 1, and 2. + +Sample Applications Overview +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For a comprehensive list of sample applications and their guides, +refer to the `DPDK Sample Applications User Guides `_. + +EAL Parameters +-------------- + +Every DPDK application is linked with the DPDK target environment’s +Environmental Abstraction Layer (EAL) library. The most essential EAL option is ``-l CORELIST``, which specifies the cores the application should run on. For example: + +- ``-l 1-3`` to run on 3 cores: 1, 2, and 3. +- ``-l 8,16`` to run on 2 cores: 8 and 16. +- ``-l 1-7,9-15`` to run on 14 cores: 1 through 7 and 9 through 15. + +Please refer to the `EAL parameters section ` section for a more comprehensive list of options. + +Running Without Root Privileges +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Refer to :ref:`running_dpdk_apps_without_root`. + +Running Applications on Windows +------------------------------- + +Running DPDK applications on Windows involves a few different steps. +This guide provides detailed instructions on how to run the helloworld example +application, which can be used as a reference for running other DPDK applications. + +Grant Lock Pages in Memory Privilege +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use of hugepages ("large pages" in Windows terminology) requires +``SeLockMemoryPrivilege`` for the user running an application. +This privilege allows the DPDK application to keep data in physical memory, +preventing the system from paging the data to virtual memory. +This can significantly improve the performance of your DPDK applications. + +To grant this privilege: + +1. Open Local Security Policy snap-in, either through Control Panel / Computer Management / Local Security Policy, or by pressing Win+R, typing ``secpol``, and pressing Enter. +2. Open Local Policies / User Rights Assignment / Lock pages in memory. +3. Add desired users or groups to the list of grantees. + +The privilege is applied upon the next logon. If the privilege has been granted to the +current user, a logoff is required before it is available. +More details can be found in the `Large-Page Support in MSDN `_. + +Running the helloworld Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After setting up the drivers, you can run the helloworld example to verify your setup. +Here are the steps: + +1. Navigate to the examples in the build directory:: + + cd C:\\Users\\me\\dpdk\\build\\examples + +2. Run the helloworld application:: + + dpdk-helloworld.exe -l 0-3 + +The output should display a hello message from each core, like this: + +:: + + hello from core 1 + hello from core 3 + hello from core 0 + hello from core 2 diff --git a/doc/guides/index.rst b/doc/guides/index.rst index 244b99624c..51a47d3a51 100644 --- a/doc/guides/index.rst +++ b/doc/guides/index.rst @@ -7,6 +7,7 @@ DPDK documentation .. toctree:: :maxdepth: 1 + getting_started_guide/index linux_gsg/index freebsd_gsg/index windows_gsg/index -- 2.41.0.windows.1