[v4,1/6] Section 1: Introduction

Message ID 20231123012633.2005-2-dave@youngcopy.com (mailing list archive)
State New
Delegated to: Thomas Monjalon
Headers
Series docs: getting started guide consolidation |

Checks

Context Check Description
ci/checkpatch warning coding style issues

Commit Message

Dave Young Nov. 23, 2023, 1:26 a.m. UTC
  Added link to Getting Started Guide in index.rst

Moved run_apps.rst to GSG index

Removed run_apps/index.rst - no longer needed

Added run_apps.rst to index

-Reformatted the introduction paragraph for better readability.
-Clarified that the guide provides basic step-by-step instructions with OS-specific instructions
included only where necessary for each operating system.
-Emphasized that by the end of this guide, the user should have a solid understanding of how to
implement and use DPDK in their networking projects, regardless of the operating system they are using.

Moved run_apps into GSG root directory
---
 doc/guides/getting_started_guide/index.rst    |  18 +++
 doc/guides/getting_started_guide/intro.rst    |  13 ++
 doc/guides/getting_started_guide/run_apps.rst | 114 ++++++++++++++++++
 doc/guides/index.rst                          |   1 +
 4 files changed, 146 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/index.rst
 create mode 100644 doc/guides/getting_started_guide/intro.rst
 create mode 100644 doc/guides/getting_started_guide/run_apps.rst
  

Patch

diff --git a/doc/guides/getting_started_guide/index.rst b/doc/guides/getting_started_guide/index.rst
new file mode 100644
index 0000000000..3d7c0eb6ee
--- /dev/null
+++ b/doc/guides/getting_started_guide/index.rst
@@ -0,0 +1,18 @@ 
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _getting_started_guide:
+
+Getting Started Guide
+=====================
+
+.. toctree::
+    :maxdepth: 2
+    :numbered:
+
+    intro
+    install_and_build/index
+    system_setup
+    run_apps
+    appendix/index
+    glossary
diff --git a/doc/guides/getting_started_guide/intro.rst b/doc/guides/getting_started_guide/intro.rst
new file mode 100644
index 0000000000..3560d705d0
--- /dev/null
+++ b/doc/guides/getting_started_guide/intro.rst
@@ -0,0 +1,13 @@ 
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2014 Intel Corporation.
+
+Introduction
+============
+
+Welcome to the getting started guide for the Data Plane Development Kit (DPDK) covering Linux, 
+FreeBSD, and Windows. DPDK is a set of libraries and drivers that accelerate packet processing 
+and allow the user to create high-performance networking applications.
+
+The guide is structured to provide basic step-by-step instructions with OS-specific instructions included only where necessary for each operating system. 
+By the end of this guide, you should have a solid understanding of how to implement
+and use DPDK in your networking projects, regardless of the operating system you are using.
diff --git a/doc/guides/getting_started_guide/run_apps.rst b/doc/guides/getting_started_guide/run_apps.rst
new file mode 100644
index 0000000000..d9ef1a6f96
--- /dev/null
+++ b/doc/guides/getting_started_guide/run_apps.rst
@@ -0,0 +1,114 @@ 
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _run_apps:
+
+Running Applications
+====================
+
+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
+
+.. note::
+   If DPDK is not installed system-wide, 
+   you can compile the examples as part of the DPDK build itself. 
+   If DPDK is not installed system-wide, you can compile the examples as part of the DPDK build 
+   itself. Use the meson build option ``-Dexamples=helloworld`` to compile specific examples 
+   or ``-Dexamples=all`` to compile all examples.
+
+To run the application, use:
+
+::
+
+    ./build/helloworld -l 0-2
+
+The ``-l`` option indicates the cores on which the application should run.
+This command runs the `helloworld` application on cores 0, 1, and 2.
+
+Sample Applications Overview
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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. The most essential EAL option is ``-l CORELIST``, which specifies the cores the application should run on. For example:
+
+- ``-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: 1 through 7 and 9 through 15.
+
+Please refer to the `EAL parameters section <eal_parameters>` section for a more comprehensive list of options.
+
+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
diff --git a/doc/guides/index.rst b/doc/guides/index.rst
index 244b99624c..51a47d3a51 100644
--- a/doc/guides/index.rst
+++ b/doc/guides/index.rst
@@ -7,6 +7,7 @@  DPDK documentation
 .. toctree::
    :maxdepth: 1
 
+   getting_started_guide/index
    linux_gsg/index
    freebsd_gsg/index
    windows_gsg/index