[4/6] Section 4: Running Applications

Message ID 20230920154817.617-5-dave@youngcopy.com (mailing list archive)
State Superseded, archived
Delegated to: Thomas Monjalon
Headers
Series docs: Unify Getting Started Guides |

Checks

Context Check Description
ci/checkpatch warning coding style issues

Commit Message

Dave Young Sept. 20, 2023, 3:48 p.m. UTC
  ---
 .../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
  

Comments

Ferruh Yigit Sept. 25, 2023, 11:32 a.m. UTC | #1
On 9/20/2023 4:48 PM, David Young wrote:
> ---
>  .../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.
>

This is not the 'examples' folder in the source code, and this is
already mentioned as 'in the DPDK distribution', but I wonder if this
requires a little more clarification.

Also this folder can be '<dpdk install dir>/share/dpdk/examples/' if
DPDK installed manually.



> +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:
> +
>

Should we mention here that running some applications requires root
privilege?



> +::
> +
> +    ./build/helloworld -l 0-2
> +
> +The ``-l`` option indicates the cores on which the application should run.
> +

Should we provide a link to the eal argument documentation, which
describes '-l' and more...

> +Sample Applications Overview
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +1. **Hello World**: A basic application that prints a "hello world" message.
>

'helloworld' sample is about core management, it distributes the work
(printing "hello world") to the cores provided in the argument list,
does it worth to mention this, not sure.
Otherwise it is not clear what just printing "hello world" is good for,
and why we have a sample like this.



> +2. **Basic Forwarding**: A skeleton example of a forwarding application.
>

"packet forwarding" ??
  

Patch

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 <https://doc.dpdk.org/guides/sample_app_ug/index.html>`_.
+
+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 <eal_parameters>`.
+
+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 <https://docs.microsoft.com/en-us/windows/win32/memory/large-page-support>`_.
+
+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