Skip to contentSkip to conversation

doc: reword sample application guides

PATCH Superseded Nandini Persad 5 participants 22 messages Jan 27, 2025 – Jun 15

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 doc: reword sample application guides

I have revised these sections to suit the template, but also, for punctuation, clarity, and removing repitition when necessary.

---
 doc/guides/sample_app_ug/dist_app.rst         |  24 +--
 .../sample_app_ug/eventdev_pipeline.rst       |  20 +--
 doc/guides/sample_app_ug/fips_validation.rst  | 139 +++++++++---------
 doc/guides/sample_app_ug/ip_pipeline.rst      |  12 +-
 doc/guides/sample_app_ug/ipsec_secgw.rst      |  95 ++++++------
 doc/guides/sample_app_ug/multi_process.rst    |  66 +++++----
 doc/guides/sample_app_ug/packet_ordering.rst  |  19 ++-
 doc/guides/sample_app_ug/pipeline.rst         |  10 +-
 doc/guides/sample_app_ug/ptpclient.rst        |  56 +++----
 doc/guides/sample_app_ug/qos_metering.rst     |  11 +-
 doc/guides/sample_app_ug/qos_scheduler.rst    |  10 +-
 doc/guides/sample_app_ug/service_cores.rst    |  41 +++---
 doc/guides/sample_app_ug/test_pipeline.rst    |   2 +-
 doc/guides/sample_app_ug/timer.rst            |  13 +-
 doc/guides/sample_app_ug/vdpa.rst             |  39 ++---
 doc/guides/sample_app_ug/vhost.rst            |  51 ++++---
 doc/guides/sample_app_ug/vhost_blk.rst        |  21 +--
 doc/guides/sample_app_ug/vhost_crypto.rst     |  15 +-
 .../sample_app_ug/vm_power_management.rst     | 138 ++++++++---------
 .../sample_app_ug/vmdq_dcb_forwarding.rst     |  77 +++++-----
 doc/guides/sample_app_ug/vmdq_forwarding.rst  |  28 ++--
 21 files changed, 456 insertions(+), 431 deletions(-)
doc/guides/sample_app_ug/dist_app.rst +12 -12
index 5c80561187..7a841bff8a 100644
@@ -4,7 +4,7 @@
 Distributor Sample Application
 ==============================
 
-The distributor sample application is a simple example of packet distribution
+The distributor sample application is an example of packet distribution
 to cores using the Data Plane Development Kit (DPDK). It also makes use of
 Intel Speed Select Technology - Base Frequency (Intel SST-BF) to pin the
 distributor to the higher frequency core if available.
@@ -31,7 +31,7 @@ generator as shown in the figure below.
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``distributor`` sub-directory.
 
@@ -66,7 +66,7 @@ The distributor application consists of four types of threads: a receive
 thread (``lcore_rx()``), a distributor thread (``lcore_dist()``), a set of
 worker threads (``lcore_worker()``), and a transmit thread(``lcore_tx()``).
 How these threads work together is shown in :numref:`figure_dist_app` below.
-The ``main()`` function launches  threads of these four types.  Each thread
+The ``main()`` function launches threads of these four types. Each thread
 has a while loop which will be doing processing and which is terminated
 only upon SIGINT or ctrl+C.
 
@@ -86,7 +86,7 @@ the distributor, doing a simple XOR operation on the input port mbuf field
 (to indicate the output port which will be used later for packet transmission)
 and then finally returning the packets back to the distributor thread.
 
-The distributor thread will then call the distributor api
+The distributor thread will then call the distributor API
 ``rte_distributor_returned_pkts()`` to get the processed packets, and will enqueue
 them to another rte_ring for transfer to the TX thread for transmission on the
 output port. The transmit thread will dequeue the packets from the ring and
@@ -105,7 +105,7 @@ final statistics to the user.
 
 
 Intel SST-BF Support
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 In DPDK 19.05, support was added to the power management library for
 Intel-SST-BF, a technology that allows some cores to run at a higher
@@ -114,20 +114,20 @@ and is entitled
 `Intel Speed Select Technology – Base Frequency - Enhancing Performance <https://builders.intel.com/docs/networkbuilders/intel-speed-select-technology-base-frequency-enhancing-performance.pdf>`_
 
 The distributor application was also enhanced to be aware of these higher
-frequency SST-BF cores, and when starting the application, if high frequency
+frequency SST-BF cores. When starting the application, if high frequency
 SST-BF cores are present in the core mask, the application will identify these
 cores and pin the workloads appropriately. The distributor core is usually
 the bottleneck, so this is given first choice of the high frequency SST-BF
-cores, followed by the rx core and the tx core.
+cores, followed by the Rx core and the Tx core.
 
 Debug Logging Support
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 Debug logging is provided as part of the application; the user needs to uncomment
 the line "#define DEBUG" defined in start of the application in main.c to enable debug logs.
 
 Statistics
-----------
+~~~~~~~~~~
 
 The main function will print statistics on the console every second. These
 statistics include the number of packets enqueued and dequeued at each stage
@@ -135,7 +135,7 @@ in the application, and also key statistics per worker, including how many
 packets of each burst size (1-8) were sent to each worker thread.
 
 Application Initialization
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Command line parsing is done in the same way as it is done in the L2 Forwarding Sample
 Application. See :ref:`l2_fwd_app_cmd_arguments`.
@@ -146,8 +146,8 @@ Sample Application. See :ref:`l2_fwd_app_mbuf_init`.
 Driver Initialization is done in same way as it is done in the L2 Forwarding Sample
 Application. See :ref:`l2_fwd_app_dvr_init`.
 
-RX queue initialization is done in the same way as it is done in the L2 Forwarding
+Rx queue initialization is done in the same way as it is done in the L2 Forwarding
 Sample Application. See :ref:`l2_fwd_app_rx_init`.
 
-TX queue initialization is done in the same way as it is done in the L2 Forwarding
+Tx queue initialization is done in the same way as it is done in the L2 Forwarding
 Sample Application. See :ref:`l2_fwd_app_tx_init`.
doc/guides/sample_app_ug/eventdev_pipeline.rst +10 -10
index 19ff53803e..103a8d7e84 100644
@@ -10,7 +10,7 @@ application can configure a pipeline and assign a set of worker cores to
 perform the processing required.
 
 The application has a range of command line arguments allowing it to be
-configured for various numbers worker cores, stages,queue depths and cycles per
+configured for various numbers worker cores, stages, queue depths and cycles per
 stage of work. This is useful for performance testing as well as quickly testing
 a particular pipeline configuration.
 
@@ -18,7 +18,7 @@ a particular pipeline configuration.
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``examples`` sub-directory.
 
@@ -61,21 +61,21 @@ will print an error message:
           rx: 0
           tx: 1
 
-Configuration of the eventdev is covered in detail in the programmers guide,
-see the Event Device Library section.
+Configuration of the eventdev is covered in detail in the programmers guide.
+See the Event Device Library section.
 
 
 Observing the Application
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-At runtime the eventdev pipeline application prints out a summary of the
-configuration, and some runtime statistics like packets per second. On exit the
+At runtime, the eventdev pipeline application prints out a summary of the
+configuration, and some runtime statistics like packets per second. On exit, the
 worker statistics are printed, along with a full dump of the PMD statistics if
 required. The following sections show sample output for each of the output
 types.
 
 Configuration
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 This provides an overview of the pipeline,
 scheduling type at each stage, and parameters to options such as how many
@@ -101,7 +101,7 @@ for details:
         Stage 3, Type Atomic    Priority = 128
 
 Runtime
-~~~~~~~
+^^^^^^^
 
 At runtime, the statistics of the consumer are printed, stating the number of
 packets received, runtime in milliseconds, average mpps, and current mpps.
@@ -111,7 +111,7 @@ packets received, runtime in milliseconds, average mpps, and current mpps.
   # consumer RX= xxxxxxx, time yyyy ms, avg z.zzz mpps [current w.www mpps]
 
 Shutdown
-~~~~~~~~
+^^^^^^^^
 
 At shutdown, the application prints the number of packets received and
 transmitted, and an overview of the distribution of work across worker cores.
doc/guides/sample_app_ug/fips_validation.rst +69 -70

148 lines not on this page · raw message

doc/guides/sample_app_ug/ip_pipeline.rst +7 -5
index ff5ee67ec2..a0b8bf5ce1 100644
@@ -4,8 +4,8 @@
 Internet Protocol (IP) Pipeline Application
 ===========================================
 
-Application overview
---------------------
+Overview
+--------
 
 The *Internet Protocol (IP) Pipeline* application is intended to be a vehicle for rapid development of packet processing
 applications on multi-core CPUs.
@@ -107,8 +107,10 @@ Once application and telnet client start running, messages can be sent from clie
 At any stage, telnet client can be terminated using the quit command.
 
 
-Application stages
-------------------
+Explanation
+-----------
+
+The following explains the stages of the application.
 
 Initialization
 ~~~~~~~~~~~~~~
@@ -134,7 +136,7 @@ executes two tasks in time-sharing mode:
    to/from given table of a specific pipeline owned by the current data plane thread, read statistics, etc.
 
 Examples
---------
+~~~~~~~~
 
 .. _table_examples:
 
doc/guides/sample_app_ug/ipsec_secgw.rst +45 -50

159 lines not on this page · raw message

doc/guides/sample_app_ug/multi_process.rst +34 -32

150 lines not on this page · raw message

doc/guides/sample_app_ug/packet_ordering.rst +11 -8
index 1eb9a478aa..6d5a993712 100644
@@ -4,29 +4,29 @@
 Packet Ordering Application
 ============================
 
-The Packet Ordering sample app simply shows the impact of reordering a stream.
-It's meant to stress the library with different configurations for performance.
+The Packet Ordering sample application shows the impact of reordering a stream.
+It is meant to stress the library with different configurations for performance.
 
 Overview
 --------
 
 The application uses at least three CPU cores:
 
-* RX core (main core) receives traffic from the NIC ports and feeds Worker
+* The RX core (main core) receives traffic from the NIC ports and feeds Worker
   cores with traffic through SW queues.
 
-* Worker (worker core) basically do some light work on the packet.
-  Currently it modifies the output port of the packet for configurations with
+* The Worker (worker core) does some light work on the packet.
+  Currently, it modifies the output port of the packet for configurations with
   more than one port enabled.
 
-* TX Core (worker core) receives traffic from Worker cores through software queues,
+* The TX Core (worker core) receives traffic from Worker cores through software queues,
   inserts out-of-order packets into reorder buffer, extracts ordered packets
   from the reorder buffer and sends them to the NIC ports for transmission.
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``packet_ordering`` sub-directory.
 
@@ -36,6 +36,9 @@ Running the Application
 Refer to *DPDK Getting Started Guide* for general information on running applications
 and the Environment Abstraction Layer (EAL) options.
 
+Explanation
+-----------
+
 Application Command Line
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -55,7 +58,7 @@ When setting more than 1 port, traffic would be forwarded in pairs.
 For example, if we enable 4 ports, traffic from port 0 to 1 and from 1 to 0,
 then the other pair from 2 to 3 and from 3 to 2, having [0,1] and [2,3] pairs.
 
-The disable-reorder long option does, as its name implies, disable the reordering
+The disable-reorder long option, as its name implies, disables the reordering
 of traffic, which should help evaluate reordering performance impact.
 
 The insight-worker long option enables output the packet statistics of each worker thread.
doc/guides/sample_app_ug/pipeline.rst +6 -4
index 58ed0d296a..e560f3fd48 100644
@@ -4,8 +4,8 @@
 Pipeline Application
 ====================
 
-Application overview
---------------------
+Overview
+--------
 
 This application showcases the features of the Software Switch (SWX) pipeline that is aligned with the P4 language.
 
@@ -93,8 +93,10 @@ When running a telnet client as above, command prompt is displayed:
 Once application and telnet client start running, messages can be sent from client to application.
 
 
-Application stages
-------------------
+Explanation
+-----------
+
+Here is a description of the various stages of the application.
 
 Initialization
 ~~~~~~~~~~~~~~
doc/guides/sample_app_ug/ptpclient.rst +31 -25

133 lines not on this page · raw message

doc/guides/sample_app_ug/qos_metering.rst +6 -5
index e7101559aa..b41567f3b0 100644
@@ -4,7 +4,7 @@
 QoS Metering Sample Application
 ===============================
 
-The QoS meter sample application is an example that demonstrates the use of DPDK to provide QoS marking and metering,
+The QoS meter sample application demonstrates the use of DPDK to provide QoS marking and metering,
 as defined by RFC2697 for Single Rate Three Color Marker (srTCM) and RFC 2698 for Two Rate Three Color Marker (trTCM) algorithm.
 
 Overview
@@ -14,7 +14,8 @@ The application uses a single thread for reading the packets from the RX port,
 metering, marking them with the appropriate color (green, yellow or red) and writing them to the TX port.
 
 A policing scheme can be applied before writing the packets to the TX port by dropping or
-changing the color of the packet in a static manner depending on both the input and output colors of the packets that are processed by the meter.
+changing the color of the packet in a static manner. This would depend on both the input and output colors
+of the packets that are processed by the meter.
 
 The operation mode can be selected as compile time out of the following options:
 
@@ -126,11 +127,11 @@ There are four different actions:
 
 In this particular case:
 
-*   Every packet which input and output color are the same, keeps the same color.
+*   For every packet where the input and output color are the same, keep the same color.
 
-*   Every packet which color has improved is dropped (this particular case can't happen, so these values will not be used).
+*   For every packet where the color has improved is dropped (this particular case can't happen, so these values will not be used).
 
-*   For the rest of the cases, the color is changed to red.
+*   For the rest of the cases, the color is changes to red.
 
 .. note::
     * In color blind mode, first row GREEN color is only valid.
doc/guides/sample_app_ug/qos_scheduler.rst +6 -4
index 9936b99172..a2d50b0a45 100644
@@ -20,18 +20,20 @@ The architecture of the QoS scheduler application is shown in the following figu
 
 There are two flavors of the runtime execution for this application,
 with two or three threads per each packet flow configuration being used.
-The RX thread reads packets from the RX port,
+
+The RX thread reads packets from the RX port and
 classifies the packets based on the double VLAN (outer and inner) and
-the lower byte of the IP destination address and puts them into the ring queue.
+the lower byte of the IP destination address. It then puts them into the ring queue.
+
 The worker thread dequeues the packets from the ring and calls the QoS scheduler enqueue/dequeue functions.
 If a separate TX core is used, these are sent to the TX ring.
 Otherwise, they are sent directly to the TX port.
-The TX thread, if present, reads from the TX ring and write the packets to the TX port.
+The TX thread, if present, reads from the TX ring and writes the packets to the TX port.
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``qos_sched`` sub-directory.
 
doc/guides/sample_app_ug/service_cores.rst +23 -18

77 lines not on this page · raw message

doc/guides/sample_app_ug/test_pipeline.rst +1 -1
index d57d08fb2c..cf9f2dabac 100644
@@ -30,7 +30,7 @@ The application uses three CPU cores:
 
 Compiling the Application
 -------------------------
-To compile the sample application see :doc:`compiling`
+To compile the sample application, see :doc:`compiling`
 
 The application is located in the ``dpdk/<build_dir>/app`` directory.
 
doc/guides/sample_app_ug/timer.rst +7 -6
index d8c6d9a656..6bef30b553 100644
@@ -4,13 +4,16 @@
 Timer Sample Application
 ========================
 
-The Timer sample application is a simple application that demonstrates the use of a timer in a DPDK application.
-This application prints some messages from different lcores regularly, demonstrating the use of timers.
+Overview
+--------
+
+The Timer sample application demonstrates the use of a timer in a DPDK application.
+This application prints messages from different lcores regularly using timers.
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``timer`` sub-directory.
 
@@ -29,8 +32,6 @@ the Environment Abstraction Layer (EAL) options.
 Explanation
 -----------
 
-The following sections provide some explanation of the code.
-
 Initialization and Main Loop
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -76,7 +77,7 @@ This call to rte_timer_init() is necessary before doing any other operation on t
     :end-before: >8 End of init timer structures.
     :dedent: 1
 
-Then, the two timers are configured:
+Next, the two timers are configured:
 
 *   The first timer (timer0) is loaded on the main lcore and expires every second.
     Since the PERIODICAL flag is provided, the timer is reloaded automatically by the timer subsystem.
doc/guides/sample_app_ug/vdpa.rst +21 -18
index bc11242d03..d4eccaafc5 100644
@@ -4,27 +4,30 @@
 Vdpa Sample Application
 =======================
 
-The vdpa sample application creates vhost-user sockets by using the
-vDPA backend. vDPA stands for vhost Data Path Acceleration which utilizes
-virtio ring compatible devices to serve virtio driver directly to enable
-datapath acceleration. As vDPA driver can help to set up vhost datapath,
-this application doesn't need to launch dedicated worker threads for vhost
+Overview
+--------
+
+The vDPA sample application creates vhost-user sockets by using the
+vDPA backend. vDPA (vhost Data Path Acceleration) utilizes
+virtio ring compatible devices to serve a virtio driver directly to enable
+datapath acceleration. A vDPA driver can help to set up vhost datapath.
+This application doesn't need to launch dedicated worker threads for vhost
 enqueue/dequeue operations.
 
-Testing steps
--------------
-
-This section shows the steps of how to start VMs with vDPA vhost-user
+This following shows the steps of how to start VMs with vDPA vhost-user
 backend and verify network connection & live migration.
 
-Build
-~~~~~
+Compiling the Application
+-------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``vdpa`` sub-directory.
 
-Start the vdpa example
+Running the Application
+-----------------------
+
+Start the vDPA example
 ~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: console
@@ -50,7 +53,7 @@ where
 
   #. quit: unregister vhost driver and exit the application
 
-Take IFCVF driver for example:
+Take IFCVF driver, for example:
 
 .. code-block:: console
 
@@ -65,7 +68,7 @@ Take IFCVF driver for example:
     * modprobe vfio-pci
     * ./usertools/dpdk-devbind.py -b vfio-pci 06:00.3 06:00.4
 
-Then we can create 2 vdpa ports in interactive cmdline.
+Then, we can create 2 vdpa ports in interactive cmdline.
 
 .. code-block:: console
 
@@ -100,9 +103,9 @@ network connection via ping or netperf.
 
 Live Migration
 ~~~~~~~~~~~~~~
-vDPA supports cross-backend live migration, user can migrate SW vhost backend
-VM to vDPA backend VM and vice versa. Here are the detailed steps. Assume A is
-the source host with SW vhost VM and B is the destination host with vDPA.
+vDPA supports cross-backend live migration. A user can migrate SW vhost backend
+VM to vDPA backend VM and vice versa. Here are the detailed steps.
+Assume A is the source host with SW vhost VM and B is the destination host with vDPA.
 
 #. Start vdpa sample and launch a VM with exact same parameters as the VM on A,
    in migration-listen mode:
doc/guides/sample_app_ug/vhost.rst +30 -21

134 lines not on this page · raw message

doc/guides/sample_app_ug/vhost_blk.rst +12 -9
index 788eef0d5f..f69b59baef 100644
@@ -4,32 +4,35 @@
 Vhost_blk Sample Application
 =============================
 
-The vhost_blk sample application implemented a simple block device,
-which used as the  backend of Qemu vhost-user-blk device. Users can extend
-the exist example to use other type of block device(e.g. AIO) besides
+Overview
+--------
+
+The vhost_blk sample application implements a simple block device,
+used as the  backend of Qemu vhost-user-blk device. Users can extend
+the exist example to use other type of block device (e.g. AIO) besides
 memory based block device. Similar with vhost-user-net device, the sample
 application used domain socket to communicate with Qemu, and the virtio
 ring (split or packed format) was processed by vhost_blk sample application.
 
-The sample application reuse lots codes from SPDK(Storage Performance
+The sample application reuses codes from SPDK (Storage Performance
 Development Kit, https://github.com/spdk/spdk) vhost-user-blk target,
 for DPDK vhost library used in storage area, user can take SPDK as
 reference as well.
 
-Testing steps
--------------
-
 This section shows the steps how to start a VM with the block device as
 fast data path for critical application.
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``examples`` sub-directory.
 
-You will also need to build DPDK both on the host and inside the guest
+You will need to build DPDK both on the host and inside the guest.
+
+Running the Application
+-----------------------
 
 Start the vhost_blk example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
doc/guides/sample_app_ug/vhost_crypto.rst +9 -6
index 7ae7addac4..cab721425b 100644
@@ -4,25 +4,28 @@
 Vhost_Crypto Sample Application
 ===============================
 
-The vhost_crypto sample application implemented a simple Crypto device,
-which used as the  backend of Qemu vhost-user-crypto device. Similar with
+Overview
+--------
+
+The vhost_crypto sample application implements a Crypto device used
+as the  backend of Qemu vhost-user-crypto device. Similar with
 vhost-user-net and vhost-user-scsi device, the sample application used
 domain socket to communicate with Qemu, and the virtio ring was processed
 by vhost_crypto sample application.
 
-Testing steps
--------------
-
 This section shows the steps how to start a VM with the crypto device as
 fast data path for critical application.
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``examples`` sub-directory.
 
+Running the Application
+-----------------------
+
 Start the vhost_crypto example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
doc/guides/sample_app_ug/vm_power_management.rst +63 -75

188 lines not on this page · raw message

doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst +40 -37

137 lines not on this page · raw message

doc/guides/sample_app_ug/vmdq_forwarding.rst +13 -15
index ed28525a15..b1b4d5a809 100644
@@ -2,9 +2,9 @@
     Copyright(c) 2020 Intel Corporation.
 
 VMDq Forwarding Sample Application
-==========================================
+==================================
 
-The VMDq Forwarding sample application is a simple example of packet processing using the DPDK.
+The VMDq Forwarding sample application is an example of packet processing using the DPDK.
 The application performs L2 forwarding using VMDq to divide the incoming traffic into queues.
 The traffic splitting is performed in hardware by the VMDq feature of the Intel® 82599 and X710/XL710 Ethernet Controllers.
 
@@ -14,12 +14,12 @@ Overview
 This sample application can be used as a starting point for developing a new application that is based on the DPDK and
 uses VMDq for traffic partitioning.
 
-VMDq filters split the incoming packets up into different "pools" - each with its own set of RX queues - based upon
+VMDq filters split the incoming packets up into different "pools" (each with its own set of Rx queues) based upon
 the MAC address and VLAN ID within the VLAN tag of the packet.
 
 All traffic is read from a single incoming port and output on another port, without any processing being performed.
 With Intel® 82599 NIC, for example, the traffic is split into 128 queues on input, where each thread of the application reads from
-multiple queues. When run with 8 threads, that is, with the -c FF option, each thread receives and forwards packets from 16 queues.
+multiple queues. When run with 8 threads with the -c FF option, each thread receives and forwards packets from 16 queues.
 
 As supplied, the sample application configures the VMDq feature to have 32 pools with 4 queues each.
 The Intel® 82599 10 Gigabit Ethernet Controller NIC also supports the splitting of traffic into 16 pools of 2 queues.
@@ -34,8 +34,8 @@ The nb-pools and enable-rss parameters can be passed on the command line, after
 
 where, NP can be 8, 16 or 32, rss is disabled by default.
 
-In Linux* user space, the application can display statistics with the number of packets received on each queue.
-To have the application display the statistics, send a SIGHUP signal to the running application process.
+In a Linux* user space, the application can display statistics with the number of packets received on each queue.
+To have the application display statistics, send a SIGHUP signal to the running application process.
 
 The VMDq Forwarding sample application is in many ways simpler than the L2 Forwarding application
 (see :doc:`l2_forward_real_virtual`)
@@ -45,7 +45,7 @@ No command-line options are taken by this application apart from the standard EA
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``vmdq`` sub-directory.
 
@@ -64,20 +64,18 @@ the Environment Abstraction Layer (EAL) options.
 Explanation
 -----------
 
-The following sections provide some explanation of the code.
+The following sections provide explanation of the code.
 
 Initialization
 ~~~~~~~~~~~~~~
 
 The EAL, driver and PCI configuration is performed largely as in the L2 Forwarding sample application,
-as is the creation of the mbuf pool.
-See :doc:`l2_forward_real_virtual`.
-Where this example application differs is in the configuration of the NIC port for RX.
+as is the creation of the mbuf pool. See :doc:`l2_forward_real_virtual`.
+This example application differs in the configuration of the NIC port for Rx.
 
 The VMDq hardware feature is configured at port initialization time by setting the appropriate values in the
 rte_eth_conf structure passed to the rte_eth_dev_configure() API.
-Initially in the application,
-a default structure is provided for VMDq configuration to be filled in later by the application.
+Initially in the application, a default structure is provided for VMDq configuration to be filled in later by the application.
 
 .. literalinclude:: ../../../examples/vmdq/main.c
     :language: c
@@ -88,8 +86,8 @@ The get_eth_conf() function fills in an rte_eth_conf structure with the appropri
 based on the global vlan_tags array.
 For the VLAN IDs, each one can be allocated to possibly multiple pools of queues.
 For destination MAC, each VMDq pool will be assigned with a MAC address. In this sample, each VMDq pool
-is assigned to the MAC like 52:54:00:12:<port_id>:<pool_id>, that is,
-the MAC of VMDq pool 2 on port 1 is 52:54:00:12:01:02.
+is assigned to the MAC like 52:54:00:12:<port_id>:<pool_id>.
+The MAC of VMDq pool 2 on port 1 is 52:54:00:12:01:02.
 
 .. literalinclude:: ../../../examples/vmdq/main.c
     :language: c
Signature · 1 line
2.34.1
#1 lore raw

PATCH v2 1/1 doc: reword sample application guides

I have revised these sections to suit the template, but also, for punctuation, clarity, and removing repetition when necessary.

---
 doc/guides/sample_app_ug/dist_app.rst         |  24 +--
 .../sample_app_ug/eventdev_pipeline.rst       |  20 +--
 doc/guides/sample_app_ug/fips_validation.rst  |  23 ++-
 doc/guides/sample_app_ug/ip_pipeline.rst      |  12 +-
 doc/guides/sample_app_ug/ipsec_secgw.rst      |  95 ++++++------
 doc/guides/sample_app_ug/multi_process.rst    |  64 ++++----
 doc/guides/sample_app_ug/packet_ordering.rst  |  19 ++-
 doc/guides/sample_app_ug/pipeline.rst         |  10 +-
 doc/guides/sample_app_ug/ptpclient.rst        |  56 +++----
 doc/guides/sample_app_ug/qos_metering.rst     |  11 +-
 doc/guides/sample_app_ug/qos_scheduler.rst    |  10 +-
 doc/guides/sample_app_ug/service_cores.rst    |  41 +++---
 doc/guides/sample_app_ug/test_pipeline.rst    |   2 +-
 doc/guides/sample_app_ug/timer.rst            |  13 +-
 doc/guides/sample_app_ug/vdpa.rst             |  39 ++---
 doc/guides/sample_app_ug/vhost.rst            |  51 ++++---
 doc/guides/sample_app_ug/vhost_blk.rst        |  21 +--
 doc/guides/sample_app_ug/vhost_crypto.rst     |  15 +-
 .../sample_app_ug/vm_power_management.rst     | 138 ++++++++----------
 .../sample_app_ug/vmdq_dcb_forwarding.rst     |  77 +++++-----
 doc/guides/sample_app_ug/vmdq_forwarding.rst  |  28 ++--
 21 files changed, 397 insertions(+), 372 deletions(-)
doc/guides/sample_app_ug/dist_app.rst +12 -12
index 5c80561187..7a841bff8a 100644
@@ -4,7 +4,7 @@
 Distributor Sample Application
 ==============================
 
-The distributor sample application is a simple example of packet distribution
+The distributor sample application is an example of packet distribution
 to cores using the Data Plane Development Kit (DPDK). It also makes use of
 Intel Speed Select Technology - Base Frequency (Intel SST-BF) to pin the
 distributor to the higher frequency core if available.
@@ -31,7 +31,7 @@ generator as shown in the figure below.
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``distributor`` sub-directory.
 
@@ -66,7 +66,7 @@ The distributor application consists of four types of threads: a receive
 thread (``lcore_rx()``), a distributor thread (``lcore_dist()``), a set of
 worker threads (``lcore_worker()``), and a transmit thread(``lcore_tx()``).
 How these threads work together is shown in :numref:`figure_dist_app` below.
-The ``main()`` function launches  threads of these four types.  Each thread
+The ``main()`` function launches threads of these four types. Each thread
 has a while loop which will be doing processing and which is terminated
 only upon SIGINT or ctrl+C.
 
@@ -86,7 +86,7 @@ the distributor, doing a simple XOR operation on the input port mbuf field
 (to indicate the output port which will be used later for packet transmission)
 and then finally returning the packets back to the distributor thread.
 
-The distributor thread will then call the distributor api
+The distributor thread will then call the distributor API
 ``rte_distributor_returned_pkts()`` to get the processed packets, and will enqueue
 them to another rte_ring for transfer to the TX thread for transmission on the
 output port. The transmit thread will dequeue the packets from the ring and
@@ -105,7 +105,7 @@ final statistics to the user.
 
 
 Intel SST-BF Support
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 In DPDK 19.05, support was added to the power management library for
 Intel-SST-BF, a technology that allows some cores to run at a higher
@@ -114,20 +114,20 @@ and is entitled
 `Intel Speed Select Technology – Base Frequency - Enhancing Performance <https://builders.intel.com/docs/networkbuilders/intel-speed-select-technology-base-frequency-enhancing-performance.pdf>`_
 
 The distributor application was also enhanced to be aware of these higher
-frequency SST-BF cores, and when starting the application, if high frequency
+frequency SST-BF cores. When starting the application, if high frequency
 SST-BF cores are present in the core mask, the application will identify these
 cores and pin the workloads appropriately. The distributor core is usually
 the bottleneck, so this is given first choice of the high frequency SST-BF
-cores, followed by the rx core and the tx core.
+cores, followed by the Rx core and the Tx core.
 
 Debug Logging Support
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 Debug logging is provided as part of the application; the user needs to uncomment
 the line "#define DEBUG" defined in start of the application in main.c to enable debug logs.
 
 Statistics
-----------
+~~~~~~~~~~
 
 The main function will print statistics on the console every second. These
 statistics include the number of packets enqueued and dequeued at each stage
@@ -135,7 +135,7 @@ in the application, and also key statistics per worker, including how many
 packets of each burst size (1-8) were sent to each worker thread.
 
 Application Initialization
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Command line parsing is done in the same way as it is done in the L2 Forwarding Sample
 Application. See :ref:`l2_fwd_app_cmd_arguments`.
@@ -146,8 +146,8 @@ Sample Application. See :ref:`l2_fwd_app_mbuf_init`.
 Driver Initialization is done in same way as it is done in the L2 Forwarding Sample
 Application. See :ref:`l2_fwd_app_dvr_init`.
 
-RX queue initialization is done in the same way as it is done in the L2 Forwarding
+Rx queue initialization is done in the same way as it is done in the L2 Forwarding
 Sample Application. See :ref:`l2_fwd_app_rx_init`.
 
-TX queue initialization is done in the same way as it is done in the L2 Forwarding
+Tx queue initialization is done in the same way as it is done in the L2 Forwarding
 Sample Application. See :ref:`l2_fwd_app_tx_init`.
doc/guides/sample_app_ug/eventdev_pipeline.rst +10 -10
index 19ff53803e..103a8d7e84 100644
@@ -10,7 +10,7 @@ application can configure a pipeline and assign a set of worker cores to
 perform the processing required.
 
 The application has a range of command line arguments allowing it to be
-configured for various numbers worker cores, stages,queue depths and cycles per
+configured for various numbers worker cores, stages, queue depths and cycles per
 stage of work. This is useful for performance testing as well as quickly testing
 a particular pipeline configuration.
 
@@ -18,7 +18,7 @@ a particular pipeline configuration.
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``examples`` sub-directory.
 
@@ -61,21 +61,21 @@ will print an error message:
           rx: 0
           tx: 1
 
-Configuration of the eventdev is covered in detail in the programmers guide,
-see the Event Device Library section.
+Configuration of the eventdev is covered in detail in the programmers guide.
+See the Event Device Library section.
 
 
 Observing the Application
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-At runtime the eventdev pipeline application prints out a summary of the
-configuration, and some runtime statistics like packets per second. On exit the
+At runtime, the eventdev pipeline application prints out a summary of the
+configuration, and some runtime statistics like packets per second. On exit, the
 worker statistics are printed, along with a full dump of the PMD statistics if
 required. The following sections show sample output for each of the output
 types.
 
 Configuration
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 This provides an overview of the pipeline,
 scheduling type at each stage, and parameters to options such as how many
@@ -101,7 +101,7 @@ for details:
         Stage 3, Type Atomic    Priority = 128
 
 Runtime
-~~~~~~~
+^^^^^^^
 
 At runtime, the statistics of the consumer are printed, stating the number of
 packets received, runtime in milliseconds, average mpps, and current mpps.
@@ -111,7 +111,7 @@ packets received, runtime in milliseconds, average mpps, and current mpps.
   # consumer RX= xxxxxxx, time yyyy ms, avg z.zzz mpps [current w.www mpps]
 
 Shutdown
-~~~~~~~~
+^^^^^^^^
 
 At shutdown, the application prints the number of packets received and
 transmitted, and an overview of the distribution of work across worker cores.
doc/guides/sample_app_ug/fips_validation.rst +11 -12
index 613c5afd19..7c7e32d9bc 100644
@@ -79,18 +79,17 @@ Application Information
 -----------------------
 
 If a ``.req`` is used as the input file after the application is finished
-running it will generate a response file or ``.rsp``. Differences between the
-two files are, the ``.req`` file has missing information for instance if doing
-encryption you will not have the cipher text and that will be generated in the
-response file. Also if doing decryption it will not have the plain text until it
-finished the work and in the response file it will be added onto the end of each
-operation.
-
-The application can be run with a ``.rsp`` file and what the outcome of that
-will be is it will add a extra line in the generated ``.rsp`` which should be
-the same as the ``.rsp`` used to run the application, this is useful for
-validating if the application has done the operation correctly.
-
+running, it will generate a response file or ``.rsp``. Differences between
+the two files are: the ``.req`` file has missing information (for instance,
+if performing encryption, you will not have the cipher text and that will be
+generated in the response file.), and, if performing decryption, it will not
+have plain text until it has finished the work. In the response file, it will
+be added onto the end of each operation.
+
+The application can be run with a ``.rsp`` file. The outcome of that is that
+an extra line in the generated ``.rsp`` will be added. This should be the same
+as the ``.rsp`` used to run the application. This is useful for validating if
+the application has done the operation correctly.
 
 Compiling the Application
 -------------------------
doc/guides/sample_app_ug/ip_pipeline.rst +7 -5
index ff5ee67ec2..a0b8bf5ce1 100644
@@ -4,8 +4,8 @@
 Internet Protocol (IP) Pipeline Application
 ===========================================
 
-Application overview
---------------------
+Overview
+--------
 
 The *Internet Protocol (IP) Pipeline* application is intended to be a vehicle for rapid development of packet processing
 applications on multi-core CPUs.
@@ -107,8 +107,10 @@ Once application and telnet client start running, messages can be sent from clie
 At any stage, telnet client can be terminated using the quit command.
 
 
-Application stages
-------------------
+Explanation
+-----------
+
+The following explains the stages of the application.
 
 Initialization
 ~~~~~~~~~~~~~~
@@ -134,7 +136,7 @@ executes two tasks in time-sharing mode:
    to/from given table of a specific pipeline owned by the current data plane thread, read statistics, etc.
 
 Examples
---------
+~~~~~~~~
 
 .. _table_examples:
 
doc/guides/sample_app_ug/ipsec_secgw.rst +45 -50

159 lines not on this page · raw message

doc/guides/sample_app_ug/multi_process.rst +33 -31

148 lines not on this page · raw message

doc/guides/sample_app_ug/packet_ordering.rst +11 -8
index 1eb9a478aa..6d5a993712 100644
@@ -4,29 +4,29 @@
 Packet Ordering Application
 ============================
 
-The Packet Ordering sample app simply shows the impact of reordering a stream.
-It's meant to stress the library with different configurations for performance.
+The Packet Ordering sample application shows the impact of reordering a stream.
+It is meant to stress the library with different configurations for performance.
 
 Overview
 --------
 
 The application uses at least three CPU cores:
 
-* RX core (main core) receives traffic from the NIC ports and feeds Worker
+* The RX core (main core) receives traffic from the NIC ports and feeds Worker
   cores with traffic through SW queues.
 
-* Worker (worker core) basically do some light work on the packet.
-  Currently it modifies the output port of the packet for configurations with
+* The Worker (worker core) does some light work on the packet.
+  Currently, it modifies the output port of the packet for configurations with
   more than one port enabled.
 
-* TX Core (worker core) receives traffic from Worker cores through software queues,
+* The TX Core (worker core) receives traffic from Worker cores through software queues,
   inserts out-of-order packets into reorder buffer, extracts ordered packets
   from the reorder buffer and sends them to the NIC ports for transmission.
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``packet_ordering`` sub-directory.
 
@@ -36,6 +36,9 @@ Running the Application
 Refer to *DPDK Getting Started Guide* for general information on running applications
 and the Environment Abstraction Layer (EAL) options.
 
+Explanation
+-----------
+
 Application Command Line
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -55,7 +58,7 @@ When setting more than 1 port, traffic would be forwarded in pairs.
 For example, if we enable 4 ports, traffic from port 0 to 1 and from 1 to 0,
 then the other pair from 2 to 3 and from 3 to 2, having [0,1] and [2,3] pairs.
 
-The disable-reorder long option does, as its name implies, disable the reordering
+The disable-reorder long option, as its name implies, disables the reordering
 of traffic, which should help evaluate reordering performance impact.
 
 The insight-worker long option enables output the packet statistics of each worker thread.
doc/guides/sample_app_ug/pipeline.rst +6 -4
index 58ed0d296a..e560f3fd48 100644
@@ -4,8 +4,8 @@
 Pipeline Application
 ====================
 
-Application overview
---------------------
+Overview
+--------
 
 This application showcases the features of the Software Switch (SWX) pipeline that is aligned with the P4 language.
 
@@ -93,8 +93,10 @@ When running a telnet client as above, command prompt is displayed:
 Once application and telnet client start running, messages can be sent from client to application.
 
 
-Application stages
-------------------
+Explanation
+-----------
+
+Here is a description of the various stages of the application.
 
 Initialization
 ~~~~~~~~~~~~~~
doc/guides/sample_app_ug/ptpclient.rst +31 -25

133 lines not on this page · raw message

doc/guides/sample_app_ug/qos_metering.rst +6 -5
index e7101559aa..b41567f3b0 100644
@@ -4,7 +4,7 @@
 QoS Metering Sample Application
 ===============================
 
-The QoS meter sample application is an example that demonstrates the use of DPDK to provide QoS marking and metering,
+The QoS meter sample application demonstrates the use of DPDK to provide QoS marking and metering,
 as defined by RFC2697 for Single Rate Three Color Marker (srTCM) and RFC 2698 for Two Rate Three Color Marker (trTCM) algorithm.
 
 Overview
@@ -14,7 +14,8 @@ The application uses a single thread for reading the packets from the RX port,
 metering, marking them with the appropriate color (green, yellow or red) and writing them to the TX port.
 
 A policing scheme can be applied before writing the packets to the TX port by dropping or
-changing the color of the packet in a static manner depending on both the input and output colors of the packets that are processed by the meter.
+changing the color of the packet in a static manner. This would depend on both the input and output colors
+of the packets that are processed by the meter.
 
 The operation mode can be selected as compile time out of the following options:
 
@@ -126,11 +127,11 @@ There are four different actions:
 
 In this particular case:
 
-*   Every packet which input and output color are the same, keeps the same color.
+*   For every packet where the input and output color are the same, keep the same color.
 
-*   Every packet which color has improved is dropped (this particular case can't happen, so these values will not be used).
+*   For every packet where the color has improved is dropped (this particular case can't happen, so these values will not be used).
 
-*   For the rest of the cases, the color is changed to red.
+*   For the rest of the cases, the color is changes to red.
 
 .. note::
     * In color blind mode, first row GREEN color is only valid.
doc/guides/sample_app_ug/qos_scheduler.rst +6 -4
index 9936b99172..a2d50b0a45 100644
@@ -20,18 +20,20 @@ The architecture of the QoS scheduler application is shown in the following figu
 
 There are two flavors of the runtime execution for this application,
 with two or three threads per each packet flow configuration being used.
-The RX thread reads packets from the RX port,
+
+The RX thread reads packets from the RX port and
 classifies the packets based on the double VLAN (outer and inner) and
-the lower byte of the IP destination address and puts them into the ring queue.
+the lower byte of the IP destination address. It then puts them into the ring queue.
+
 The worker thread dequeues the packets from the ring and calls the QoS scheduler enqueue/dequeue functions.
 If a separate TX core is used, these are sent to the TX ring.
 Otherwise, they are sent directly to the TX port.
-The TX thread, if present, reads from the TX ring and write the packets to the TX port.
+The TX thread, if present, reads from the TX ring and writes the packets to the TX port.
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``qos_sched`` sub-directory.
 
doc/guides/sample_app_ug/service_cores.rst +23 -18

77 lines not on this page · raw message

doc/guides/sample_app_ug/test_pipeline.rst +1 -1
index d57d08fb2c..cf9f2dabac 100644
@@ -30,7 +30,7 @@ The application uses three CPU cores:
 
 Compiling the Application
 -------------------------
-To compile the sample application see :doc:`compiling`
+To compile the sample application, see :doc:`compiling`
 
 The application is located in the ``dpdk/<build_dir>/app`` directory.
 
doc/guides/sample_app_ug/timer.rst +7 -6
index d8c6d9a656..6bef30b553 100644
@@ -4,13 +4,16 @@
 Timer Sample Application
 ========================
 
-The Timer sample application is a simple application that demonstrates the use of a timer in a DPDK application.
-This application prints some messages from different lcores regularly, demonstrating the use of timers.
+Overview
+--------
+
+The Timer sample application demonstrates the use of a timer in a DPDK application.
+This application prints messages from different lcores regularly using timers.
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``timer`` sub-directory.
 
@@ -29,8 +32,6 @@ the Environment Abstraction Layer (EAL) options.
 Explanation
 -----------
 
-The following sections provide some explanation of the code.
-
 Initialization and Main Loop
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -76,7 +77,7 @@ This call to rte_timer_init() is necessary before doing any other operation on t
     :end-before: >8 End of init timer structures.
     :dedent: 1
 
-Then, the two timers are configured:
+Next, the two timers are configured:
 
 *   The first timer (timer0) is loaded on the main lcore and expires every second.
     Since the PERIODICAL flag is provided, the timer is reloaded automatically by the timer subsystem.
doc/guides/sample_app_ug/vdpa.rst +21 -18
index bc11242d03..d4eccaafc5 100644
@@ -4,27 +4,30 @@
 Vdpa Sample Application
 =======================
 
-The vdpa sample application creates vhost-user sockets by using the
-vDPA backend. vDPA stands for vhost Data Path Acceleration which utilizes
-virtio ring compatible devices to serve virtio driver directly to enable
-datapath acceleration. As vDPA driver can help to set up vhost datapath,
-this application doesn't need to launch dedicated worker threads for vhost
+Overview
+--------
+
+The vDPA sample application creates vhost-user sockets by using the
+vDPA backend. vDPA (vhost Data Path Acceleration) utilizes
+virtio ring compatible devices to serve a virtio driver directly to enable
+datapath acceleration. A vDPA driver can help to set up vhost datapath.
+This application doesn't need to launch dedicated worker threads for vhost
 enqueue/dequeue operations.
 
-Testing steps
--------------
-
-This section shows the steps of how to start VMs with vDPA vhost-user
+This following shows the steps of how to start VMs with vDPA vhost-user
 backend and verify network connection & live migration.
 
-Build
-~~~~~
+Compiling the Application
+-------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``vdpa`` sub-directory.
 
-Start the vdpa example
+Running the Application
+-----------------------
+
+Start the vDPA example
 ~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: console
@@ -50,7 +53,7 @@ where
 
   #. quit: unregister vhost driver and exit the application
 
-Take IFCVF driver for example:
+Take IFCVF driver, for example:
 
 .. code-block:: console
 
@@ -65,7 +68,7 @@ Take IFCVF driver for example:
     * modprobe vfio-pci
     * ./usertools/dpdk-devbind.py -b vfio-pci 06:00.3 06:00.4
 
-Then we can create 2 vdpa ports in interactive cmdline.
+Then, we can create 2 vdpa ports in interactive cmdline.
 
 .. code-block:: console
 
@@ -100,9 +103,9 @@ network connection via ping or netperf.
 
 Live Migration
 ~~~~~~~~~~~~~~
-vDPA supports cross-backend live migration, user can migrate SW vhost backend
-VM to vDPA backend VM and vice versa. Here are the detailed steps. Assume A is
-the source host with SW vhost VM and B is the destination host with vDPA.
+vDPA supports cross-backend live migration. A user can migrate SW vhost backend
+VM to vDPA backend VM and vice versa. Here are the detailed steps.
+Assume A is the source host with SW vhost VM and B is the destination host with vDPA.
 
 #. Start vdpa sample and launch a VM with exact same parameters as the VM on A,
    in migration-listen mode:
doc/guides/sample_app_ug/vhost.rst +30 -21

134 lines not on this page · raw message

doc/guides/sample_app_ug/vhost_blk.rst +12 -9
index 788eef0d5f..f69b59baef 100644
@@ -4,32 +4,35 @@
 Vhost_blk Sample Application
 =============================
 
-The vhost_blk sample application implemented a simple block device,
-which used as the  backend of Qemu vhost-user-blk device. Users can extend
-the exist example to use other type of block device(e.g. AIO) besides
+Overview
+--------
+
+The vhost_blk sample application implements a simple block device,
+used as the  backend of Qemu vhost-user-blk device. Users can extend
+the exist example to use other type of block device (e.g. AIO) besides
 memory based block device. Similar with vhost-user-net device, the sample
 application used domain socket to communicate with Qemu, and the virtio
 ring (split or packed format) was processed by vhost_blk sample application.
 
-The sample application reuse lots codes from SPDK(Storage Performance
+The sample application reuses codes from SPDK (Storage Performance
 Development Kit, https://github.com/spdk/spdk) vhost-user-blk target,
 for DPDK vhost library used in storage area, user can take SPDK as
 reference as well.
 
-Testing steps
--------------
-
 This section shows the steps how to start a VM with the block device as
 fast data path for critical application.
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``examples`` sub-directory.
 
-You will also need to build DPDK both on the host and inside the guest
+You will need to build DPDK both on the host and inside the guest.
+
+Running the Application
+-----------------------
 
 Start the vhost_blk example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
doc/guides/sample_app_ug/vhost_crypto.rst +9 -6
index 7ae7addac4..cab721425b 100644
@@ -4,25 +4,28 @@
 Vhost_Crypto Sample Application
 ===============================
 
-The vhost_crypto sample application implemented a simple Crypto device,
-which used as the  backend of Qemu vhost-user-crypto device. Similar with
+Overview
+--------
+
+The vhost_crypto sample application implements a Crypto device used
+as the  backend of Qemu vhost-user-crypto device. Similar with
 vhost-user-net and vhost-user-scsi device, the sample application used
 domain socket to communicate with Qemu, and the virtio ring was processed
 by vhost_crypto sample application.
 
-Testing steps
--------------
-
 This section shows the steps how to start a VM with the crypto device as
 fast data path for critical application.
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``examples`` sub-directory.
 
+Running the Application
+-----------------------
+
 Start the vhost_crypto example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
doc/guides/sample_app_ug/vm_power_management.rst +63 -75

188 lines not on this page · raw message

doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst +40 -37

137 lines not on this page · raw message

doc/guides/sample_app_ug/vmdq_forwarding.rst +13 -15
index ed28525a15..b1b4d5a809 100644
@@ -2,9 +2,9 @@
     Copyright(c) 2020 Intel Corporation.
 
 VMDq Forwarding Sample Application
-==========================================
+==================================
 
-The VMDq Forwarding sample application is a simple example of packet processing using the DPDK.
+The VMDq Forwarding sample application is an example of packet processing using the DPDK.
 The application performs L2 forwarding using VMDq to divide the incoming traffic into queues.
 The traffic splitting is performed in hardware by the VMDq feature of the Intel® 82599 and X710/XL710 Ethernet Controllers.
 
@@ -14,12 +14,12 @@ Overview
 This sample application can be used as a starting point for developing a new application that is based on the DPDK and
 uses VMDq for traffic partitioning.
 
-VMDq filters split the incoming packets up into different "pools" - each with its own set of RX queues - based upon
+VMDq filters split the incoming packets up into different "pools" (each with its own set of Rx queues) based upon
 the MAC address and VLAN ID within the VLAN tag of the packet.
 
 All traffic is read from a single incoming port and output on another port, without any processing being performed.
 With Intel® 82599 NIC, for example, the traffic is split into 128 queues on input, where each thread of the application reads from
-multiple queues. When run with 8 threads, that is, with the -c FF option, each thread receives and forwards packets from 16 queues.
+multiple queues. When run with 8 threads with the -c FF option, each thread receives and forwards packets from 16 queues.
 
 As supplied, the sample application configures the VMDq feature to have 32 pools with 4 queues each.
 The Intel® 82599 10 Gigabit Ethernet Controller NIC also supports the splitting of traffic into 16 pools of 2 queues.
@@ -34,8 +34,8 @@ The nb-pools and enable-rss parameters can be passed on the command line, after
 
 where, NP can be 8, 16 or 32, rss is disabled by default.
 
-In Linux* user space, the application can display statistics with the number of packets received on each queue.
-To have the application display the statistics, send a SIGHUP signal to the running application process.
+In a Linux* user space, the application can display statistics with the number of packets received on each queue.
+To have the application display statistics, send a SIGHUP signal to the running application process.
 
 The VMDq Forwarding sample application is in many ways simpler than the L2 Forwarding application
 (see :doc:`l2_forward_real_virtual`)
@@ -45,7 +45,7 @@ No command-line options are taken by this application apart from the standard EA
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``vmdq`` sub-directory.
 
@@ -64,20 +64,18 @@ the Environment Abstraction Layer (EAL) options.
 Explanation
 -----------
 
-The following sections provide some explanation of the code.
+The following sections provide explanation of the code.
 
 Initialization
 ~~~~~~~~~~~~~~
 
 The EAL, driver and PCI configuration is performed largely as in the L2 Forwarding sample application,
-as is the creation of the mbuf pool.
-See :doc:`l2_forward_real_virtual`.
-Where this example application differs is in the configuration of the NIC port for RX.
+as is the creation of the mbuf pool. See :doc:`l2_forward_real_virtual`.
+This example application differs in the configuration of the NIC port for Rx.
 
 The VMDq hardware feature is configured at port initialization time by setting the appropriate values in the
 rte_eth_conf structure passed to the rte_eth_dev_configure() API.
-Initially in the application,
-a default structure is provided for VMDq configuration to be filled in later by the application.
+Initially in the application, a default structure is provided for VMDq configuration to be filled in later by the application.
 
 .. literalinclude:: ../../../examples/vmdq/main.c
     :language: c
@@ -88,8 +86,8 @@ The get_eth_conf() function fills in an rte_eth_conf structure with the appropri
 based on the global vlan_tags array.
 For the VLAN IDs, each one can be allocated to possibly multiple pools of queues.
 For destination MAC, each VMDq pool will be assigned with a MAC address. In this sample, each VMDq pool
-is assigned to the MAC like 52:54:00:12:<port_id>:<pool_id>, that is,
-the MAC of VMDq pool 2 on port 1 is 52:54:00:12:01:02.
+is assigned to the MAC like 52:54:00:12:<port_id>:<pool_id>.
+The MAC of VMDq pool 2 on port 1 is 52:54:00:12:01:02.
 
 .. literalinclude:: ../../../examples/vmdq/main.c
     :language: c
Signature · 1 line
2.34.1
#2 lore raw
Quoted 5 lines · Nandini Persad

I have revised these sections to suit the template, but also, for punctuation, clarity, and removing repetition when necessary.

---

I wonder if this should be split up into individual guides' updates for easier review?

Signature · 2 lines
Thanks,
Anatoly
#3 lore raw

cover doc: clean up sample application guides

In reply to Nandini Persad

This series revises the sample application user guides for clarity, grammar, and formatting consistency. Changes are documentation only:
wording is simplified, command-line options are normalised, Linux and Ethernet capitalisation is corrected, and definition lists replace ad hoc bullet lists where a term/description structure fits.

This work started from edits by Nandini Persad and was extended and reworked across the rest of the sample application guides.

Stephen Hemminger (15):
doc: cleanups to bbdev sample application
doc: cleanup cmd_line example documentation
doc: cleanup the distribution sample application guide
doc: improve structure and clarity of compiling guide
doc: improve clarity and consistency in DMA sample app guide
doc: correct capitalization and formatting in ethtool guide
doc: improve clarity in eventdev, FIPS, and flow filtering
doc: enhance hello_world, intro, IP frag and pipeline
doc: improve IP reassembly, IPsec, multicast, and keep-alive
doc: enhance L2 forwarding sample application guides
doc: enhance multi-process, NTB, ordering, and PTP guides
doc: improve QoS, callbacks, EFD, and service cores guides
doc: enhance skeleton, pipeline, timer, and vhost guides
doc: improve vhost, VM power, and VMDq sample guides
doc: correct grammar and punctuation consistency issues

 doc/guides/sample_app_ug/bbdev_app.rst        |  73 +++--
 doc/guides/sample_app_ug/cmd_line.rst         |  37 +--
 doc/guides/sample_app_ug/compiling.rst        |  84 +++---
 doc/guides/sample_app_ug/dist_app.rst         |  52 ++--
 doc/guides/sample_app_ug/dma.rst              |  60 ++--
 doc/guides/sample_app_ug/ethtool.rst          |  18 +-
 .../sample_app_ug/eventdev_pipeline.rst       |  51 ++--
 doc/guides/sample_app_ug/fips_validation.rst  |  65 +++--
 doc/guides/sample_app_ug/flow_filtering.rst   |  51 ++--
 doc/guides/sample_app_ug/hello_world.rst      |   8 +-
 doc/guides/sample_app_ug/intro.rst            |  34 +--
 doc/guides/sample_app_ug/ip_frag.rst          |  46 +--
 doc/guides/sample_app_ug/ip_pipeline.rst      | 109 ++++----
 doc/guides/sample_app_ug/ip_reassembly.rst    |  57 ++--
 doc/guides/sample_app_ug/ipsec_secgw.rst      | 128 ++++-----
 doc/guides/sample_app_ug/ipv4_multicast.rst   |  26 +-
 doc/guides/sample_app_ug/keep_alive.rst       |  12 +-
 doc/guides/sample_app_ug/l2_forward_cat.rst   |  34 +--
 .../sample_app_ug/l2_forward_crypto.rst       |  70 +++--
 doc/guides/sample_app_ug/l2_forward_event.rst |  20 +-
 .../sample_app_ug/l2_forward_job_stats.rst    |  46 ++-
 .../sample_app_ug/l2_forward_macsec.rst       |  38 +--
 .../sample_app_ug/l2_forward_real_virtual.rst |   4 +-
 doc/guides/sample_app_ug/link_status_intr.rst |   2 +-
 doc/guides/sample_app_ug/multi_process.rst    |  49 ++--
 doc/guides/sample_app_ug/ntb.rst              |   4 +-
 doc/guides/sample_app_ug/packet_ordering.rst  |  42 +--
 doc/guides/sample_app_ug/pipeline.rst         |  26 +-
 doc/guides/sample_app_ug/ptp_tap_relay_sw.rst |   2 +-
 doc/guides/sample_app_ug/ptpclient.rst        |  51 ++--
 doc/guides/sample_app_ug/qos_metering.rst     |  11 +-
 doc/guides/sample_app_ug/qos_scheduler.rst    |  16 +-
 doc/guides/sample_app_ug/rxtx_callbacks.rst   |  11 +-
 doc/guides/sample_app_ug/server_node_efd.rst  |   4 +-
 doc/guides/sample_app_ug/service_cores.rst    |  67 ++---
 doc/guides/sample_app_ug/skeleton.rst         |   8 +-
 doc/guides/sample_app_ug/test_pipeline.rst    |  17 +-
 doc/guides/sample_app_ug/timer.rst            |  19 +-
 doc/guides/sample_app_ug/vdpa.rst             |  51 ++--
 doc/guides/sample_app_ug/vhost.rst            | 178 ++++++------
 doc/guides/sample_app_ug/vhost_blk.rst        |  66 +++--
 doc/guides/sample_app_ug/vhost_crypto.rst     |  64 ++---
 .../sample_app_ug/vm_power_management.rst     | 262 ++++++++----------
 .../sample_app_ug/vmdq_dcb_forwarding.rst     | 101 ++++---
 doc/guides/sample_app_ug/vmdq_forwarding.rst  |  38 ++-
 45 files changed, 1121 insertions(+), 1091 deletions(-)
Signature · 1 line
2.53.0
#4 lore raw

PATCH 1/15 doc: cleanups to bbdev sample application

Semi-automated cleanup of wording of bbdev sample guide.

Refactored the bbdev sample application documentation for better clarity:
- Simplified the overview section with clearer flow description
- Improved formatting of command-line options using definition list
- Clarified hardware/software device requirements
- Enhanced example command explanation with bullet points
- Fixed grammatical issues and improved readability

---
 doc/guides/sample_app_ug/bbdev_app.rst | 69 +++++++++++++-------------
 1 file changed, 34 insertions(+), 35 deletions(-)
doc/guides/sample_app_ug/bbdev_app.rst +34 -35
index a699e8a61d..00bbd1aa27 100644
@@ -14,14 +14,13 @@ Overview
 --------
 
 The Baseband device sample application performs a loop-back operation using a
-baseband device capable of transceiving data packets.
-A packet is received on an ethernet port -> enqueued for downlink baseband
-operation -> dequeued from the downlink baseband device -> enqueued for uplink
-baseband operation -> dequeued from the baseband device -> then the received
-packet is compared with the baseband operations output. Then it's looped back to
-the ethernet port.
+baseband device capable of performing encoding and decoding operations.
+A packet is received on an Ethernet port, enqueued for downlink baseband
+operation, dequeued from the downlink baseband device, enqueued for uplink
+baseband operation, dequeued from the baseband device, compared with the
+expected output, and then transmitted back to the Ethernet port.
 
-*   The MAC header is preserved in the packet
+The MAC header is preserved in the packet throughout the loop-back operation.
 
 Limitations
 -----------
@@ -33,7 +32,7 @@ Compiling the Application
 
 DPDK needs to be built with ``baseband_turbo_sw`` PMD enabled along
 with ``FLEXRAN SDK`` Libraries. Refer to *SW Turbo Poll Mode Driver*
-documentation for more details on this.
+documentation for more details.
 
 To compile the sample application see :doc:`compiling`.
 
@@ -48,40 +47,41 @@ The application accepts a number of command line options:
     $ ./<build_dir>/examples/dpdk-bbdev [EAL options] -- [-e ENCODING_CORES] /
     [-d DECODING_CORES] [-p ETH_PORT_ID] [-b BBDEV_ID]
 
-where:
+Where:
+
+``-e ENCODING_CORES``
+   Hexadecimal bitmask specifying lcores for encoding operations (default: 0x2).
+
+``-d DECODING_CORES``
+   Hexadecimal bitmask specifying lcores for decoding operations (default: 0x4).
 
-* ``e ENCODING_CORES``: hexmask for encoding lcores (default = 0x2)
-* ``d DECODING_CORES``: hexmask for decoding lcores (default = 0x4)
-* ``p ETH_PORT_ID``: ethernet port ID (default = 0)
-* ``b BBDEV_ID``: BBDev ID (default = 0)
+``-p ETH_PORT_ID``
+   Ethernet port ID (default: 0).
 
-The application requires that baseband devices is capable of performing
-the specified baseband operation are available on application initialization.
-This means that HW baseband device/s must be bound to a DPDK driver or
-a SW baseband device/s (virtual BBdev) must be created (using --vdev).
+``-b BBDEV_ID``
+   Baseband device ID (default: 0).
 
-To run the application in linux environment with the turbo_sw baseband device
-using the allow option for pci device running on 1 encoding lcore and 1 decoding lcore
-issue the command:
+The application requires that baseband devices are capable of performing
+the specified baseband operations at initialization time. Hardware baseband
+devices must be bound to a DPDK driver, or software baseband devices (virtual
+BBdev) must be created using the ``--vdev`` option.
+
+To run the application in a Linux environment with the turbo_sw baseband device,
+using one encoding lcore and one decoding lcore:
 
 .. code-block:: console
 
     $ ./<build_dir>/examples/dpdk-bbdev --vdev='baseband_turbo_sw' -a <NIC0PCIADDR> \
     -l 3,4,5 --numa-mem=2,2 --file-prefix=bbdev -- -e 0x10 -d 0x20
 
-where, NIC0PCIADDR is the PCI address of the Rx port
-
-This command creates one virtual bbdev devices ``baseband_turbo_sw`` where the
-device gets linked to a corresponding ethernet port as allowed by
-the parameter -a.
-3 cores are allocated to the application, and assigned as:
-
- - core 3 is the main and used to print the stats live on screen,
+Where ``NIC0PCIADDR`` is the PCI address of the Ethernet port.
 
- - core 4 is the encoding lcore performing Rx and Turbo Encode operations
+This command creates one virtual BBdev device (``baseband_turbo_sw``) and
+allows access to the specified Ethernet port. Three cores are allocated:
 
- - core 5 is the downlink lcore performing Turbo Decode, validation and Tx
-   operations
+- Core 3: Main lcore, prints statistics to screen
+- Core 4: Encoding lcore, performs Rx and Turbo Encode operations
+- Core 5: Decoding lcore, performs Turbo Decode, validation, and Tx operations
 
 
 Refer to the *DPDK Getting Started Guide* for general information on running
@@ -91,9 +91,8 @@ Using Packet Generator with baseband device sample application
 --------------------------------------------------------------
 
 To allow the bbdev sample app to do the loopback, an influx of traffic is required.
-This can be done by using DPDK Pktgen to burst traffic on two ethernet ports, and
-it will print the transmitted along with the looped-back traffic on Rx ports.
-Executing the command below will generate traffic on the two allowed ethernet
+This can be done using DPDK Pktgen to generate traffic on Ethernet ports.
+Executing the command below will generate traffic on the allowed Ethernet
 ports.
 
 .. code-block:: console
@@ -111,5 +110,5 @@ where:
 * ``-P``: PROMISCUOUS mode
 
 
-Refer to *The Pktgen Application* documents for general information on running
+Refer to *The Pktgen Application* documentation for general information on running
 Pktgen with DPDK applications.
Signature · 1 line
2.53.0
#5 lore raw

PATCH 2/15 doc: cleanup cmd_line example documentation

In reply to Stephen Hemminger

Semi-automated review of sample application for cmd_line.

Enhanced the command line sample application guide:
- Simplified the production code warning note for clarity
- Converted command descriptions to definition list format
- Fixed typo in "Ethernet Address Token" description
- Clarified the parsing and callback mechanism description
- Improved overall readability and consistency

---
 doc/guides/sample_app_ug/cmd_line.rst | 35 +++++++++++++++------------
 1 file changed, 19 insertions(+), 16 deletions(-)
doc/guides/sample_app_ug/cmd_line.rst +19 -16
index e038667bd5..5b192bc615 100644
@@ -13,29 +13,32 @@ Overview
 The Command Line sample application is a simple application that
 demonstrates the use of the command line interface in the DPDK.
 This application is a readline-like interface that can be used
-to debug a DPDK application in a Linux* application environment.
+to debug DPDK applications in a Linux application environment.
 
 .. note::
 
     The rte_cmdline library should not be used in production code since
     it is not validated to the same standard as other DPDK libraries.
-    See also the "rte_cmdline library should not be used in production code due to limited testing" item
-    in the "Known Issues" section of the Release Notes.
+    See also the Known Issues section of the Release Notes for the item
+    regarding limited testing of the rte_cmdline library.
 
 The Command Line sample application supports some of the features of the GNU readline library
 such as completion, cut/paste and other special bindings
-that make configuration and debug faster and easier.
+that make configuration and debugging faster and easier.
 
-The application shows how the ``cmdline`` library can be extended
+The application demonstrates how the ``cmdline`` library can be extended
 to handle a list of objects.
 
 There are three simple commands:
 
-*   add obj_name IP: Add a new object with an IP/IPv6 address associated to it.
+``add obj_name IP``
+   Add a new object with an IP/IPv6 address associated with it.
 
-*   del obj_name: Delete the specified object.
+``del obj_name``
+   Delete the specified object.
 
-*   show obj_name: Show the IP associated with the specified object.
+``show obj_name``
+   Show the IP associated with the specified object.
 
 .. note::
 
@@ -63,7 +66,7 @@ and the Environment Abstraction Layer (EAL) options.
 Explanation
 -----------
 
-The following sections provide explanation of the code.
+The following sections provide an explanation of the code.
 
 EAL Initialization and cmdline Start
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -84,7 +87,7 @@ Then, a new command line object is created and starts to interact with the user
     :end-before: >8 End of creating a new command line object.
     :dedent: 1
 
-The ``cmdline_interact()`` function returns when the user types **Ctrl-d** and,
+The ``cmdline_interact()`` function returns when the user types **Ctrl-d**, and
 in this case, the application exits.
 
 Defining a cmdline Context
@@ -102,15 +105,15 @@ Each command (of type cmdline_parse_inst_t) is defined statically.
 It contains a pointer to a callback function that is executed when the command is parsed,
 an opaque pointer, a help string and a list of tokens in a NULL-terminated table.
 
-The rte_cmdline application provides a list of pre-defined token types:
+The rte_cmdline library provides a list of predefined token types:
 
-*   String Token: Match a static string, a list of static strings or any string.
+*   String Token: Match a static string, a list of static strings, or any string.
 
-*   Number Token: Match a number that can be signed or unsigned, from 8-bit to 32-bit.
+*   Number Token: Match a number that can be signed or unsigned, from 8 bits to 32 bits.
 
 *   IP Address Token: Match an IPv4 or IPv6 address or network.
 
-*   Ethernet* Address Token: Match a MAC address.
+*   Ethernet Address Token: Match a MAC address.
 
 In this example, a new token type obj_list is defined and implemented
 in the parse_obj_list.c and parse_obj_list.h files.
@@ -128,5 +131,5 @@ This command is composed of two tokens:
 
 *   The second token is an object that was previously added using the add command in the global_obj_list variable.
 
-Once the command is parsed, the rte_cmdline application fills a cmd_obj_del_show_result structure.
-A pointer to this structure is given as an argument to the callback function and can be used in the body of this function.
+Once the command is parsed, the rte_cmdline library fills a cmd_obj_del_show_result structure
+and passes a pointer to it as an argument to the callback function.
Signature · 1 line
2.53.0
#6 lore raw

PATCH 3/15 doc: cleanup the distribution sample application guide

In reply to Stephen Hemminger

Fix punctuation, clarity, and removing repetition when necessary.

---
 doc/guides/sample_app_ug/dist_app.rst | 52 +++++++++++++--------------
 1 file changed, 26 insertions(+), 26 deletions(-)
doc/guides/sample_app_ug/dist_app.rst +26 -26
index 30b4184d40..11496471ae 100644
@@ -4,7 +4,7 @@
 Distributor Sample Application
 ==============================
 
-The distributor sample application is a simple example of packet distribution
+The distributor sample application is an example of packet distribution
 to cores using the Data Plane Development Kit (DPDK). It also makes use of
 Intel Speed Select Technology - Base Frequency (Intel SST-BF) to pin the
 distributor to the higher frequency core if available.
@@ -31,7 +31,7 @@ generator as shown in the figure below.
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``distributor`` sub-directory.
 
@@ -49,7 +49,7 @@ Running the Application
    *   -p PORTMASK: Hexadecimal bitmask of ports to configure
    *   -c: Combines the RX core with distribution core
 
-#. To run the application in linux environment with 10 lcores, 4 ports,
+#. To run the application in a Linux environment with 10 lcores, 4 ports,
    issue the command:
 
    ..  code-block:: console
@@ -64,19 +64,19 @@ Explanation
 
 The distributor application consists of four types of threads: a receive
 thread (``lcore_rx()``), a distributor thread (``lcore_dist()``), a set of
-worker threads (``lcore_worker()``), and a transmit thread(``lcore_tx()``).
+worker threads (``lcore_worker()``), and a transmit thread (``lcore_tx()``).
 How these threads work together is shown in :numref:`figure_dist_app` below.
-The ``main()`` function launches  threads of these four types.  Each thread
-has a while loop which will be doing processing and which is terminated
+The ``main()`` function launches threads of these four types. Each thread
+has a while loop that performs processing and is terminated
 only upon SIGINT or ctrl+C.
 
 The receive thread receives the packets using ``rte_eth_rx_burst()`` and will
-enqueue them to an rte_ring. The distributor thread will dequeue the packets
-from the ring and assign them to workers (using ``rte_distributor_process()`` API).
-This assignment is based on the tag (or flow ID) of the packet - indicated by
-the hash field in the mbuf. For IP traffic, this field is automatically filled
-by the NIC with the "usr" hash value for the packet, which works as a per-flow
-tag.  The distributor thread communicates with the worker threads using a
+enqueue them to an rte_ring. The distributor thread dequeues the packets
+from the ring and assigns them to workers using the ``rte_distributor_process()``
+API. This assignment is based on the tag (or flow ID) of the packet, indicated
+by the hash field in the mbuf. For IP traffic, this field is automatically
+filled by the NIC with the "user" hash value for the packet, which works as a
+per-flow tag. The distributor thread communicates with the worker threads using a
 cache-line swapping mechanism, passing up to 8 mbuf pointers at a time
 (one cache line) to each worker.
 
@@ -86,11 +86,11 @@ the distributor, doing a simple XOR operation on the input port mbuf field
 (to indicate the output port which will be used later for packet transmission)
 and then finally returning the packets back to the distributor thread.
 
-The distributor thread will then call the distributor api
-``rte_distributor_returned_pkts()`` to get the processed packets, and will enqueue
-them to another rte_ring for transfer to the TX thread for transmission on the
-output port. The transmit thread will dequeue the packets from the ring and
-transmit them on the output port specified in packet mbuf.
+The distributor thread will then call the distributor API
+``rte_distributor_returned_pkts()`` to get the processed packets and enqueue
+them to another rte_ring for transfer to the TX thread. The transmit thread
+dequeues the packets from the ring and transmits them on the output port
+specified in the packet mbuf.
 
 Users who wish to terminate the running of the application have to press ctrl+C
 (or send SIGINT to the app). Upon this signal, a signal handler provided
@@ -105,29 +105,29 @@ final statistics to the user.
 
 
 Intel SST-BF Support
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 In DPDK 19.05, support was added to the power management library for
-Intel-SST-BF, a technology that allows some cores to run at a higher
+Intel SST-BF, a technology that allows some cores to run at a higher
 frequency than others. An application note for Intel SST-BF is available,
 and is entitled
 `Intel Speed Select Technology – Base Frequency - Enhancing Performance <https://builders.intel.com/docs/networkbuilders/intel-speed-select-technology-base-frequency-enhancing-performance.pdf>`_
 
 The distributor application was also enhanced to be aware of these higher
-frequency SST-BF cores, and when starting the application, if high frequency
+frequency SST-BF cores. When starting the application, if high frequency
 SST-BF cores are present in the core mask, the application will identify these
 cores and pin the workloads appropriately. The distributor core is usually
 the bottleneck, so this is given first choice of the high frequency SST-BF
-cores, followed by the rx core and the tx core.
+cores, followed by the Rx core and the Tx core.
 
 Debug Logging Support
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 Debug logging is provided as part of the application; the user needs to uncomment
 the line "#define DEBUG" defined in start of the application in main.c to enable debug logs.
 
 Statistics
-----------
+~~~~~~~~~~
 
 The main function will print statistics on the console every second. These
 statistics include the number of packets enqueued and dequeued at each stage
@@ -135,7 +135,7 @@ in the application, and also key statistics per worker, including how many
 packets of each burst size (1-8) were sent to each worker thread.
 
 Application Initialization
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Command line parsing is done in the same way as it is done in the L2 Forwarding Sample
 Application. See :ref:`l2_fwd_app_cmd_arguments`.
@@ -146,8 +146,8 @@ Sample Application. See :ref:`l2_fwd_app_mbuf_init`.
 Driver Initialization is done in same way as it is done in the L2 Forwarding Sample
 Application. See :ref:`l2_fwd_app_dvr_init`.
 
-RX queue initialization is done in the same way as it is done in the L2 Forwarding
+Rx queue initialization is done in the same way as it is done in the L2 Forwarding
 Sample Application. See :ref:`l2_fwd_app_rx_init`.
 
-TX queue initialization is done in the same way as it is done in the L2 Forwarding
+Tx queue initialization is done in the same way as it is done in the L2 Forwarding
 Sample Application. See :ref:`l2_fwd_app_tx_init`.
Signature · 1 line
2.53.0
#7 lore raw

PATCH 4/15 doc: improve structure and clarity of compiling guide

In reply to Stephen Hemminger

Restructured the sample applications compiling guide:
- Added clearer section headers with proper capitalization
- Improved command block formatting and indentation consistency
- Added setup instructions for build directory creation
- Clarified the distinction between meson and make approaches
- Enhanced explanations with better context for each step
- Added note about flexible build directory naming
- Improved overall document flow and readability

---
 doc/guides/sample_app_ug/compiling.rst | 84 ++++++++++++++++----------
 1 file changed, 51 insertions(+), 33 deletions(-)
doc/guides/sample_app_ug/compiling.rst +51 -33
index adde775d4e..a68a9e713c 100644
@@ -5,79 +5,97 @@ Compiling the Sample Applications
 =================================
 
 This section explains how to compile the DPDK sample applications.
+Sample applications are located in ``dpdk/examples/``.
 
-To compile all the sample applications
---------------------------------------
+To Compile All the Sample Applications
+---------------------------------------
 
-Go to DPDK build directory:
+Set up the build directory (if not already done):
 
-    .. code-block:: console
+.. code-block:: console
 
-       cd dpdk/<build_dir>
+   cd dpdk
+   meson setup build
 
-Enable examples compilation:
+.. note::
 
-   .. code-block:: console
+   The build directory name (``build`` in this example) can be chosen freely.
+   Replace ``<build_dir>`` in subsequent commands with your chosen directory name.
 
-      meson configure -Dexamples=all
+Go to the build directory:
 
-Build:
+.. code-block:: console
 
-   .. code-block:: console
+   cd build
 
-      ninja
+.. code-block:: console
+
+   meson configure -Dexamples=all
+
+Compile:
+
+.. code-block:: console
+
+   ninja
 
 For additional information on compiling see
 :ref:`Compiling DPDK on Linux <linux_gsg_compiling_dpdk>` or
 :ref:`Compiling DPDK on FreeBSD <building_from_source>`.
-Applications are output to: ``dpdk/<build_dir>/examples``.
 
+Compiled applications are output to ``dpdk/<build_dir>/examples``.
 
-To compile a single application
--------------------------------
 
+To Compile a Single Application
+--------------------------------
+
+A single application can be compiled using meson during the DPDK build,
+or standalone using make with an installed DPDK.
 
 Using meson
 ~~~~~~~~~~~
 
-Go to DPDK build directory:
+Go to the build directory (after ``meson setup`` as shown above):
 
-    .. code-block:: console
+.. code-block:: console
 
-       cd dpdk/<build_dir>
+   cd dpdk/build
 
 Enable example app compilation:
 
-   .. code-block:: console
+.. code-block:: console
+
+   meson configure -Dexamples=helloworld
+
+Compile:
 
-      meson configure -Dexamples=helloworld
+.. code-block:: console
 
-Build:
+   ninja
 
-   .. code-block:: console
 
-      ninja
+Using make (standalone)
+~~~~~~~~~~~~~~~~~~~~~~~
 
+To compile a sample application standalone using make, DPDK must first
+be installed on the system and pkg-config must be configured.
+See :ref:`building_app_using_installed_dpdk` for installation instructions.
 
-Using Make
-~~~~~~~~~~
+Go to the sample application directory:
 
-Pkg-config is used when building an example app standalone using make, please
-see :ref:`building_app_using_installed_dpdk` for more information.
+.. code-block:: console
 
-Go to the sample application directory. Unless otherwise specified the sample
-applications are located in ``dpdk/examples/``.
+   cd dpdk/examples/helloworld
 
 Build the application:
 
-    .. code-block:: console
+.. code-block:: console
 
-        make
+   make
 
 To build the application for debugging use the ``DEBUG`` option.
 This option adds some extra flags, disables compiler optimizations and
-sets verbose output.
+sets verbose output:
 
-    .. code-block:: console
+.. code-block:: console
 
-       make DEBUG=1
+   make DEBUG=1
Signature · 1 line
2.53.0
#8 lore raw

PATCH 5/15 doc: improve clarity and consistency in DMA sample app guide

In reply to Stephen Hemminger

Enhanced the DMA sample application documentation:
- Simplified MAC address modification description using bullet points
- Improved grammar and readability throughout
- Standardized terminology (DMAdev, Tx/Rx port formatting)
- Fixed article usage and clarified technical explanations
- Enhanced sentence structure for better flow
- Corrected minor grammatical issues and typos

---
 doc/guides/sample_app_ug/dma.rst | 60 +++++++++++++++-----------------
 1 file changed, 29 insertions(+), 31 deletions(-)
doc/guides/sample_app_ug/dma.rst +29 -31
index 9605996c6c..484fe27d92 100644
@@ -13,16 +13,15 @@ This sample is intended as a demonstration of the basic components of a DPDK
 forwarding application and an example of how to use the DMAdev API to make a packet
 copy application.
 
-Also, while forwarding, the MAC addresses are affected as follows:
+While forwarding, the application modifies MAC addresses:
 
-*   The source MAC address is replaced by the TX port MAC address
+*   Source MAC address: replaced with the Tx port MAC address
+*   Destination MAC address: replaced with ``02:00:00:00:00:TX_PORT_ID``
 
-*   The destination MAC address is replaced by  02:00:00:00:00:TX_PORT_ID
-
-This application can be used to compare performance of using software packet
-copy with copy done using a DMA device for different sizes of packets.
-The example will print out statistics each second. The stats shows
-received/send packets and packets dropped or failed to copy.
+This application can be used to compare the performance of using software packet
+copy versus DMA device copy for different packet sizes.
+The application prints statistics at a configurable interval.
+The statistics show received/sent packets and packets dropped or failed to copy.
 
 Compiling the Application
 -------------------------
@@ -35,7 +34,7 @@ The application is located in the ``dma`` sub-directory.
 Running the Application
 -----------------------
 
-In order to run the hardware copy application, the copying device
+To run the hardware copy application, the copying device
 needs to be bound to user-space IO driver.
 
 Refer to the :doc:`../prog_guide/dmadev` for information on using the library.
@@ -54,10 +53,10 @@ where,
 *   q NQ: Number of Rx queues used per port equivalent to DMA channels
     per port (default is 1)
 
-*   c CT: Performed packet copy type: software (sw) or hardware using
+*   c CT: Packet copy type: software (``sw``) or hardware using
     DMA (hw) (default is hw)
 
-*   s RS: Size of dmadev descriptor ring for hardware copy mode or rte_ring for
+*   s RS: Size of DMAdev descriptor ring for hardware copy mode or rte_ring for
     software copy mode (default is 2048)
 
 *   --[no-]mac-updating: Whether MAC address of packets should be changed
@@ -71,9 +70,9 @@ where,
 
 The application can be launched in various configurations depending on the
 provided parameters. The app can use up to 2 lcores: one of them receives
-incoming traffic and makes a copy of each packet. The second lcore then
+incoming traffic and makes a copy of each packet, and the second lcore
 updates the MAC address and sends the copy. If one lcore per port is used,
-both operations are done sequentially. For each configuration, an additional
+both operations are performed sequentially. For each configuration, an additional
 lcore is needed since the main lcore does not handle traffic but is
 responsible for configuration, statistics printing and safe shutdown of
 all ports and devices.
@@ -89,7 +88,7 @@ updating issue the command:
     $ ./<build_dir>/examples/dpdk-dma -l 0-2 -n 2 -- -p 0x1 --mac-updating -c sw
 
 To run the application in a Linux environment with 2 lcores (the main lcore,
-plus one forwarding core), 2 ports (ports 0 and 1), hardware copying and no MAC
+plus one forwarding core), 2 ports (ports 0 and 1), hardware copying, and no MAC
 updating issue the command:
 
 .. code-block:: console
@@ -146,7 +145,7 @@ The ``main()`` function also initializes the ports:
     :end-before: >8 End of initializing each port.
     :dedent: 1
 
-Each port is configured using ``port_init()`` function. The Ethernet
+Each port is configured using the ``port_init()`` function. The Ethernet
 ports are configured with local settings using the ``rte_eth_dev_configure()``
 function and the ``port_conf`` struct. The RSS is enabled so that
 multiple Rx queues could be used for packet receiving and copying by
@@ -198,7 +197,7 @@ and HW copy modes.
     :dedent: 0
 
 
-When using hardware copy each Rx queue of the port is assigned a DMA device
+When using hardware copy, each Rx queue of the port is assigned a DMA device
 (``assign_dmadevs()``) using DMAdev library API functions:
 
 .. literalinclude:: ../../../examples/dma/dmafwd.c
@@ -220,7 +219,7 @@ using ``rte_dma_start()`` function. Each of the above operations is done in
     :end-before: >8 End of configuration of device.
     :dedent: 0
 
-If initialization is successful, memory for hardware device
+If initialization is successful, memory for the hardware device
 statistics is allocated.
 
 Finally, the ``main()`` function starts all packet handling lcores and starts
@@ -228,7 +227,7 @@ printing stats in a loop on the main lcore. The application can be
 interrupted and closed using ``Ctrl-C``. The main lcore waits for
 all worker lcores to finish, deallocates resources and exits.
 
-The processing lcores launching function are described below.
+The processing lcore launching functions are described below.
 
 The Lcores Launching Functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -259,10 +258,10 @@ corresponding to ports and lcores configuration provided by the user.
 The Lcores Processing Functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For receiving packets on each port, the ``dma_rx_port()`` function is used.
-The function receives packets on each configured Rx queue. Depending on the
+The ``dma_rx_port()`` function receives packets on each port.
+It receives packets on each configured Rx queue. Depending on the
 mode the user chose, it will enqueue packets to DMA channels and
-then invoke copy process (hardware copy), or perform software copy of each
+then invoke the copy process (hardware copy), or perform software copy of each
 packet using ``pktmbuf_sw_copy()`` function and enqueue them to an rte_ring:
 
 .. literalinclude:: ../../../examples/dma/dmafwd.c
@@ -271,13 +270,13 @@ packet using ``pktmbuf_sw_copy()`` function and enqueue them to an rte_ring:
     :end-before: >8 End of receive packets on one port and enqueue to dmadev or rte_ring.
     :dedent: 0
 
-The packets are received in burst mode using ``rte_eth_rx_burst()``
-function. When using hardware copy mode the packets are enqueued in the
-copying device's buffer using ``dma_enqueue_packets()`` which calls
+Packets are received in burst mode using the ``rte_eth_rx_burst()``
+function. When using hardware copy mode, packets are enqueued in the
+DMA device buffer using ``dma_enqueue_packets()``, which calls
 ``rte_dma_copy()``. When all received packets are in the
 buffer, the copy operations are started by calling ``rte_dma_submit()``.
-Function ``rte_dma_copy()`` operates on physical address of
-the packet. Structure ``rte_mbuf`` contains only physical address to
+The ``rte_dma_copy()`` function operates on the physical address of
+the packet. The ``rte_mbuf`` structure contains only the physical address to the
 start of the data buffer (``buf_iova``). Thus, the ``rte_pktmbuf_iova()`` API is
 used to get the address of the start of the data within the mbuf.
 
@@ -287,12 +286,11 @@ used to get the address of the start of the data within the mbuf.
     :end-before: >8 End of receive packets on one port and enqueue to dmadev or rte_ring.
     :dedent: 0
 
-
-Once the copies have been completed (this includes gathering the completions in
+Once the copies have been completed (which includes gathering the completions in
 HW copy mode), the copied packets are enqueued to the ``rx_to_tx_ring``, which
 is used to pass the packets to the Tx function.
 
-All completed copies are processed by ``dma_tx_port()`` function. This function
+All completed copies are processed by the ``dma_tx_port()`` function. This function
 dequeues copied packets from the ``rx_to_tx_ring``. Then, each packet MAC address is changed
 if it was enabled. After that, copies are sent in burst mode using ``rte_eth_tx_burst()``.
 
@@ -306,7 +304,7 @@ if it was enabled. After that, copies are sent in burst mode using ``rte_eth_tx_
 The Packet Copying Functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In order to perform SW packet copy, there are user-defined functions to the first copy
+To perform software packet copy, the user-defined functions first copy
 the packet metadata (``pktmbuf_metadata_copy()``) and then the packet data
 (``pktmbuf_sw_copy()``):
 
@@ -319,5 +317,5 @@ the packet metadata (``pktmbuf_metadata_copy()``) and then the packet data
 The metadata in this example is copied from ``rx_descriptor_fields1`` marker of
 ``rte_mbuf`` struct up to ``buf_len`` member.
 
-In order to understand why software packet copying is done as shown
+To understand why software packet copying is performed as shown
 above, please refer to the :doc:`../prog_guide/mbuf_lib`.
Signature · 1 line
2.53.0
Acked-by on v1 5/15
#9 lore raw

Re: [PATCH 05/15] doc: improve clarity and consistency in DMA sample app guide

Quoted 9 lines · Stephen Hemminger

Enhanced the DMA sample application documentation:
- Simplified MAC address modification description using bullet points
- Improved grammar and readability throughout
- Standardized terminology (DMAdev, Tx/Rx port formatting)
- Fixed article usage and clarified technical explanations
- Enhanced sentence structure for better flow
- Corrected minor grammatical issues and typos

#10 lore raw

PATCH 6/15 doc: correct capitalization and formatting in ethtool guide

In reply to Stephen Hemminger

Correct consistency issues in the ethtool sample application guide:
- Changed "sub-directory" to "subdirectory" for consistency
- Fixed heading capitalization inconsistencies
- Corrected "Ethtool" to "ethtool" where appropriate
- Fixed "call-back" to "callback" (single word)
- Improved sentence structure and readability

---
 doc/guides/sample_app_ug/ethtool.rst | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)
doc/guides/sample_app_ug/ethtool.rst +8 -8
index 8bb8b73922..68bcf25b1f 100644
@@ -20,9 +20,9 @@ Compiling the Application
 
 To compile the sample application see :doc:`compiling`.
 
-The application is located in the ``ethtool`` sub-directory.
+The application is located in the ``ethtool`` subdirectory.
 
-Running the Application
+Running the application
 -----------------------
 
 The application requires an available core for each port, plus one.
@@ -43,7 +43,7 @@ The application is console-driven using the cmdline DPDK interface:
         EthApp>
 
 From this interface, the available commands and descriptions
-of what they do are as follows:
+are as follows:
 
 * ``drvinfo``: Print driver info
 * ``eeprom``: Dump EEPROM to file
@@ -67,8 +67,8 @@ Explanation
 -----------
 
 The sample program has two parts: A background `packet reflector`_
-that runs on a worker core, and a foreground `Ethtool Shell`_ that
-runs on the main core. These are described below.
+that runs on a worker core, and a foreground `ethtool shell`_ that
+runs on the main core.
 
 Packet Reflector
 ~~~~~~~~~~~~~~~~
@@ -82,11 +82,11 @@ source address, and is then sent out on the same port.
 Ethtool Shell
 ~~~~~~~~~~~~~
 
-The foreground part of the Ethtool sample is a console-based
+The foreground part of the ethtool sample is a console-based
 interface that accepts commands as described in `running the
-application`_. Individual call-back functions handle the detail
+Running the application`_. Individual callback functions handle the detail
 associated with each command, which make use of the functions
-defined in the `Ethtool interface`_ to the DPDK functions.
+defined in the `ethtool interface`_ to the DPDK functions.
 
 Ethtool interface
 -----------------
Signature · 1 line
2.53.0
#11 lore raw

PATCH 7/15 doc: improve clarity in eventdev, FIPS, and flow filtering

In reply to Stephen Hemminger

Enhanced multiple sample application guides:

eventdev_pipeline.rst:
- Improved command-line option formatting and descriptions
- Standardized terminology and fixed grammatical issues
- Clarified pipeline stage descriptions

fips_validation.rst:
- Restructured algorithm support sections for clarity
- Fixed formatting inconsistencies
- Improved readability of validation process descriptions

flow_filtering.rst:
- Enhanced code explanations and flow descriptions
- Fixed formatting and indentation issues
- Clarified API usage examples

---
 .../sample_app_ug/eventdev_pipeline.rst       | 51 ++++++++-------
 doc/guides/sample_app_ug/fips_validation.rst  | 63 +++++++++----------
 doc/guides/sample_app_ug/flow_filtering.rst   | 51 +++++++--------
 3 files changed, 82 insertions(+), 83 deletions(-)
doc/guides/sample_app_ug/eventdev_pipeline.rst +25 -26
index 19ff53803e..343d3f46ec 100644
@@ -4,41 +4,40 @@
 Eventdev Pipeline Sample Application
 ====================================
 
-The eventdev pipeline sample application is a sample app that demonstrates
+The eventdev pipeline sample application is an application that demonstrates
 the usage of the eventdev API using the software PMD. It shows how an
 application can configure a pipeline and assign a set of worker cores to
 perform the processing required.
 
-The application has a range of command line arguments allowing it to be
-configured for various numbers worker cores, stages,queue depths and cycles per
-stage of work. This is useful for performance testing as well as quickly testing
+The application has a range of command line arguments that allow it to be
+configured for various numbers of worker cores, stages, queue depths, and cycles
+per stage of work. This is useful for performance testing as well as quickly testing
 a particular pipeline configuration.
 
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
-
-The application is located in the ``examples`` sub-directory.
+To compile the sample application, see :doc:`compiling`.
 
+The application is located in the ``examples`` directory.
 
 
 Running the Application
 -----------------------
 
-The application has a lot of command line options. This allows specification of
-the eventdev PMD to use, and a number of attributes of the processing pipeline
+The application has a lot of command line options. This allows the specification of
+the eventdev PMD to use and for a number of attributes of the processing pipeline
 options.
 
 An example eventdev pipeline running with the software eventdev PMD using
 these settings is shown below:
 
- * ``-l 0,2,8-15``: lcore to use
+ * ``-l 0,2,8-15``: lcores to use
  * ``-r1``: core mask 0x1 for RX
  * ``-t1``: core mask 0x1 for TX
  * ``-e4``: core mask 0x4 for the software scheduler
- * ``-w FF00``: core mask for worker cores, 8 cores from 8th to 16th
+ * ``-w FF00``: core mask for worker cores, 8 cores from 8th to 15th
  * ``-s4``: 4 atomic stages
  * ``-n0``: process infinite packets (run forever)
  * ``-c32``: worker dequeue depth of 32
@@ -50,8 +49,8 @@ these settings is shown below:
     ./<build_dir>/examples/dpdk-eventdev_pipeline -l 0,2,8-15 --vdev event_sw0 \
     -- -r1 -t1 -e4 -w FF00 -s4 -n0 -c32 -W1000 -D
 
-The application has some sanity checking built-in, so if there is a function
-(e.g.; the RX core) which doesn't have a cpu core mask assigned, the application
+The application has sanity checking built-in, so if there is a function
+(e.g., the RX core) which does not have a CPU core mask assigned, the application
 will print an error message:
 
 .. code-block:: console
@@ -61,26 +60,26 @@ will print an error message:
           rx: 0
           tx: 1
 
-Configuration of the eventdev is covered in detail in the programmers guide,
-see the Event Device Library section.
+Configuration of the eventdev is covered in detail in the programmer's guide.
+See the Event Device Library section.
 
 
 Observing the Application
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-At runtime the eventdev pipeline application prints out a summary of the
-configuration, and some runtime statistics like packets per second. On exit the
-worker statistics are printed, along with a full dump of the PMD statistics if
+At runtime, the eventdev pipeline application prints out a summary of the
+configuration, and some runtime statistics like packets per second. On exit, the
+worker core statistics are printed, along with a full dump of the PMD statistics if
 required. The following sections show sample output for each of the output
 types.
 
 Configuration
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
-This provides an overview of the pipeline,
-scheduling type at each stage, and parameters to options such as how many
-flows to use and what eventdev PMD is in use. See the following sample output
-for details:
+The configuration output provides an overview of the pipeline, the scheduling
+type at each stage,
+and parameters such as the number of flows and the eventdev PMD in use.
+See the following sample output for details:
 
 .. code-block:: console
 
@@ -101,7 +100,7 @@ for details:
         Stage 3, Type Atomic    Priority = 128
 
 Runtime
-~~~~~~~
+^^^^^^^
 
 At runtime, the statistics of the consumer are printed, stating the number of
 packets received, runtime in milliseconds, average mpps, and current mpps.
@@ -111,7 +110,7 @@ packets received, runtime in milliseconds, average mpps, and current mpps.
   # consumer RX= xxxxxxx, time yyyy ms, avg z.zzz mpps [current w.www mpps]
 
 Shutdown
-~~~~~~~~
+^^^^^^^^
 
 At shutdown, the application prints the number of packets received and
 transmitted, and an overview of the distribution of work across worker cores.
doc/guides/sample_app_ug/fips_validation.rst +31 -32

116 lines not on this page · raw message

doc/guides/sample_app_ug/flow_filtering.rst +26 -25

133 lines not on this page · raw message

Signature · 1 line
2.53.0
#12 lore raw

PATCH 8/15 doc: enhance hello_world, intro, IP frag and pipeline

In reply to Stephen Hemminger

Improved documentation across multiple sample applications:

hello_world.rst:
- Minor formatting and clarity improvements

intro.rst:
- Updated sample application descriptions for accuracy
- Fixed formatting and improved readability
- Clarified application purposes and use cases

ip_frag.rst:
- Enhanced command-line option descriptions
- Improved flow explanations
- Fixed terminology and formatting consistency

ip_pipeline.rst:
- Restructured pipeline configuration sections
- Improved CLI command descriptions
- Enhanced clarity of pipeline concepts

---
 doc/guides/sample_app_ug/hello_world.rst |   6 +-
 doc/guides/sample_app_ug/intro.rst       |  34 +++----
 doc/guides/sample_app_ug/ip_frag.rst     |  46 +++++-----
 doc/guides/sample_app_ug/ip_pipeline.rst | 109 ++++++++++++-----------
 4 files changed, 103 insertions(+), 92 deletions(-)
doc/guides/sample_app_ug/hello_world.rst +3 -3
index b7167aa345..603a1d8767 100644
@@ -9,7 +9,7 @@ Overview
 --------
 
 The Hello World sample application is an example of the simplest DPDK application that can be written.
-The application simply prints an "helloworld" message on every enabled lcore.
+The application simply prints a "helloworld" message on every enabled lcore.
 
 Compiling the Application
 -------------------------
@@ -21,7 +21,7 @@ The application is located in the ``helloworld`` sub-directory.
 Running the Application
 -----------------------
 
-To run the example in a linux environment:
+To run the example in a Linux environment:
 
 .. code-block:: console
 
@@ -50,7 +50,7 @@ This call finishes the initialization process that was started before main() is
 The argc and argv arguments are provided to the rte_eal_init() function.
 The value returned is the number of parsed arguments.
 
-Starting Application Unit Lcores
+Starting Application on Lcores
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Once the EAL is initialized, the application is ready to launch a function on an lcore.
doc/guides/sample_app_ug/intro.rst +17 -17
index a19c0b8c13..dfd0254b0c 100644
@@ -4,9 +4,9 @@
 Introduction to the DPDK Sample Applications
 ============================================
 
-The DPDK Sample Applications are small standalone applications that
-demonstrate various features of DPDK. They can be considered as a cookbook of
-DPDK features. Users interested in getting started with DPDK can take the
+The DPDK sample applications are small standalone applications that
+demonstrate various features of DPDK. They serve as practical examples of
+DPDK functionality. Users interested in getting started with DPDK can take the
 applications, try out the features, and then extend them to fit their needs.
 
 
@@ -30,7 +30,7 @@ examples are highlighted below.
 
 
 * :doc:`Hello World<hello_world>`: As with most introductions to a
-  programming framework, a good place to start is with the Hello World
+  programming framework, a good place to start is the Hello World
   application. The Hello World example sets up the DPDK Environment Abstraction
   Layer (EAL), and prints a simple "Hello World" message to each of the DPDK
   enabled cores. This application doesn't do any packet forwarding, but it is a
@@ -38,32 +38,32 @@ examples are highlighted below.
 
 * :doc:`Basic Forwarding/Skeleton Application<skeleton>`: The Basic
   Forwarding/Skeleton contains the minimum amount of code required to enable
-  basic packet forwarding with DPDK. This allows you to test if your network
+  basic packet forwarding with DPDK. This allows you to test whether your network
   interfaces are working with DPDK.
 
 * :doc:`Network Layer 2 forwarding<l2_forward_real_virtual>`: The Network Layer 2
   forwarding, or ``l2fwd`` application does forwarding based on Ethernet MAC
   addresses like a simple switch.
 
-* :doc:`Network Layer 2 forwarding<l2_forward_event>`: The Network Layer 2
-  forwarding, or ``l2fwd-event`` application does forwarding based on Ethernet MAC
-  addresses like a simple switch. It demonstrates usage of poll and event mode
-  IO mechanism under a single application.
+* :doc:`Network Layer 2 forwarding with event mode<l2_forward_event>`: The
+  ``l2fwd-event`` application does forwarding based on Ethernet MAC addresses
+  like a simple switch. It demonstrates usage of poll and event mode IO
+  mechanisms under a single application.
 
-* :doc:`Network Layer 3 forwarding<l3_forward>`: The Network Layer3
+* :doc:`Network Layer 3 forwarding<l3_forward>`: The Network Layer 3
   forwarding, or ``l3fwd`` application does forwarding based on Internet
   Protocol, IPv4 or IPv6 like a simple router.
 
-* :doc:`Network Layer 3 forwarding Graph<l3_forward_graph>`: The Network Layer3
+* :doc:`Network Layer 3 forwarding Graph<l3_forward_graph>`: The Network Layer 3
   forwarding Graph, or ``l3fwd_graph`` application does forwarding based on IPv4
-  like a simple router with DPDK Graph framework.
+  like a simple router with the DPDK Graph framework.
 
 * :doc:`Hardware packet copying<dma>`: The Hardware packet copying,
-  or ``dmafwd`` application demonstrates how to use DMAdev library for
+  or ``dmafwd`` application demonstrates how to use the DMAdev library for
   copying packets between two threads.
 
 * :doc:`Packet Distributor<dist_app>`: The Packet Distributor
-  demonstrates how to distribute packets arriving on an Rx port to different
+  demonstrates how to distribute packets arriving on a receive port to different
   cores for processing and transmission.
 
 * :doc:`Multi-Process Application<multi_process>`: The
@@ -78,9 +78,9 @@ examples are highlighted below.
   and TX packet processing functions.
 
 * :doc:`IPsec Security Gateway<ipsec_secgw>`: The IPsec Security
-  Gateway application is a minimal example of something closer to a real world
-  example. This is also a good example of an application using the DPDK
-  Cryptodev framework.
+  Gateway application demonstrates a minimal implementation that is closer to
+  a real-world use case. This is also a good example of an application using
+  the DPDK Cryptodev framework.
 
 * :doc:`Precision Time Protocol (PTP) client<ptpclient>`: The PTP
   client is another minimal implementation of a real world application.
doc/guides/sample_app_ug/ip_frag.rst +26 -20

94 lines not on this page · raw message

doc/guides/sample_app_ug/ip_pipeline.rst +57 -52

261 lines not on this page · raw message

Signature · 1 line
2.53.0
#13 lore raw

PATCH 9/15 doc: improve IP reassembly, IPsec, multicast, and keep-alive

In reply to Stephen Hemminger

Updated multiple networking sample application guides:

ip_reassembly.rst:
- Enhanced fragment reassembly process descriptions
- Improved command-line parameter documentation
- Fixed formatting and terminology consistency

ipsec_secgw.rst:
- Restructured configuration file format sections
- Improved security association descriptions
- Enhanced clarity of IPsec gateway operations

ipv4_multicast.rst:
- Simplified multicast forwarding explanations
- Fixed formatting in code examples
- Improved readability of routing descriptions

keep_alive.rst:
- Enhanced keep-alive mechanism descriptions
- Fixed minor formatting issues

---
 doc/guides/sample_app_ug/ip_reassembly.rst  |  57 ++++++-----
 doc/guides/sample_app_ug/ipsec_secgw.rst    | 108 ++++++++++----------
 doc/guides/sample_app_ug/ipv4_multicast.rst |  26 ++---
 doc/guides/sample_app_ug/keep_alive.rst     |  12 +--
 4 files changed, 105 insertions(+), 98 deletions(-)
doc/guides/sample_app_ug/ip_reassembly.rst +31 -26
index 04b581a489..02ed9f0472 100644
@@ -4,15 +4,15 @@
 IP Reassembly Sample Application
 ================================
 
-The L3 Forwarding application is a simple example of packet processing using the DPDK.
-The application performs L3 forwarding with reassembly for fragmented IPv4 and IPv6 packets.
+The IP Reassembly application is a simple example of packet processing using the DPDK.
+The application performs L3 forwarding with reassembly of fragmented IPv4 and IPv6 packets.
 
 Overview
 --------
 
 The application demonstrates the use of the DPDK libraries to implement packet forwarding
 with reassembly for IPv4 and IPv6 fragmented packets.
-The initialization and run- time paths are very similar to those of the :doc:`l2_forward_real_virtual`.
+The initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`.
 The main difference from the L2 Forwarding sample application is that
 it reassembles fragmented IPv4 and IPv6 packets before forwarding.
 The maximum allowed size of reassembled packet is 9.5 KB.
@@ -21,11 +21,11 @@ There are two key differences from the L2 Forwarding sample application:
 
 *   The first difference is that the forwarding decision is taken based on information read from the input packet's IP header.
 
-*   The second difference is that the application differentiates between IP and non-IP traffic by means of offload flags.
+*   The second difference is that the applications differentiate between IP and non-IP traffic by means of offload flags.
 
 The Longest Prefix Match (LPM for IPv4, LPM6 for IPv6) table is used to store/lookup an outgoing port number,
-associated with that IPv4 address. Any unmatched packets are forwarded to the originating port.
-
+associated with that IPv4 address.
+Any unmatched packets are forwarded to the originating port.
 
 Compiling the Application
 -------------------------
@@ -46,15 +46,20 @@ The application has a number of command line options:
 
 where:
 
-*   -p PORTMASK: Hexadecimal bitmask of ports to configure
+``-p PORTMASK``
+    Hexadecimal bitmask of ports to configure
 
-*   -q NQ: Number of RX queues per lcore
+``-q NQ``
+    Number of RX queues per lcore
 
-*   --maxflows=FLOWS: determines maximum number of active fragmented flows (1-65535). Default value: 4096.
+``--maxflows=FLOWS``
+    Determines the maximum number of active fragmented flows (1-65535).
+    Default value: 4096.
 
-*   --flowttl=TTL[(s|ms)]: determines maximum Time To Live for fragmented packet.
-    If all fragments of the packet wouldn't appear within given time-out,
-    then they are considered as invalid and will be dropped.
+``--flowttl=TTL[(s|ms)]``
+    Determines the maximum Time To Live for fragmented packets.
+    If all fragments of the packet do not appear within the given timeout,
+    then they are considered invalid and will be dropped.
     Valid range is 1ms - 3600s. Default value: 1s.
 
 To run the example in a Linux environment with 2 lcores (2,4) over 2 ports(0,2)
@@ -69,7 +74,7 @@ with 1 Rx queue per lcore:
     Skipping disabled port 1
     Initializing port 2 on lcore 4... Address:00:1B:21:5C:FF:54, rxq=0 txq=2,0 txq=4,1
     done: Link Up - speed 10000 Mbps - full-duplex
-    Skipping disabled port 3IP_FRAG: Socket 0: adding route 100.10.0.0/16 (port 0)
+    Skipping disabled port 3 IP_FRAG: Socket 0: adding route 100.10.0.0/16 (port 0)
     IP_RSMBL: Socket 0: adding route 100.20.0.0/16 (port 1)
     ...
     IP_RSMBL: Socket 0: adding route 0101:0101:0101:0101:0101:0101:0101:0101/48 (port 0)
@@ -110,7 +115,7 @@ The default l3fwd_ipv6_route_array table is:
     :end-before: >8 End of default l3fwd_ipv6_route_array table.
 
 For example, for the fragmented input IPv4 packet with destination address: 100.10.1.1,
-a reassembled IPv4 packet be sent out from port #0 to the destination address 100.10.1.1
+a reassembled IPv4 packet will be sent out from port #0 to the destination address 100.10.1.1
 once all the fragments are collected.
 
 Explanation
@@ -119,12 +124,12 @@ Explanation
 The following sections provide in-depth explanation of the sample application code.
 As mentioned in the overview section, the initialization and run-time paths
 are very similar to those of the :doc:`l2_forward_real_virtual`.
-The following sections describe aspects that are specific to the IP reassemble sample application.
+The following sections describe aspects that are specific to the IP reassembly sample application.
 
 IPv4 Fragment Table Initialization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This application uses the :doc:`../prog_guide/ip_fragment_reassembly_lib` library.
+This application uses the IP Fragment and Reassembly Library (:doc:`../prog_guide/ip_fragment_reassembly_lib`).
 The fragment table maintains information about already received fragments of the packet.
 Each IP packet is uniquely identified by triple <Source IP address>, <Destination IP address>, <ID>.
 To avoid lock contention, each Rx queue has its own fragment table.
@@ -144,7 +149,7 @@ Mempools Initialization
 
 The reassembly application demands a lot of mbuf's to be allocated.
 At any given time, up to (2 \* max_flow_num \* RTE_LIBRTE_IP_FRAG_MAX_FRAG \* <maximum number of mbufs per packet>)
-can be stored inside the fragment table waiting for remaining fragments.
+can be stored inside the fragment table, waiting for remaining fragments.
 To keep mempool size under reasonable limits
 and to avoid a situation when one Rx queue can starve other queues,
 each Rx queue uses its own mempool.
@@ -161,8 +166,8 @@ Packet Reassembly and Forwarding
 For each input packet, the packet forwarding operation is done by the l3fwd_simple_forward() function.
 If the packet is an IPv4 or IPv6 fragment, then it calls ``rte_ipv4_reassemble_packet()`` for IPv4 packets,
 or ``rte_ipv6_reassemble_packet()`` for IPv6 packets.
-These functions either return a pointer to a valid mbuf that contains a reassembled packet,
-or NULL (if the packet can't be reassembled for some reason).
+These functions return either a pointer to a valid mbuf that contains a reassembled packet,
+or NULL (if the packet cannot be reassembled for some reason).
 Then, ``l3fwd_simple_forward()`` continues with the code for the packet forwarding decision
 (that is, the identification of the output interface for the packet) and
 actual transmit of the packet.
@@ -171,25 +176,25 @@ The ``rte_ipv4_reassemble_packet()`` or ``rte_ipv6_reassemble_packet()`` are res
 
 #.  Searching the fragment table for entry with packet's <IP Source Address, IP Destination Address, Packet ID>
 
-#.  If the entry is found, then check if that entry already timed-out.
+#.  If the entry is found, then check whether that entry has already timed out.
     If yes, then free all previously received fragments,
     and remove information about them from the entry.
 
 #.  If no entry with such key is found, then try to create a new one by one of two ways:
 
-    #.  Use as empty entry
+    #.  Use an empty entry
 
-    #.  Delete a timed-out entry, free mbufs associated with it mbufs and store a new entry with specified key in it.
+    #.  Delete a timed-out entry, free mbufs associated with it, and store a new entry with the specified key in it.
 
-#.  Update the entry with new fragment information and check
-    if a packet can be reassembled (the packet's entry contains all fragments).
+#.  Update the entry with new fragment information and check whether
+    the packet can be reassembled (the packet's entry contains all fragments).
 
     #.  If yes, then, reassemble the packet, mark table's entry as empty and return the reassembled mbuf to the caller.
 
     #.  If no, then just return a NULL to the caller.
 
-If at any stage of packet processing a reassembly function encounters an error
-(can't insert new entry into the Fragment table, or invalid/timed-out fragment),
+If at any stage of packet processing, a reassembly function encounters an error
+(cannot insert new entry into the Fragment table, or invalid/timed-out fragment),
 then it will free all associated with the packet fragments,
 mark the table entry as invalid and return NULL to the caller.
 
doc/guides/sample_app_ug/ipsec_secgw.rst +55 -53

214 lines not on this page · raw message

doc/guides/sample_app_ug/ipv4_multicast.rst +13 -13
index 3eb8b95f29..4304be665d 100644
@@ -63,7 +63,7 @@ where,
 
 *   -p PORTMASK: Hexadecimal bitmask of ports to configure
 
-*   -q NQ: determines the number of queues per lcore
+*   -q NQ: number of queues per lcore
 
 .. note::
 
@@ -125,7 +125,7 @@ Forwarding
 ~~~~~~~~~~
 
 All forwarding is done inside the ``mcast_forward()`` function.
-Firstly, the Ethernet* header is removed from the packet and the IPv4 address is extracted from the IPv4 header:
+Firstly, the Ethernet header is removed from the packet and the IPv4 address is extracted from the IPv4 header:
 
 .. literalinclude:: ../../../examples/ipv4_multicast/main.c
     :language: c
@@ -170,7 +170,7 @@ with the Ethernet address 01:00:5e:00:00:00, as per RFC 1112:
     :start-after: Construct Ethernet multicast address from IPv4 multicast Address. 8<
     :end-before: >8 End of Construction of multicast address from IPv4 multicast address.
 
-Packets are then dispatched to the destination ports according to the portmask associated with a multicast group:
+Packets are then dispatched to the destination ports according to the port mask associated with the multicast group:
 
 .. literalinclude:: ../../../examples/ipv4_multicast/main.c
     :language: c
@@ -190,12 +190,11 @@ Buffer Cloning
 
 This is the most important part of the application
 since it demonstrates the use of zero-copy buffer cloning.
-There are two approaches for creating the outgoing packet.
-Although both are based on the data zero-copy idea,
-there are some differences in the details.
+There are two approaches for creating outgoing packets.
+Both are based on the zero-copy idea, but they differ in implementation details.
 
-The first approach creates a clone of the input packet. For example,
-walk though all segments of the input packet and for each of segment,
+The first approach creates a clone of the input packet:
+walk through all segments of the input packet and for each segment,
 create a new buffer and attach that new buffer to the segment
 (refer to ``rte_pktmbuf_clone()`` in the mbuf library for more details).
 A new buffer is then allocated for the packet header and is prepended to the cloned buffer.
@@ -205,18 +204,19 @@ It simply increments the reference counter for all input packet segments,
 allocates a new buffer for the packet header and prepends it to the input packet.
 
 Basically, the first approach reuses only the input packet's data, but creates its own copy of packet's metadata.
-The second approach reuses both input packet's data and metadata.
+The second approach reuses both the input packet's data and metadata.
 
-The advantage of the first approach is that each outgoing packet has its own copy of the metadata,
+The advantage of the first approach is that each outgoing packet has its own copy of metadata,
 so we can safely modify the data pointer of the input packet.
-That allows us to skip creation if the output packet is for the last destination port
+That allows us to skip packet creation if the output packet is for the last destination port
 and, instead, modify the input packet's header in place.
 For example, for N destination ports, we need to invoke ``mcast_out_pkt()`` (N-1) times.
 
 The advantage of the second approach is that there is less work to be done for each outgoing packet.
 The "clone" operation is skipped completely.
-However, there is a price to pay.
-The input packet's metadata must remain intact. For N destination ports,
+However, there is a price to pay:
+the input packet's metadata must remain intact.
+For N destination ports,
 we need to invoke ``mcast_out_pkt()`` (N) times.
 
 Therefore, for a small number of outgoing ports (and segments in the input packet),
doc/guides/sample_app_ug/keep_alive.rst +6 -6
index 8ae9d7c689..9353b65e91 100644
@@ -5,7 +5,7 @@ Keep Alive Sample Application
 =============================
 
 The Keep Alive application is a simple example of a
-heartbeat/watchdog for packet processing cores. It demonstrates how
+heartbeat and watchdog for packet processing cores. It demonstrates how
 to detect 'failed' DPDK cores and notify a fault management entity
 of this failure. Its purpose is to ensure the failure of the core
 does not result in a fault that is not detectable by a management
@@ -19,7 +19,7 @@ The application demonstrates how to protect against 'silent outages'
 on packet processing cores. A Keep Alive Monitor Agent Core (main)
 monitors the state of packet processing cores (worker cores) by
 dispatching pings at a regular time interval (default is 5ms) and
-monitoring the state of the cores. Cores states are: Alive, MIA, Dead
+monitoring the state of the cores. Core states are: Alive, MIA, Dead
 or Buried. MIA indicates a missed ping, and Dead indicates two missed
 pings within the specified time interval. When a core is Dead, a
 callback function is invoked to restart the packet processing core;
@@ -80,16 +80,16 @@ Explanation
 
 The following sections provide explanation of the
 Keep-Alive/'Liveliness' conceptual scheme. As mentioned in the
-overview section, the initialization and run-time paths are very
+Overview section, the initialization and run-time paths are very
 similar to those of the :doc:`l2_forward_real_virtual`.
 
 The Keep-Alive/'Liveliness' conceptual scheme:
 
-* A Keep- Alive Agent Runs every N Milliseconds.
+* A keep-alive agent runs every N milliseconds.
 
-* DPDK Cores respond to the keep-alive agent.
+* DPDK cores respond to the keep-alive agent.
 
-* If a keep-alive agent detects time-outs, it notifies the
+* If a keep-alive agent detects timeouts, it notifies the
   fault management entity through a callback function.
 
 The following sections provide explanation of the code aspects
Signature · 1 line
2.53.0
Acked-by on v1 9/15
#14 lore raw

Re: [PATCH 09/15] doc: improve IP reassembly, IPsec, multicast, and keep-alive

Quoted 17 lines · Stephen Hemminger

Updated multiple networking sample application guides:

ip_reassembly.rst:
- Enhanced fragment reassembly process descriptions
- Improved command-line parameter documentation
- Fixed formatting and terminology consistency

ipsec_secgw.rst:
- Restructured configuration file format sections
- Improved security association descriptions
- Enhanced clarity of IPsec gateway operations

ipv4_multicast.rst:
- Simplified multicast forwarding explanations
- Fixed formatting in code examples
- Improved readability of routing descriptions

Quoted 6 lines

keep_alive.rst:
- Enhanced keep-alive mechanism descriptions
- Fixed minor formatting issues

---

#15 lore raw

PATCH 10/15 doc: enhance L2 forwarding sample application guides

In reply to Stephen Hemminger

Improved documentation for L2 forwarding variants:

l2_forward_cat.rst:
- Enhanced Cache Allocation Technology descriptions
- Fixed command-line parameter formatting
- Improved clarity of CAT configuration steps

l2_forward_crypto.rst:
- Restructured cryptographic operation descriptions
- Improved cipher and authentication algorithm lists
- Enhanced command-line option explanations

l2_forward_event.rst:
- Clarified event-driven processing model
- Fixed formatting and terminology consistency

l2_forward_job_stats.rst:
- Improved job statistics collection descriptions
- Enhanced clarity of monitoring mechanisms

l2_forward_macsec.rst:
- Simplified MACsec configuration explanations
- Fixed formatting in security association setup

---
 doc/guides/sample_app_ug/l2_forward_cat.rst   | 34 ++++-----
 .../sample_app_ug/l2_forward_crypto.rst       | 70 +++++++++----------
 doc/guides/sample_app_ug/l2_forward_event.rst | 20 +++---
 .../sample_app_ug/l2_forward_job_stats.rst    | 46 ++++++------
 .../sample_app_ug/l2_forward_macsec.rst       | 38 +++++-----
 5 files changed, 100 insertions(+), 108 deletions(-)
doc/guides/sample_app_ug/l2_forward_cat.rst +17 -17
index f96f789f75..9901a796e0 100644
@@ -14,22 +14,22 @@ Overview
 
 This app is intended as a demonstration of the basic components
 of a DPDK forwarding application
-and use of the libpqos library to the program CAT.
+and the use of the libpqos library to program CAT.
 For more detailed implementations, see the L2 and L3 forwarding sample applications.
 
-CAT and Code Data Prioritization (CDP) features allow management of the CPU's
-last level cache. CAT introduces classes of service (COS) that are essentially
+The CAT and Code Data Prioritization (CDP) features allow management of the CPU's
+last level cache. CAT introduces Classes of Service (COS) that are essentially
 bitmasks. In current CAT implementations, a bit in a COS bitmask corresponds to
 one cache way in last level cache.
 
 A CPU core is always assigned to one of the CAT classes.
 By programming CPU core assignment and COS bitmasks, applications can be given
 exclusive, shared, or mixed access to the CPU's last level cache.
-CDP extends CAT so that there are two bitmasks per COS,
+The CDP feature extends CAT so that there are two bitmasks per COS,
 one for data and one for code.
 The number of classes and number of valid bits in a COS bitmask is CPU model
 specific and COS bitmasks need to be contiguous. Sample code calls this bitmask
-``cbm`` or capacity bitmask.
+a ``cbm`` or capacity bitmask.
 By default, after reset, all CPU cores are assigned to COS 0 and all classes
 are programmed to allow fill into all cache ways.
 CDP is off by default.
@@ -47,7 +47,7 @@ Compiling the Application
 
 .. note::
 
-    Requires ``libpqos`` from Intel's
+    Requires the ``libpqos`` library from Intel's
     `intel-cmt-cat software package <https://github.com/01org/intel-cmt-cat>`_
     hosted on GitHub repository. For installation notes, please see ``README`` file.
 
@@ -70,7 +70,7 @@ The application is located in the ``l2fwd-cat`` sub-directory.
 Running the Application
 -----------------------
 
-To run the example in a ``linux`` environment and enable CAT on cpus 0-2:
+To run the example in a Linux environment and enable CAT on CPUs 0-2:
 
 .. code-block:: console
 
@@ -87,7 +87,7 @@ If CDP is not supported, it will fail with following error message:
 .. code-block:: console
 
     PQOS: CDP requested but not supported.
-    PQOS: Requested CAT configuration is not valid!
+    PQOS: Requested CAT configuration is not valid.
     PQOS: Shutting down PQoS library...
     EAL: Error - exiting with code: 1
       Cause: PQOS: L3CA init failed!
@@ -99,7 +99,7 @@ The option to enable CAT is:
   where ``cbm`` stands for capacity bitmask and must be expressed in
   hexadecimal form.
 
-  ``common_cbm`` is a single mask, for a CDP enabled system, a group of two
+  ``common_cbm`` is a single mask; for a CDP-enabled system, a group of two
   masks (``code_cbm`` and ``data_cbm``) is used.
 
   ``(`` and ``)`` are necessary if it's a group.
@@ -125,7 +125,7 @@ The option to enable CAT is:
     data ways are not overlapping.
 
 
-Refer to *DPDK Getting Started Guide* for general information on running
+Refer to the *DPDK Getting Started Guide* for general information on running
 applications and the Environment Abstraction Layer (EAL) options.
 
 
@@ -133,7 +133,7 @@ To reset or list CAT configuration and control CDP please use ``pqos`` tool
 from Intel's
 `intel-cmt-cat software package <https://github.com/01org/intel-cmt-cat>`_.
 
-To enabled or disable CDP:
+To enable or disable CDP:
 
 .. code-block:: console
 
@@ -141,7 +141,7 @@ To enabled or disable CDP:
 
     sudo ./pqos -S cdp-off
 
-to reset CAT configuration:
+To reset CAT configuration:
 
 .. code-block:: console
 
@@ -193,11 +193,11 @@ function. The value returned is the number of parsed arguments:
     :end-before: >8 End of initialization of PQoS.
     :dedent: 1
 
-``cat_init()`` is a wrapper function which parses the command, validates
+The ``cat_init()`` function is a wrapper function which parses the command, validates
 the requested parameters and configures CAT accordingly.
 
-The parsing of command line arguments is done in ``parse_args(...)``.
-Libpqos is then initialized with the ``pqos_init(...)`` call.
+The parsing of command line arguments is done in the ``parse_args(...)`` function.
+The libpqos library is then initialized with the ``pqos_init(...)`` call.
 Next, libpqos is
 queried for system CPU information and L3CA capabilities via
 ``pqos_cap_get(...)`` and ``pqos_cap_get_type(..., PQOS_CAP_TYPE_L3CA, ...)``
@@ -207,6 +207,6 @@ for a sufficient number of un-associated COS. COS are selected and
 configured via the ``pqos_l3ca_set(...)`` call. Finally, COS are associated to
 relevant CPUs via ``pqos_l3ca_assoc_set(...)`` calls.
 
-``atexit(...)`` is used to register ``cat_exit(...)`` to be called on
-a clean exit. ``cat_exit(...)`` performs a simple CAT clean-up, by associating
+The ``atexit(...)`` function is used to register ``cat_exit(...)`` to be called on
+a clean exit. The ``cat_exit(...)`` function performs a simple CAT clean-up, by associating
 COS 0 to all involved CPUs via ``pqos_l3ca_assoc_set(...)`` calls.
doc/guides/sample_app_ug/l2_forward_crypto.rst +34 -36

171 lines not on this page · raw message

doc/guides/sample_app_ug/l2_forward_event.rst +10 -10
index 1d52211b9a..c4329d0036 100644
@@ -17,7 +17,7 @@ The destination port is the adjacent port from the enabled portmask.
 If the first four ports are enabled (portmask=0x0f),
 ports 1 and 2 forward into each other,
 and ports 3 and 4 forward into each other.
-Also, if MAC address updating is enabled,
+Also, if MAC addresses updating is enabled,
 the MAC addresses are affected as follows:
 
 *   The source MAC address is replaced by the Tx port MAC address
@@ -26,7 +26,7 @@ the MAC addresses are affected as follows:
 Application receives packets from Rx port using these methods:
 
 *   Poll mode
-*   Eventdev mode (default)
+*   Eventdev mode (by default)
 
 This application can be used to benchmark performance using a traffic-generator,
 as shown in the :numref:`figure_l2fwd_event_benchmark_setup`.
@@ -64,7 +64,7 @@ where,
 
 *   q NQ: Maximum number of queues per lcore (default is 1)
 
-*   --[no-]mac-updating: Enable or disable MAC addresses updating (enabled by default).
+*   --[no-]mac-updating: Enable or disable MAC addresses updating (enabled by default)
 
 *   --mode=MODE: Packet transfer mode for I/O, poll or eventdev. Eventdev by default.
 
@@ -374,9 +374,9 @@ is assigned that is either the next or previous enabled port from the portmask.
 If the number of ports are odd in portmask, then the packet from the last port will be
 forwarded to first port i.e. if portmask=0x07, then forwarding will take place
 like p0--->p1, p1--->p2, p2--->p0.
+If MAC address updating is enabled, the source and destination MAC addresses are updated.
 
-Also, to optimize enqueue operation, ``l2fwd_simple_forward()`` stores incoming mbufs
-up to ``MAX_PKT_BURST``.
+To optimize enqueue operation, ``l2fwd_simple_forward()`` stores incoming mbufs up to ``MAX_PKT_BURST``.
 Once it reaches the limit, all packets are transmitted to destination ports.
 
 .. literalinclude:: ../../../examples/l2fwd/main.c
@@ -420,15 +420,15 @@ to ensure the correct allowed deq length by the eventdev.
 The ``rte_event_dequeue_burst()`` function writes the mbuf pointers in a local table
 and returns the number of available mbufs in the table.
 
-Then, each mbuf in the table is processed by the ``l2fwd_eventdev_forward()``
-function. The processing is very simple: process the TX port from the RX port,
-then replace the source and destination MAC addresses if MAC address updating
-is enabled.
+Then, each mbuf in the table is processed by the ``l2fwd_eventdev_forward()`` function.
+The processing is very simple: determine the TX port from the RX port,
+then replace the source and destination MAC addresses if MAC addresses updating is enabled.
 
 During the initialization process, a static array of destination ports
 (``l2fwd_dst_ports[]``) is filled so that for each source port, a destination port
 is assigned that is either the next or previous enabled port from the portmask.
-If number of ports are odd in portmask then packet from last port will be
+If the number of ports are odd in portmask,
+then the packet from the last port will be
 forwarded to first port i.e. if portmask=0x07, then forwarding will take place
 like p0--->p1, p1--->p2, p2--->p0.
 
doc/guides/sample_app_ug/l2_forward_job_stats.rst +20 -26

114 lines not on this page · raw message

doc/guides/sample_app_ug/l2_forward_macsec.rst +19 -19
index 7e6c971465..c0452992e8 100644
@@ -15,7 +15,7 @@ The L2 forwarding MACsec application performs L2 forwarding for each packet
 that is received on an Rx port after encrypting/decrypting the packets
 based on rte_security sessions using inline protocol mode.
 
-The destination port is the adjacent port from the enabled portmask
+The destination port is the adjacent port from the enabled portmask,
 if the first four ports are enabled (portmask ``0xf``),
 ports 1 and 2 forward into each other, and ports 3 and 4 forward into each other.
 
@@ -43,44 +43,44 @@ The application requires a number of command line options:
        [--portmap="(port, port)[,(port, port)]"]
        [-T STAT_INTERVAL]
 
-where,
+where:
 
-``p PORTMASK``
-  Hexadecimal bitmask of the ports to configure.
+``-p PORTMASK``
+   Hexadecimal bitmask of the ports to configure.
 
-``q NQ``
-  Number of queues (=ports) per lcore (default is 1).
+``-q NQ``
+   Number of queues (=ports) per lcore (default is 1).
 
-``T STAT_INTERVAL``
-  Time interval in seconds for refreshing the stats (default is 1 sec).
-  Value 0 disables stats display.
+``-T STAT_INTERVAL``
+   Time interval in seconds for refreshing the stats (default is 1).
+   Value 0 disables stats display.
 
 ``--mcs-tx-portmask OUTBOUND_PORTMASK``
-  Hexadecimal bitmask of the ports to configure encryption flows.
+   Hexadecimal bitmask of the ports to configure encryption flows.
 
 ``--mcs-rx-portmask INBOUND_PORTMASK``
-  Hexadecimal bitmask of the ports to configure decryption flows.
+   Hexadecimal bitmask of the ports to configure decryption flows.
 
-``--mcs-port-config '(port,src_mac,dst_mac)[,(port,src_mac,dst_mac)]'``
-  Source and destination MAC addresses of incoming packets
-  on a port for which MACsec processing is to be done.
+``--mcs-port-config "(port,src_mac,dst_mac)[,(port,src_mac,dst_mac)]"``
+   Source and destination MAC addresses of incoming packets
+   on a port for which MACsec processing is to be done.
 
 ``--portmap="(port,port)[,(port,port)]"``
   Forwarding ports mapping.
 
 To run the application in Linux environment with 4 lcores,
-4 ports with 2 ports for outbound and 2 ports for outbound,
+4 ports with 2 ports for outbound and 2 ports for inbound,
 issue the command:
 
 .. code-block:: console
 
    $ ./<build_dir>/examples/dpdk-l2fwd-macsec -a 0002:04:00.0 -a 0002:05:00.0 \
        -a 0002:06:00.0 -a 0002:07:00.0 -l 1-4 -- -p 0xf                      \
-       --mcs-tx-portmask 0x5 --mcs-rx-portmask 0xA                            \
-       --mcs-port-config '(0,02:03:04:05:06:07,01:02:03:04:05:06),            \
+       --mcs-tx-portmask 0x5 --mcs-rx-portmask 0xa                            \
+       --mcs-port-config="(0,02:03:04:05:06:07,01:02:03:04:05:06),            \
        (1,02:03:04:05:06:17,01:02:03:04:05:16),                               \
        (2,02:03:04:05:06:27,01:02:03:04:05:26),                               \
-       (3,02:03:04:05:06:37,01:02:03:04:05:36)' -T 10
+       (3,02:03:04:05:06:37,01:02:03:04:05:36)" -T 10
 
 To run the application in Linux environment with 4 lcores, 4 ports,
 to forward Rx traffic of ports 0 & 1 on ports 2 & 3 respectively and vice versa,
@@ -90,7 +90,7 @@ issue the command:
 
    $ ./<build_dir>/examples/dpdk-l2fwd-macsec -a 0002:04:00.0 -a 0002:05:00.0 \
        -a 0002:06:00.0 -a 0002:07:00.0 -l 1-4 -- -p 0xf                      \
-       --mcs-tx-portmask 0x5 --mcs-rx-portmask 0xA                            \
+       --mcs-tx-portmask 0x5 --mcs-rx-portmask 0xa                            \
        --mcs-port-config="(0,02:03:04:05:06:07,01:02:03:04:05:06),            \
        (1,02:03:04:05:06:17,01:02:03:04:05:16),                               \
        (2,02:03:04:05:06:27,01:02:03:04:05:26),                               \
Signature · 1 line
2.53.0
#16 lore raw

PATCH 11/15 doc: enhance multi-process, NTB, ordering, and PTP guides

In reply to Stephen Hemminger

Improved documentation for various sample applications:

multi_process.rst:
- Clarified primary/secondary process model
- Enhanced shared memory descriptions
- Improved command-line examples

ntb.rst:
- Minor formatting fix

packet_ordering.rst:
- Improved packet reordering algorithm descriptions
- Enhanced worker thread explanations
- Fixed formatting consistency

pipeline.rst:
- Clarified pipeline stage configurations
- Improved table action descriptions

ptpclient.rst:
- Enhanced PTP synchronization explanations
- Improved timestamp handling descriptions
- Fixed formatting in configuration examples

---
 doc/guides/sample_app_ug/multi_process.rst   | 47 ++++++++++---------
 doc/guides/sample_app_ug/ntb.rst             |  2 +-
 doc/guides/sample_app_ug/packet_ordering.rst | 42 +++++++++--------
 doc/guides/sample_app_ug/pipeline.rst        | 26 ++++++-----
 doc/guides/sample_app_ug/ptpclient.rst       | 49 +++++++++++---------
 5 files changed, 89 insertions(+), 77 deletions(-)
doc/guides/sample_app_ug/multi_process.rst +24 -23
index 1bd858bfb5..e9e5809a92 100644
@@ -42,9 +42,10 @@ passing at least two cores in the corelist:
 
     ./<build_dir>/examples/dpdk-simple_mp -l 0-1 --proc-type=primary
 
-For the first DPDK process run, the proc-type flag can be omitted or set to auto,
-since all DPDK processes will default to being a primary instance,
-meaning they have control over the hugepage shared memory regions.
+For the first DPDK process run, the proc-type flag can be omitted or set to auto
+since all DPDK processes will default to being a primary instance
+(meaning, they have control over the hugepage shared memory regions).
+
 The process should start successfully and display a command prompt as follows:
 
 .. code-block:: console
@@ -99,7 +100,7 @@ At any stage, either process can be terminated using the quit command.
     The secondary process can be stopped and restarted without affecting the primary process.
 
 How the Application Works
-^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This application uses two queues and a single memory pool created in the primary process.
 The secondary process then uses lookup functions to attach to these objects.
@@ -141,7 +142,7 @@ Each process writes outgoing packets to a different Tx queue on each port.
 Running the Application
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-The first instance of the ``symmetric_mp`` process is the primary instance, with the EAL arguments:
+The first instance of the ``symmetric_mp`` process becomes the primary instance, with the following application arguments:
 
 ``-p <portmask>``
   The ``portmask`` is a hexadecimal bitmask of what ports on the system are to be used.
@@ -155,7 +156,7 @@ The first instance of the ``symmetric_mp`` process is the primary instance, with
 ``--proc-id <n>``
   Where ``n`` is a numeric value in the range ``0 <= n < N``
   (number of processes, specified above).
-  This identifies which ``symmetric_mp`` instance is being run,
+  This identifies which ``symmetric_mp`` instance is running,
   so that each process can read a unique receive queue on each network port.
 
 The secondary instance must be started with similar EAL parameters.
@@ -173,7 +174,7 @@ Example:
    In the above example, ``auto`` is used so the first instance becomes the primary process.
 
 How the Application Works
-^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The primary instance creates the memory pool and initializes the network ports.
 
@@ -183,8 +184,8 @@ The primary instance creates the memory pool and initializes the network ports.
         :end-before: >8 End of primary instance initialization.
         :dedent: 1
 
-The secondary instance gets the port information and exported by the primary process.
-The memory pool is accessed by doing a lookup for it by name:
+The secondary instance gets the port information exported by the primary process.
+The memory pool is accessed by looking it up by name:
 
 .. code-block:: c
 
@@ -198,7 +199,7 @@ Each process reads from each port using the queue corresponding to its proc-id p
 and writes to the corresponding transmit queue on the output port.
 
 Client-Server Multi-process Example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------
 
 The example multi-process application demonstrates a client-server type multi-process design.
 A single server process receives a set of packets from the ports
@@ -216,22 +217,22 @@ The following diagram shows the data-flow through the application, using two cli
 
 
 Running the Application
-^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~
 
-The server process must be run as the primary process to set up all memory structures.
+The server process must run as the primary process to set up all memory structures.
 In addition to the EAL parameters, the application-specific parameters are:
 
-*   -p <portmask >, where portmask is a hexadecimal bitmask of what ports on the system are to be used.
-    For example: -p 3 to use ports 0 and 1 only.
+*   ``-p <portmask>``, where portmask is a hexadecimal bitmask of what ports on the system are to be used.
+    For example: ``-p 3`` to use ports 0 and 1 only.
 
-*   -n <num-clients>, where the num-clients parameter is the number of client processes that will process the packets received
+*   ``-n <num-clients>``, where the num-clients parameter is the number of client processes that will process the packets received
     by the server application.
 
 .. note::
 
-   In the server process, has a single thread using the lowest numbered lcore
-   in the corelist, performs all packet I/O.
-   If corelist parameter specifies with more than a single lcore,
+   In the server process, a single thread using the lowest numbered lcore
+   in the corelist performs all packet I/O.
+   If the corelist parameter specifies more than a single lcore,
    an additional lcore will be used for a thread to print packet count periodically.
 
 The server application stores configuration data in shared memory,
@@ -251,14 +252,14 @@ the commands are:
 
     If the server application dies and needs to be restarted, all client applications also need to be restarted,
     as there is no support in the server application for it to run as a secondary process.
-    Any client processes that need restarting can be restarted without affecting the server process.
+    Client processes can be restarted without affecting the server process.
 
 How the Application Works
-^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The server (primary) process performs the initialization of network port and data structure
+The server (primary) process performs the initialization of network ports and data structures
 and stores its port configuration data in a memory zone in hugepage shared memory.
-The client process does not need the portmask parameter passed in via the command line.
+The client processes do not need the portmask parameter passed in via the command line.
 The server process is the primary process, and the client processes are secondary processes.
 
 The server operates by reading packets from each network port
@@ -266,4 +267,4 @@ and distributing those packets to the client queues.
 The client reads from the ring and routes the packet to a different network port.
 The routing used is very simple: all packets received on the first NIC port
 are transmitted back out on the second port and vice versa.
-Similarly, packets are routed between the 3rd and 4th network ports and so on.
+Similarly, packets are routed between the third and fourth network ports and so on.
doc/guides/sample_app_ug/ntb.rst +1 -1
index f54de6cecd..ca0ff54757 100644
@@ -12,7 +12,7 @@ This sample supports 4 types of packet forwarding mode.
 
 * ``file-trans``: transmit files between two systems. The sample will
   be polling to receive files from the peer and save the file as
-  ``ntb_recv_file[N]``, [N] represents the number of received file.
+  ``ntb_recv_file[N]``, where [N] represents the number of received files.
 * ``rxonly``: NTB receives packets but doesn't transmit them.
 * ``txonly``: NTB generates and transmits packets without receiving any.
 * ``iofwd``: iofwd between NTB device and ethdev.
doc/guides/sample_app_ug/packet_ordering.rst +23 -19

74 lines not on this page · raw message

doc/guides/sample_app_ug/pipeline.rst +14 -12
index 2d7c977068..2e8f5b7f24 100644
@@ -4,10 +4,10 @@
 Pipeline Application
 ====================
 
-Application overview
---------------------
+Overview
+--------
 
-This application showcases the features of the Software Switch (SWX) pipeline that is aligned with the P4 language.
+This application showcases the features of the Software Switch (SWX) pipeline that aligns with the P4 language.
 
 Each pipeline is created using a specification file that can either be manually developed or generated using a P4 compiler.
 
@@ -78,7 +78,7 @@ To run remote client (e.g. telnet) to communicate with the application:
 
     $ telnet 0.0.0.0 8086
 
-When running a telnet client as above, command prompt is displayed:
+When running a telnet client as above, the command prompt is displayed:
 
 .. code-block:: console
 
@@ -90,23 +90,25 @@ When running a telnet client as above, command prompt is displayed:
 
     pipeline>
 
-Once application and telnet client start running, messages can be sent from client to application.
+Once the application and telnet client start running, you can send messages from the client to the application.
 
 
-Application stages
-------------------
+Explanation
+-----------
+
+Here is a description of the various stages of the application.
 
 Initialization
 ~~~~~~~~~~~~~~
 
-During this stage, EAL layer is initialised and application specific arguments are parsed. Furthermore, the data structures
-for application objects are initialized. In case of any initialization error, an error message is displayed and the application
-is terminated.
+During this stage, EAL layer is initialized and application specific arguments are parsed.
+Furthermore, the data structures for application objects are initialized.
+In case of any initialization error, an error message is displayed and the application is terminated.
 
 Run-time
 ~~~~~~~~
 
-The main thread is creating and managing all the application objects based on CLI input.
+The main thread creates and manages all the application objects based on CLI input.
 
 Each data plane thread runs one or several pipelines previously assigned to it in round-robin order. Each data plane thread
 executes two tasks in time-sharing mode:
@@ -114,5 +116,5 @@ executes two tasks in time-sharing mode:
 #. *Packet processing task*: Process bursts of input packets read from the pipeline input ports.
 
 #. *Message handling task*: Periodically, the data plane thread pauses the packet processing task and polls for request
-   messages send by the main thread. Examples: add/remove pipeline to/from current data plane thread, add/delete rules
+   messages sent by the main thread. Examples: add/remove pipeline to/from current data plane thread, add/delete rules
    to/from given table of a specific pipeline owned by the current data plane thread, read statistics, etc.
doc/guides/sample_app_ug/ptpclient.rst +27 -22

111 lines not on this page · raw message

Signature · 1 line
2.53.0
#17 lore raw

PATCH 12/15 doc: improve QoS, callbacks, EFD, and service cores guides

In reply to Stephen Hemminger

Enhanced documentation for QoS and service applications:

qos_metering.rst:
- Improved traffic metering algorithm descriptions
- Fixed formatting consistency

qos_scheduler.rst:
- Enhanced hierarchical scheduler explanations
- Improved traffic class descriptions

rxtx_callbacks.rst:
- Clarified callback mechanism usage
- Fixed formatting in code examples

server_node_efd.rst:
- Minor formatting improvements

service_cores.rst:
- Restructured service core architecture descriptions
- Improved service mapping explanations
- Enhanced clarity of multi-service configurations

---
 doc/guides/sample_app_ug/qos_metering.rst    |  9 +--
 doc/guides/sample_app_ug/qos_scheduler.rst   | 16 +++--
 doc/guides/sample_app_ug/rxtx_callbacks.rst  |  9 ++-
 doc/guides/sample_app_ug/server_node_efd.rst |  4 +-
 doc/guides/sample_app_ug/service_cores.rst   | 67 +++++++++++---------
 5 files changed, 56 insertions(+), 49 deletions(-)
doc/guides/sample_app_ug/qos_metering.rst +5 -4
index e7101559aa..b317d4079d 100644
@@ -4,7 +4,7 @@
 QoS Metering Sample Application
 ===============================
 
-The QoS meter sample application is an example that demonstrates the use of DPDK to provide QoS marking and metering,
+The QoS meter sample application demonstrates the use of DPDK to provide QoS marking and metering,
 as defined by RFC2697 for Single Rate Three Color Marker (srTCM) and RFC 2698 for Two Rate Three Color Marker (trTCM) algorithm.
 
 Overview
@@ -14,7 +14,8 @@ The application uses a single thread for reading the packets from the RX port,
 metering, marking them with the appropriate color (green, yellow or red) and writing them to the TX port.
 
 A policing scheme can be applied before writing the packets to the TX port by dropping or
-changing the color of the packet in a static manner depending on both the input and output colors of the packets that are processed by the meter.
+changing the color of the packet in a static manner. This would depend on both the input and output colors
+of the packets that are processed by the meter.
 
 The operation mode can be selected as compile time out of the following options:
 
@@ -126,9 +127,9 @@ There are four different actions:
 
 In this particular case:
 
-*   Every packet which input and output color are the same, keeps the same color.
+*   For every packet where the input and output color are the same, keep the same color.
 
-*   Every packet which color has improved is dropped (this particular case can't happen, so these values will not be used).
+*   For every packet where the color has improved is dropped (this particular case can't happen, so these values will not be used).
 
 *   For the rest of the cases, the color is changed to red.
 
doc/guides/sample_app_ug/qos_scheduler.rst +9 -7
index cd33beecb0..645f134e7f 100644
@@ -20,24 +20,26 @@ The architecture of the QoS scheduler application is shown in the following figu
 
 There are two flavors of the runtime execution for this application,
 with two or three threads per each packet flow configuration being used.
-The RX thread reads packets from the RX port,
+
+The RX thread reads packets from the RX port and
 classifies the packets based on the double VLAN (outer and inner) and
-the lower byte of the IP destination address and puts them into the ring queue.
+the lower byte of the IP destination address. It then puts them into the ring queue.
+
 The worker thread dequeues the packets from the ring and calls the QoS scheduler enqueue/dequeue functions.
 If a separate TX core is used, these are sent to the TX ring.
 Otherwise, they are sent directly to the TX port.
-The TX thread, if present, reads from the TX ring and write the packets to the TX port.
+The TX thread, if present, reads from the TX ring and writes the packets to the TX port.
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``qos_sched`` sub-directory.
 
     .. note::
 
-        This application is intended as a linux only.
+        This application is intended for Linux only.
 
 .. note::
 
@@ -63,7 +65,7 @@ Mandatory application parameters include:
 
 *   --pfc "RX PORT, TX PORT, RX LCORE, WT LCORE, TX CORE": Packet flow configuration.
     Multiple pfc entities can be configured in the command line,
-    having 4 or 5 items (if TX core defined or not).
+    with 4 or 5 items (depending on whether a TX core is defined).
 
 Optional application parameters include:
 
@@ -153,7 +155,7 @@ These are the commands that are currently working under the command line interfa
 
 All of these commands work the same way, averaging the number of packets throughout a specific subset of queues.
 
-Two parameters can be configured for this prior to calling any of these commands:
+Two parameters can be configured prior to calling any of these commands:
 
     *   qavg n X: n is the number of times that the calculation will take place.
         Bigger numbers provide higher accuracy. The default value is 10.
doc/guides/sample_app_ug/rxtx_callbacks.rst +4 -5
index cd6512508b..7dfcab5d65 100644
@@ -18,10 +18,9 @@ prior to transmission to calculate the elapsed time in CPU cycles.
 
 If hardware timestamping is supported by the NIC, the sample application will
 also display the average latency.
-The packet was timestamped in hardware
-on top of the latency since the packet was received and processed by the RX
-callback.
-
+This shows the additional hardware timestamping latency on top of the
+software latency measured since the packet was received and processed by
+the RX callback.
 
 Compiling the Application
 -------------------------
@@ -72,7 +71,7 @@ callbacks are added. This is explained in the next section:
 
 
 The Port Initialization Function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The main functional part of the port initialization is shown below with
 comments:
doc/guides/sample_app_ug/server_node_efd.rst +2 -2
index c90d74ae1c..d543148328 100644
@@ -9,7 +9,7 @@ load balancer. For more information about the EFD Library, please refer to the
 DPDK programmer's guide.
 
 This sample application is a variant of the :doc:`multi_process`
-where a specific target node is specified for every and each flow
+where a specific target node is specified for each flow
 (not in a round-robin fashion as the original load balancing sample application).
 
 Overview
@@ -192,7 +192,7 @@ flow is not handled by the node.
     :start-after: Packets dequeued from the shared ring. 8<
     :end-before: >8 End of packets dequeuing.
 
-Finally, note that both processes updates statistics, such as transmitted, received
+Finally, note that both processes update statistics, such as transmitted, received
 and dropped packets, which are shown and refreshed by the server app.
 
 .. literalinclude:: ../../../examples/server_node_efd/efd_server/main.c
doc/guides/sample_app_ug/service_cores.rst +36 -31

113 lines not on this page · raw message

Signature · 1 line
2.53.0
#18 lore raw

PATCH 13/15 doc: enhance skeleton, pipeline, timer, and vhost guides

In reply to Stephen Hemminger

Improved documentation for core sample applications:

skeleton.rst:
- Simplified basic forwarding example descriptions
- Fixed formatting consistency

test_pipeline.rst:
- Enhanced pipeline testing methodology descriptions
- Improved command-line parameter documentation

timer.rst:
- Clarified timer management mechanisms
- Improved periodic timer explanations

vdpa.rst:
- Enhanced vDPA device configuration descriptions
- Improved live migration support explanations

vhost.rst:
- Restructured vhost-user implementation sections
- Improved virtio device emulation descriptions
- Enhanced performance tuning recommendations

---
 doc/guides/sample_app_ug/skeleton.rst      |   8 +-
 doc/guides/sample_app_ug/test_pipeline.rst |  17 +-
 doc/guides/sample_app_ug/timer.rst         |  19 +--
 doc/guides/sample_app_ug/vdpa.rst          |  51 +++---
 doc/guides/sample_app_ug/vhost.rst         | 178 +++++++++++----------
 5 files changed, 143 insertions(+), 130 deletions(-)
doc/guides/sample_app_ug/skeleton.rst +4 -4
index 5f7f18dbc2..b1cd4e12f5 100644
@@ -73,7 +73,7 @@ Mbufs are the packet buffer structure used by DPDK. They are explained in
 detail in the "Mbuf Library" section of the *DPDK Programmer's Guide*.
 
 The ``main()`` function also initializes all the ports using the user defined
-``port_init()`` function which is explained in the next section:
+``port_init()`` function, which is explained in the next section:
 
 .. literalinclude:: ../../../examples/skeleton/basicfwd.c
     :language: c
@@ -129,10 +129,10 @@ Finally, the Rx port is set in promiscuous mode:
         :dedent: 1
 
 
-The Lcores Main
+The Lcore Main
 ~~~~~~~~~~~~~~~
 
-As we saw above, the ``main()`` function calls an application function
+As shown above, the ``main()`` function calls an application function
 on the available lcores.
 For the basic forwarding application, the lcore function
 looks like the following:
@@ -152,7 +152,7 @@ The main work of the application is done within the loop:
 
 Packets are received in bursts on the RX ports and transmitted in bursts on
 the TX ports. The ports are grouped in pairs with a simple mapping scheme
-using the an XOR on the port number::
+using XOR on the port number::
 
     0 -> 1
     1 -> 0
doc/guides/sample_app_ug/test_pipeline.rst +7 -10
index 818be93cd6..c18326105d 100644
@@ -30,7 +30,7 @@ The application uses three CPU cores:
 
 Compiling the Application
 -------------------------
-To compile the sample application see :doc:`compiling`
+To compile the sample application, see :doc:`compiling`
 
 The application is located in the ``dpdk/<build_dir>/app`` directory.
 
@@ -95,7 +95,7 @@ For hash tables, the following parameters can be selected:
    |       |                        |                                                          | [4-byte index, 4 bytes of 0]                          |
    |       |                        |                                                          |                                                       |
    |       |                        |                                                          | The action configured for all table entries is        |
-   |       |                        |                                                          | "Sendto output port", with the output port index      |
+   |       |                        |                                                          | "send to output port", with the output port index     |
    |       |                        |                                                          | uniformly distributed for the range of output ports.  |
    |       |                        |                                                          |                                                       |
    |       |                        |                                                          | The default table rule (used in the case of a lookup  |
@@ -118,7 +118,7 @@ For hash tables, the following parameters can be selected:
    |       |                        |                                                          | [4-byte index, 12 bytes of 0]                         |
    |       |                        |                                                          |                                                       |
    |       |                        |                                                          | The action configured for all table entries is        |
-   |       |                        |                                                          | "Send to output port", with the output port index     |
+   |       |                        |                                                          | "send to output port", with the output port index     |
    |       |                        |                                                          | uniformly distributed for the range of output ports.  |
    |       |                        |                                                          |                                                       |
    |       |                        |                                                          | The default table rule (used in the case of a lookup  |
@@ -141,7 +141,7 @@ For hash tables, the following parameters can be selected:
    |       |                        |                                                          | [4-byte index, 28 bytes of 0].                        |
    |       |                        |                                                          |                                                       |
    |       |                        |                                                          | The action configured for all table entries is        |
-   |       |                        |                                                          | "Send to output port", with the output port index     |
+   |       |                        |                                                          | "send to output port", with the output port index     |
    |       |                        |                                                          | uniformly distributed for the range of output ports.  |
    |       |                        |                                                          |                                                       |
    |       |                        |                                                          | The default table rule (used in the case of a lookup  |
@@ -149,7 +149,7 @@ For hash tables, the following parameters can be selected:
    |       |                        |                                                          |                                                       |
    |       |                        |                                                          | At run time, core A is creating the following lookup  |
    |       |                        |                                                          | key and storing it into the packet meta data for      |
-   |       |                        |                                                          | Lpmcore B to use for table lookup:                    |
+   |       |                        |                                                          | core B to use for table lookup:                       |
    |       |                        |                                                          |                                                       |
    |       |                        |                                                          | [destination IPv4 address, 28 bytes of 0]             |
    |       |                        |                                                          |                                                       |
@@ -177,8 +177,8 @@ For hash tables, the following parameters can be selected:
    |       |                        |                                                          | [0.192.0.0/10 => send to output port 3]               |
    |       |                        |                                                          |                                                       |
    |       |                        |                                                          | The default table rule (used in the case of a lookup  |
-   |       |                        |                                                          | miss) is to drop the packet.                          |
    |       |                        |                                                          |                                                       |
+   |       |                        |                                                          | miss) is to drop the packet.                          |
    |       |                        |                                                          | At run time, core A is storing the IPv4 destination   |
    |       |                        |                                                          | within the packet meta data to be later used by core  |
    |       |                        |                                                          | B as the lookup key.                                  |
@@ -201,11 +201,9 @@ For hash tables, the following parameters can be selected:
    |       |                        |                                                          |                                                       |
    |       |                        |                                                          | => send to output port 0]                             |
    |       |                        |                                                          |                                                       |
-   |       |                        |                                                          |                                                       |
    |       |                        |                                                          | [priority = 0 (highest),                              |
    |       |                        |                                                          |                                                       |
    |       |                        |                                                          | IPv4 source = ANY,                                    |
-   |       |                        |                                                          |                                                       |
    |       |                        |                                                          | IPv4 destination = 0.128.0.0/9,                       |
    |       |                        |                                                          |                                                       |
    |       |                        |                                                          | L4 protocol = ANY,                                    |
@@ -214,8 +212,7 @@ For hash tables, the following parameters can be selected:
    |       |                        |                                                          |                                                       |
    |       |                        |                                                          | TCP destination port = ANY                            |
    |       |                        |                                                          |                                                       |
-   |       |                        |                                                          | => send to output port 0].                            |
-   |       |                        |                                                          |                                                       |
+   |       |                        |                                                          | => send to output port 1]                             |
    |       |                        |                                                          |                                                       |
    |       |                        |                                                          | The default table rule (used in the case of a lookup  |
    |       |                        |                                                          | miss) is to drop the packet.                          |
doc/guides/sample_app_ug/timer.rst +10 -9
index 7af35d3d67..e6b821d7fd 100644
@@ -4,20 +4,23 @@
 Timer Sample Application
 ========================
 
-The Timer sample application is a simple application that demonstrates the use of a timer in a DPDK application.
-This application prints some messages from different lcores regularly, demonstrating the use of timers.
+Overview
+--------
+
+The Timer sample application demonstrates the use of a timer in a DPDK application.
+This application prints messages from different lcores regularly using timers.
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``timer`` sub-directory.
 
 Running the Application
 -----------------------
 
-To run the example in linux environment:
+To run the example in a Linux environment:
 
 .. code-block:: console
 
@@ -29,8 +32,6 @@ the Environment Abstraction Layer (EAL) options.
 Explanation
 -----------
 
-The following sections provide some explanation of the code.
-
 Initialization and Main Loop
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -44,7 +45,7 @@ In addition to EAL initialization, the timer subsystem must be initialized, by c
 
 After timer creation (see the next paragraph), the main loop is
 executed on each worker lcore using the well-known
-rte_eal_remote_launch() and also on the main.
+rte_eal_remote_launch() and also on the main lcore.
 
 .. literalinclude:: ../../../examples/timer/main.c
     :language: c
@@ -76,13 +77,13 @@ This call to rte_timer_init() is necessary before doing any other operation on t
     :end-before: >8 End of init timer structures.
     :dedent: 1
 
-Then, the two timers are configured:
+Next, the two timers are configured:
 
 *   The first timer (timer0) is loaded on the main lcore and expires every second.
     Since the PERIODICAL flag is provided, the timer is reloaded automatically by the timer subsystem.
     The callback function is timer0_cb().
 
-*   The second timer (timer1) is loaded on the next available lcore every 333 ms.
+*   The second timer (timer1) is loaded on a next available lcore every 333 ms.
     The SINGLE flag means that the timer expires only once and must be reloaded manually if required.
     The callback function is timer1_cb().
 
doc/guides/sample_app_ug/vdpa.rst +28 -23

97 lines not on this page · raw message

doc/guides/sample_app_ug/vhost.rst +94 -84

293 lines not on this page · raw message

Signature · 1 line
2.53.0
#19 lore raw

PATCH 14/15 doc: improve vhost, VM power, and VMDq sample guides

In reply to Stephen Hemminger

Enhanced documentation for virtualization-related samples:

vhost_blk.rst:
- Improved vhost block device descriptions
- Enhanced SCSI target configuration explanations
- Fixed formatting consistency

vhost_crypto.rst:
- Clarified cryptographic backend setup
- Improved virtio-crypto device descriptions
- Enhanced command-line examples

vm_power_management.rst:
- Restructured power management policy sections
- Improved guest-host communication descriptions
- Enhanced frequency scaling explanations
- Clarified branch ratio monitoring

vmdq_dcb_forwarding.rst:
- Enhanced VMDq and DCB configuration descriptions
- Improved traffic class explanations
- Fixed formatting in configuration examples

vmdq_forwarding.rst:
- Simplified VMDq pool configuration descriptions
- Improved MAC address filtering explanations

---
 doc/guides/sample_app_ug/vhost_blk.rst        |  66 +++--
 doc/guides/sample_app_ug/vhost_crypto.rst     |  64 ++---
 .../sample_app_ug/vm_power_management.rst     | 262 ++++++++----------
 .../sample_app_ug/vmdq_dcb_forwarding.rst     | 101 ++++---
 doc/guides/sample_app_ug/vmdq_forwarding.rst  |  38 ++-
 5 files changed, 251 insertions(+), 280 deletions(-)
doc/guides/sample_app_ug/vhost_blk.rst +37 -29
index 788eef0d5f..7a3421302d 100644
@@ -4,34 +4,37 @@
 Vhost_blk Sample Application
 =============================
 
-The vhost_blk sample application implemented a simple block device,
-which used as the  backend of Qemu vhost-user-blk device. Users can extend
-the exist example to use other type of block device(e.g. AIO) besides
-memory based block device. Similar with vhost-user-net device, the sample
-application used domain socket to communicate with Qemu, and the virtio
-ring (split or packed format) was processed by vhost_blk sample application.
-
-The sample application reuse lots codes from SPDK(Storage Performance
-Development Kit, https://github.com/spdk/spdk) vhost-user-blk target,
-for DPDK vhost library used in storage area, user can take SPDK as
-reference as well.
-
-Testing steps
--------------
-
-This section shows the steps how to start a VM with the block device as
+Overview
+--------
+
+The vhost_blk sample application implements a simple block device,
+which serves as the backend for the QEMU vhost-user-blk device. Users can
+extend the existing example to use other types of block devices (e.g., AIO)
+besides memory-based block devices. Similar to the vhost-user-net device,
+the sample application uses a Unix domain socket to communicate with QEMU
+and processes the virtio ring (split or packed format).
+
+The sample application reuses code from SPDK (Storage Performance
+Development Kit, https://github.com/spdk/spdk) vhost-user-blk target.
+For DPDK vhost library usage in storage applications, users can refer
+to SPDK as well.
+
+This section shows how to start a VM with the block device as
 fast data path for critical application.
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
-The application is located in the ``examples`` sub-directory.
+The application is located in the ``examples/vhost_blk`` directory.
 
-You will also need to build DPDK both on the host and inside the guest
+You will need to build DPDK both on the host and inside the guest.
 
-Start the vhost_blk example
+Running the Application
+-----------------------
+
+Start the vhost_blk application
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: console
@@ -54,12 +57,17 @@ Start the VM
         -device vhost-user-blk-pci,packed=on,chardev=char0,num-queues=1 \
         ...
 
-.. note::
-    You must check whether your Qemu can support "vhost-user-blk" or not,
-    Qemu v4.0 or newer version is required.
-    reconnect=1 means live recovery support that qemu can reconnect vhost_blk
-    after we restart vhost_blk example.
-    packed=on means the device support packed ring but need the guest kernel
-    version >= 5.0.
-    Now Qemu commit 9bb73502321d46f4d320fa17aa38201445783fc4 both support the
-    vhost-blk reconnect and packed ring.
+QEMU Options
+^^^^^^^^^^^^
+
+QEMU v4.0 or newer is required for vhost-user-blk support.
+
+reconnect=1
+   Enables live recovery support, allowing QEMU to reconnect to the
+   vhost_blk application after it restarts.
+
+packed=on
+   Enables packed virtqueue support. Requires guest kernel version 5.0
+   or newer.
+
+QEMU commit 9bb73502321d supports both vhost-blk reconnect and packed ring.
doc/guides/sample_app_ug/vhost_crypto.rst +33 -31

95 lines not on this page · raw message

doc/guides/sample_app_ug/vm_power_management.rst +108 -154

411 lines not on this page · raw message

doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst +55 -46

180 lines not on this page · raw message

doc/guides/sample_app_ug/vmdq_forwarding.rst +18 -20
index c998a5a223..3124483f79 100644
@@ -2,9 +2,9 @@
     Copyright(c) 2020 Intel Corporation.
 
 VMDq Forwarding Sample Application
-==========================================
+==================================
 
-The VMDq Forwarding sample application is a simple example of packet processing using the DPDK.
+The VMDq Forwarding sample application is an example of packet processing using the DPDK.
 The application performs L2 forwarding using VMDq to divide the incoming traffic into queues.
 The traffic splitting is performed in hardware by the VMDq feature of the Intel® 82599 and X710/XL710 Ethernet Controllers.
 
@@ -14,28 +14,28 @@ Overview
 This sample application can be used as a starting point for developing a new application that is based on the DPDK and
 uses VMDq for traffic partitioning.
 
-VMDq filters split the incoming packets up into different "pools" - each with its own set of RX queues - based upon
+VMDq filtering splits incoming packets into different "pools" (each with its own set of Rx queues) based on
 the MAC address and VLAN ID within the VLAN tag of the packet.
 
 All traffic is read from a single incoming port and output on another port, without any processing being performed.
-With Intel® 82599 NIC, for example, the traffic is split into 128 queues on input, where each thread of the application reads from
-multiple queues. When run with 8 threads, that is, with the -c FF option, each thread receives and forwards packets from 16 queues.
+With the Intel® 82599 NIC, for example, traffic is split into 128 queues on input, where each thread of the application reads from
+multiple queues. When run with 8 threads with the -c FF option, each thread receives and forwards packets from 16 queues.
 
-As supplied, the sample application configures the VMDq feature to have 32 pools with 4 queues each.
+As supplied, the sample application configures the VMDq feature to have 32 pools, with 4 queues each.
 The Intel® 82599 10 Gigabit Ethernet Controller NIC also supports the splitting of traffic into 16 pools of 2 queues.
 While the Intel® X710 or XL710 Ethernet Controller NICs support many configurations of VMDq pools of 4 or 8 queues each.
 And queues numbers for each VMDq pool can be changed by setting RTE_LIBRTE_I40E_QUEUE_NUM_PER_VM
 in config/rte_config.h file.
-The nb-pools and enable-rss parameters can be passed on the command line, after the EAL parameters:
+The ``--nb-pools`` and ``--enable-rss`` parameters can be passed on the command line, after the EAL parameters:
 
 .. code-block:: console
 
     ./<build_dir>/examples/dpdk-vmdq [EAL options] -- -p PORTMASK --nb-pools NP --enable-rss
 
-where, NP can be 8, 16 or 32, rss is disabled by default.
+where NP can be 8, 16 or 32. RSS is disabled by default.
 
-In Linux* user space, the application can display statistics with the number of packets received on each queue.
-To have the application display the statistics, send a SIGHUP signal to the running application process.
+In a Linux user space, the application can display statistics on standard output showing the number of packets received on each queue.
+To have the application display statistics, send a SIGHUP signal to the running application process.
 
 The VMDq Forwarding sample application is in many ways simpler than the L2 Forwarding application
 (see :doc:`l2_forward_real_virtual`)
@@ -45,7 +45,7 @@ No command-line options are taken by this application apart from the standard EA
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``vmdq`` sub-directory.
 
@@ -64,20 +64,18 @@ the Environment Abstraction Layer (EAL) options.
 Explanation
 -----------
 
-The following sections provide some explanation of the code.
+The following sections provide explanation of the code.
 
 Initialization
 ~~~~~~~~~~~~~~
 
 The EAL, driver and PCI configuration is performed largely as in the L2 Forwarding sample application,
-as is the creation of the mbuf pool.
-See :doc:`l2_forward_real_virtual`.
-Where this example application differs is in the configuration of the NIC port for RX.
+as is the creation of the mbuf pool. See :doc:`l2_forward_real_virtual`.
+This example application differs in the configuration of the NIC port for Rx.
 
 The VMDq hardware feature is configured at port initialization time by setting the appropriate values in the
 rte_eth_conf structure passed to the rte_eth_dev_configure() API.
-Initially in the application,
-a default structure is provided for VMDq configuration to be filled in later by the application.
+Initially in the application, a default structure is provided for VMDq configuration to be filled in later by the application.
 
 .. literalinclude:: ../../../examples/vmdq/main.c
     :language: c
@@ -88,8 +86,8 @@ The get_eth_conf() function fills in an rte_eth_conf structure with the appropri
 based on the global vlan_tags array.
 For the VLAN IDs, each one can be allocated to possibly multiple pools of queues.
 For destination MAC, each VMDq pool will be assigned with a MAC address. In this sample, each VMDq pool
-is assigned to the MAC like 52:54:00:12:<port_id>:<pool_id>, that is,
-the MAC of VMDq pool 2 on port 1 is 52:54:00:12:01:02.
+is assigned to the MAC like 52:54:00:12:<port_id>:<pool_id>.
+The MAC of VMDq pool 2 on port 1 is 52:54:00:12:01:02.
 
 .. literalinclude:: ../../../examples/vmdq/main.c
     :language: c
@@ -126,5 +124,5 @@ To generate the statistics output, use the following command:
 
     user@host$ sudo killall -HUP vmdq_app
 
-Please note that the statistics output will appear on the terminal where the vmdq_app is running,
+Please note that the statistics output will appear on the terminal where the application is running,
 rather than the terminal from which the HUP signal was sent.
Signature · 1 line
2.53.0
#20 lore raw

PATCH 15/15 doc: correct grammar and punctuation consistency issues

In reply to Stephen Hemminger

Correct grammar and punctuation issues across sample application guides:
- Added missing comma after "To compile the sample application" in 11 files
- Added missing period in cmd_line.rst compilation instruction
- Fixed capitalization of "Linux" (was lowercase "linux") in 4 files
- Fixed capitalization of "Ethernet" (was lowercase "ethernet") in 2 files
- Fixed "then" to "than" in comparison contexts (2 instances)
- Fixed subject-verb agreement: "specify" to "specifies"

These changes ensure consistency with the style used in other documentation files and improve overall readability.

---
 doc/guides/sample_app_ug/bbdev_app.rst        |  4 ++--
 doc/guides/sample_app_ug/cmd_line.rst         |  2 +-
 doc/guides/sample_app_ug/ethtool.rst          |  2 +-
 doc/guides/sample_app_ug/fips_validation.rst  |  2 +-
 doc/guides/sample_app_ug/hello_world.rst      |  2 +-
 doc/guides/sample_app_ug/ipsec_secgw.rst      | 20 +++++++++----------
 .../sample_app_ug/l2_forward_real_virtual.rst |  4 ++--
 doc/guides/sample_app_ug/link_status_intr.rst |  2 +-
 doc/guides/sample_app_ug/multi_process.rst    |  2 +-
 doc/guides/sample_app_ug/ntb.rst              |  2 +-
 doc/guides/sample_app_ug/ptp_tap_relay_sw.rst |  2 +-
 doc/guides/sample_app_ug/ptpclient.rst        |  2 +-
 doc/guides/sample_app_ug/qos_metering.rst     |  2 +-
 doc/guides/sample_app_ug/rxtx_callbacks.rst   |  2 +-
 14 files changed, 25 insertions(+), 25 deletions(-)
doc/guides/sample_app_ug/bbdev_app.rst +2 -2
index 00bbd1aa27..58deb6d90f 100644
@@ -25,7 +25,7 @@ The MAC header is preserved in the packet throughout the loop-back operation.
 Limitations
 -----------
 
-* Only one baseband device and one ethernet port can be used.
+* Only one baseband device and one Ethernet port can be used.
 
 Compiling the Application
 -------------------------
@@ -34,7 +34,7 @@ DPDK needs to be built with ``baseband_turbo_sw`` PMD enabled along
 with ``FLEXRAN SDK`` Libraries. Refer to *SW Turbo Poll Mode Driver*
 documentation for more details.
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 
 Running the Application
doc/guides/sample_app_ug/cmd_line.rst +1 -1
index 5b192bc615..072e4850b4 100644
@@ -47,7 +47,7 @@ There are three simple commands:
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``cmd_line`` sub-directory.
 
doc/guides/sample_app_ug/ethtool.rst +1 -1
index 68bcf25b1f..4f740b09a7 100644
@@ -18,7 +18,7 @@ is based upon a simple L2 frame reflector.
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``ethtool`` subdirectory.
 
doc/guides/sample_app_ug/fips_validation.rst +1 -1
index 732f47212a..ad51beb4f4 100644
@@ -96,7 +96,7 @@ Compiling the Application
 
 * Compile Application
 
-    To compile the sample application see :doc:`compiling`.
+    To compile the sample application, see :doc:`compiling`.
 
 *  Run ``dos2unix`` on the request files
 
doc/guides/sample_app_ug/hello_world.rst +1 -1
index 603a1d8767..feee6b52ae 100644
@@ -14,7 +14,7 @@ The application simply prints a "helloworld" message on every enabled lcore.
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``helloworld`` sub-directory.
 
doc/guides/sample_app_ug/ipsec_secgw.rst +10 -10
index 8826ffb286..1f172fd4b6 100644
@@ -89,7 +89,7 @@ The application supports two modes of operation: poll mode and event mode.
   **Currently the application provides non-burst, internal port worker threads.**
   It also provides infrastructure for non-internal ports but does not define any worker threads.
 
-  Event mode also supports event vectorization. The event devices, ethernet device
+  Event mode also supports event vectorization. The event devices, Ethernet device
   pairs which support the capability ``RTE_EVENT_ETH_RX_ADAPTER_CAP_EVENT_VECTOR`` can
   aggregate packets based on flow characteristics and generate a ``rte_event``
   containing ``rte_event_vector``.
@@ -245,9 +245,9 @@ Where:
     Zero value disables reassembly functionality.
     Default value: 0.
 
-*   ``--mtu MTU``: MTU value (in bytes) on all attached ethernet ports.
-    Outgoing packets with length bigger then MTU will be fragmented.
-    Incoming packets with length bigger then MTU will be discarded.
+*   ``--mtu MTU``: MTU value (in bytes) on all attached Ethernet ports.
+    Outgoing packets with length bigger than MTU will be fragmented.
+    Incoming packets with length bigger than MTU will be discarded.
     Default value: 1500.
 
 *   ``--frag-ttl FRAG_TTL_NS``: fragment lifetime (in nanoseconds).
@@ -694,10 +694,10 @@ where each options means:
 
 ``<type>``
 
- * Action type to specify the security action. This option specify
+ * Action type to specify the security action. This option specifies
    the SA to be performed with look aside protocol offload to HW
-   accelerator or protocol offload on ethernet device or inline
-   crypto processing on the ethernet device during transmission.
+   accelerator or protocol offload on Ethernet device or inline
+   crypto processing on the Ethernet device during transmission.
 
  * Optional: Yes, default type *no-offload*
 
@@ -1083,7 +1083,7 @@ The test directory contains scripts for testing the various encryption
 algorithms.
 
 The purpose of the scripts is to automate ipsec-secgw testing
-using another system running linux as a DUT.
+using another system running Linux as a DUT.
 
 The user must setup the following environment variables:
 
@@ -1127,11 +1127,11 @@ key to the DUT. It will ask for credentials so that it can upload the public key
 
 The SUT and DUT are connected through at least 2 NIC ports.
 
-One NIC port is expected to be managed by linux on both machines and will be
+One NIC port is expected to be managed by Linux on both machines and will be
 used as a control path.
 
 The second NIC port (test-port) should be bound to DPDK on the SUT, and should
-be managed by linux on the DUT.
+be managed by Linux on the DUT.
 
 The script starts ``ipsec-secgw`` with 2 NIC devices: ``test-port`` and
 ``tap vdev``.
doc/guides/sample_app_ug/l2_forward_real_virtual.rst +2 -2
index dbe880e1b3..e31dd98ae5 100644
@@ -111,14 +111,14 @@ where,
 
 *   --portmap="(port,port)[,(port,port)]": Determines forwarding ports mapping.
 
-To run the application in linux environment with 4 lcores, 16 ports and 8 RX queues per lcore and MAC address
+To run the application in Linux environment with 4 lcores, 16 ports and 8 RX queues per lcore and MAC address
 updating enabled, issue the command:
 
 .. code-block:: console
 
     $ ./<build_dir>/examples/dpdk-l2fwd -l 0-3 -- -q 8 -p ffff
 
-To run the application in linux environment with 4 lcores, 4 ports, 8 RX queues
+To run the application in Linux environment with 4 lcores, 4 ports, 8 RX queues
 per lcore, to forward RX traffic of ports 0 & 1 on ports 2 & 3 respectively and
 vice versa, issue the command:
 
doc/guides/sample_app_ug/link_status_intr.rst +1 -1
index fd4e32560c..d1021df5c8 100644
@@ -50,7 +50,7 @@ where,
 
 *   -T PERIOD: statistics will be refreshed each PERIOD seconds (0 to disable, 10 default)
 
-To run the application in a linux environment with 4 lcores, 16 ports and 8 RX queues per lcore,
+To run the application in a Linux environment with 4 lcores, 16 ports and 8 RX queues per lcore,
 issue the command:
 
 .. code-block:: console
doc/guides/sample_app_ug/multi_process.rst +1 -1
index e9e5809a92..f1ec980e20 100644
@@ -16,7 +16,7 @@ The multi-process example applications are built the same way as other sample ap
 and as documented in the *DPDK Getting Started Guide*.
 
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The applications are located in the ``multi_process`` sub-directory.
 
doc/guides/sample_app_ug/ntb.rst +1 -1
index ca0ff54757..8557b73042 100644
@@ -20,7 +20,7 @@ This sample supports 4 types of packet forwarding mode.
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``ntb`` sub-directory.
 
doc/guides/sample_app_ug/ptp_tap_relay_sw.rst +1 -1
index 466879cd46..a880a1295a 100644
@@ -75,7 +75,7 @@ This minimises the gap between the measured timestamp and the actual wire egress
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``ptp_tap_relay_sw`` sub-directory.
 
doc/guides/sample_app_ug/ptpclient.rst +1 -1
index 28007604a0..b842f5e0b8 100644
@@ -58,7 +58,7 @@ synchronizes the PTP PHC clock with the Linux kernel clock.
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``ptpclient`` sub-directory.
 
doc/guides/sample_app_ug/qos_metering.rst +1 -1
index b317d4079d..e8f3c6af19 100644
@@ -38,7 +38,7 @@ all the incoming packets are colored as green.
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``qos_meter`` sub-directory.
 
doc/guides/sample_app_ug/rxtx_callbacks.rst +1 -1
index 7dfcab5d65..31e2e5c811 100644
@@ -33,7 +33,7 @@ The application is located in the ``rxtx_callbacks`` sub-directory.
 Running the Application
 -----------------------
 
-To run the example in a ``linux`` environment:
+To run the example in a ``Linux`` environment:
 
 .. code-block:: console
 
Signature · 1 line
2.53.0
Acked-by on v1 15/15
#21 lore raw

Re: [PATCH 15/15] doc: correct grammar and punctuation consistency issues

Quoted 8 lines · Stephen Hemminger

Correct grammar and punctuation issues across sample application guides:
- Added missing comma after "To compile the sample application" in 11 files
- Added missing period in cmd_line.rst compilation instruction
- Fixed capitalization of "Linux" (was lowercase "linux") in 4 files
- Fixed capitalization of "Ethernet" (was lowercase "ethernet") in 2 files
- Fixed "then" to "than" in comparison contexts (2 instances)
- Fixed subject-verb agreement: "specify" to "specifies"

Quoted 5 lines

These changes ensure consistency with the style used in other documentation files and improve overall readability.

---