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