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