From patchwork Thu Nov 23 01:26:25 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Dave Young X-Patchwork-Id: 134545 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 2AB1D4339F; Thu, 23 Nov 2023 02:27:25 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 7178D42D89; Thu, 23 Nov 2023 02:27:10 +0100 (CET) Received: from mail-yw1-f170.google.com (mail-yw1-f170.google.com [209.85.128.170]) by mails.dpdk.org (Postfix) with ESMTP id A887142D66 for ; Thu, 23 Nov 2023 02:27:00 +0100 (CET) Received: by mail-yw1-f170.google.com with SMTP id 00721157ae682-5cc933f9219so908917b3.0 for ; Wed, 22 Nov 2023 17:27:00 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=youngcopy-com.20230601.gappssmtp.com; s=20230601; t=1700702819; x=1701307619; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=78Yn5i8ehISscfBlUdClNrI/spv0HhuYxBJLTMBPRx0=; b=gOFFBxmPCVevZN1vs6Gv0JWrPHFeGv5fhDBpGfzRHWq7bKnwQ+7lpzyoWfz3M4JqqF mzbU3BU73Fj6WtNlf179B3WHqYcDvH9NBPai/aFZfvs3lioLDT2eNoLtc+hiGIrKnWAj lv1ldR5vIlGNge7Noq/ZOQR7xefnJjhKjNTNsuZtFprgMy+9d+khTSWb6VSUzQ5Ai7zg OFTqppPEVYpktNDit2KyCpxLHEGHZOcdLg+CL+gdSHAKlx/ImVcz3oucCcu6Ww+ipg1H 5OqGQ6Ik2l37dvoZv0YnHSPcA2qqFp2sZT4BtsmIVEyH4iDfyXn816vbJUcalg04jVNl Fm/w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700702819; x=1701307619; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=78Yn5i8ehISscfBlUdClNrI/spv0HhuYxBJLTMBPRx0=; b=KY6XSLXCc0DWkJDog0ojqd/hJt6sMziQyIGhM5t/KVvxBLU1uGueeJPB5OOuzNYQpW mio1qt/tFWmOVmlSsOPZuBCdojqre7XResFXqeeiONXlj3az0yWZDiK6oN8yZxtfOgWO U784wSXFw5JvVE1i+T7gWO+4VUYNuf+rbjkqGtHzwS1DMX/PjCMF45k8f24zglCLAEsS A4OSVmP8evdsPgHs0LTNGzos530aunxBKKj/RJZEHxxnHPyGLknjW2FDjLUOVQ47j0h9 PwRrNI19vQ3/x2teehOA2nSqRR7G2M9xORaXBgyoGdJKMxCwGJSvwMSZgKTHYJytt3Gg YJFA== X-Gm-Message-State: AOJu0Ywo5oI1cmgJRBlL2zDLMNBVKAT4zaHsNFTFSnyX9VWOkkt8ttA3 crElFH3hi0W4z6vyUdKcQYsUFOdGbBRTOMpBNwc= X-Google-Smtp-Source: AGHT+IG6EfpjrZYV0dXLhooELOB1c8icV7v7QK86Z/rzh/pnXnkExhr1uPSDSQJ3+EKo43gy9c7hVA== X-Received: by 2002:a81:af1c:0:b0:5af:a690:e47f with SMTP id n28-20020a81af1c000000b005afa690e47fmr3149404ywh.5.1700702819198; Wed, 22 Nov 2023 17:26:59 -0800 (PST) Received: from localhost.localdomain ([2600:1700:20c0:a560:40f7:d2c:d53a:d071]) by smtp.gmail.com with ESMTPSA id j184-20020a0dc7c1000000b005a815346d95sm89832ywd.71.2023.11.22.17.26.57 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 22 Nov 2023 17:26:57 -0800 (PST) From: David Young To: dev@dpdk.org Cc: Bruce Richardson , Aaron Conole , David Young Subject: [PATCH v4 4/6] Section 4: Running Applications Date: Wed, 22 Nov 2023 20:26:25 -0500 Message-ID: <20231123012633.2005-5-dave@youngcopy.com> X-Mailer: git-send-email 2.41.0.windows.1 In-Reply-To: <20231123012633.2005-1-dave@youngcopy.com> References: <20231103040202.2849-1-dave@youngcopy.com> <20231123012633.2005-1-dave@youngcopy.com> MIME-Version: 1.0 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org --- .../getting_started_guide/run_apps/index.rst | 10 ++ .../run_apps/run_apps.rst | 118 ++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 doc/guides/getting_started_guide/run_apps/index.rst create mode 100644 doc/guides/getting_started_guide/run_apps/run_apps.rst diff --git a/doc/guides/getting_started_guide/run_apps/index.rst b/doc/guides/getting_started_guide/run_apps/index.rst new file mode 100644 index 0000000000..f033cac5f0 --- /dev/null +++ b/doc/guides/getting_started_guide/run_apps/index.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +Running Applications +==================== + +.. toctree:: + :maxdepth: 2 + + run_apps \ No newline at end of file diff --git a/doc/guides/getting_started_guide/run_apps/run_apps.rst b/doc/guides/getting_started_guide/run_apps/run_apps.rst new file mode 100644 index 0000000000..339d4c0a68 --- /dev/null +++ b/doc/guides/getting_started_guide/run_apps/run_apps.rst @@ -0,0 +1,118 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2025 Intel Corporation. + +.. _run_apps: + +Running Applications +==================== + +The following instructions apply to Linux, FreeBSD, and Windows. + +.. contents:: Table of Contents + :local: + +Running Applications on Linux and FreeBSD +----------------------------------------- + +Compiling and Running Sample Applications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To compile a sample application: + +1. Navigate to the application's directory in the DPDK distribution. +2. Execute the ``make`` command on Linux or ``gmake`` on FreeBSD. + +For instance, to compile the ``helloworld`` application: + +:: + + cd examples/helloworld + make # On Linux + gmake # On FreeBSD + +To run the application, use: + +:: + + ./build/helloworld -l 0-2 + +The ``-l`` option indicates the cores on which the application should run. + +Sample Applications Overview +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. **Hello World**: A basic application that prints a "hello world" message. +2. **Basic Forwarding**: A skeleton example of a forwarding application. +3. **Command Line**: Demonstrates the command line interface in DPDK. +4. **Ethtool**: Showcases the Ethtool API in DPDK. + +For a comprehensive list of sample applications and their guides, +refer to the `DPDK Sample Applications User Guides `_. + +EAL Parameters +^^^^^^^^^^^^^^ + +Every DPDK application is linked with the DPDK target environment’s +Environmental Abstraction Layer (EAL) library, which provides generic options. +Some of these options include: + +- ``-c COREMASK`` or ``-l CORELIST``: Specifies the cores to run on. +- ``-n NUM``: Number of memory channels per processor socket. +- ``--socket-mem``: Memory allocation from hugepages on specific sockets. + +For a detailed list of EAL options, +refer to the `EAL parameters section `. + +Running Without Root Privileges +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Refer to :ref:`running_dpdk_apps_without_root`. + +Running Applications on Windows +------------------------------- + +Running DPDK applications on Windows involves a few different steps. +This guide provides detailed instructions on how to run the helloworld example +application, which can be used as a reference for running other DPDK applications. + +Grant Lock Pages in Memory Privilege +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use of hugepages ("large pages" in Windows terminology) requires +``SeLockMemoryPrivilege`` for the user running an application. +This privilege allows the DPDK application to keep data in physical memory, +preventing the system from paging the data to virtual memory. +This can significantly improve the performance of your DPDK applications. + +To grant this privilege: + +1. Open Local Security Policy snap-in, either through Control Panel / Computer Management / Local Security Policy, or by pressing Win+R, typing ``secpol``, and pressing Enter. +2. Open Local Policies / User Rights Assignment / Lock pages in memory. +3. Add desired users or groups to the list of grantees. + +The privilege is applied upon the next logon. If the privilege has been granted to the +current user, a logoff is required before it is available. +More details can be found in the `Large-Page Support in MSDN `_. + +Running the helloworld Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After setting up the drivers, you can run the helloworld example to verify your setup. +Here are the steps: + +1. Navigate to the examples in the build directory:: + + cd C:\\Users\\me\\dpdk\\build\\examples + +2. Run the helloworld application:: + + dpdk-helloworld.exe -l 0-3 + +The output should display a hello message from each core, like this: + +:: + + hello from core 1 + hello from core 3 + hello from core 0 + hello from core 2