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

[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

Signed-off-by: Stephen Hemminger <stephen at networkplumber.org>
---
 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(-)

diff --git a/doc/guides/sample_app_ug/qos_metering.rst b/doc/guides/sample_app_ug/qos_metering.rst
index e7101559aa..b317d4079d 100644
--- a/doc/guides/sample_app_ug/qos_metering.rst
+++ b/doc/guides/sample_app_ug/qos_metering.rst
@@ -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.
 
diff --git a/doc/guides/sample_app_ug/qos_scheduler.rst b/doc/guides/sample_app_ug/qos_scheduler.rst
index cd33beecb0..645f134e7f 100644
--- a/doc/guides/sample_app_ug/qos_scheduler.rst
+++ b/doc/guides/sample_app_ug/qos_scheduler.rst
@@ -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.
diff --git a/doc/guides/sample_app_ug/rxtx_callbacks.rst b/doc/guides/sample_app_ug/rxtx_callbacks.rst
index cd6512508b..7dfcab5d65 100644
--- a/doc/guides/sample_app_ug/rxtx_callbacks.rst
+++ b/doc/guides/sample_app_ug/rxtx_callbacks.rst
@@ -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:
diff --git a/doc/guides/sample_app_ug/server_node_efd.rst b/doc/guides/sample_app_ug/server_node_efd.rst
index c90d74ae1c..d543148328 100644
--- a/doc/guides/sample_app_ug/server_node_efd.rst
+++ b/doc/guides/sample_app_ug/server_node_efd.rst
@@ -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
diff --git a/doc/guides/sample_app_ug/service_cores.rst b/doc/guides/sample_app_ug/service_cores.rst
index 307a6c5fbb..11b6ebde1e 100644
--- a/doc/guides/sample_app_ug/service_cores.rst
+++ b/doc/guides/sample_app_ug/service_cores.rst
@@ -4,31 +4,34 @@
 Service Cores Sample Application
 ================================
 
-The service cores sample application demonstrates the service cores capabilities
-of DPDK. The service cores infrastructure is part of the DPDK EAL, and allows
-any DPDK component to register a service. A service is a work item or task, that
+Overview
+--------
+
+This sample application demonstrates the service cores API of DPDK.
+The service cores infrastructure is part of the DPDK EAL and allows any
+DPDK component to register a service. A service is a work item or task that
 requires CPU time to perform its duty.
 
-This sample application registers 5 dummy services. These 5 services are used
-to show how the service_cores API can be used to orchestrate these services to
-run on different service lcores. This orchestration is done by calling the
-service cores APIs, however the sample application introduces a "profile"
-concept to contain the service mapping details. Note that the profile concept
-is application specific, and not a part of the service cores API.
+This sample application registers 5 dummy services to demonstrate how the
+service cores API can orchestrate these services to run on different service
+lcores. The orchestration is performed by calling the service cores APIs.
+The sample application introduces a "profile" concept to group service-to-core
+mapping configurations. Note that profiles are application-specific and not
+part of the service cores API itself.
 
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+See :doc:`compiling`.
 
 The application is located in the ``service_cores`` sub-directory.
 
 Running the Application
 -----------------------
 
-To run the example, just execute the binary. Since the application dynamically
-adds service cores in the application code itself, there is no requirement to
+To run the example, execute the binary. Since the application dynamically
+adds service cores at runtime, there is no requirement to
 pass a service core-mask as an EAL argument at startup time.
 
 .. code-block:: console
@@ -39,19 +42,19 @@ pass a service core-mask as an EAL argument at startup time.
 Explanation
 -----------
 
-The following sections provide some explanation of code focusing on
-registering applications from an applications point of view, and modifying the
-service core counts and mappings at runtime.
+The following sections explain the application code, focusing on registering
+services from an application's perspective and modifying service core counts
+and mappings at runtime.
 
 
 Registering a Service
 ~~~~~~~~~~~~~~~~~~~~~
 
 The following code section shows how to register a service as an application.
-Note that the service component header must be included by the application in
-order to register services: ``rte_service_component.h``, in addition
-to the ordinary service cores header ``rte_service.h`` which provides
-the runtime functions to add, remove and remap service cores.
+Note: The service component header must be included by the application in
+order to register services: ``rte_service_component.h``. In addition, the
+service cores header ``rte_service.h`` provides the runtime functions to add,
+remove, and remap service cores.
 
 .. literalinclude:: ../../../examples/service_cores/main.c
     :language: c
@@ -63,9 +66,9 @@ the runtime functions to add, remove and remap service cores.
 Controlling A Service Core
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This section demonstrates how to add a service core. The ``rte_service.h``
-header file provides the functions for dynamically adding and removing cores.
-The APIs to add and remove cores use lcore IDs similar to existing DPDK
+This section demonstrates how to add a service core and assign a service to it.
+The ``rte_service.h`` header file provides functions for dynamically adding
+and removing cores. These APIs use lcore IDs similar to existing DPDK
 functions.
 
 These are the functions to start a service core, and have it run a service:
@@ -79,18 +82,20 @@ These are the functions to start a service core, and have it run a service:
 Removing A Service Core
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-To remove a service core, the steps are similar to adding but in reverse order.
-Note that it is not allowed to remove a service core if the service is running,
-and the service-core is the only core running that service (see documentation
+To remove a service core, perform the adding steps in reverse order.
+Note: Removing a service core is not allowed if a service is running and
+the service core is the only core running that service (see documentation
 for ``rte_service_lcore_stop`` function for details).
 
 
 Conclusion
 ~~~~~~~~~~
 
-The service cores infrastructure provides DPDK with two main features. The first
-is to abstract away hardware differences: the service core can CPU cycles to
-a software fallback implementation, allowing the application to be abstracted
-from the difference in HW / SW availability. The second feature is a flexible
-method of registering functions to be run, allowing the running of the
-functions to be scaled across multiple CPUs.
+The service cores infrastructure provides DPDK with two main features.
+
+First, it abstracts hardware differences: service cores can provide CPU cycles
+to software fallback implementations, allowing applications to be abstracted
+from hardware and software availability differences.
+
+Second, it provides a flexible method for registering functions to run,
+allowing function execution to scale across multiple CPUs.
-- 
2.53.0