Re: [PATCH v3 4/7] Section 4: Running Applications

[Bruce Richardson <bruce.richardson@intel.com>]

On Fri, Nov 03, 2023 at 12:01:50AM -0400, 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

There seems to be only a single run_apps file, so we don't need a whole
subdir for it.

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

Do they apply for windows? <self-update :-)> I see windows at the end, so yes,
we have instructions but they are split. I'd drop this opening line.

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

There is an assumption here (maybe all through this doc) that DPDK is
installed system-wide.
If not, maybe we tell the user they can compile the examples as part of a
DPDK build itself using meson option "-Dexamples=...".

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

I'd drop this list. The reference below for the sample app guide is best.

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

Unrelated to your work, there has been some discussion on the DPDK mailing
list around moving away from coremasks in DPDK, since they are unwieldy to
use. Therefore, for simplicity, just document the -l option, and give a
couple of examples e.g.

	'-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, using 1 through 7 and then 9
		through 15

> +- ``-n NUM``: Number of memory channels per processor socket.
> +- ``--socket-mem``: Memory allocation from hugepages on specific sockets.
> +

I would drop these last two options, they are very much for advanced users.
So in the opening paragraph, instead of saying "some of these options
include", we can just talk about the "most important option" or similar to
that. Again, we have a refence link to get more info.

> +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
> -- 
> 2.41.0.windows.1
>