* [PATCH] doc: reword sample app guides
@ 2024-10-21 23:42 Nandini Persad
2024-11-29 22:04 ` Thomas Monjalon
0 siblings, 1 reply; 5+ messages in thread
From: Nandini Persad @ 2024-10-21 23:42 UTC (permalink / raw)
To: Tomasz Kantecki, Sunil Kumar Kori, Pavan Nikhilesh, Akhil Goyal,
Bruce Richardson, Jerin Jacob, Kiran Kumar K, Nithin Dabilpuram,
Zhirun Yan, Anatoly Burakov, David Hunt, Sivaprasad Tummala,
Byron Marohn, Yipeng Wang
Cc: dev
I revised these sections mostly for grammar and clarity.
Signed-off-by: Nandini Persad <nandinipersad361@gmail.com>
---
doc/guides/sample_app_ug/l2_forward_cat.rst | 24 +++--
doc/guides/sample_app_ug/l2_forward_event.rst | 96 +++++++++----------
.../sample_app_ug/l2_forward_macsec.rst | 8 +-
.../sample_app_ug/l2_forward_real_virtual.rst | 49 +++++-----
doc/guides/sample_app_ug/l3_forward.rst | 29 +++---
doc/guides/sample_app_ug/l3_forward_graph.rst | 12 +--
.../sample_app_ug/l3_forward_power_man.rst | 10 +-
doc/guides/sample_app_ug/link_status_intr.rst | 9 +-
doc/guides/sample_app_ug/server_node_efd.rst | 12 +--
9 files changed, 128 insertions(+), 121 deletions(-)
diff --git a/doc/guides/sample_app_ug/l2_forward_cat.rst b/doc/guides/sample_app_ug/l2_forward_cat.rst
index 51621b692f..ab38d99821 100644
--- a/doc/guides/sample_app_ug/l2_forward_cat.rst
+++ b/doc/guides/sample_app_ug/l2_forward_cat.rst
@@ -4,19 +4,23 @@
L2 Forwarding Sample Application with Cache Allocation Technology (CAT)
=======================================================================
-Basic Forwarding sample application is a simple *skeleton* example of
+The Basic Forwarding sample application is a *skeleton* example of
a forwarding application. It has been extended to make use of CAT via extended
command line options and linking against the libpqos library.
-It is intended as a demonstration of the basic components of a DPDK forwarding
-application and use of the libpqos library to program CAT.
-For more detailed implementations see the L2 and L3 forwarding
+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.
+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
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.
@@ -29,7 +33,7 @@ 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.
-For more information about CAT please see:
+For more information about CAT, please see:
* https://github.com/01org/intel-cmt-cat
@@ -57,7 +61,7 @@ To compile the application, export the path to PQoS lib:
export CFLAGS=-I/path/to/intel-cmt-cat/include
export LDFLAGS=-L/path/to/intel-cmt-cat/lib
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
The application is located in the ``l2fwd-cat`` sub-directory.
@@ -71,13 +75,13 @@ To run the example in a ``linux`` environment and enable CAT on cpus 0-2:
./<build_dir>/examples/dpdk-l2fwd-cat -l 1 -n 4 -- --l3ca="0x3@(0-2)"
-or to enable CAT and CDP on cpus 1,3:
+Or to enable CAT and CDP on cpus 1,3:
.. code-block:: console
./<build_dir>/examples/dpdk-l2fwd-cat -l 1 -n 4 -- --l3ca="(0x00C00,0x00300)@(1,3)"
-If CDP is not supported it will fail with following error message:
+If CDP is not supported, it will fail with following error message:
.. code-block:: console
@@ -191,8 +195,8 @@ function. The value returned is the number of parsed arguments:
``cat_init()`` is a wrapper function which parses the command, validates
the requested parameters and configures CAT accordingly.
-Parsing of command line arguments is done in ``parse_args(...)``.
-libpqos is then initialized with the ``pqos_init(...)`` call. Next, libpqos is
+The parsing of command line arguments is done in ``parse_args(...)``.
+Libpqos 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, ...)``
calls. When all capability and topology information is collected, the requested
diff --git a/doc/guides/sample_app_ug/l2_forward_event.rst b/doc/guides/sample_app_ug/l2_forward_event.rst
index 904f6f1a4a..4c9cac871e 100644
--- a/doc/guides/sample_app_ug/l2_forward_event.rst
+++ b/doc/guides/sample_app_ug/l2_forward_event.rst
@@ -6,24 +6,24 @@
L2 Forwarding Eventdev Sample Application
=========================================
-The L2 Forwarding eventdev sample application is a simple example of packet
-processing using the Data Plane Development Kit (DPDK) to demonstrate usage of
-poll and event mode packet I/O mechanism.
+The L2 Forwarding eventdev sample application is an example of packet
+processing using the Data Plane Development Kit (DPDK) to demonstrate the usage of
+the poll and event mode packet I/O mechanism.
Overview
--------
-The L2 Forwarding eventdev sample application, performs L2 forwarding for each
+The L2 Forwarding eventdev sample application performs L2 forwarding for each
packet that is received on an RX_PORT. The destination port is the adjacent port
-from the enabled portmask, that is, if the first four ports are enabled (portmask=0x0f),
+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 addresses updating is enabled, the MAC addresses are affected as follows:
+Also, if MAC address updating is enabled, the MAC addresses are affected as follows:
* The source MAC address is replaced by the TX_PORT MAC address
* The destination MAC address is replaced by 02:00:00:00:00:TX_PORT_ID
-Application receives packets from RX_PORT using below mentioned methods:
+Application receives packets from RX_PORT using these methods:
* Poll mode
@@ -41,7 +41,7 @@ as shown in the :numref:`figure_l2fwd_event_benchmark_setup`.
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 ``l2fwd-event`` sub-directory.
@@ -79,7 +79,7 @@ where,
* --event-vector-tmo: Max timeout to form vector in nanoseconds if event vectorization is enabled.
-Sample usage commands are given below to run the application into different mode:
+Sample usage commands are given below to run the application into different modes:
Poll mode with 4 lcores, 16 ports and 8 RX queues per lcore and MAC address updating enabled,
issue the command:
@@ -88,7 +88,7 @@ issue the command:
./<build_dir>/examples/dpdk-l2fwd-event -l 0-3 -n 4 -- -q 8 -p ffff --mode=poll
-Eventdev mode with 4 lcores, 16 ports , sched method ordered and MAC address updating enabled,
+Eventdev mode with 4 lcores, 16 ports, schedule method ordered and MAC address updating enabled,
issue the command:
.. code-block:: console
@@ -102,17 +102,17 @@ or
./<build_dir>/examples/dpdk-l2fwd-event -l 0-3 -n 4 -- -q 8 -p ffff --mode=eventdev --eventq-sched=ordered
Refer to the *DPDK Getting Started Guide* for general information on running
-applications and the Environment Abstraction Layer (EAL) options.
+applications and Environment Abstraction Layer (EAL) options.
-To run application with S/W scheduler, it uses following DPDK services:
+To run the application with S/W scheduler, it uses following DPDK services:
* Software scheduler
* Rx adapter service function
* Tx adapter service function
-Application needs service cores to run above mentioned services. Service cores
+The application needs service cores to run the above mentioned services. Service cores
must be provided as EAL parameters along with the --vdev=event_sw0 to enable S/W
-scheduler. Following is the sample command:
+scheduler. The following is the sample command:
.. code-block:: console
@@ -121,24 +121,24 @@ scheduler. Following is the sample command:
Explanation
-----------
-The following sections provide some explanation of the code.
+The following sections provide an explanation of the code.
.. _l2_fwd_event_app_cmd_arguments:
Command Line Arguments
~~~~~~~~~~~~~~~~~~~~~~
-The L2 Forwarding eventdev sample application takes specific parameters,
-in addition to Environment Abstraction Layer (EAL) arguments.
-The preferred way to parse parameters is to use the getopt() function,
+The L2 Forwarding eventdev sample application takes specific parameters
+and Environment Abstraction Layer (EAL) arguments.
+The preferred way to parse parameters is to use the getopt() function
since it is part of a well-defined and portable library.
-The parsing of arguments is done in the **l2fwd_parse_args()** function for non
+The parsing of arguments is done in the **l2fwd_parse_args()** function for non-
eventdev parameters and in **parse_eventdev_args()** for eventdev parameters.
-The method of argument parsing is not described here. Refer to the
-*glibc getopt(3)* man page for details.
+This method of argument parsing is not described here. Refer to the
+*glibc getopt(3)* main page for details.
-EAL arguments are parsed first, then application-specific arguments.
+EAL arguments are parsed first, then application-specific arguments follow.
This is done at the beginning of the main() function and eventdev parameters
are parsed in eventdev_resource_setup() function during eventdev setup:
@@ -181,7 +181,7 @@ Driver Initialization
The main part of the code in the main() function relates to the initialization
of the driver. To fully understand this code, it is recommended to study the
-chapters that related to the Poll Mode and Event mode Driver in the
+chapters related to the Poll Mode and Event mode Driver in the
*DPDK Programmer's Guide* - Rel 1.4 EAR and the *DPDK API Reference*.
.. literalinclude:: ../../../examples/l2fwd-event/main.c
@@ -234,7 +234,7 @@ loop (see :ref:`l2_fwd_event_app_rx_tx_packets`).
TX Queue Initialization
~~~~~~~~~~~~~~~~~~~~~~~
-Each lcore should be able to transmit on any port. For every port, a single TX
+Each lcore should be able to transmit on any port. For each port, a single TX
queue is initialized.
.. literalinclude:: ../../../examples/l2fwd-event/l2fwd_common.c
@@ -243,7 +243,7 @@ queue is initialized.
:end-before: >8 End of init one TX queue on each port.
:dedent: 2
-To configure eventdev support, application setups following components:
+To configure eventdev support, the application sets up following components:
* Event dev
* Event queue
@@ -257,7 +257,7 @@ Event device Initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Application can use either H/W or S/W based event device scheduler
implementation and supports single instance of event device. It configures event
-device as per below configuration
+device as per the following configuration:
.. literalinclude:: ../../../examples/l2fwd-event/l2fwd_event_generic.c
:language: c
@@ -265,8 +265,8 @@ device as per below configuration
:end-before: >8 End of configuration event device as per below configuration.
:dedent: 1
-In case of S/W scheduler, application runs eventdev scheduler service on service
-core. Application retrieves service id and finds the best possible service core to
+In case of S/W scheduler, the application runs eventdev the scheduler service on the service
+core. The application retrieves the service id and finds the best possible service core to
run S/W scheduler.
.. literalinclude:: ../../../examples/l2fwd-event/l2fwd_event.c
@@ -278,7 +278,7 @@ run S/W scheduler.
Event queue Initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~
Each Ethernet device is assigned a dedicated event queue which will be linked
-to all available event ports i.e. each lcore can dequeue packets from any of the
+to all available event ports, i.e. each lcore can dequeue packets from any of the
Ethernet ports.
.. literalinclude:: ../../../examples/l2fwd-event/l2fwd_event_generic.c
@@ -295,7 +295,7 @@ Tx adapter service function for enqueue operation.
Event port Initialization
~~~~~~~~~~~~~~~~~~~~~~~~~
Each worker thread is assigned a dedicated event port for enq/deq operations
-to/from an event device. All event ports are linked with all available event
+to/from an event device. All event ports are linked to all available event
queues.
.. literalinclude:: ../../../examples/l2fwd-event/l2fwd_event_generic.c
@@ -304,8 +304,8 @@ queues.
:end-before: >8 End of event port initialization.
:dedent: 1
-In case of S/W scheduler, an extra event port is created by DPDK library which
-is retrieved by the application and same will be used by Tx adapter service.
+In case of S/W scheduler, an extra event port is created by the DPDK library which
+is retrieved by the application. It will be used by Tx adapter service.
.. literalinclude:: ../../../examples/l2fwd-event/l2fwd_event_generic.c
:language: c
@@ -327,9 +327,9 @@ connected via Tx adapter.
:dedent: 1
For S/W scheduler instead of dedicated adapters, common Rx/Tx adapters are
-configured which will be shared among all the Ethernet ports. Also DPDK library
-need service cores to run internal services for Rx/Tx adapters. Application gets
-service id for Rx/Tx adapters and after successful setup it runs the services
+configured which will be shared among all the Ethernet ports. Also, the DPDK library
+needs service cores to run internal services for Rx/Tx adapters. The application gets a
+service id for Rx/Tx adapters. After a successful setup, it runs the services
on dedicated service cores.
.. literalinclude:: ../../../examples/l2fwd-event/l2fwd_event.c
@@ -358,18 +358,18 @@ available mbufs in the table.
Then, each mbuf in the table is processed by the l2fwd_simple_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 addresses updating
+then replace the source and destination MAC addresses if MAC address updating
is enabled.
During the initialization process, a static array of destination ports
-(l2fwd_dst_ports[]) is filled such that for each source port, a destination port
+(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.
-Also to optimize enqueue operation, l2fwd_simple_forward() stores incoming mbufs
-up to MAX_PKT_BURST. Once it reaches up to limit, all packets are transmitted to
+Also, 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
@@ -383,14 +383,14 @@ the rte_eth_tx_buffer() function directly from the main loop to send all the
received packets on the same TX port, using the burst-oriented send function,
which is more efficient.
-However, in real-life applications (such as, L3 routing),
+However, in real-life applications (such as L3 routing),
packet N is not necessarily forwarded on the same port as packet N-1.
-The application is implemented to illustrate that, so the same approach can be
+The application is implemented to illustrate so the same approach can be
reused in a more complex application.
To ensure that no packets remain in the tables, each lcore does a draining of TX
queue in its main loop. This technique introduces some latency when there are
-not many packets to send, however it improves performance:
+not many packets to send. However, it improves performance:
.. literalinclude:: ../../../examples/l2fwd-event/l2fwd_poll.c
:language: c
@@ -408,25 +408,25 @@ packets from the event ports. This is done using the following code:
:dedent: 2
-Before reading packets, deq_len is fetched to ensure correct allowed deq length
+Before reading packets, deq_len is fetched 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 addresses updating
+then replace the source and destination MAC addresses if MAC address updating
is enabled.
During the initialization process, a static array of destination ports
-(l2fwd_dst_ports[]) is filled such that for each source port, a destination port
+(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
forwarded to first port i.e. if portmask=0x07, then forwarding will take place
like p0--->p1, p1--->p2, p2--->p0.
-l2fwd_eventdev_forward() does not stores incoming mbufs. Packet will forwarded
-be to destination ports via Tx adapter or generic event dev enqueue API
+l2fwd_eventdev_forward() does not stores incoming mbufs. The packet will forwarded
+to destination ports via Tx adapter or generic event dev enqueue API
depending H/W or S/W scheduler is used.
.. literalinclude:: ../../../examples/l2fwd-event/l2fwd_event.c
diff --git a/doc/guides/sample_app_ug/l2_forward_macsec.rst b/doc/guides/sample_app_ug/l2_forward_macsec.rst
index 15dd57cfed..5ae27ff2de 100644
--- a/doc/guides/sample_app_ug/l2_forward_macsec.rst
+++ b/doc/guides/sample_app_ug/l2_forward_macsec.rst
@@ -4,8 +4,8 @@
L2 Forwarding MACsec Sample Application
=======================================
-The L2 forwarding MACsec application is a simple example of packet processing
-using the Data Plane Development Kit (DPDK) which encrypt/decrypt packets
+The L2 forwarding MACsec application is an example of packet processing
+using the Data Plane Development Kit (DPDK) to encrypt/decrypt packets
based on rte_security MACsec sessions.
Overview
@@ -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, that is,
+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.
@@ -24,7 +24,7 @@ This application can be used to benchmark performance using a traffic-generator.
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 ``l2fwd-macsec`` sub-directory.
diff --git a/doc/guides/sample_app_ug/l2_forward_real_virtual.rst b/doc/guides/sample_app_ug/l2_forward_real_virtual.rst
index aeeda7059c..8154ce4a49 100644
--- a/doc/guides/sample_app_ug/l2_forward_real_virtual.rst
+++ b/doc/guides/sample_app_ug/l2_forward_real_virtual.rst
@@ -6,9 +6,10 @@
L2 Forwarding Sample Application (in Real and Virtualized Environments)
=======================================================================
-The L2 Forwarding sample application is a simple example of packet processing using
-the Data Plane Development Kit (DPDK) which
-also takes advantage of Single Root I/O Virtualization (SR-IOV) features in a virtualized environment.
+The L2 Forwarding sample application is an example of packet processing using
+the Data Plane Development Kit (DPDK).
+It also takes advantage of Single Root I/O Virtualization (SR-IOV) features in a
+virtualized environment.
.. note::
@@ -20,10 +21,10 @@ Overview
The L2 Forwarding sample application, which can operate in real and virtualized environments,
performs L2 forwarding for each packet that is received on an RX_PORT.
-The destination port is the adjacent port from the enabled portmask, that is,
-if the first four ports are enabled (portmask 0xf),
+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.
-Also, if MAC addresses updating is enabled, the MAC addresses are affected as follows:
+Also, if MAC address updating is enabled, the MAC addresses are affected as follows:
* The source MAC address is replaced by the TX_PORT MAC address
@@ -75,12 +76,12 @@ This command enables two Virtual Functions on each of Physical Function of the N
with two physical ports in the PCI configuration space.
It is important to note that enabled Virtual Function 0 and 2 would belong to Physical Function 0
and Virtual Function 1 and 3 would belong to Physical Function 1,
-in this case enabling a total of four Virtual Functions.
+in this case, enabling a total of four Virtual Functions.
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 ``l2fwd`` sub-directory.
@@ -133,21 +134,21 @@ and the Environment Abstraction Layer (EAL) options.
Explanation
-----------
-The following sections provide some explanation of the code.
+The following sections provide explanation of the code.
.. _l2_fwd_app_cmd_arguments:
Command Line Arguments
~~~~~~~~~~~~~~~~~~~~~~
-The L2 Forwarding sample application takes specific parameters,
-in addition to Environment Abstraction Layer (EAL) arguments.
-The preferred way to parse parameters is to use the getopt() function,
+The L2 Forwarding sample application takes specific parameters
+and Environment Abstraction Layer (EAL) arguments.
+The preferred way to parse parameters is to use the getopt() function
since it is part of a well-defined and portable library.
The parsing of arguments is done in the l2fwd_parse_args() function.
-The method of argument parsing is not described here.
-Refer to the *glibc getopt(3)* man page for details.
+This method of argument parsing is not described here.
+Refer to the *glibc getopt(3)* main page for details.
EAL arguments are parsed first, then application-specific arguments.
This is done at the beginning of the main() function:
@@ -192,7 +193,7 @@ Driver Initialization
~~~~~~~~~~~~~~~~~~~~~
The main part of the code in the main() function relates to the initialization of the driver.
-To fully understand this code, it is recommended to study the chapters that related to the Poll Mode Driver
+To fully understand this code, it is recommended to study the chapters related to the Poll Mode Driver
in the *DPDK Programmer's Guide* - Rel 1.4 EAR and the *DPDK API Reference*.
.. literalinclude:: ../../../examples/l2fwd/main.c
@@ -217,7 +218,7 @@ The rte_eth_dev_configure() function is used to configure the number of queues f
RX Queue Initialization
~~~~~~~~~~~~~~~~~~~~~~~
-The application uses one lcore to poll one or several ports, depending on the -q option,
+The application uses one lcore to poll one or several ports depending on the -q option,
which specifies the number of queues per lcore.
For example, if the user specifies -q 4, the application is able to poll four ports with one lcore.
@@ -245,7 +246,7 @@ The values n_rx_port and rx_port_list[] are used in the main packet processing l
TX Queue Initialization
~~~~~~~~~~~~~~~~~~~~~~~
-Each lcore should be able to transmit on any port. For every port, a single TX queue is initialized.
+Each lcore should be able to transmit on any port. For each port, a single TX queue is initialized.
.. literalinclude:: ../../../examples/l2fwd/main.c
:language: c
@@ -272,7 +273,7 @@ The rte_eth_rx_burst() function writes the mbuf pointers in a local table and re
Then, each mbuf in the table is processed by the l2fwd_simple_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
-addresses updating is enabled.
+address updating is enabled.
.. note::
@@ -280,7 +281,7 @@ addresses updating is enabled.
During the initialization process, a static array of destination ports (l2fwd_dst_ports[]) is filled such that for each source port,
a destination port is assigned that is either the next or previous enabled port from the portmask.
-Naturally, the number of ports in the portmask must be even, otherwise, the application exits.
+Naturally, the number of ports in the portmask must be even. Otherwise, the application exits.
.. literalinclude:: ../../../examples/l2fwd/main.c
:language: c
@@ -288,15 +289,15 @@ Naturally, the number of ports in the portmask must be even, otherwise, the appl
:end-before: >8 End of simple forward.
-Then, the packet is sent using the l2fwd_send_packet (m, dst_port) function.
+At this point, the packet is sent using the l2fwd_send_packet (m, dst_port) function.
For this test application, the processing is exactly the same for all packets arriving on the same RX port.
Therefore, it would have been possible to call the l2fwd_send_burst() function directly from the main loop
to send all the received packets on the same TX port,
using the burst-oriented send function, which is more efficient.
-However, in real-life applications (such as, L3 routing),
+However, in real-life applications (such as L3 routing),
packet N is not necessarily forwarded on the same port as packet N-1.
-The application is implemented to illustrate that, so the same approach can be reused in a more complex application.
+The application is implemented to illustrate this so the same approach can be reused in a more complex application.
The l2fwd_send_packet() function stores the packet in a per-lcore and per-txport table.
If the table is full, the whole packets table is transmitted using the l2fwd_send_burst() function:
@@ -307,8 +308,8 @@ If the table is full, the whole packets table is transmitted using the l2fwd_sen
:end-before: >8 End of Enqueuing packets for TX.
To ensure that no packets remain in the tables, each lcore does a draining of TX queue in its main loop.
-This technique introduces some latency when there are not many packets to send,
-however it improves performance:
+This technique introduces some latency when there are not many packets to send.
+However it improves performance:
.. literalinclude:: ../../../examples/l2fwd/main.c
:language: c
diff --git a/doc/guides/sample_app_ug/l3_forward.rst b/doc/guides/sample_app_ug/l3_forward.rst
index 1cc2c1dd1d..95a3bfc114 100644
--- a/doc/guides/sample_app_ug/l3_forward.rst
+++ b/doc/guides/sample_app_ug/l3_forward.rst
@@ -4,8 +4,8 @@
L3 Forwarding Sample Application
================================
-The L3 Forwarding application is a simple example of packet processing using
-DPDK to demonstrate usage of poll and event mode packet I/O mechanism.
+The L3 Forwarding application is an example of packet processing using
+DPDK to demonstrate the usage of poll and event mode packet I/O mechanism.
The application performs L3 forwarding.
Overview
@@ -16,7 +16,7 @@ to implement packet forwarding using poll or event mode PMDs for packet I/O.
The initialization and run-time paths are very similar to those of the
:doc:`l2_forward_real_virtual` and :doc:`l2_forward_event`.
The main difference from the L2 Forwarding sample application is that optionally
-packet can be Rx/Tx from/to eventdev instead of port directly and forwarding
+the packet can be Rx/Tx from/to eventdev instead of to port directly. The forwarding
decision is made based on information read from the input packet.
Eventdev can optionally use S/W or H/W (if supported by platform) scheduler
@@ -58,12 +58,12 @@ a source port, a destination port and a protocol identifier.
In the sample application, hash-based, LPM-based, FIB-based and ACL-based forwarding supports
both IPv4 and IPv6.
-During the initialization phase route rules for IPv4 and IPv6 are read from rule files.
+During the initialization, phase route rules for IPv4 and IPv6 are read from rule files.
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 ``l3fwd`` sub-directory.
@@ -184,8 +184,8 @@ In this command:
* The -rule_ipv6 option specifies the reading of IPv6 rules sets from the rule_ipv6.cfg file.
-To use eventdev mode with sync method **ordered** on above mentioned environment,
-Following is the sample command:
+To use eventdev mode with sync method **ordered** on the above environment,
+the following is the sample command:
.. code-block:: console
@@ -213,16 +213,16 @@ If application uses S/W scheduler, it uses following DPDK services:
* Rx adapter service function
* Tx adapter service function
-Application needs service cores to run above mentioned services. Service cores
+The application needs service cores to run the above mentioned services. Service cores
must be provided as EAL parameters along with the --vdev=event_sw0 to enable S/W
-scheduler. Following is the sample command:
+scheduler. The following is the sample command:
.. code-block:: console
./<build_dir>/examples/dpdk-l3fwd -l 0-7 -s 0xf0000 -n 4 --vdev event_sw0 -- -p 0x3 --mode=eventdev --eventq-sched=ordered --rule_ipv4="rule_ipv4.cfg" --rule_ipv6="rule_ipv6.cfg"
In case of eventdev mode, *--config* option is not used for ethernet port
-configuration. Instead each ethernet port will be configured with mentioned
+configuration. Instead, each ethernet port will be configured with this
setup:
* Single Rx/Tx queue
@@ -239,7 +239,7 @@ the Environment Abstraction Layer (EAL) options.
Explanation
-----------
-The following sections provide some explanation of the sample application code. As mentioned in the overview section,
+The following sections provide 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` and :doc:`l2_forward_event`.
The following sections describe aspects that are specific to the L3 Forwarding sample application.
@@ -293,12 +293,12 @@ IPv4 addresses are specified in CIDR format as specified in RFC 4632.
For LPM/FIB/ACL they consist of the dot notation for the address
and a prefix length separated by '/'.
For example, 192.168.0.34/32, where the address is 192.168.0.34 and the prefix length is 32.
-For EM they consist of just the dot notation for the address and no prefix length.
+For EM, they consist of just the dot notation for the address and no prefix length.
For example, 192.168.0.34, where the Address is 192.168.0.34.
EM also includes ports which are specified as a single number which represents a single port.
The application parses the rules from the file,
-it ignores empty and comment lines,
+it ignores empty and comment lines
and parses and validates the rules it reads.
If errors are detected, the application exits
with messages to identify the errors encountered.
@@ -476,5 +476,6 @@ can be found in the sample app code.
Eventdev Driver Initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Eventdev driver initialization is same as L2 forwarding eventdev application.
+
+Eventdev driver initialization is the same as L2 forwarding eventdev application.
Refer :doc:`l2_forward_event` for more details.
diff --git a/doc/guides/sample_app_ug/l3_forward_graph.rst b/doc/guides/sample_app_ug/l3_forward_graph.rst
index eb56f9b94a..37f063dad3 100644
--- a/doc/guides/sample_app_ug/l3_forward_graph.rst
+++ b/doc/guides/sample_app_ug/l3_forward_graph.rst
@@ -4,7 +4,7 @@
L3 Forwarding Graph Sample Application
======================================
-The L3 Forwarding Graph application is a simple example of packet processing
+The L3 Forwarding Graph application is an example of packet processing
using the DPDK Graph framework. The application performs L3 forwarding using
Graph framework and nodes written for graph framework.
@@ -22,7 +22,7 @@ and configuration per lcore.
Run-time path is main thing that differs from L3 forwarding sample application.
Difference is that forwarding logic starting from Rx, followed by LPM lookup,
TTL update and finally Tx is implemented inside graph nodes. These nodes are
-interconnected in graph framework. Application main loop needs to walk over
+interconnected in graph framework. The application main loop needs to walk over
graph using ``rte_graph_walk()`` with graph objects created one per worker lcore.
The lookup method is as per implementation of ``ip4_lookup``/``ip6_lookup`` graph node.
@@ -38,7 +38,7 @@ In the sample application, IPv4 and IPv6 forwarding is supported.
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 ``l3fwd-graph`` sub-directory.
@@ -181,7 +181,7 @@ specific graph object.
Graph Initialization
~~~~~~~~~~~~~~~~~~~~
-Now a graph needs to be created with a specific set of nodes for every lcore.
+Now, a graph needs to be created with a specific set of nodes for every lcore.
A graph object returned after graph creation is a per lcore object and
cannot be shared between lcores. Since ``ethdev_tx-X`` node is per port node,
it can be associated with all the graphs created as all the lcores should have
@@ -226,8 +226,8 @@ Packet Forwarding using Graph Walk
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Now that all the device configurations are done, graph creations are done and
-forwarding data is updated with nodes, worker lcores will be launched with graph
-main loop. Graph main loop is very simple in the sense that it needs to
+forwarding data is updated with nodes, worker lcores will be launched with the graph
+main loop.The graph main loop is very simple in the sense that it needs to
continuously call a non-blocking API ``rte_graph_walk()`` with it's lcore
specific graph object that was already created.
diff --git a/doc/guides/sample_app_ug/l3_forward_power_man.rst b/doc/guides/sample_app_ug/l3_forward_power_man.rst
index 4a6f33bf4f..98b0ce5aa9 100644
--- a/doc/guides/sample_app_ug/l3_forward_power_man.rst
+++ b/doc/guides/sample_app_ug/l3_forward_power_man.rst
@@ -8,7 +8,7 @@ Introduction
------------
The L3 Forwarding with Power Management application is an example of power-aware packet processing using the DPDK.
-The application is based on existing L3 Forwarding sample application,
+The application is based on the existing L3 Forwarding sample application,
with the power management algorithms to control the P-states and
C-states of the Intel processor via a power management library.
@@ -77,7 +77,7 @@ instead of always running to the C0 state waiting for packets.
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 ``l3fwd-power`` sub-directory.
@@ -127,7 +127,7 @@ The L3fwd-power example reuses the L3fwd command line options.
Explanation
-----------
-The following sections provide some explanation of the sample application code.
+The following sections provide explanation of the sample application code.
As mentioned in the overview section,
the initialization and run-time paths are identical to those of the L3 forwarding application.
The following sections describe aspects that are specific to the L3 Forwarding with Power Management sample application.
@@ -239,7 +239,7 @@ in order to avoid a potential performance impact.
Telemetry Mode
--------------
-The telemetry mode support for ``l3fwd-power`` is a standalone mode, in this mode
+The telemetry mode support for ``l3fwd-power`` is a standalone mode. In this mode,
``l3fwd-power`` does simple l3fwding along with calculating empty polls, full polls,
and busy percentage for each forwarding core. The aggregation of these
values of all cores is reported as application level telemetry to metric
@@ -261,7 +261,7 @@ The new stats ``empty_poll`` , ``full_poll`` and ``busy_percent`` can be viewed
PMD power management Mode
-------------------------
-The PMD power management mode support for ``l3fwd-power`` is a standalone mode.
+The PMD power management mode support for ``l3fwd-power`` is a standalone mode.
In this mode, ``l3fwd-power`` does simple l3fwding
along with enabling the power saving scheme on specific port/queue/lcore.
Main purpose for this mode is to demonstrate
diff --git a/doc/guides/sample_app_ug/link_status_intr.rst b/doc/guides/sample_app_ug/link_status_intr.rst
index a4c0712bd9..22c736a6eb 100644
--- a/doc/guides/sample_app_ug/link_status_intr.rst
+++ b/doc/guides/sample_app_ug/link_status_intr.rst
@@ -4,7 +4,7 @@
Link Status Interrupt Sample Application
========================================
-The Link Status Interrupt sample application is a simple example of packet processing using
+The Link Status Interrupt sample application is an example of packet processing using
the Data Plane Development Kit (DPDK) that
demonstrates how network link status changes for a network port can be captured and
used by a DPDK application.
@@ -14,6 +14,7 @@ Overview
The Link Status Interrupt sample application registers a user space callback for the link status interrupt of each port
and performs L2 forwarding for each packet that is received on an RX_PORT.
+
The following operations are performed:
* RX_PORT and TX_PORT are paired with available ports one-by-one according to the core mask
@@ -28,7 +29,7 @@ and the behavior of L2 forwarding each time the link status changes.
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 ``link_status_interrupt`` sub-directory.
@@ -67,8 +68,8 @@ The following sections provide some explanation of the code.
Command Line Arguments
~~~~~~~~~~~~~~~~~~~~~~
-The Link Status Interrupt sample application takes specific parameters,
-in addition to Environment Abstraction Layer (EAL) arguments (see Section `Running the Application`_).
+The Link Status Interrupt sample application takes specific parameters
+and Environment Abstraction Layer (EAL) arguments (see Section `Running the Application`_).
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` for more information.
diff --git a/doc/guides/sample_app_ug/server_node_efd.rst b/doc/guides/sample_app_ug/server_node_efd.rst
index 7253b38da7..a580f0e7b4 100644
--- a/doc/guides/sample_app_ug/server_node_efd.rst
+++ b/doc/guides/sample_app_ug/server_node_efd.rst
@@ -5,7 +5,7 @@ Server-Node EFD Sample Application
==================================
This sample application demonstrates the use of EFD library as a flow-level
-load balancer, for more information about the EFD Library please refer to the
+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
@@ -56,12 +56,12 @@ then the pair of <key,target> is inserted into the flow distribution table.
The main loop of the server process receives a burst of packets, then for
each packet, a flow key (IP destination address) is extracted. The flow
-distributor table is looked up and the target node id is returned. Packets are
+distributor table is looked up and the target node id is returned. Packets are
then enqueued to the specified target node id.
-It should be noted that flow distributor table is not a membership test table.
-I.e. if the key has already been inserted the target node id will be correct,
-but for new keys the flow distributor table will return a value (which can be
+It should be noted that flow distributor table is not a membership test table,
+i.e. if the key has already been inserted the target node id will be correct.
+But for new keys, the flow distributor table will return a value (which can be
valid).
Backend Worker Nodes
@@ -81,7 +81,7 @@ that this is a new flow, which is dropped.
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 ``server_node_efd`` sub-directory.
--
2.34.1
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [PATCH] doc: reword sample app guides
2024-10-21 23:42 [PATCH] doc: reword sample app guides Nandini Persad
@ 2024-11-29 22:04 ` Thomas Monjalon
0 siblings, 0 replies; 5+ messages in thread
From: Thomas Monjalon @ 2024-11-29 22:04 UTC (permalink / raw)
To: Nandini Persad
Cc: Tomasz Kantecki, Sunil Kumar Kori, Pavan Nikhilesh, Akhil Goyal,
Bruce Richardson, Jerin Jacob, Kiran Kumar K, Nithin Dabilpuram,
Zhirun Yan, Anatoly Burakov, David Hunt, Sivaprasad Tummala,
Byron Marohn, Yipeng Wang, dev
22/10/2024 01:42, Nandini Persad:
> I revised these sections mostly for grammar and clarity.
>
> Signed-off-by: Nandini Persad <nandinipersad361@gmail.com>
Applied with few improvements in links and code formatting, thanks.
^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH] doc: reword sample app guides
@ 2024-10-10 2:51 Nandini Persad
0 siblings, 0 replies; 5+ messages in thread
From: Nandini Persad @ 2024-10-10 2:51 UTC (permalink / raw)
To: Chengwen Feng, Kevin Laatz, Bruce Richardson, Ori Kam,
Konstantin Ananyev, John McNamara
Cc: dev
I have reviewed these sections for grammar/clarity
and made small modifications to the formatting of sections
to adhere to a template which will create uniformality
in the sample application user guides overall.
Signed-off-by: Nandini Persad <nandinipersad361@gmail.com>
Acked-by: Chengwen Feng <fengchengwen@huawei.com>
---
doc/guides/sample_app_ug/cmd_line.rst | 24 ++++----
doc/guides/sample_app_ug/dma.rst | 38 ++++++-------
doc/guides/sample_app_ug/ethtool.rst | 13 +++--
doc/guides/sample_app_ug/flow_filtering.rst | 50 +++++++++--------
doc/guides/sample_app_ug/hello_world.rst | 6 +-
doc/guides/sample_app_ug/intro.rst | 20 +++----
doc/guides/sample_app_ug/ip_frag.rst | 11 ++--
doc/guides/sample_app_ug/ip_reassembly.rst | 38 +++++++------
doc/guides/sample_app_ug/ipv4_multicast.rst | 39 ++++++-------
doc/guides/sample_app_ug/keep_alive.rst | 10 ++--
.../sample_app_ug/l2_forward_crypto.rst | 29 +++++-----
.../sample_app_ug/l2_forward_job_stats.rst | 56 +++++++++++--------
doc/guides/sample_app_ug/rxtx_callbacks.rst | 21 ++++---
doc/guides/sample_app_ug/skeleton.rst | 30 +++++-----
14 files changed, 212 insertions(+), 173 deletions(-)
diff --git a/doc/guides/sample_app_ug/cmd_line.rst b/doc/guides/sample_app_ug/cmd_line.rst
index 6655b1e5a7..72ce5fc27f 100644
--- a/doc/guides/sample_app_ug/cmd_line.rst
+++ b/doc/guides/sample_app_ug/cmd_line.rst
@@ -13,7 +13,7 @@ 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 a DPDK application in a Linux* application environment.
.. note::
@@ -22,10 +22,13 @@ to debug a DPDK application, in a Linux* application environment.
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.
-The Command Line sample application supports some of the features of the GNU readline library such as, completion,
-cut/paste and some other special bindings that make configuration and debug faster and easier.
+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.
+
+The application shows how the rte_cmdline application can be extended
+to handle a list of objects.
-The application shows how the rte_cmdline application 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.
@@ -48,7 +51,7 @@ The application is located in the ``cmd_line`` sub-directory.
Running the Application
-----------------------
-To run the application in linux environment, issue the following command:
+To run the application in a linux environment, issue the following command:
.. code-block:: console
@@ -60,7 +63,7 @@ and the Environment Abstraction Layer (EAL) options.
Explanation
-----------
-The following sections provide some explanation of the code.
+The following sections provide explanation of the code.
EAL Initialization and cmdline Start
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -73,7 +76,7 @@ This is achieved as follows:
:start-after: Initialization of the Environment Abstraction Layer (EAL). 8<
:end-before: >8 End of initialization of Environment Abstraction Layer (EAL).
-Then, a new command line object is created and started to interact with the user through the console:
+Then, a new command line object is created and starts to interact with the user through the console:
.. literalinclude:: ../../../examples/cmdline/main.c
:language: c
@@ -81,13 +84,14 @@ Then, a new command line object is created and started to interact with the user
:end-before: >8 End of creating a new command line object.
:dedent: 1
-The cmd line_interact() function returns when the user types **Ctrl-d** and in this case,
-the application exits.
+The cmd line_interact() function returns when the user types **Ctrl-d** and,
+in this case, the application exits.
Defining a cmdline Context
~~~~~~~~~~~~~~~~~~~~~~~~~~
-A cmdline context is a list of commands that are listed in a NULL-terminated table, for example:
+A cmdline context is a list of commands that are listed in a NULL-terminated table.
+For example:
.. literalinclude:: ../../../examples/cmdline/commands.c
:language: c
diff --git a/doc/guides/sample_app_ug/dma.rst b/doc/guides/sample_app_ug/dma.rst
index 2765895564..701d09d1b3 100644
--- a/doc/guides/sample_app_ug/dma.rst
+++ b/doc/guides/sample_app_ug/dma.rst
@@ -10,10 +10,10 @@ Overview
--------
This sample is intended as a demonstration of the basic components of a DPDK
-forwarding application and example of how to use the DMAdev API to make a packet
+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:
+Also, while forwarding, the MAC addresses are affected as follows:
* The source MAC address is replaced by the TX port MAC address
@@ -27,7 +27,7 @@ received/send packets and packets dropped or failed to copy.
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 ``dma`` sub-directory.
@@ -38,7 +38,7 @@ Running the Application
In order to run the hardware copy application, the copying device
needs to be bound to user-space IO driver.
-Refer to the "DMAdev library" chapter in the "Programmers guide" for information
+Refer to the "DMAdev library" chapter in the Programmer's guide for information
on using the library.
The application requires a number of command line options:
@@ -70,11 +70,11 @@ where,
* i SI: set the interval, in second, between statistics prints (default is 1)
-The application can be launched in various configurations depending on
+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
-updates MAC address and sends the copy. If one lcore per port is used,
-both operations are done sequentially. For each configuration an additional
+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
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.
@@ -159,7 +159,7 @@ multiple DMA channels per port:
:end-before: >8 End of configuring port to use RSS for multiple RX queues.
:dedent: 1
-For this example the ports are set up with the number of Rx queues provided
+For this example, the ports are set up with the number of Rx queues provided
with -q option and 1 Tx queue using the ``rte_eth_rx_queue_setup()``
and ``rte_eth_tx_queue_setup()`` functions.
@@ -172,7 +172,7 @@ The Ethernet port is then started:
:dedent: 1
-Finally the Rx port is set in promiscuous mode:
+Finally, the Rx port is set in promiscuous mode:
.. literalinclude:: ../../../examples/dma/dmafwd.c
:language: c
@@ -181,7 +181,7 @@ Finally the Rx port is set in promiscuous mode:
:dedent: 1
-After that each port application assigns resources needed.
+After that, each port application assigns resources needed.
.. literalinclude:: ../../../examples/dma/dmafwd.c
:language: c
@@ -224,7 +224,7 @@ using ``rte_dma_start()`` function. Each of the above operations is done in
If initialization is successful, memory for hardware device
statistics is allocated.
-Finally ``main()`` function starts all packet handling lcores and starts
+Finally, the ``main()`` function starts all packet handling lcores and starts
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.
@@ -273,13 +273,13 @@ packet using ``pktmbuf_sw_copy()`` function and enqueue them to an 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
+function. When using hardware copy mode the packets are enqueued in the
copying device's 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()``.
+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
-start of the data buffer (``buf_iova``). Thus the ``rte_pktmbuf_iova()`` API is
+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.
.. literalinclude:: ../../../examples/dma/dmafwd.c
@@ -291,11 +291,11 @@ used to get the address of the start of the data within the mbuf.
Once the copies have been completed (this 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.
+is used to pass the packets to the Tx function.
All completed copies are processed by ``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()``.
+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()``.
.. literalinclude:: ../../../examples/dma/dmafwd.c
@@ -307,7 +307,7 @@ if it was enabled. After that copies are sent in burst mode using ``rte_eth_tx_b
The Packet Copying Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In order to perform SW packet copy, there are user-defined functions to first copy
+In order to perform SW packet copy, there are user-defined functions to the first copy
the packet metadata (``pktmbuf_metadata_copy()``) and then the packet data
(``pktmbuf_sw_copy()``):
@@ -321,5 +321,5 @@ 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
-above please refer to the "Mbuf Library" section of the
+above, please refer to the "Mbuf Library" section of the
*DPDK Programmer's Guide*.
diff --git a/doc/guides/sample_app_ug/ethtool.rst b/doc/guides/sample_app_ug/ethtool.rst
index 159e9e0639..433175368b 100644
--- a/doc/guides/sample_app_ug/ethtool.rst
+++ b/doc/guides/sample_app_ug/ethtool.rst
@@ -4,6 +4,12 @@
Ethtool Sample Application
==========================
+This chapter describes the Ethrool sample application that
+is part of the Data Plane Development Kit (DPDK).
+
+Overview
+--------
+
The Ethtool sample application shows an implementation of an
ethtool-like API and provides a console environment that allows
its use to query and change Ethernet card parameters. The sample
@@ -30,17 +36,14 @@ Refer to the *DPDK Getting Started Guide* for general information on
running applications and the Environment Abstraction Layer (EAL)
options.
-Using the application
----------------------
-
The application is console-driven using the cmdline DPDK interface:
.. code-block:: console
EthApp>
-From this interface the available commands and descriptions of what
-they do as follows:
+From this interface, the available commands and descriptions of what
+they do are as follows:
* ``drvinfo``: Print driver info
* ``eeprom``: Dump EEPROM to file
diff --git a/doc/guides/sample_app_ug/flow_filtering.rst b/doc/guides/sample_app_ug/flow_filtering.rst
index 8cac2f8a8f..2cf7973852 100644
--- a/doc/guides/sample_app_ug/flow_filtering.rst
+++ b/doc/guides/sample_app_ug/flow_filtering.rst
@@ -4,16 +4,20 @@
Basic RTE Flow Filtering Sample Application
===========================================
-The Basic RTE flow filtering sample application is a simple example of a
+
+Overview
+--------
+
+The Basic RTE flow filtering sample application is a simple example of
creating a RTE flow rule.
-It is intended as a demonstration of the basic components RTE flow rules.
+It demonstrates the basic components of RTE flow rules.
Compiling the Application
-------------------------
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
Running the Application
@@ -33,7 +37,7 @@ Explanation
-----------
The example is built from 2 files,
-``main.c`` which holds the example logic and ``flow_blocks.c`` that holds the
+``main.c`` which holds the example logic and ``flow_blocks.c`` holds the
implementation for building the flow rule.
The following sections provide an explanation of the main components of the
@@ -49,7 +53,7 @@ The Main Function
The ``main()`` function located in ``main.c`` file performs the initialization
and runs the main loop function.
-The first task is to initialize the Environment Abstraction Layer (EAL). The
+The first task is to initialize the Environment Abstraction Layer (EAL). The
``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
function. The value returned is the number of parsed arguments:
@@ -90,8 +94,8 @@ following code:
:end-before: >8 End of creating flow for send packet with.
:dedent: 1
-In the last part the application is ready to launch the
-``main_loop()`` function. Which is explained below.
+In the last part, the application is ready to launch the
+``main_loop()`` function, which is explained below.
.. literalinclude:: ../../../examples/flow_filtering/main.c
@@ -100,8 +104,9 @@ In the last part the application is ready to launch the
:end-before: >8 End of launching main_loop().
:dedent: 1
-The Port Initialization Function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Port Initialization Function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The main functional part of the port initialization used in the flow filtering
application is shown below:
@@ -120,7 +125,7 @@ The Ethernet port is configured with default settings using the
:end-before: >8 End of ethernet port configured with default settings.
:dedent: 1
-For this example we are configuring number of rx and tx queues that are connected
+For this example, we are configuring a number of Rx and Tx queues that are connected
to a single port.
.. literalinclude:: ../../../examples/flow_filtering/main.c
@@ -129,8 +134,8 @@ to a single port.
:end-before: >8 End of Configuring RX and TX queues connected to single port.
:dedent: 1
-In the next step we create and apply the flow rule. which is to send packets
-with destination ip equals to 192.168.1.1 to queue number 1. The detail
+In the next step, we create and apply the flow rule to send packets
+with destination IP equal to 192.168.1.1 to queue number 1. A detailed
explanation of the ``generate_ipv4_flow()`` appears later in this document:
.. literalinclude:: ../../../examples/flow_filtering/main.c
@@ -159,8 +164,8 @@ The last step is to start the port.
The main_loop function
~~~~~~~~~~~~~~~~~~~~~~
-As we saw above the ``main()`` function calls an application function to handle
-the main loop. For the flow filtering application the main_loop function
+As we saw above, the ``main()`` function calls an application function to handle
+the main loop. For the flow filtering application, the main_loop function
looks like the following:
.. literalinclude:: ../../../examples/flow_filtering/main.c
@@ -169,7 +174,7 @@ looks like the following:
:end-before: >8 End of reading the packets from all queues.
The main work of the application is reading the packets from all
-queues and printing for each packet the destination queue:
+queues and printing each packet from the destination queue:
.. literalinclude:: ../../../examples/flow_filtering/main.c
:language: c
@@ -178,9 +183,10 @@ queues and printing for each packet the destination queue:
The forwarding loop can be interrupted and the application closed using
-``Ctrl-C``. Which results in closing the port and the device using
+``Ctrl-C`` which results in closing the port and the device using
``rte_eth_dev_stop`` and ``rte_eth_dev_close``
+
The generate_ipv4_flow function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -200,7 +206,7 @@ The first part of the function is declaring the structures that will be used.
:end-before: >8 End of declaring structs being used.
:dedent: 1
-The following part create the flow attributes, in our case ingress.
+The following part creates the flow attributes. In this case, ingress.
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
@@ -209,7 +215,7 @@ The following part create the flow attributes, in our case ingress.
:dedent: 1
The third part defines the action to be taken when a packet matches
-the rule. In this case send the packet to queue.
+the rule. In this case, send the packet to queue.
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
@@ -217,10 +223,10 @@ the rule. In this case send the packet to queue.
:end-before: >8 End of setting the rule attribute.
The fourth part is responsible for creating the pattern and is built from
-number of steps. In each step we build one level of the pattern starting with
+number of steps. In each step, we build one level of the pattern starting with
the lowest one.
-Setting the first level of the pattern ETH:
+Set the first level of the pattern ETH:
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
@@ -228,7 +234,7 @@ Setting the first level of the pattern ETH:
:end-before: >8 End of setting the first level of the pattern.
:dedent: 1
-Setting the second level of the pattern IP:
+Set the second level of the pattern IP:
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
@@ -236,7 +242,7 @@ Setting the second level of the pattern IP:
:end-before: >8 End of setting the second level of the pattern.
:dedent: 1
-Closing the pattern part.
+Close the pattern part:
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
diff --git a/doc/guides/sample_app_ug/hello_world.rst b/doc/guides/sample_app_ug/hello_world.rst
index c4db52c6a1..f4f83efac4 100644
--- a/doc/guides/sample_app_ug/hello_world.rst
+++ b/doc/guides/sample_app_ug/hello_world.rst
@@ -4,6 +4,10 @@
Hello World Sample Application
==============================
+
+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.
@@ -29,7 +33,7 @@ and the Environment Abstraction Layer (EAL) options.
Explanation
-----------
-The following sections provide some explanation of code.
+The following sections provide an explanation of the code required to start and use the application.
EAL Initialization
~~~~~~~~~~~~~~~~~~
diff --git a/doc/guides/sample_app_ug/intro.rst b/doc/guides/sample_app_ug/intro.rst
index e765f1fd6b..41378118bc 100644
--- a/doc/guides/sample_app_ug/intro.rst
+++ b/doc/guides/sample_app_ug/intro.rst
@@ -4,9 +4,9 @@
Introduction to the DPDK Sample Applications
============================================
-The DPDK Sample Applications are small standalone applications which
+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
+DPDK features. Users interested in getting started with DPDK can take the
applications, try out the features, and then extend them to fit their needs.
@@ -14,7 +14,7 @@ Running Sample Applications
---------------------------
Some sample applications may have their own command-line parameters described in
-their respective guides, however all of them also share the same EAL parameters.
+their respective guides. However, they all also share the same EAL parameters.
Please refer to :doc:`EAL parameters (Linux) <../linux_gsg/linux_eal_parameters>`
or :doc:`EAL parameters (FreeBSD) <../freebsd_gsg/freebsd_eal_parameters>` for
a list of available EAL command-line options.
@@ -24,16 +24,16 @@ The DPDK Sample Applications
----------------------------
There are many sample applications available in the examples directory of DPDK.
-These examples range from simple to reasonably complex but most are designed
+These examples range from simple to reasonably complex, but most are designed
to demonstrate one particular feature of DPDK. Some of the more interesting
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 with 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
+ enabled cores. This application doesn't do any packet forwarding, but it is a
good way to test if the DPDK environment is compiled and set up properly.
* :doc:`Basic Forwarding/Skeleton Application<skeleton>`: The Basic
@@ -72,19 +72,19 @@ examples are highlighted below.
* :doc:`RX/TX callbacks Application<rxtx_callbacks>`: The RX/TX
callbacks sample application is a packet forwarding application that
- demonstrates the use of user defined callbacks on received and transmitted
+ demonstrates the use of user-defined callbacks on received and transmitted
packets. The application calculates the latency of a packet between RX
(packet arrival) and TX (packet transmission) by adding callbacks to the RX
and TX packet processing functions.
* :doc:`IPsec Security Gateway<ipsec_secgw>`: The IPsec Security
- Gateway application is minimal example of something closer to a real world
+ Gateway application is a minimal example of something close to a real world
example. 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.
- In this case the application is a PTP client that communicates with a PTP
+ In this case, the application is a PTP client that communicates with a PTP
master clock to synchronize time on a Network Interface Card (NIC) using the
IEEE1588 protocol.
@@ -93,4 +93,4 @@ examples are highlighted below.
There are many more examples shown in the following chapters. Each of the
documented sample applications show how to compile, configure and run the
-application as well as explaining the main functionality of the code.
+application, as well as explaining the main functionality of the code.
diff --git a/doc/guides/sample_app_ug/ip_frag.rst b/doc/guides/sample_app_ug/ip_frag.rst
index 5fdeb2a84e..39e3f6b1dd 100644
--- a/doc/guides/sample_app_ug/ip_frag.rst
+++ b/doc/guides/sample_app_ug/ip_frag.rst
@@ -25,17 +25,18 @@ There are three key differences from the L2 Forwarding sample application:
* The third difference is that the application differentiates 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 IP address.
+The Longest Prefix Match (LPM for IPv4, LPM6 for IPv6) table is used to store/lookup an
+outgoing port number associated with that IP address.
Any unmatched packets are forwarded to the originating port.
By default, input frame sizes up to 9.5 KB are supported.
-Before forwarding, the input IP packet is fragmented to fit into the "standard" Ethernet* v2 MTU (1500 bytes).
+Before forwarding, the input IP packet is fragmented to fit into the "standard" Ethernet*
+v2 MTU (1500 bytes).
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 ``ip_fragmentation`` sub-directory.
@@ -46,7 +47,7 @@ The LPM object is created and loaded with the pre-configured entries read from
global l3fwd_ipv4_route_array and l3fwd_ipv6_route_array tables.
For each input packet, the packet forwarding decision
(that is, the identification of the output interface for the packet) is taken as a result of LPM lookup.
-If the IP packet size is greater than default output MTU,
+If the IP packet size is greater than the default output MTU,
then the input packet is fragmented and several fragments are sent via the output interface.
Application usage:
diff --git a/doc/guides/sample_app_ug/ip_reassembly.rst b/doc/guides/sample_app_ug/ip_reassembly.rst
index 5280bf4ea0..a15d6751fb 100644
--- a/doc/guides/sample_app_ug/ip_reassembly.rst
+++ b/doc/guides/sample_app_ug/ip_reassembly.rst
@@ -30,7 +30,7 @@ associated with that IPv4 address. Any unmatched packets are forwarded to the or
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 ``ip_reassembly`` sub-directory.
@@ -57,7 +57,7 @@ where:
then they are considered as invalid and will be dropped.
Valid range is 1ms - 3600s. Default value: 1s.
-To run the example in linux environment with 2 lcores (2,4) over 2 ports(0,2) with 1 RX queue per lcore:
+To run the example in a linux environment with 2 lcores (2,4) over 2 ports(0,2) with 1 RX queue per lcore:
.. code-block:: console
@@ -88,7 +88,7 @@ To run the example in linux environment with 2 lcores (2,4) over 2 ports(0,2) wi
IP_RSMBL: entering main loop on lcore 2
IP_RSMBL: -- lcoreid=2 portid=0
-To run the example in linux environment with 1 lcore (4) over 2 ports(0,2) with 2 RX queues per lcore:
+To run the example in a linux environment with 1 lcore (4) over 2 ports(0,2) with 2 RX queues per lcore:
.. code-block:: console
@@ -100,7 +100,7 @@ l3fwd_ipv4_route_array and/or l3fwd_ipv6_route_array table.
Please note that in order to test this application,
the traffic generator should be generating valid fragmented IP packets.
For IPv6, the only supported case is when no other extension headers other than
-fragment extension header are present in the packet.
+the fragment extension header are present in the packet.
The default l3fwd_ipv4_route_array table is:
@@ -123,19 +123,21 @@ once all the fragments are collected.
Explanation
-----------
-The following sections provide some 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 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.
IPv4 Fragment Table Initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This application uses the rte_ip_frag library. Please refer to Programmer's Guide for more detailed explanation of how to use this library.
-Fragment table maintains information about already received fragments of the packet.
+This application uses the rte_ip_frag library. Please refer to Programmer's Guide for more
+detailed explanation of how to use this library.
+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,
-e.g. the application can't handle the situation when different fragments of the same packet arrive through different RX queues.
-Each table entry can hold information about packet consisting of up to RTE_LIBRTE_IP_FRAG_MAX_FRAGS fragments.
+To avoid lock contention, each RX queue has its own Fragment Table. The application
+cannot handle when different fragments of the same packet arrive through different Rx queues.
+Each table entry can hold information about packets consisting of up to RTE_LIBRTE_IP_FRAG_MAX_FRAGS fragments.
.. literalinclude:: ../../../examples/ip_reassembly/main.c
:language: c
@@ -147,10 +149,10 @@ 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_FRAGS \* <maximum number of mbufs per packet>)
-can be stored inside Fragment Table waiting for remaining fragments.
-To keep mempool size under reasonable limits and to avoid situation when one RX queue can starve other queues,
-each RX queue uses its own mempool.
+At any given time, up to (2 \* max_flow_num \* RTE_LIBRTE_IP_FRAG_MAX_FRAGS \* <maximum number of mbufs per packet>)
+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.
.. literalinclude:: ../../../examples/ip_reassembly/main.c
:language: c
@@ -164,9 +166,9 @@ 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 valid mbuf that contains reassembled packet,
+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).
-Then l3fwd_simple_forward() continues with the code for the packet forwarding decision
+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.
@@ -204,5 +206,5 @@ This macro is disabled by default, but it can be enabled by modifying the approp
in ``config/rte_config.h``.
To make ip_reassembly print the statistics to the standard output,
the user must send either an USR1, INT or TERM signal to the process.
-For all of these signals, the ip_reassembly process prints Fragment table statistics for each RX queue,
+For all of these signals, the ip_reassembly process prints Fragment table statistics for each Rx queue,
plus the INT and TERM will cause process termination as usual.
diff --git a/doc/guides/sample_app_ug/ipv4_multicast.rst b/doc/guides/sample_app_ug/ipv4_multicast.rst
index b8d0b1429a..23843a1a4f 100644
--- a/doc/guides/sample_app_ug/ipv4_multicast.rst
+++ b/doc/guides/sample_app_ug/ipv4_multicast.rst
@@ -21,7 +21,7 @@ There are two key differences from the L2 Forwarding sample application:
* The forwarding decision is taken based on information read from the input packet's IPv4 header.
The lookup method is the Four-byte Key (FBK) hash-based method.
-The lookup table is composed of pairs of destination IPv4 address (the FBK)
+The lookup table is composed of pairs of destination IPv4 addresses (the FBK)
and a port mask associated with that IPv4 address.
By default, the following IP addresses and their respective port masks are added:
@@ -38,14 +38,15 @@ By default, the following IP addresses and their respective port masks are added
For convenience and simplicity, this sample application does not take IANA-assigned multicast addresses into account,
but instead equates the last four bytes of the multicast group (that is, the last four bytes of the destination IP address)
-with the mask of ports to multicast packets to.
+with the mask of ports to multicast packets.
+
Also, the application does not consider the Ethernet addresses;
it looks only at the IPv4 destination address for any given packet.
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 ``ipv4_multicast`` sub-directory.
@@ -91,7 +92,7 @@ and the Environment Abstraction Layer (EAL) options.
Explanation
-----------
-The following sections provide some explanation of the code.
+The following sections explain the code needed for this sample application.
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 IPv4 Multicast sample application.
@@ -109,8 +110,8 @@ Memory pools for indirect buffers are initialized differently from the memory po
:end-before: >8 End of create mbuf pools.
:dedent: 1
-The reason for this is because indirect buffers are not supposed to hold any packet data and
-therefore can be initialized with lower amount of reserved memory for each buffer.
+The reason for this is that indirect buffers are not supposed to hold any packet data and
+therefore can be initialized with the lower amount of reserved memory for each buffer.
Hash Initialization
~~~~~~~~~~~~~~~~~~~
@@ -143,7 +144,7 @@ if the routing table has any ports assigned to the destination address:
:end-before: >8 End of valid multicast address check.
:dedent: 1
-Then, the number of ports in the destination portmask is calculated with the help of the bitcnt() function:
+Next, the number of ports in the destination portmask is calculated with the help of the bitcnt() function:
.. literalinclude:: ../../../examples/ipv4_multicast/main.c
:language: c
@@ -170,7 +171,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.
-Then, packets are 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 portmask associated with a multicast group:
.. literalinclude:: ../../../examples/ipv4_multicast/main.c
:language: c
@@ -188,36 +189,36 @@ The actual packet transmission is done in the mcast_send_pkt() function:
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 and although both are based on the data zero-copy idea,
-there are some differences in the detail.
+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.
-The first approach creates a clone of the input packet, for example,
+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,
create a new buffer and attach that new buffer to the segment
(refer to rte_pktmbuf_clone() in the rte_mbuf library for more details).
A new buffer is then allocated for the packet header and is prepended to the cloned buffer.
-The second approach does not make a clone, it just increments the reference counter for all input packet segment,
+The second approach does not make a clone. 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 advantage of 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 the 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
-and instead modify input packet's header in place.
+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,
-that is, the "clone" operation is skipped completely.
+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, so for N destination ports,
+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),
-first approach is faster.
+the first approach is faster.
As the number of outgoing ports (and/or input segments) grows, the second approach becomes more preferable.
Depending on the number of segments or the number of ports in the outgoing portmask,
diff --git a/doc/guides/sample_app_ug/keep_alive.rst b/doc/guides/sample_app_ug/keep_alive.rst
index a907ff36a1..79bdc531aa 100644
--- a/doc/guides/sample_app_ug/keep_alive.rst
+++ b/doc/guides/sample_app_ug/keep_alive.rst
@@ -38,7 +38,7 @@ of the L2 forwarding 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 ``l2fwd_keep_alive`` sub-directory.
@@ -78,7 +78,7 @@ options.
Explanation
-----------
-The following sections provide some explanation of the
+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
similar to those of the :doc:`l2_forward_real_virtual`.
@@ -89,10 +89,10 @@ The Keep-Alive/'Liveliness' conceptual scheme:
* DPDK Cores respond to the keep-alive agent.
-* If keep-alive agent detects time-outs, it notifies the
+* If a keep-alive agent detects time-outs, it notifies the
fault management entity through a callback function.
-The following sections provide some explanation of the code aspects
+The following sections provide explanation of the code aspects
that are specific to the Keep Alive sample application.
The keepalive functionality is initialized with a struct
@@ -114,7 +114,7 @@ is configured to run every check_period milliseconds.
:end-before: >8 End of issuing the pings keepalive_dispatch_pings().
:dedent: 2
-The rest of the initialization and run-time path follows
+The rest of the initialization and run-time paths follow
the same paths as the L2 forwarding application. The only
addition to the main processing loop is the mark alive
functionality and the example random failures.
diff --git a/doc/guides/sample_app_ug/l2_forward_crypto.rst b/doc/guides/sample_app_ug/l2_forward_crypto.rst
index ce49eab96f..c9226ce578 100644
--- a/doc/guides/sample_app_ug/l2_forward_crypto.rst
+++ b/doc/guides/sample_app_ug/l2_forward_crypto.rst
@@ -6,20 +6,21 @@
L2 Forwarding with Crypto Sample Application
============================================
-The L2 Forwarding with Crypto (l2fwd-crypto) sample application is a simple example of packet processing using
-the Data Plane Development Kit (DPDK), in conjunction with the Cryptodev library.
+The L2 Forwarding with Crypto (l2fwd-crypto) sample application is a simple example
+of packet processing using the Data Plane Development Kit (DPDK) in conjunction with
+the Cryptodev library.
Overview
--------
The L2 Forwarding with Crypto sample application performs a crypto operation (cipher/hash)
-specified by the user from command line (or using the default values),
+specified by the user from the command line (or using the default values),
with a crypto device capable of doing that operation,
for each packet that is received on an RX_PORT and performs L2 forwarding.
-The destination port is the adjacent port from the enabled portmask, that is,
-if the first four ports are enabled (portmask 0xf),
+The destination port is the adjacent port from the enabled portmask.
+If the first four ports are enabled (portmask 0xf),
ports 0 and 1 forward into each other, and ports 2 and 3 forward into each other.
-Also, if MAC addresses updating is enabled, the MAC addresses are affected as follows:
+If the MAC addresses updating is enabled, the MAC addresses are affected as follows:
* The source MAC address is replaced by the TX_PORT MAC address
@@ -28,7 +29,7 @@ Also, if MAC addresses updating is enabled, the MAC addresses are affected as fo
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 ``l2fwd-crypt`` sub-directory.
@@ -161,7 +162,7 @@ the specified crypto operation are available on application initialization.
This means that HW crypto device/s must be bound to a DPDK driver or
a SW crypto device/s (virtual crypto PMD) must be created (using --vdev).
-To run the application in linux environment with 2 lcores, 2 ports and 2 crypto devices, issue the command:
+To run the application in Linux environment with 2 lcores, 2 ports and 2 crypto devices, issue the command:
.. code-block:: console
@@ -199,12 +200,12 @@ from reception until transmission.
Encryption flow through the L2 Forwarding with Crypto Application
-The following sections provide some explanation of the application.
+The following sections provide explanation of the application.
Crypto operation specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-All the packets received in all the ports get transformed by the crypto device/s
+All the packets received in all the ports get transformed by the crypto devices
(ciphering and/or authentication).
The crypto operation to be performed on the packet is parsed from the command line.
(Go to "Running the Application" section for all the options.)
@@ -228,16 +229,16 @@ There are two methods to pass keys, IV and ADD from the command line:
--cipher_key_random_size 16
**Note**:
- If full key is passed (first method) and the size is passed as well (second method),
+ If the full key is passed (first method) and the size is passed as well (second method),
the latter will be ignored.
-Size of these keys are checked (regardless the method), before starting the app,
+The size of these keys are checked (regardless of the method) before starting the app,
to make sure that it is supported by the crypto devices.
Crypto device initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Once the encryption operation is defined, crypto devices are initialized.
+Once the encryption operation is defined, the crypto devices are initialized.
The crypto devices must be either bound to a DPDK driver (if they are physical devices)
or created using the EAL option --vdev (if they are virtual devices),
when running the application.
@@ -278,7 +279,7 @@ Session creation
~~~~~~~~~~~~~~~~
The crypto operation has a crypto session associated to it, which contains
-information such as the transform chain to perform (e.g. ciphering then hashing),
+information such as the transform chain to perform (e.g. ciphering then hashing)
pointers to the keys, lengths... etc.
This session is created and is later attached to the crypto operation:
diff --git a/doc/guides/sample_app_ug/l2_forward_job_stats.rst b/doc/guides/sample_app_ug/l2_forward_job_stats.rst
index 349ad56ec6..f90da8ee6c 100644
--- a/doc/guides/sample_app_ug/l2_forward_job_stats.rst
+++ b/doc/guides/sample_app_ug/l2_forward_job_stats.rst
@@ -19,10 +19,11 @@ Overview
The L2 Forwarding sample application, which can operate in real and virtualized environments,
performs L2 forwarding for each packet that is received.
-The destination port is the adjacent port from the enabled portmask, that is,
-if the first four ports are enabled (portmask 0xf),
+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.
-Also, the MAC addresses are affected as follows:
+
+The MAC addresses are affected as follows:
* The source MAC address is replaced by the TX port MAC address
@@ -51,8 +52,8 @@ Virtual Function Setup Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This application can use the virtual function available in the system and
-therefore can be used in a virtual machine without passing through
-the whole Network Device into a guest machine in a virtualized scenario.
+can be used in a virtual machine without passing through
+the whole Network Device into a guest machine when in a virtualized scenario.
The virtual functions can be enabled in the host machine or the hypervisor with the respective physical function driver.
For example, in a Linux* host machine, it is possible to enable a virtual function using the following command:
@@ -65,15 +66,17 @@ This command enables two Virtual Functions on each of Physical Function of the N
with two physical ports in the PCI configuration space.
It is important to note that enabled Virtual Function 0 and 2 would belong to Physical Function 0
and Virtual Function 1 and 3 would belong to Physical Function 1,
-in this case enabling a total of four Virtual Functions.
+enabling a total of four Virtual Functions (in this case).
+
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 ``l2fwd-jobstats`` sub-directory.
+
Running the Application
-----------------------
@@ -91,8 +94,8 @@ where,
* l: Use locale thousands separator when formatting big numbers.
-To run the application in linux environment with 4 lcores, 16 ports, 8 RX queues per lcore and
-thousands separator printing, issue the command:
+To run the application in a linux environment with 4 lcores, 16 ports, 8 RX queues per lcore and
+thousands separator printing, issue the command:
.. code-block:: console
@@ -101,22 +104,24 @@ thousands separator printing, issue the command:
Refer to the *DPDK Getting Started Guide* for general information on running applications
and the Environment Abstraction Layer (EAL) options.
+
Explanation
-----------
-The following sections provide some explanation of the code.
+The following sections provide explanation of the code.
+
Command Line Arguments
~~~~~~~~~~~~~~~~~~~~~~
-The L2 Forwarding sample application takes specific parameters,
+The L2 Forwarding sample application takes specific parameters
in addition to Environment Abstraction Layer (EAL) arguments
(see `Running the Application`_).
The preferred way to parse parameters is to use the getopt() function,
since it is part of a well-defined and portable library.
The parsing of arguments is done in the l2fwd_parse_args() function.
-The method of argument parsing is not described here.
+This method of argument parsing is not described here.
Refer to the *glibc getopt(3)* man page for details.
EAL arguments are parsed first, then application-specific arguments.
@@ -255,7 +260,7 @@ Main loop
~~~~~~~~~
The forwarding path is reworked comparing to original L2 Forwarding application.
-In the l2fwd_main_loop() function three loops are placed.
+In the l2fwd_main_loop() function, three loops are placed.
.. literalinclude:: ../../../examples/l2fwd-jobstats/main.c
:language: c
@@ -263,15 +268,20 @@ In the l2fwd_main_loop() function three loops are placed.
:end-before: >8 End of minimize impact of stats reading.
:dedent: 1
-First infinite for loop is to minimize impact of stats reading. Lock is only locked/unlocked when asked.
+The first infinite for loop is to minimize impact of stats reading. Lock is only locked/unlocked
+when asked.
+
+Second inner while loop do the whole jobs management. When any job is ready,
+the use rte_timer_manage() is used to call the job handler.
-Second inner while loop do the whole jobs management. When any job is ready, the use rte_timer_manage() is used to call the job handler.
-In this place functions l2fwd_fwd_job() and l2fwd_flush_job() are called when needed.
-Then rte_jobstats_context_finish() is called to mark loop end - no other jobs are ready to execute. By this time stats are ready to be read
+In this place, functions l2fwd_fwd_job() and l2fwd_flush_job() are called when needed.
+Then, rte_jobstats_context_finish() is called to mark loop end - no other jobs are ready to execute.
+By this time, stats are ready to be read
and if stats_read_pending is set, loop breaks allowing stats to be read.
-Third do-while loop is the idle job (idle stats counter). Its only purpose is monitoring if any job is ready or stats job read is pending
-for this lcore. Statistics from this part of code is considered as the headroom available for additional processing.
+Third do-while loop is the idle job (idle stats counter). Its only purpose is monitoring if any job is
+ready or stats job read is pending for this lcore. Statistics from this part of the code is considered as
+the headroom available for additional processing.
Receive, Process and Transmit Packets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -291,7 +301,7 @@ The processing is very simple: process the TX port from the RX port, then replac
The rte_eth_rx_burst() function writes the mbuf pointers in a local table and returns the number of available mbufs in the table.
-After first read second try is issued.
+After first read, a second try is issued.
.. literalinclude:: ../../../examples/l2fwd-jobstats/main.c
:language: c
@@ -299,7 +309,7 @@ After first read second try is issued.
:end-before: >8 End of read second try.
:dedent: 1
-This second read is important to give job stats library a feedback how many packets was processed.
+This second read is important to give the job stats library feedback of how many packets were processed.
.. literalinclude:: ../../../examples/l2fwd-jobstats/main.c
:language: c
@@ -307,8 +317,8 @@ This second read is important to give job stats library a feedback how many pack
:end-before: >8 End of adjust period time in which we are running.
:dedent: 1
-To maximize performance exactly MAX_PKT_BURST is expected (the target value) to be read for each l2fwd_fwd_job() call.
-If total_nb_rx is smaller than target value job->period will be increased. If it is greater the period will be decreased.
+To maximize performance, exactly MAX_PKT_BURST is expected (the target value) to be read for each l2fwd_fwd_job() call.
+If total_nb_rx is smaller than target value job->period will be increased. If it is greater, the period will be decreased.
.. note::
diff --git a/doc/guides/sample_app_ug/rxtx_callbacks.rst b/doc/guides/sample_app_ug/rxtx_callbacks.rst
index f06c5c866a..ddec20cf69 100644
--- a/doc/guides/sample_app_ug/rxtx_callbacks.rst
+++ b/doc/guides/sample_app_ug/rxtx_callbacks.rst
@@ -4,24 +4,29 @@
RX/TX Callbacks Sample Application
==================================
+
+Overview
+--------
+
The RX/TX Callbacks sample application is a packet forwarding application that
demonstrates the use of user defined callbacks on received and transmitted
packets. The application performs a simple latency check, using callbacks, to
-determine the time packets spend within the application.
+determine the time that packets spend within the application.
-In the sample application a user defined callback is applied to all received
+In the sample application, a user defined callback is applied to all received
packets to add a timestamp. A separate callback is applied to all packets
-prior to transmission to calculate the elapsed time, in CPU cycles.
+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 since the packet was timestamped in hardware,
+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.
+
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 ``rxtx_callbacks`` sub-directory.
@@ -66,8 +71,8 @@ The main difference is in the user defined ``port_init()`` function where the
callbacks are added. This is explained in the next section:
-The Port Initialization Function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Port Initialization Function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The main functional part of the port initialization is shown below with
comments:
@@ -122,5 +127,5 @@ packets prior to transmission:
The ``calc_latency()`` function accumulates the total number of packets and
the total number of cycles used. Once more than 100 million packets have been
-transmitted the average cycle count per packet is printed out and the counters
+transmitted, the average cycle count per packet is printed out and the counters
are reset.
diff --git a/doc/guides/sample_app_ug/skeleton.rst b/doc/guides/sample_app_ug/skeleton.rst
index 08ddd7aa59..cb7ff6da4b 100644
--- a/doc/guides/sample_app_ug/skeleton.rst
+++ b/doc/guides/sample_app_ug/skeleton.rst
@@ -7,14 +7,17 @@ Basic Forwarding Sample Application
The Basic Forwarding sample application is a simple *skeleton* example of a
forwarding application.
-It is intended as a demonstration of the basic components of a DPDK forwarding
-application. For more detailed implementations see the L2 and L3 forwarding
+Overview
+--------
+
+This application demonstrates the basic components of a DPDK forwarding
+application. For more detailed implementations, see the L2 and L3 forwarding
sample applications.
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 ``skeleton`` sub-directory.
@@ -28,7 +31,7 @@ To run the example in a ``linux`` environment:
./<build_dir>/examples/dpdk-skeleton -l 1 -n 4
Refer to *DPDK Getting Started Guide* for general information on running
-applications and the Environment Abstraction Layer (EAL) options.
+applications and Environment Abstraction Layer (EAL) options.
Explanation
@@ -47,8 +50,8 @@ The Main Function
The ``main()`` function performs the initialization and calls the execution
threads for each lcore.
-The first task is to initialize the Environment Abstraction Layer (EAL). The
-``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
+The first task is to initialize the Environment Abstraction Layer (EAL).
+The ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
function. The value returned is the number of parsed arguments:
.. literalinclude:: ../../../examples/skeleton/basicfwd.c
@@ -80,7 +83,7 @@ The ``main()`` function also initializes all the ports using the user defined
:dedent: 1
Once the initialization is complete, the application is ready to launch a
-function on an lcore. In this example ``lcore_main()`` is called on a single
+function on an lcore. In this example, ``lcore_main()`` is called on a single
lcore.
@@ -93,9 +96,8 @@ lcore.
The ``lcore_main()`` function is explained below.
-
-The Port Initialization Function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Port Initialization Function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The main functional part of the port initialization used in the Basic
Forwarding application is shown below:
@@ -108,7 +110,7 @@ Forwarding application is shown below:
The Ethernet ports are configured with default settings using the
``rte_eth_dev_configure()`` function.
-For this example the ports are set up with 1 RX and 1 TX queue using the
+In this example, the ports are set up with 1 RX and 1 TX queue using the
``rte_eth_rx_queue_setup()`` and ``rte_eth_tx_queue_setup()`` functions.
The Ethernet port is then started:
@@ -120,7 +122,7 @@ The Ethernet port is then started:
:dedent: 1
-Finally the RX port is set in promiscuous mode:
+Finally, the RX port is set in promiscuous mode:
.. literalinclude:: ../../../examples/skeleton/basicfwd.c
:language: c
@@ -132,8 +134,8 @@ Finally the RX port is set in promiscuous mode:
The Lcores Main
~~~~~~~~~~~~~~~
-As we saw above the ``main()`` function calls an application function on the
-available lcores. For the Basic Forwarding application the lcore function
+As we saw above, the ``main()`` function calls an application function on the
+available lcores. For the Basic Forwarding application, the lcore function
looks like the following:
.. literalinclude:: ../../../examples/skeleton/basicfwd.c
--
2.34.1
^ permalink raw reply [flat|nested] 5+ messages in thread* [PATCH] doc: reword sample app guides
@ 2024-10-06 22:45 Nandini Persad
0 siblings, 0 replies; 5+ messages in thread
From: Nandini Persad @ 2024-10-06 22:45 UTC (permalink / raw)
To: Thomas Monjalon, Ferruh Yigit, Andrew Rybchenko, Chengwen Feng,
Kevin Laatz, Bruce Richardson, Ori Kam, Konstantin Ananyev,
John McNamara
Cc: dev
I have reviewed these sections for grammar/clarity
and made small modifications to the formatting of sections
to adhere to a template which will create uniformality
in the sample application user guides overall.
Signed-off-by: Nandini Persad <nandinipersad361@gmail.com>
---
.../prog_guide/switch_representation.rst | 18 +++---
.../traffic_metering_and_policing.rst | 4 +-
doc/guides/sample_app_ug/cmd_line.rst | 24 ++++----
doc/guides/sample_app_ug/dma.rst | 38 ++++++-------
doc/guides/sample_app_ug/ethtool.rst | 13 +++--
doc/guides/sample_app_ug/flow_filtering.rst | 50 +++++++++--------
doc/guides/sample_app_ug/hello_world.rst | 6 +-
doc/guides/sample_app_ug/intro.rst | 20 +++----
doc/guides/sample_app_ug/ip_frag.rst | 11 ++--
doc/guides/sample_app_ug/ip_reassembly.rst | 38 +++++++------
doc/guides/sample_app_ug/ipv4_multicast.rst | 39 ++++++-------
doc/guides/sample_app_ug/keep_alive.rst | 10 ++--
.../sample_app_ug/l2_forward_crypto.rst | 29 +++++-----
.../sample_app_ug/l2_forward_job_stats.rst | 56 +++++++++++--------
doc/guides/sample_app_ug/rxtx_callbacks.rst | 21 ++++---
doc/guides/sample_app_ug/skeleton.rst | 30 +++++-----
16 files changed, 223 insertions(+), 184 deletions(-)
diff --git a/doc/guides/prog_guide/switch_representation.rst b/doc/guides/prog_guide/switch_representation.rst
index 46e0ca85a5..98c2830b03 100644
--- a/doc/guides/prog_guide/switch_representation.rst
+++ b/doc/guides/prog_guide/switch_representation.rst
@@ -15,8 +15,8 @@ Network adapters with multiple physical ports and/or SR-IOV capabilities
usually support the offload of traffic steering rules between their virtual
functions (VFs), sub functions (SFs), physical functions (PFs) and ports.
-Like for standard Ethernet switches, this involves a combination of
-automatic MAC learning and manual configuration. For most purposes it is
+For standard Ethernet switches, this involves a combination of
+automatic MAC learning and manual configuration. For most purposes, it is
managed by the host system and fully transparent to users and applications.
On the other hand, applications typically found on hypervisors that process
@@ -26,23 +26,23 @@ according on their own criteria.
Without a standard software interface to manage traffic steering rules
between VFs, SFs, PFs and the various physical ports of a given device,
applications cannot take advantage of these offloads; software processing is
-mandatory even for traffic which ends up re-injected into the device it
+mandatory, even for traffic, which ends up re-injected into the device it
originates from.
This document describes how such steering rules can be configured through
the DPDK flow API (**rte_flow**), with emphasis on the SR-IOV use case
-(PF/VF steering) using a single physical port for clarity, however the same
+(PF/VF steering) using a single physical port for clarity. However, the same
logic applies to any number of ports without necessarily involving SR-IOV.
Sub Function
------------
-Besides SR-IOV, Sub function is a portion of the PCI device, a SF netdev
-has its own dedicated queues(txq, rxq). A SF netdev supports E-Switch
+Besides SR-IOV, Sub function is a portion of the PCI device and a SF netdev
+has its own dedicated queues (txq, rxq). A SF netdev supports E-Switch
representation offload similar to existing PF and VF representors.
A SF shares PCI level resources with other SFs and/or with its parent PCI
function.
-Sub function is created on-demand, coexists with VFs. Number of SFs is
+Sub function is created on-demand and coexists with VFs. The number of SFs is
limited by hardware resources.
Port Representors
@@ -80,7 +80,7 @@ thought as a software "patch panel" front-end for applications.
-a pci:dbdf,representor=[pf[0-1],pf2vf[0-2],pf3[3,5]]
- As virtual devices, they may be more limited than their physical
- counterparts, for instance by exposing only a subset of device
+ counterparts. For instance, by exposing only a subset of device
configuration callbacks and/or by not necessarily having Rx/Tx capability.
- Among other things, they can be used to assign MAC addresses to the
@@ -100,7 +100,7 @@ thought as a software "patch panel" front-end for applications.
- The device or group relationship of ports can be discovered using the
switch ``domain_id`` field within the devices switch information structure. By
- default the switch ``domain_id`` of a port will be
+ default, the switch ``domain_id`` of a port will be
``RTE_ETH_DEV_SWITCH_DOMAIN_ID_INVALID`` to indicate that the port doesn't
support the concept of a switch domain, but ports which do support the concept
will be allocated a unique switch ``domain_id``, ports within the same switch
diff --git a/doc/guides/prog_guide/traffic_metering_and_policing.rst b/doc/guides/prog_guide/traffic_metering_and_policing.rst
index 2e8f419f97..d288dc0f9f 100644
--- a/doc/guides/prog_guide/traffic_metering_and_policing.rst
+++ b/doc/guides/prog_guide/traffic_metering_and_policing.rst
@@ -48,7 +48,7 @@ red) based on the previous history for this flow as maintained by the MTR
object. The policer can do nothing, override the color the packet or drop the
packet. Statistics counters are maintained for MTR object, as configured.
-The processing done for each input packet hitting an MTR object is:
+The processing for each input packet hitting an MTR object is:
* Traffic metering: The packet is assigned a color (the meter output color)
based on the previous traffic history reflected in the current state of the
@@ -118,7 +118,7 @@ Protocol based input color selection
------------------------------------
The API supports selecting the input color based on the packet content.
-Following is the API usage model for the same.
+The following is the API usage model for the same purpose.
#. Probe the protocol based input color selection device capabilities using
the following parameters with ``rte_mtr_capabilities_get()`` API.
diff --git a/doc/guides/sample_app_ug/cmd_line.rst b/doc/guides/sample_app_ug/cmd_line.rst
index 6655b1e5a7..72ce5fc27f 100644
--- a/doc/guides/sample_app_ug/cmd_line.rst
+++ b/doc/guides/sample_app_ug/cmd_line.rst
@@ -13,7 +13,7 @@ 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 a DPDK application in a Linux* application environment.
.. note::
@@ -22,10 +22,13 @@ to debug a DPDK application, in a Linux* application environment.
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.
-The Command Line sample application supports some of the features of the GNU readline library such as, completion,
-cut/paste and some other special bindings that make configuration and debug faster and easier.
+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.
+
+The application shows how the rte_cmdline application can be extended
+to handle a list of objects.
-The application shows how the rte_cmdline application 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.
@@ -48,7 +51,7 @@ The application is located in the ``cmd_line`` sub-directory.
Running the Application
-----------------------
-To run the application in linux environment, issue the following command:
+To run the application in a linux environment, issue the following command:
.. code-block:: console
@@ -60,7 +63,7 @@ and the Environment Abstraction Layer (EAL) options.
Explanation
-----------
-The following sections provide some explanation of the code.
+The following sections provide explanation of the code.
EAL Initialization and cmdline Start
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -73,7 +76,7 @@ This is achieved as follows:
:start-after: Initialization of the Environment Abstraction Layer (EAL). 8<
:end-before: >8 End of initialization of Environment Abstraction Layer (EAL).
-Then, a new command line object is created and started to interact with the user through the console:
+Then, a new command line object is created and starts to interact with the user through the console:
.. literalinclude:: ../../../examples/cmdline/main.c
:language: c
@@ -81,13 +84,14 @@ Then, a new command line object is created and started to interact with the user
:end-before: >8 End of creating a new command line object.
:dedent: 1
-The cmd line_interact() function returns when the user types **Ctrl-d** and in this case,
-the application exits.
+The cmd line_interact() function returns when the user types **Ctrl-d** and,
+in this case, the application exits.
Defining a cmdline Context
~~~~~~~~~~~~~~~~~~~~~~~~~~
-A cmdline context is a list of commands that are listed in a NULL-terminated table, for example:
+A cmdline context is a list of commands that are listed in a NULL-terminated table.
+For example:
.. literalinclude:: ../../../examples/cmdline/commands.c
:language: c
diff --git a/doc/guides/sample_app_ug/dma.rst b/doc/guides/sample_app_ug/dma.rst
index 2765895564..701d09d1b3 100644
--- a/doc/guides/sample_app_ug/dma.rst
+++ b/doc/guides/sample_app_ug/dma.rst
@@ -10,10 +10,10 @@ Overview
--------
This sample is intended as a demonstration of the basic components of a DPDK
-forwarding application and example of how to use the DMAdev API to make a packet
+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:
+Also, while forwarding, the MAC addresses are affected as follows:
* The source MAC address is replaced by the TX port MAC address
@@ -27,7 +27,7 @@ received/send packets and packets dropped or failed to copy.
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 ``dma`` sub-directory.
@@ -38,7 +38,7 @@ Running the Application
In order to run the hardware copy application, the copying device
needs to be bound to user-space IO driver.
-Refer to the "DMAdev library" chapter in the "Programmers guide" for information
+Refer to the "DMAdev library" chapter in the Programmer's guide for information
on using the library.
The application requires a number of command line options:
@@ -70,11 +70,11 @@ where,
* i SI: set the interval, in second, between statistics prints (default is 1)
-The application can be launched in various configurations depending on
+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
-updates MAC address and sends the copy. If one lcore per port is used,
-both operations are done sequentially. For each configuration an additional
+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
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.
@@ -159,7 +159,7 @@ multiple DMA channels per port:
:end-before: >8 End of configuring port to use RSS for multiple RX queues.
:dedent: 1
-For this example the ports are set up with the number of Rx queues provided
+For this example, the ports are set up with the number of Rx queues provided
with -q option and 1 Tx queue using the ``rte_eth_rx_queue_setup()``
and ``rte_eth_tx_queue_setup()`` functions.
@@ -172,7 +172,7 @@ The Ethernet port is then started:
:dedent: 1
-Finally the Rx port is set in promiscuous mode:
+Finally, the Rx port is set in promiscuous mode:
.. literalinclude:: ../../../examples/dma/dmafwd.c
:language: c
@@ -181,7 +181,7 @@ Finally the Rx port is set in promiscuous mode:
:dedent: 1
-After that each port application assigns resources needed.
+After that, each port application assigns resources needed.
.. literalinclude:: ../../../examples/dma/dmafwd.c
:language: c
@@ -224,7 +224,7 @@ using ``rte_dma_start()`` function. Each of the above operations is done in
If initialization is successful, memory for hardware device
statistics is allocated.
-Finally ``main()`` function starts all packet handling lcores and starts
+Finally, the ``main()`` function starts all packet handling lcores and starts
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.
@@ -273,13 +273,13 @@ packet using ``pktmbuf_sw_copy()`` function and enqueue them to an 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
+function. When using hardware copy mode the packets are enqueued in the
copying device's 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()``.
+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
-start of the data buffer (``buf_iova``). Thus the ``rte_pktmbuf_iova()`` API is
+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.
.. literalinclude:: ../../../examples/dma/dmafwd.c
@@ -291,11 +291,11 @@ used to get the address of the start of the data within the mbuf.
Once the copies have been completed (this 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.
+is used to pass the packets to the Tx function.
All completed copies are processed by ``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()``.
+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()``.
.. literalinclude:: ../../../examples/dma/dmafwd.c
@@ -307,7 +307,7 @@ if it was enabled. After that copies are sent in burst mode using ``rte_eth_tx_b
The Packet Copying Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In order to perform SW packet copy, there are user-defined functions to first copy
+In order to perform SW packet copy, there are user-defined functions to the first copy
the packet metadata (``pktmbuf_metadata_copy()``) and then the packet data
(``pktmbuf_sw_copy()``):
@@ -321,5 +321,5 @@ 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
-above please refer to the "Mbuf Library" section of the
+above, please refer to the "Mbuf Library" section of the
*DPDK Programmer's Guide*.
diff --git a/doc/guides/sample_app_ug/ethtool.rst b/doc/guides/sample_app_ug/ethtool.rst
index 159e9e0639..433175368b 100644
--- a/doc/guides/sample_app_ug/ethtool.rst
+++ b/doc/guides/sample_app_ug/ethtool.rst
@@ -4,6 +4,12 @@
Ethtool Sample Application
==========================
+This chapter describes the Ethrool sample application that
+is part of the Data Plane Development Kit (DPDK).
+
+Overview
+--------
+
The Ethtool sample application shows an implementation of an
ethtool-like API and provides a console environment that allows
its use to query and change Ethernet card parameters. The sample
@@ -30,17 +36,14 @@ Refer to the *DPDK Getting Started Guide* for general information on
running applications and the Environment Abstraction Layer (EAL)
options.
-Using the application
----------------------
-
The application is console-driven using the cmdline DPDK interface:
.. code-block:: console
EthApp>
-From this interface the available commands and descriptions of what
-they do as follows:
+From this interface, the available commands and descriptions of what
+they do are as follows:
* ``drvinfo``: Print driver info
* ``eeprom``: Dump EEPROM to file
diff --git a/doc/guides/sample_app_ug/flow_filtering.rst b/doc/guides/sample_app_ug/flow_filtering.rst
index 8cac2f8a8f..2cf7973852 100644
--- a/doc/guides/sample_app_ug/flow_filtering.rst
+++ b/doc/guides/sample_app_ug/flow_filtering.rst
@@ -4,16 +4,20 @@
Basic RTE Flow Filtering Sample Application
===========================================
-The Basic RTE flow filtering sample application is a simple example of a
+
+Overview
+--------
+
+The Basic RTE flow filtering sample application is a simple example of
creating a RTE flow rule.
-It is intended as a demonstration of the basic components RTE flow rules.
+It demonstrates the basic components of RTE flow rules.
Compiling the Application
-------------------------
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
Running the Application
@@ -33,7 +37,7 @@ Explanation
-----------
The example is built from 2 files,
-``main.c`` which holds the example logic and ``flow_blocks.c`` that holds the
+``main.c`` which holds the example logic and ``flow_blocks.c`` holds the
implementation for building the flow rule.
The following sections provide an explanation of the main components of the
@@ -49,7 +53,7 @@ The Main Function
The ``main()`` function located in ``main.c`` file performs the initialization
and runs the main loop function.
-The first task is to initialize the Environment Abstraction Layer (EAL). The
+The first task is to initialize the Environment Abstraction Layer (EAL). The
``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
function. The value returned is the number of parsed arguments:
@@ -90,8 +94,8 @@ following code:
:end-before: >8 End of creating flow for send packet with.
:dedent: 1
-In the last part the application is ready to launch the
-``main_loop()`` function. Which is explained below.
+In the last part, the application is ready to launch the
+``main_loop()`` function, which is explained below.
.. literalinclude:: ../../../examples/flow_filtering/main.c
@@ -100,8 +104,9 @@ In the last part the application is ready to launch the
:end-before: >8 End of launching main_loop().
:dedent: 1
-The Port Initialization Function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Port Initialization Function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The main functional part of the port initialization used in the flow filtering
application is shown below:
@@ -120,7 +125,7 @@ The Ethernet port is configured with default settings using the
:end-before: >8 End of ethernet port configured with default settings.
:dedent: 1
-For this example we are configuring number of rx and tx queues that are connected
+For this example, we are configuring a number of Rx and Tx queues that are connected
to a single port.
.. literalinclude:: ../../../examples/flow_filtering/main.c
@@ -129,8 +134,8 @@ to a single port.
:end-before: >8 End of Configuring RX and TX queues connected to single port.
:dedent: 1
-In the next step we create and apply the flow rule. which is to send packets
-with destination ip equals to 192.168.1.1 to queue number 1. The detail
+In the next step, we create and apply the flow rule to send packets
+with destination IP equal to 192.168.1.1 to queue number 1. A detailed
explanation of the ``generate_ipv4_flow()`` appears later in this document:
.. literalinclude:: ../../../examples/flow_filtering/main.c
@@ -159,8 +164,8 @@ The last step is to start the port.
The main_loop function
~~~~~~~~~~~~~~~~~~~~~~
-As we saw above the ``main()`` function calls an application function to handle
-the main loop. For the flow filtering application the main_loop function
+As we saw above, the ``main()`` function calls an application function to handle
+the main loop. For the flow filtering application, the main_loop function
looks like the following:
.. literalinclude:: ../../../examples/flow_filtering/main.c
@@ -169,7 +174,7 @@ looks like the following:
:end-before: >8 End of reading the packets from all queues.
The main work of the application is reading the packets from all
-queues and printing for each packet the destination queue:
+queues and printing each packet from the destination queue:
.. literalinclude:: ../../../examples/flow_filtering/main.c
:language: c
@@ -178,9 +183,10 @@ queues and printing for each packet the destination queue:
The forwarding loop can be interrupted and the application closed using
-``Ctrl-C``. Which results in closing the port and the device using
+``Ctrl-C`` which results in closing the port and the device using
``rte_eth_dev_stop`` and ``rte_eth_dev_close``
+
The generate_ipv4_flow function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -200,7 +206,7 @@ The first part of the function is declaring the structures that will be used.
:end-before: >8 End of declaring structs being used.
:dedent: 1
-The following part create the flow attributes, in our case ingress.
+The following part creates the flow attributes. In this case, ingress.
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
@@ -209,7 +215,7 @@ The following part create the flow attributes, in our case ingress.
:dedent: 1
The third part defines the action to be taken when a packet matches
-the rule. In this case send the packet to queue.
+the rule. In this case, send the packet to queue.
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
@@ -217,10 +223,10 @@ the rule. In this case send the packet to queue.
:end-before: >8 End of setting the rule attribute.
The fourth part is responsible for creating the pattern and is built from
-number of steps. In each step we build one level of the pattern starting with
+number of steps. In each step, we build one level of the pattern starting with
the lowest one.
-Setting the first level of the pattern ETH:
+Set the first level of the pattern ETH:
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
@@ -228,7 +234,7 @@ Setting the first level of the pattern ETH:
:end-before: >8 End of setting the first level of the pattern.
:dedent: 1
-Setting the second level of the pattern IP:
+Set the second level of the pattern IP:
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
@@ -236,7 +242,7 @@ Setting the second level of the pattern IP:
:end-before: >8 End of setting the second level of the pattern.
:dedent: 1
-Closing the pattern part.
+Close the pattern part:
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
diff --git a/doc/guides/sample_app_ug/hello_world.rst b/doc/guides/sample_app_ug/hello_world.rst
index c4db52c6a1..f4f83efac4 100644
--- a/doc/guides/sample_app_ug/hello_world.rst
+++ b/doc/guides/sample_app_ug/hello_world.rst
@@ -4,6 +4,10 @@
Hello World Sample Application
==============================
+
+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.
@@ -29,7 +33,7 @@ and the Environment Abstraction Layer (EAL) options.
Explanation
-----------
-The following sections provide some explanation of code.
+The following sections provide an explanation of the code required to start and use the application.
EAL Initialization
~~~~~~~~~~~~~~~~~~
diff --git a/doc/guides/sample_app_ug/intro.rst b/doc/guides/sample_app_ug/intro.rst
index e765f1fd6b..41378118bc 100644
--- a/doc/guides/sample_app_ug/intro.rst
+++ b/doc/guides/sample_app_ug/intro.rst
@@ -4,9 +4,9 @@
Introduction to the DPDK Sample Applications
============================================
-The DPDK Sample Applications are small standalone applications which
+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
+DPDK features. Users interested in getting started with DPDK can take the
applications, try out the features, and then extend them to fit their needs.
@@ -14,7 +14,7 @@ Running Sample Applications
---------------------------
Some sample applications may have their own command-line parameters described in
-their respective guides, however all of them also share the same EAL parameters.
+their respective guides. However, they all also share the same EAL parameters.
Please refer to :doc:`EAL parameters (Linux) <../linux_gsg/linux_eal_parameters>`
or :doc:`EAL parameters (FreeBSD) <../freebsd_gsg/freebsd_eal_parameters>` for
a list of available EAL command-line options.
@@ -24,16 +24,16 @@ The DPDK Sample Applications
----------------------------
There are many sample applications available in the examples directory of DPDK.
-These examples range from simple to reasonably complex but most are designed
+These examples range from simple to reasonably complex, but most are designed
to demonstrate one particular feature of DPDK. Some of the more interesting
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 with 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
+ enabled cores. This application doesn't do any packet forwarding, but it is a
good way to test if the DPDK environment is compiled and set up properly.
* :doc:`Basic Forwarding/Skeleton Application<skeleton>`: The Basic
@@ -72,19 +72,19 @@ examples are highlighted below.
* :doc:`RX/TX callbacks Application<rxtx_callbacks>`: The RX/TX
callbacks sample application is a packet forwarding application that
- demonstrates the use of user defined callbacks on received and transmitted
+ demonstrates the use of user-defined callbacks on received and transmitted
packets. The application calculates the latency of a packet between RX
(packet arrival) and TX (packet transmission) by adding callbacks to the RX
and TX packet processing functions.
* :doc:`IPsec Security Gateway<ipsec_secgw>`: The IPsec Security
- Gateway application is minimal example of something closer to a real world
+ Gateway application is a minimal example of something close to a real world
example. 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.
- In this case the application is a PTP client that communicates with a PTP
+ In this case, the application is a PTP client that communicates with a PTP
master clock to synchronize time on a Network Interface Card (NIC) using the
IEEE1588 protocol.
@@ -93,4 +93,4 @@ examples are highlighted below.
There are many more examples shown in the following chapters. Each of the
documented sample applications show how to compile, configure and run the
-application as well as explaining the main functionality of the code.
+application, as well as explaining the main functionality of the code.
diff --git a/doc/guides/sample_app_ug/ip_frag.rst b/doc/guides/sample_app_ug/ip_frag.rst
index 5fdeb2a84e..39e3f6b1dd 100644
--- a/doc/guides/sample_app_ug/ip_frag.rst
+++ b/doc/guides/sample_app_ug/ip_frag.rst
@@ -25,17 +25,18 @@ There are three key differences from the L2 Forwarding sample application:
* The third difference is that the application differentiates 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 IP address.
+The Longest Prefix Match (LPM for IPv4, LPM6 for IPv6) table is used to store/lookup an
+outgoing port number associated with that IP address.
Any unmatched packets are forwarded to the originating port.
By default, input frame sizes up to 9.5 KB are supported.
-Before forwarding, the input IP packet is fragmented to fit into the "standard" Ethernet* v2 MTU (1500 bytes).
+Before forwarding, the input IP packet is fragmented to fit into the "standard" Ethernet*
+v2 MTU (1500 bytes).
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 ``ip_fragmentation`` sub-directory.
@@ -46,7 +47,7 @@ The LPM object is created and loaded with the pre-configured entries read from
global l3fwd_ipv4_route_array and l3fwd_ipv6_route_array tables.
For each input packet, the packet forwarding decision
(that is, the identification of the output interface for the packet) is taken as a result of LPM lookup.
-If the IP packet size is greater than default output MTU,
+If the IP packet size is greater than the default output MTU,
then the input packet is fragmented and several fragments are sent via the output interface.
Application usage:
diff --git a/doc/guides/sample_app_ug/ip_reassembly.rst b/doc/guides/sample_app_ug/ip_reassembly.rst
index 5280bf4ea0..a15d6751fb 100644
--- a/doc/guides/sample_app_ug/ip_reassembly.rst
+++ b/doc/guides/sample_app_ug/ip_reassembly.rst
@@ -30,7 +30,7 @@ associated with that IPv4 address. Any unmatched packets are forwarded to the or
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 ``ip_reassembly`` sub-directory.
@@ -57,7 +57,7 @@ where:
then they are considered as invalid and will be dropped.
Valid range is 1ms - 3600s. Default value: 1s.
-To run the example in linux environment with 2 lcores (2,4) over 2 ports(0,2) with 1 RX queue per lcore:
+To run the example in a linux environment with 2 lcores (2,4) over 2 ports(0,2) with 1 RX queue per lcore:
.. code-block:: console
@@ -88,7 +88,7 @@ To run the example in linux environment with 2 lcores (2,4) over 2 ports(0,2) wi
IP_RSMBL: entering main loop on lcore 2
IP_RSMBL: -- lcoreid=2 portid=0
-To run the example in linux environment with 1 lcore (4) over 2 ports(0,2) with 2 RX queues per lcore:
+To run the example in a linux environment with 1 lcore (4) over 2 ports(0,2) with 2 RX queues per lcore:
.. code-block:: console
@@ -100,7 +100,7 @@ l3fwd_ipv4_route_array and/or l3fwd_ipv6_route_array table.
Please note that in order to test this application,
the traffic generator should be generating valid fragmented IP packets.
For IPv6, the only supported case is when no other extension headers other than
-fragment extension header are present in the packet.
+the fragment extension header are present in the packet.
The default l3fwd_ipv4_route_array table is:
@@ -123,19 +123,21 @@ once all the fragments are collected.
Explanation
-----------
-The following sections provide some 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 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.
IPv4 Fragment Table Initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This application uses the rte_ip_frag library. Please refer to Programmer's Guide for more detailed explanation of how to use this library.
-Fragment table maintains information about already received fragments of the packet.
+This application uses the rte_ip_frag library. Please refer to Programmer's Guide for more
+detailed explanation of how to use this library.
+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,
-e.g. the application can't handle the situation when different fragments of the same packet arrive through different RX queues.
-Each table entry can hold information about packet consisting of up to RTE_LIBRTE_IP_FRAG_MAX_FRAGS fragments.
+To avoid lock contention, each RX queue has its own Fragment Table. The application
+cannot handle when different fragments of the same packet arrive through different Rx queues.
+Each table entry can hold information about packets consisting of up to RTE_LIBRTE_IP_FRAG_MAX_FRAGS fragments.
.. literalinclude:: ../../../examples/ip_reassembly/main.c
:language: c
@@ -147,10 +149,10 @@ 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_FRAGS \* <maximum number of mbufs per packet>)
-can be stored inside Fragment Table waiting for remaining fragments.
-To keep mempool size under reasonable limits and to avoid situation when one RX queue can starve other queues,
-each RX queue uses its own mempool.
+At any given time, up to (2 \* max_flow_num \* RTE_LIBRTE_IP_FRAG_MAX_FRAGS \* <maximum number of mbufs per packet>)
+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.
.. literalinclude:: ../../../examples/ip_reassembly/main.c
:language: c
@@ -164,9 +166,9 @@ 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 valid mbuf that contains reassembled packet,
+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).
-Then l3fwd_simple_forward() continues with the code for the packet forwarding decision
+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.
@@ -204,5 +206,5 @@ This macro is disabled by default, but it can be enabled by modifying the approp
in ``config/rte_config.h``.
To make ip_reassembly print the statistics to the standard output,
the user must send either an USR1, INT or TERM signal to the process.
-For all of these signals, the ip_reassembly process prints Fragment table statistics for each RX queue,
+For all of these signals, the ip_reassembly process prints Fragment table statistics for each Rx queue,
plus the INT and TERM will cause process termination as usual.
diff --git a/doc/guides/sample_app_ug/ipv4_multicast.rst b/doc/guides/sample_app_ug/ipv4_multicast.rst
index b8d0b1429a..23843a1a4f 100644
--- a/doc/guides/sample_app_ug/ipv4_multicast.rst
+++ b/doc/guides/sample_app_ug/ipv4_multicast.rst
@@ -21,7 +21,7 @@ There are two key differences from the L2 Forwarding sample application:
* The forwarding decision is taken based on information read from the input packet's IPv4 header.
The lookup method is the Four-byte Key (FBK) hash-based method.
-The lookup table is composed of pairs of destination IPv4 address (the FBK)
+The lookup table is composed of pairs of destination IPv4 addresses (the FBK)
and a port mask associated with that IPv4 address.
By default, the following IP addresses and their respective port masks are added:
@@ -38,14 +38,15 @@ By default, the following IP addresses and their respective port masks are added
For convenience and simplicity, this sample application does not take IANA-assigned multicast addresses into account,
but instead equates the last four bytes of the multicast group (that is, the last four bytes of the destination IP address)
-with the mask of ports to multicast packets to.
+with the mask of ports to multicast packets.
+
Also, the application does not consider the Ethernet addresses;
it looks only at the IPv4 destination address for any given packet.
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 ``ipv4_multicast`` sub-directory.
@@ -91,7 +92,7 @@ and the Environment Abstraction Layer (EAL) options.
Explanation
-----------
-The following sections provide some explanation of the code.
+The following sections explain the code needed for this sample application.
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 IPv4 Multicast sample application.
@@ -109,8 +110,8 @@ Memory pools for indirect buffers are initialized differently from the memory po
:end-before: >8 End of create mbuf pools.
:dedent: 1
-The reason for this is because indirect buffers are not supposed to hold any packet data and
-therefore can be initialized with lower amount of reserved memory for each buffer.
+The reason for this is that indirect buffers are not supposed to hold any packet data and
+therefore can be initialized with the lower amount of reserved memory for each buffer.
Hash Initialization
~~~~~~~~~~~~~~~~~~~
@@ -143,7 +144,7 @@ if the routing table has any ports assigned to the destination address:
:end-before: >8 End of valid multicast address check.
:dedent: 1
-Then, the number of ports in the destination portmask is calculated with the help of the bitcnt() function:
+Next, the number of ports in the destination portmask is calculated with the help of the bitcnt() function:
.. literalinclude:: ../../../examples/ipv4_multicast/main.c
:language: c
@@ -170,7 +171,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.
-Then, packets are 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 portmask associated with a multicast group:
.. literalinclude:: ../../../examples/ipv4_multicast/main.c
:language: c
@@ -188,36 +189,36 @@ The actual packet transmission is done in the mcast_send_pkt() function:
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 and although both are based on the data zero-copy idea,
-there are some differences in the detail.
+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.
-The first approach creates a clone of the input packet, for example,
+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,
create a new buffer and attach that new buffer to the segment
(refer to rte_pktmbuf_clone() in the rte_mbuf library for more details).
A new buffer is then allocated for the packet header and is prepended to the cloned buffer.
-The second approach does not make a clone, it just increments the reference counter for all input packet segment,
+The second approach does not make a clone. 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 advantage of 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 the 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
-and instead modify input packet's header in place.
+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,
-that is, the "clone" operation is skipped completely.
+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, so for N destination ports,
+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),
-first approach is faster.
+the first approach is faster.
As the number of outgoing ports (and/or input segments) grows, the second approach becomes more preferable.
Depending on the number of segments or the number of ports in the outgoing portmask,
diff --git a/doc/guides/sample_app_ug/keep_alive.rst b/doc/guides/sample_app_ug/keep_alive.rst
index a907ff36a1..79bdc531aa 100644
--- a/doc/guides/sample_app_ug/keep_alive.rst
+++ b/doc/guides/sample_app_ug/keep_alive.rst
@@ -38,7 +38,7 @@ of the L2 forwarding 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 ``l2fwd_keep_alive`` sub-directory.
@@ -78,7 +78,7 @@ options.
Explanation
-----------
-The following sections provide some explanation of the
+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
similar to those of the :doc:`l2_forward_real_virtual`.
@@ -89,10 +89,10 @@ The Keep-Alive/'Liveliness' conceptual scheme:
* DPDK Cores respond to the keep-alive agent.
-* If keep-alive agent detects time-outs, it notifies the
+* If a keep-alive agent detects time-outs, it notifies the
fault management entity through a callback function.
-The following sections provide some explanation of the code aspects
+The following sections provide explanation of the code aspects
that are specific to the Keep Alive sample application.
The keepalive functionality is initialized with a struct
@@ -114,7 +114,7 @@ is configured to run every check_period milliseconds.
:end-before: >8 End of issuing the pings keepalive_dispatch_pings().
:dedent: 2
-The rest of the initialization and run-time path follows
+The rest of the initialization and run-time paths follow
the same paths as the L2 forwarding application. The only
addition to the main processing loop is the mark alive
functionality and the example random failures.
diff --git a/doc/guides/sample_app_ug/l2_forward_crypto.rst b/doc/guides/sample_app_ug/l2_forward_crypto.rst
index ce49eab96f..c9226ce578 100644
--- a/doc/guides/sample_app_ug/l2_forward_crypto.rst
+++ b/doc/guides/sample_app_ug/l2_forward_crypto.rst
@@ -6,20 +6,21 @@
L2 Forwarding with Crypto Sample Application
============================================
-The L2 Forwarding with Crypto (l2fwd-crypto) sample application is a simple example of packet processing using
-the Data Plane Development Kit (DPDK), in conjunction with the Cryptodev library.
+The L2 Forwarding with Crypto (l2fwd-crypto) sample application is a simple example
+of packet processing using the Data Plane Development Kit (DPDK) in conjunction with
+the Cryptodev library.
Overview
--------
The L2 Forwarding with Crypto sample application performs a crypto operation (cipher/hash)
-specified by the user from command line (or using the default values),
+specified by the user from the command line (or using the default values),
with a crypto device capable of doing that operation,
for each packet that is received on an RX_PORT and performs L2 forwarding.
-The destination port is the adjacent port from the enabled portmask, that is,
-if the first four ports are enabled (portmask 0xf),
+The destination port is the adjacent port from the enabled portmask.
+If the first four ports are enabled (portmask 0xf),
ports 0 and 1 forward into each other, and ports 2 and 3 forward into each other.
-Also, if MAC addresses updating is enabled, the MAC addresses are affected as follows:
+If the MAC addresses updating is enabled, the MAC addresses are affected as follows:
* The source MAC address is replaced by the TX_PORT MAC address
@@ -28,7 +29,7 @@ Also, if MAC addresses updating is enabled, the MAC addresses are affected as fo
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 ``l2fwd-crypt`` sub-directory.
@@ -161,7 +162,7 @@ the specified crypto operation are available on application initialization.
This means that HW crypto device/s must be bound to a DPDK driver or
a SW crypto device/s (virtual crypto PMD) must be created (using --vdev).
-To run the application in linux environment with 2 lcores, 2 ports and 2 crypto devices, issue the command:
+To run the application in Linux environment with 2 lcores, 2 ports and 2 crypto devices, issue the command:
.. code-block:: console
@@ -199,12 +200,12 @@ from reception until transmission.
Encryption flow through the L2 Forwarding with Crypto Application
-The following sections provide some explanation of the application.
+The following sections provide explanation of the application.
Crypto operation specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-All the packets received in all the ports get transformed by the crypto device/s
+All the packets received in all the ports get transformed by the crypto devices
(ciphering and/or authentication).
The crypto operation to be performed on the packet is parsed from the command line.
(Go to "Running the Application" section for all the options.)
@@ -228,16 +229,16 @@ There are two methods to pass keys, IV and ADD from the command line:
--cipher_key_random_size 16
**Note**:
- If full key is passed (first method) and the size is passed as well (second method),
+ If the full key is passed (first method) and the size is passed as well (second method),
the latter will be ignored.
-Size of these keys are checked (regardless the method), before starting the app,
+The size of these keys are checked (regardless of the method) before starting the app,
to make sure that it is supported by the crypto devices.
Crypto device initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Once the encryption operation is defined, crypto devices are initialized.
+Once the encryption operation is defined, the crypto devices are initialized.
The crypto devices must be either bound to a DPDK driver (if they are physical devices)
or created using the EAL option --vdev (if they are virtual devices),
when running the application.
@@ -278,7 +279,7 @@ Session creation
~~~~~~~~~~~~~~~~
The crypto operation has a crypto session associated to it, which contains
-information such as the transform chain to perform (e.g. ciphering then hashing),
+information such as the transform chain to perform (e.g. ciphering then hashing)
pointers to the keys, lengths... etc.
This session is created and is later attached to the crypto operation:
diff --git a/doc/guides/sample_app_ug/l2_forward_job_stats.rst b/doc/guides/sample_app_ug/l2_forward_job_stats.rst
index 349ad56ec6..f90da8ee6c 100644
--- a/doc/guides/sample_app_ug/l2_forward_job_stats.rst
+++ b/doc/guides/sample_app_ug/l2_forward_job_stats.rst
@@ -19,10 +19,11 @@ Overview
The L2 Forwarding sample application, which can operate in real and virtualized environments,
performs L2 forwarding for each packet that is received.
-The destination port is the adjacent port from the enabled portmask, that is,
-if the first four ports are enabled (portmask 0xf),
+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.
-Also, the MAC addresses are affected as follows:
+
+The MAC addresses are affected as follows:
* The source MAC address is replaced by the TX port MAC address
@@ -51,8 +52,8 @@ Virtual Function Setup Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This application can use the virtual function available in the system and
-therefore can be used in a virtual machine without passing through
-the whole Network Device into a guest machine in a virtualized scenario.
+can be used in a virtual machine without passing through
+the whole Network Device into a guest machine when in a virtualized scenario.
The virtual functions can be enabled in the host machine or the hypervisor with the respective physical function driver.
For example, in a Linux* host machine, it is possible to enable a virtual function using the following command:
@@ -65,15 +66,17 @@ This command enables two Virtual Functions on each of Physical Function of the N
with two physical ports in the PCI configuration space.
It is important to note that enabled Virtual Function 0 and 2 would belong to Physical Function 0
and Virtual Function 1 and 3 would belong to Physical Function 1,
-in this case enabling a total of four Virtual Functions.
+enabling a total of four Virtual Functions (in this case).
+
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 ``l2fwd-jobstats`` sub-directory.
+
Running the Application
-----------------------
@@ -91,8 +94,8 @@ where,
* l: Use locale thousands separator when formatting big numbers.
-To run the application in linux environment with 4 lcores, 16 ports, 8 RX queues per lcore and
-thousands separator printing, issue the command:
+To run the application in a linux environment with 4 lcores, 16 ports, 8 RX queues per lcore and
+thousands separator printing, issue the command:
.. code-block:: console
@@ -101,22 +104,24 @@ thousands separator printing, issue the command:
Refer to the *DPDK Getting Started Guide* for general information on running applications
and the Environment Abstraction Layer (EAL) options.
+
Explanation
-----------
-The following sections provide some explanation of the code.
+The following sections provide explanation of the code.
+
Command Line Arguments
~~~~~~~~~~~~~~~~~~~~~~
-The L2 Forwarding sample application takes specific parameters,
+The L2 Forwarding sample application takes specific parameters
in addition to Environment Abstraction Layer (EAL) arguments
(see `Running the Application`_).
The preferred way to parse parameters is to use the getopt() function,
since it is part of a well-defined and portable library.
The parsing of arguments is done in the l2fwd_parse_args() function.
-The method of argument parsing is not described here.
+This method of argument parsing is not described here.
Refer to the *glibc getopt(3)* man page for details.
EAL arguments are parsed first, then application-specific arguments.
@@ -255,7 +260,7 @@ Main loop
~~~~~~~~~
The forwarding path is reworked comparing to original L2 Forwarding application.
-In the l2fwd_main_loop() function three loops are placed.
+In the l2fwd_main_loop() function, three loops are placed.
.. literalinclude:: ../../../examples/l2fwd-jobstats/main.c
:language: c
@@ -263,15 +268,20 @@ In the l2fwd_main_loop() function three loops are placed.
:end-before: >8 End of minimize impact of stats reading.
:dedent: 1
-First infinite for loop is to minimize impact of stats reading. Lock is only locked/unlocked when asked.
+The first infinite for loop is to minimize impact of stats reading. Lock is only locked/unlocked
+when asked.
+
+Second inner while loop do the whole jobs management. When any job is ready,
+the use rte_timer_manage() is used to call the job handler.
-Second inner while loop do the whole jobs management. When any job is ready, the use rte_timer_manage() is used to call the job handler.
-In this place functions l2fwd_fwd_job() and l2fwd_flush_job() are called when needed.
-Then rte_jobstats_context_finish() is called to mark loop end - no other jobs are ready to execute. By this time stats are ready to be read
+In this place, functions l2fwd_fwd_job() and l2fwd_flush_job() are called when needed.
+Then, rte_jobstats_context_finish() is called to mark loop end - no other jobs are ready to execute.
+By this time, stats are ready to be read
and if stats_read_pending is set, loop breaks allowing stats to be read.
-Third do-while loop is the idle job (idle stats counter). Its only purpose is monitoring if any job is ready or stats job read is pending
-for this lcore. Statistics from this part of code is considered as the headroom available for additional processing.
+Third do-while loop is the idle job (idle stats counter). Its only purpose is monitoring if any job is
+ready or stats job read is pending for this lcore. Statistics from this part of the code is considered as
+the headroom available for additional processing.
Receive, Process and Transmit Packets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -291,7 +301,7 @@ The processing is very simple: process the TX port from the RX port, then replac
The rte_eth_rx_burst() function writes the mbuf pointers in a local table and returns the number of available mbufs in the table.
-After first read second try is issued.
+After first read, a second try is issued.
.. literalinclude:: ../../../examples/l2fwd-jobstats/main.c
:language: c
@@ -299,7 +309,7 @@ After first read second try is issued.
:end-before: >8 End of read second try.
:dedent: 1
-This second read is important to give job stats library a feedback how many packets was processed.
+This second read is important to give the job stats library feedback of how many packets were processed.
.. literalinclude:: ../../../examples/l2fwd-jobstats/main.c
:language: c
@@ -307,8 +317,8 @@ This second read is important to give job stats library a feedback how many pack
:end-before: >8 End of adjust period time in which we are running.
:dedent: 1
-To maximize performance exactly MAX_PKT_BURST is expected (the target value) to be read for each l2fwd_fwd_job() call.
-If total_nb_rx is smaller than target value job->period will be increased. If it is greater the period will be decreased.
+To maximize performance, exactly MAX_PKT_BURST is expected (the target value) to be read for each l2fwd_fwd_job() call.
+If total_nb_rx is smaller than target value job->period will be increased. If it is greater, the period will be decreased.
.. note::
diff --git a/doc/guides/sample_app_ug/rxtx_callbacks.rst b/doc/guides/sample_app_ug/rxtx_callbacks.rst
index f06c5c866a..ddec20cf69 100644
--- a/doc/guides/sample_app_ug/rxtx_callbacks.rst
+++ b/doc/guides/sample_app_ug/rxtx_callbacks.rst
@@ -4,24 +4,29 @@
RX/TX Callbacks Sample Application
==================================
+
+Overview
+--------
+
The RX/TX Callbacks sample application is a packet forwarding application that
demonstrates the use of user defined callbacks on received and transmitted
packets. The application performs a simple latency check, using callbacks, to
-determine the time packets spend within the application.
+determine the time that packets spend within the application.
-In the sample application a user defined callback is applied to all received
+In the sample application, a user defined callback is applied to all received
packets to add a timestamp. A separate callback is applied to all packets
-prior to transmission to calculate the elapsed time, in CPU cycles.
+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 since the packet was timestamped in hardware,
+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.
+
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 ``rxtx_callbacks`` sub-directory.
@@ -66,8 +71,8 @@ The main difference is in the user defined ``port_init()`` function where the
callbacks are added. This is explained in the next section:
-The Port Initialization Function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Port Initialization Function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The main functional part of the port initialization is shown below with
comments:
@@ -122,5 +127,5 @@ packets prior to transmission:
The ``calc_latency()`` function accumulates the total number of packets and
the total number of cycles used. Once more than 100 million packets have been
-transmitted the average cycle count per packet is printed out and the counters
+transmitted, the average cycle count per packet is printed out and the counters
are reset.
diff --git a/doc/guides/sample_app_ug/skeleton.rst b/doc/guides/sample_app_ug/skeleton.rst
index 08ddd7aa59..cb7ff6da4b 100644
--- a/doc/guides/sample_app_ug/skeleton.rst
+++ b/doc/guides/sample_app_ug/skeleton.rst
@@ -7,14 +7,17 @@ Basic Forwarding Sample Application
The Basic Forwarding sample application is a simple *skeleton* example of a
forwarding application.
-It is intended as a demonstration of the basic components of a DPDK forwarding
-application. For more detailed implementations see the L2 and L3 forwarding
+Overview
+--------
+
+This application demonstrates the basic components of a DPDK forwarding
+application. For more detailed implementations, see the L2 and L3 forwarding
sample applications.
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 ``skeleton`` sub-directory.
@@ -28,7 +31,7 @@ To run the example in a ``linux`` environment:
./<build_dir>/examples/dpdk-skeleton -l 1 -n 4
Refer to *DPDK Getting Started Guide* for general information on running
-applications and the Environment Abstraction Layer (EAL) options.
+applications and Environment Abstraction Layer (EAL) options.
Explanation
@@ -47,8 +50,8 @@ The Main Function
The ``main()`` function performs the initialization and calls the execution
threads for each lcore.
-The first task is to initialize the Environment Abstraction Layer (EAL). The
-``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
+The first task is to initialize the Environment Abstraction Layer (EAL).
+The ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
function. The value returned is the number of parsed arguments:
.. literalinclude:: ../../../examples/skeleton/basicfwd.c
@@ -80,7 +83,7 @@ The ``main()`` function also initializes all the ports using the user defined
:dedent: 1
Once the initialization is complete, the application is ready to launch a
-function on an lcore. In this example ``lcore_main()`` is called on a single
+function on an lcore. In this example, ``lcore_main()`` is called on a single
lcore.
@@ -93,9 +96,8 @@ lcore.
The ``lcore_main()`` function is explained below.
-
-The Port Initialization Function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Port Initialization Function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The main functional part of the port initialization used in the Basic
Forwarding application is shown below:
@@ -108,7 +110,7 @@ Forwarding application is shown below:
The Ethernet ports are configured with default settings using the
``rte_eth_dev_configure()`` function.
-For this example the ports are set up with 1 RX and 1 TX queue using the
+In this example, the ports are set up with 1 RX and 1 TX queue using the
``rte_eth_rx_queue_setup()`` and ``rte_eth_tx_queue_setup()`` functions.
The Ethernet port is then started:
@@ -120,7 +122,7 @@ The Ethernet port is then started:
:dedent: 1
-Finally the RX port is set in promiscuous mode:
+Finally, the RX port is set in promiscuous mode:
.. literalinclude:: ../../../examples/skeleton/basicfwd.c
:language: c
@@ -132,8 +134,8 @@ Finally the RX port is set in promiscuous mode:
The Lcores Main
~~~~~~~~~~~~~~~
-As we saw above the ``main()`` function calls an application function on the
-available lcores. For the Basic Forwarding application the lcore function
+As we saw above, the ``main()`` function calls an application function on the
+available lcores. For the Basic Forwarding application, the lcore function
looks like the following:
.. literalinclude:: ../../../examples/skeleton/basicfwd.c
--
2.34.1
^ permalink raw reply [flat|nested] 5+ messages in thread* [PATCH] doc: reword sample app guides
@ 2024-10-06 19:44 Nandini Persad
0 siblings, 0 replies; 5+ messages in thread
From: Nandini Persad @ 2024-10-06 19:44 UTC (permalink / raw)
To: Thomas Monjalon, Ferruh Yigit, Andrew Rybchenko, Chengwen Feng,
Kevin Laatz, Bruce Richardson, Ori Kam, Konstantin Ananyev,
John McNamara
Cc: dev
I have reviewed these sections for grammar/clarity
and made small modifications to the formatting of sections
to adhere to a template which will create uniformality
in the sample application user guides overall.
Signed-off-by: Nandini Persad <nandinipersad361@gmail.com>
---
.../prog_guide/switch_representation.rst | 18 +++---
.../traffic_metering_and_policing.rst | 4 +-
doc/guides/sample_app_ug/cmd_line.rst | 24 ++++----
doc/guides/sample_app_ug/dma.rst | 38 ++++++-------
doc/guides/sample_app_ug/ethtool.rst | 13 +++--
doc/guides/sample_app_ug/flow_filtering.rst | 50 +++++++++--------
doc/guides/sample_app_ug/hello_world.rst | 6 +-
doc/guides/sample_app_ug/intro.rst | 20 +++----
doc/guides/sample_app_ug/ip_frag.rst | 11 ++--
doc/guides/sample_app_ug/ip_reassembly.rst | 38 +++++++------
doc/guides/sample_app_ug/ipv4_multicast.rst | 39 ++++++-------
doc/guides/sample_app_ug/keep_alive.rst | 10 ++--
.../sample_app_ug/l2_forward_crypto.rst | 29 +++++-----
.../sample_app_ug/l2_forward_job_stats.rst | 56 +++++++++++--------
doc/guides/sample_app_ug/rxtx_callbacks.rst | 21 ++++---
doc/guides/sample_app_ug/skeleton.rst | 30 +++++-----
16 files changed, 223 insertions(+), 184 deletions(-)
diff --git a/doc/guides/prog_guide/switch_representation.rst b/doc/guides/prog_guide/switch_representation.rst
index 46e0ca85a5..98c2830b03 100644
--- a/doc/guides/prog_guide/switch_representation.rst
+++ b/doc/guides/prog_guide/switch_representation.rst
@@ -15,8 +15,8 @@ Network adapters with multiple physical ports and/or SR-IOV capabilities
usually support the offload of traffic steering rules between their virtual
functions (VFs), sub functions (SFs), physical functions (PFs) and ports.
-Like for standard Ethernet switches, this involves a combination of
-automatic MAC learning and manual configuration. For most purposes it is
+For standard Ethernet switches, this involves a combination of
+automatic MAC learning and manual configuration. For most purposes, it is
managed by the host system and fully transparent to users and applications.
On the other hand, applications typically found on hypervisors that process
@@ -26,23 +26,23 @@ according on their own criteria.
Without a standard software interface to manage traffic steering rules
between VFs, SFs, PFs and the various physical ports of a given device,
applications cannot take advantage of these offloads; software processing is
-mandatory even for traffic which ends up re-injected into the device it
+mandatory, even for traffic, which ends up re-injected into the device it
originates from.
This document describes how such steering rules can be configured through
the DPDK flow API (**rte_flow**), with emphasis on the SR-IOV use case
-(PF/VF steering) using a single physical port for clarity, however the same
+(PF/VF steering) using a single physical port for clarity. However, the same
logic applies to any number of ports without necessarily involving SR-IOV.
Sub Function
------------
-Besides SR-IOV, Sub function is a portion of the PCI device, a SF netdev
-has its own dedicated queues(txq, rxq). A SF netdev supports E-Switch
+Besides SR-IOV, Sub function is a portion of the PCI device and a SF netdev
+has its own dedicated queues (txq, rxq). A SF netdev supports E-Switch
representation offload similar to existing PF and VF representors.
A SF shares PCI level resources with other SFs and/or with its parent PCI
function.
-Sub function is created on-demand, coexists with VFs. Number of SFs is
+Sub function is created on-demand and coexists with VFs. The number of SFs is
limited by hardware resources.
Port Representors
@@ -80,7 +80,7 @@ thought as a software "patch panel" front-end for applications.
-a pci:dbdf,representor=[pf[0-1],pf2vf[0-2],pf3[3,5]]
- As virtual devices, they may be more limited than their physical
- counterparts, for instance by exposing only a subset of device
+ counterparts. For instance, by exposing only a subset of device
configuration callbacks and/or by not necessarily having Rx/Tx capability.
- Among other things, they can be used to assign MAC addresses to the
@@ -100,7 +100,7 @@ thought as a software "patch panel" front-end for applications.
- The device or group relationship of ports can be discovered using the
switch ``domain_id`` field within the devices switch information structure. By
- default the switch ``domain_id`` of a port will be
+ default, the switch ``domain_id`` of a port will be
``RTE_ETH_DEV_SWITCH_DOMAIN_ID_INVALID`` to indicate that the port doesn't
support the concept of a switch domain, but ports which do support the concept
will be allocated a unique switch ``domain_id``, ports within the same switch
diff --git a/doc/guides/prog_guide/traffic_metering_and_policing.rst b/doc/guides/prog_guide/traffic_metering_and_policing.rst
index 2e8f419f97..d288dc0f9f 100644
--- a/doc/guides/prog_guide/traffic_metering_and_policing.rst
+++ b/doc/guides/prog_guide/traffic_metering_and_policing.rst
@@ -48,7 +48,7 @@ red) based on the previous history for this flow as maintained by the MTR
object. The policer can do nothing, override the color the packet or drop the
packet. Statistics counters are maintained for MTR object, as configured.
-The processing done for each input packet hitting an MTR object is:
+The processing for each input packet hitting an MTR object is:
* Traffic metering: The packet is assigned a color (the meter output color)
based on the previous traffic history reflected in the current state of the
@@ -118,7 +118,7 @@ Protocol based input color selection
------------------------------------
The API supports selecting the input color based on the packet content.
-Following is the API usage model for the same.
+The following is the API usage model for the same purpose.
#. Probe the protocol based input color selection device capabilities using
the following parameters with ``rte_mtr_capabilities_get()`` API.
diff --git a/doc/guides/sample_app_ug/cmd_line.rst b/doc/guides/sample_app_ug/cmd_line.rst
index 6655b1e5a7..72ce5fc27f 100644
--- a/doc/guides/sample_app_ug/cmd_line.rst
+++ b/doc/guides/sample_app_ug/cmd_line.rst
@@ -13,7 +13,7 @@ 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 a DPDK application in a Linux* application environment.
.. note::
@@ -22,10 +22,13 @@ to debug a DPDK application, in a Linux* application environment.
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.
-The Command Line sample application supports some of the features of the GNU readline library such as, completion,
-cut/paste and some other special bindings that make configuration and debug faster and easier.
+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.
+
+The application shows how the rte_cmdline application can be extended
+to handle a list of objects.
-The application shows how the rte_cmdline application 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.
@@ -48,7 +51,7 @@ The application is located in the ``cmd_line`` sub-directory.
Running the Application
-----------------------
-To run the application in linux environment, issue the following command:
+To run the application in a linux environment, issue the following command:
.. code-block:: console
@@ -60,7 +63,7 @@ and the Environment Abstraction Layer (EAL) options.
Explanation
-----------
-The following sections provide some explanation of the code.
+The following sections provide explanation of the code.
EAL Initialization and cmdline Start
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -73,7 +76,7 @@ This is achieved as follows:
:start-after: Initialization of the Environment Abstraction Layer (EAL). 8<
:end-before: >8 End of initialization of Environment Abstraction Layer (EAL).
-Then, a new command line object is created and started to interact with the user through the console:
+Then, a new command line object is created and starts to interact with the user through the console:
.. literalinclude:: ../../../examples/cmdline/main.c
:language: c
@@ -81,13 +84,14 @@ Then, a new command line object is created and started to interact with the user
:end-before: >8 End of creating a new command line object.
:dedent: 1
-The cmd line_interact() function returns when the user types **Ctrl-d** and in this case,
-the application exits.
+The cmd line_interact() function returns when the user types **Ctrl-d** and,
+in this case, the application exits.
Defining a cmdline Context
~~~~~~~~~~~~~~~~~~~~~~~~~~
-A cmdline context is a list of commands that are listed in a NULL-terminated table, for example:
+A cmdline context is a list of commands that are listed in a NULL-terminated table.
+For example:
.. literalinclude:: ../../../examples/cmdline/commands.c
:language: c
diff --git a/doc/guides/sample_app_ug/dma.rst b/doc/guides/sample_app_ug/dma.rst
index 2765895564..701d09d1b3 100644
--- a/doc/guides/sample_app_ug/dma.rst
+++ b/doc/guides/sample_app_ug/dma.rst
@@ -10,10 +10,10 @@ Overview
--------
This sample is intended as a demonstration of the basic components of a DPDK
-forwarding application and example of how to use the DMAdev API to make a packet
+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:
+Also, while forwarding, the MAC addresses are affected as follows:
* The source MAC address is replaced by the TX port MAC address
@@ -27,7 +27,7 @@ received/send packets and packets dropped or failed to copy.
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 ``dma`` sub-directory.
@@ -38,7 +38,7 @@ Running the Application
In order to run the hardware copy application, the copying device
needs to be bound to user-space IO driver.
-Refer to the "DMAdev library" chapter in the "Programmers guide" for information
+Refer to the "DMAdev library" chapter in the Programmer's guide for information
on using the library.
The application requires a number of command line options:
@@ -70,11 +70,11 @@ where,
* i SI: set the interval, in second, between statistics prints (default is 1)
-The application can be launched in various configurations depending on
+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
-updates MAC address and sends the copy. If one lcore per port is used,
-both operations are done sequentially. For each configuration an additional
+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
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.
@@ -159,7 +159,7 @@ multiple DMA channels per port:
:end-before: >8 End of configuring port to use RSS for multiple RX queues.
:dedent: 1
-For this example the ports are set up with the number of Rx queues provided
+For this example, the ports are set up with the number of Rx queues provided
with -q option and 1 Tx queue using the ``rte_eth_rx_queue_setup()``
and ``rte_eth_tx_queue_setup()`` functions.
@@ -172,7 +172,7 @@ The Ethernet port is then started:
:dedent: 1
-Finally the Rx port is set in promiscuous mode:
+Finally, the Rx port is set in promiscuous mode:
.. literalinclude:: ../../../examples/dma/dmafwd.c
:language: c
@@ -181,7 +181,7 @@ Finally the Rx port is set in promiscuous mode:
:dedent: 1
-After that each port application assigns resources needed.
+After that, each port application assigns resources needed.
.. literalinclude:: ../../../examples/dma/dmafwd.c
:language: c
@@ -224,7 +224,7 @@ using ``rte_dma_start()`` function. Each of the above operations is done in
If initialization is successful, memory for hardware device
statistics is allocated.
-Finally ``main()`` function starts all packet handling lcores and starts
+Finally, the ``main()`` function starts all packet handling lcores and starts
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.
@@ -273,13 +273,13 @@ packet using ``pktmbuf_sw_copy()`` function and enqueue them to an 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
+function. When using hardware copy mode the packets are enqueued in the
copying device's 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()``.
+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
-start of the data buffer (``buf_iova``). Thus the ``rte_pktmbuf_iova()`` API is
+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.
.. literalinclude:: ../../../examples/dma/dmafwd.c
@@ -291,11 +291,11 @@ used to get the address of the start of the data within the mbuf.
Once the copies have been completed (this 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.
+is used to pass the packets to the Tx function.
All completed copies are processed by ``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()``.
+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()``.
.. literalinclude:: ../../../examples/dma/dmafwd.c
@@ -307,7 +307,7 @@ if it was enabled. After that copies are sent in burst mode using ``rte_eth_tx_b
The Packet Copying Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In order to perform SW packet copy, there are user-defined functions to first copy
+In order to perform SW packet copy, there are user-defined functions to the first copy
the packet metadata (``pktmbuf_metadata_copy()``) and then the packet data
(``pktmbuf_sw_copy()``):
@@ -321,5 +321,5 @@ 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
-above please refer to the "Mbuf Library" section of the
+above, please refer to the "Mbuf Library" section of the
*DPDK Programmer's Guide*.
diff --git a/doc/guides/sample_app_ug/ethtool.rst b/doc/guides/sample_app_ug/ethtool.rst
index 159e9e0639..433175368b 100644
--- a/doc/guides/sample_app_ug/ethtool.rst
+++ b/doc/guides/sample_app_ug/ethtool.rst
@@ -4,6 +4,12 @@
Ethtool Sample Application
==========================
+This chapter describes the Ethrool sample application that
+is part of the Data Plane Development Kit (DPDK).
+
+Overview
+--------
+
The Ethtool sample application shows an implementation of an
ethtool-like API and provides a console environment that allows
its use to query and change Ethernet card parameters. The sample
@@ -30,17 +36,14 @@ Refer to the *DPDK Getting Started Guide* for general information on
running applications and the Environment Abstraction Layer (EAL)
options.
-Using the application
----------------------
-
The application is console-driven using the cmdline DPDK interface:
.. code-block:: console
EthApp>
-From this interface the available commands and descriptions of what
-they do as follows:
+From this interface, the available commands and descriptions of what
+they do are as follows:
* ``drvinfo``: Print driver info
* ``eeprom``: Dump EEPROM to file
diff --git a/doc/guides/sample_app_ug/flow_filtering.rst b/doc/guides/sample_app_ug/flow_filtering.rst
index 8cac2f8a8f..2cf7973852 100644
--- a/doc/guides/sample_app_ug/flow_filtering.rst
+++ b/doc/guides/sample_app_ug/flow_filtering.rst
@@ -4,16 +4,20 @@
Basic RTE Flow Filtering Sample Application
===========================================
-The Basic RTE flow filtering sample application is a simple example of a
+
+Overview
+--------
+
+The Basic RTE flow filtering sample application is a simple example of
creating a RTE flow rule.
-It is intended as a demonstration of the basic components RTE flow rules.
+It demonstrates the basic components of RTE flow rules.
Compiling the Application
-------------------------
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
Running the Application
@@ -33,7 +37,7 @@ Explanation
-----------
The example is built from 2 files,
-``main.c`` which holds the example logic and ``flow_blocks.c`` that holds the
+``main.c`` which holds the example logic and ``flow_blocks.c`` holds the
implementation for building the flow rule.
The following sections provide an explanation of the main components of the
@@ -49,7 +53,7 @@ The Main Function
The ``main()`` function located in ``main.c`` file performs the initialization
and runs the main loop function.
-The first task is to initialize the Environment Abstraction Layer (EAL). The
+The first task is to initialize the Environment Abstraction Layer (EAL). The
``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
function. The value returned is the number of parsed arguments:
@@ -90,8 +94,8 @@ following code:
:end-before: >8 End of creating flow for send packet with.
:dedent: 1
-In the last part the application is ready to launch the
-``main_loop()`` function. Which is explained below.
+In the last part, the application is ready to launch the
+``main_loop()`` function, which is explained below.
.. literalinclude:: ../../../examples/flow_filtering/main.c
@@ -100,8 +104,9 @@ In the last part the application is ready to launch the
:end-before: >8 End of launching main_loop().
:dedent: 1
-The Port Initialization Function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Port Initialization Function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The main functional part of the port initialization used in the flow filtering
application is shown below:
@@ -120,7 +125,7 @@ The Ethernet port is configured with default settings using the
:end-before: >8 End of ethernet port configured with default settings.
:dedent: 1
-For this example we are configuring number of rx and tx queues that are connected
+For this example, we are configuring a number of Rx and Tx queues that are connected
to a single port.
.. literalinclude:: ../../../examples/flow_filtering/main.c
@@ -129,8 +134,8 @@ to a single port.
:end-before: >8 End of Configuring RX and TX queues connected to single port.
:dedent: 1
-In the next step we create and apply the flow rule. which is to send packets
-with destination ip equals to 192.168.1.1 to queue number 1. The detail
+In the next step, we create and apply the flow rule to send packets
+with destination IP equal to 192.168.1.1 to queue number 1. A detailed
explanation of the ``generate_ipv4_flow()`` appears later in this document:
.. literalinclude:: ../../../examples/flow_filtering/main.c
@@ -159,8 +164,8 @@ The last step is to start the port.
The main_loop function
~~~~~~~~~~~~~~~~~~~~~~
-As we saw above the ``main()`` function calls an application function to handle
-the main loop. For the flow filtering application the main_loop function
+As we saw above, the ``main()`` function calls an application function to handle
+the main loop. For the flow filtering application, the main_loop function
looks like the following:
.. literalinclude:: ../../../examples/flow_filtering/main.c
@@ -169,7 +174,7 @@ looks like the following:
:end-before: >8 End of reading the packets from all queues.
The main work of the application is reading the packets from all
-queues and printing for each packet the destination queue:
+queues and printing each packet from the destination queue:
.. literalinclude:: ../../../examples/flow_filtering/main.c
:language: c
@@ -178,9 +183,10 @@ queues and printing for each packet the destination queue:
The forwarding loop can be interrupted and the application closed using
-``Ctrl-C``. Which results in closing the port and the device using
+``Ctrl-C`` which results in closing the port and the device using
``rte_eth_dev_stop`` and ``rte_eth_dev_close``
+
The generate_ipv4_flow function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -200,7 +206,7 @@ The first part of the function is declaring the structures that will be used.
:end-before: >8 End of declaring structs being used.
:dedent: 1
-The following part create the flow attributes, in our case ingress.
+The following part creates the flow attributes. In this case, ingress.
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
@@ -209,7 +215,7 @@ The following part create the flow attributes, in our case ingress.
:dedent: 1
The third part defines the action to be taken when a packet matches
-the rule. In this case send the packet to queue.
+the rule. In this case, send the packet to queue.
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
@@ -217,10 +223,10 @@ the rule. In this case send the packet to queue.
:end-before: >8 End of setting the rule attribute.
The fourth part is responsible for creating the pattern and is built from
-number of steps. In each step we build one level of the pattern starting with
+number of steps. In each step, we build one level of the pattern starting with
the lowest one.
-Setting the first level of the pattern ETH:
+Set the first level of the pattern ETH:
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
@@ -228,7 +234,7 @@ Setting the first level of the pattern ETH:
:end-before: >8 End of setting the first level of the pattern.
:dedent: 1
-Setting the second level of the pattern IP:
+Set the second level of the pattern IP:
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
@@ -236,7 +242,7 @@ Setting the second level of the pattern IP:
:end-before: >8 End of setting the second level of the pattern.
:dedent: 1
-Closing the pattern part.
+Close the pattern part:
.. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
:language: c
diff --git a/doc/guides/sample_app_ug/hello_world.rst b/doc/guides/sample_app_ug/hello_world.rst
index c4db52c6a1..f4f83efac4 100644
--- a/doc/guides/sample_app_ug/hello_world.rst
+++ b/doc/guides/sample_app_ug/hello_world.rst
@@ -4,6 +4,10 @@
Hello World Sample Application
==============================
+
+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.
@@ -29,7 +33,7 @@ and the Environment Abstraction Layer (EAL) options.
Explanation
-----------
-The following sections provide some explanation of code.
+The following sections provide an explanation of the code required to start and use the application.
EAL Initialization
~~~~~~~~~~~~~~~~~~
diff --git a/doc/guides/sample_app_ug/intro.rst b/doc/guides/sample_app_ug/intro.rst
index e765f1fd6b..41378118bc 100644
--- a/doc/guides/sample_app_ug/intro.rst
+++ b/doc/guides/sample_app_ug/intro.rst
@@ -4,9 +4,9 @@
Introduction to the DPDK Sample Applications
============================================
-The DPDK Sample Applications are small standalone applications which
+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
+DPDK features. Users interested in getting started with DPDK can take the
applications, try out the features, and then extend them to fit their needs.
@@ -14,7 +14,7 @@ Running Sample Applications
---------------------------
Some sample applications may have their own command-line parameters described in
-their respective guides, however all of them also share the same EAL parameters.
+their respective guides. However, they all also share the same EAL parameters.
Please refer to :doc:`EAL parameters (Linux) <../linux_gsg/linux_eal_parameters>`
or :doc:`EAL parameters (FreeBSD) <../freebsd_gsg/freebsd_eal_parameters>` for
a list of available EAL command-line options.
@@ -24,16 +24,16 @@ The DPDK Sample Applications
----------------------------
There are many sample applications available in the examples directory of DPDK.
-These examples range from simple to reasonably complex but most are designed
+These examples range from simple to reasonably complex, but most are designed
to demonstrate one particular feature of DPDK. Some of the more interesting
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 with 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
+ enabled cores. This application doesn't do any packet forwarding, but it is a
good way to test if the DPDK environment is compiled and set up properly.
* :doc:`Basic Forwarding/Skeleton Application<skeleton>`: The Basic
@@ -72,19 +72,19 @@ examples are highlighted below.
* :doc:`RX/TX callbacks Application<rxtx_callbacks>`: The RX/TX
callbacks sample application is a packet forwarding application that
- demonstrates the use of user defined callbacks on received and transmitted
+ demonstrates the use of user-defined callbacks on received and transmitted
packets. The application calculates the latency of a packet between RX
(packet arrival) and TX (packet transmission) by adding callbacks to the RX
and TX packet processing functions.
* :doc:`IPsec Security Gateway<ipsec_secgw>`: The IPsec Security
- Gateway application is minimal example of something closer to a real world
+ Gateway application is a minimal example of something close to a real world
example. 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.
- In this case the application is a PTP client that communicates with a PTP
+ In this case, the application is a PTP client that communicates with a PTP
master clock to synchronize time on a Network Interface Card (NIC) using the
IEEE1588 protocol.
@@ -93,4 +93,4 @@ examples are highlighted below.
There are many more examples shown in the following chapters. Each of the
documented sample applications show how to compile, configure and run the
-application as well as explaining the main functionality of the code.
+application, as well as explaining the main functionality of the code.
diff --git a/doc/guides/sample_app_ug/ip_frag.rst b/doc/guides/sample_app_ug/ip_frag.rst
index 5fdeb2a84e..39e3f6b1dd 100644
--- a/doc/guides/sample_app_ug/ip_frag.rst
+++ b/doc/guides/sample_app_ug/ip_frag.rst
@@ -25,17 +25,18 @@ There are three key differences from the L2 Forwarding sample application:
* The third difference is that the application differentiates 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 IP address.
+The Longest Prefix Match (LPM for IPv4, LPM6 for IPv6) table is used to store/lookup an
+outgoing port number associated with that IP address.
Any unmatched packets are forwarded to the originating port.
By default, input frame sizes up to 9.5 KB are supported.
-Before forwarding, the input IP packet is fragmented to fit into the "standard" Ethernet* v2 MTU (1500 bytes).
+Before forwarding, the input IP packet is fragmented to fit into the "standard" Ethernet*
+v2 MTU (1500 bytes).
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 ``ip_fragmentation`` sub-directory.
@@ -46,7 +47,7 @@ The LPM object is created and loaded with the pre-configured entries read from
global l3fwd_ipv4_route_array and l3fwd_ipv6_route_array tables.
For each input packet, the packet forwarding decision
(that is, the identification of the output interface for the packet) is taken as a result of LPM lookup.
-If the IP packet size is greater than default output MTU,
+If the IP packet size is greater than the default output MTU,
then the input packet is fragmented and several fragments are sent via the output interface.
Application usage:
diff --git a/doc/guides/sample_app_ug/ip_reassembly.rst b/doc/guides/sample_app_ug/ip_reassembly.rst
index 5280bf4ea0..a15d6751fb 100644
--- a/doc/guides/sample_app_ug/ip_reassembly.rst
+++ b/doc/guides/sample_app_ug/ip_reassembly.rst
@@ -30,7 +30,7 @@ associated with that IPv4 address. Any unmatched packets are forwarded to the or
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 ``ip_reassembly`` sub-directory.
@@ -57,7 +57,7 @@ where:
then they are considered as invalid and will be dropped.
Valid range is 1ms - 3600s. Default value: 1s.
-To run the example in linux environment with 2 lcores (2,4) over 2 ports(0,2) with 1 RX queue per lcore:
+To run the example in a linux environment with 2 lcores (2,4) over 2 ports(0,2) with 1 RX queue per lcore:
.. code-block:: console
@@ -88,7 +88,7 @@ To run the example in linux environment with 2 lcores (2,4) over 2 ports(0,2) wi
IP_RSMBL: entering main loop on lcore 2
IP_RSMBL: -- lcoreid=2 portid=0
-To run the example in linux environment with 1 lcore (4) over 2 ports(0,2) with 2 RX queues per lcore:
+To run the example in a linux environment with 1 lcore (4) over 2 ports(0,2) with 2 RX queues per lcore:
.. code-block:: console
@@ -100,7 +100,7 @@ l3fwd_ipv4_route_array and/or l3fwd_ipv6_route_array table.
Please note that in order to test this application,
the traffic generator should be generating valid fragmented IP packets.
For IPv6, the only supported case is when no other extension headers other than
-fragment extension header are present in the packet.
+the fragment extension header are present in the packet.
The default l3fwd_ipv4_route_array table is:
@@ -123,19 +123,21 @@ once all the fragments are collected.
Explanation
-----------
-The following sections provide some 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 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.
IPv4 Fragment Table Initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This application uses the rte_ip_frag library. Please refer to Programmer's Guide for more detailed explanation of how to use this library.
-Fragment table maintains information about already received fragments of the packet.
+This application uses the rte_ip_frag library. Please refer to Programmer's Guide for more
+detailed explanation of how to use this library.
+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,
-e.g. the application can't handle the situation when different fragments of the same packet arrive through different RX queues.
-Each table entry can hold information about packet consisting of up to RTE_LIBRTE_IP_FRAG_MAX_FRAGS fragments.
+To avoid lock contention, each RX queue has its own Fragment Table. The application
+cannot handle when different fragments of the same packet arrive through different Rx queues.
+Each table entry can hold information about packets consisting of up to RTE_LIBRTE_IP_FRAG_MAX_FRAGS fragments.
.. literalinclude:: ../../../examples/ip_reassembly/main.c
:language: c
@@ -147,10 +149,10 @@ 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_FRAGS \* <maximum number of mbufs per packet>)
-can be stored inside Fragment Table waiting for remaining fragments.
-To keep mempool size under reasonable limits and to avoid situation when one RX queue can starve other queues,
-each RX queue uses its own mempool.
+At any given time, up to (2 \* max_flow_num \* RTE_LIBRTE_IP_FRAG_MAX_FRAGS \* <maximum number of mbufs per packet>)
+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.
.. literalinclude:: ../../../examples/ip_reassembly/main.c
:language: c
@@ -164,9 +166,9 @@ 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 valid mbuf that contains reassembled packet,
+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).
-Then l3fwd_simple_forward() continues with the code for the packet forwarding decision
+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.
@@ -204,5 +206,5 @@ This macro is disabled by default, but it can be enabled by modifying the approp
in ``config/rte_config.h``.
To make ip_reassembly print the statistics to the standard output,
the user must send either an USR1, INT or TERM signal to the process.
-For all of these signals, the ip_reassembly process prints Fragment table statistics for each RX queue,
+For all of these signals, the ip_reassembly process prints Fragment table statistics for each Rx queue,
plus the INT and TERM will cause process termination as usual.
diff --git a/doc/guides/sample_app_ug/ipv4_multicast.rst b/doc/guides/sample_app_ug/ipv4_multicast.rst
index b8d0b1429a..23843a1a4f 100644
--- a/doc/guides/sample_app_ug/ipv4_multicast.rst
+++ b/doc/guides/sample_app_ug/ipv4_multicast.rst
@@ -21,7 +21,7 @@ There are two key differences from the L2 Forwarding sample application:
* The forwarding decision is taken based on information read from the input packet's IPv4 header.
The lookup method is the Four-byte Key (FBK) hash-based method.
-The lookup table is composed of pairs of destination IPv4 address (the FBK)
+The lookup table is composed of pairs of destination IPv4 addresses (the FBK)
and a port mask associated with that IPv4 address.
By default, the following IP addresses and their respective port masks are added:
@@ -38,14 +38,15 @@ By default, the following IP addresses and their respective port masks are added
For convenience and simplicity, this sample application does not take IANA-assigned multicast addresses into account,
but instead equates the last four bytes of the multicast group (that is, the last four bytes of the destination IP address)
-with the mask of ports to multicast packets to.
+with the mask of ports to multicast packets.
+
Also, the application does not consider the Ethernet addresses;
it looks only at the IPv4 destination address for any given packet.
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 ``ipv4_multicast`` sub-directory.
@@ -91,7 +92,7 @@ and the Environment Abstraction Layer (EAL) options.
Explanation
-----------
-The following sections provide some explanation of the code.
+The following sections explain the code needed for this sample application.
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 IPv4 Multicast sample application.
@@ -109,8 +110,8 @@ Memory pools for indirect buffers are initialized differently from the memory po
:end-before: >8 End of create mbuf pools.
:dedent: 1
-The reason for this is because indirect buffers are not supposed to hold any packet data and
-therefore can be initialized with lower amount of reserved memory for each buffer.
+The reason for this is that indirect buffers are not supposed to hold any packet data and
+therefore can be initialized with the lower amount of reserved memory for each buffer.
Hash Initialization
~~~~~~~~~~~~~~~~~~~
@@ -143,7 +144,7 @@ if the routing table has any ports assigned to the destination address:
:end-before: >8 End of valid multicast address check.
:dedent: 1
-Then, the number of ports in the destination portmask is calculated with the help of the bitcnt() function:
+Next, the number of ports in the destination portmask is calculated with the help of the bitcnt() function:
.. literalinclude:: ../../../examples/ipv4_multicast/main.c
:language: c
@@ -170,7 +171,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.
-Then, packets are 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 portmask associated with a multicast group:
.. literalinclude:: ../../../examples/ipv4_multicast/main.c
:language: c
@@ -188,36 +189,36 @@ The actual packet transmission is done in the mcast_send_pkt() function:
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 and although both are based on the data zero-copy idea,
-there are some differences in the detail.
+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.
-The first approach creates a clone of the input packet, for example,
+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,
create a new buffer and attach that new buffer to the segment
(refer to rte_pktmbuf_clone() in the rte_mbuf library for more details).
A new buffer is then allocated for the packet header and is prepended to the cloned buffer.
-The second approach does not make a clone, it just increments the reference counter for all input packet segment,
+The second approach does not make a clone. 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 advantage of 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 the 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
-and instead modify input packet's header in place.
+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,
-that is, the "clone" operation is skipped completely.
+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, so for N destination ports,
+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),
-first approach is faster.
+the first approach is faster.
As the number of outgoing ports (and/or input segments) grows, the second approach becomes more preferable.
Depending on the number of segments or the number of ports in the outgoing portmask,
diff --git a/doc/guides/sample_app_ug/keep_alive.rst b/doc/guides/sample_app_ug/keep_alive.rst
index a907ff36a1..79bdc531aa 100644
--- a/doc/guides/sample_app_ug/keep_alive.rst
+++ b/doc/guides/sample_app_ug/keep_alive.rst
@@ -38,7 +38,7 @@ of the L2 forwarding 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 ``l2fwd_keep_alive`` sub-directory.
@@ -78,7 +78,7 @@ options.
Explanation
-----------
-The following sections provide some explanation of the
+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
similar to those of the :doc:`l2_forward_real_virtual`.
@@ -89,10 +89,10 @@ The Keep-Alive/'Liveliness' conceptual scheme:
* DPDK Cores respond to the keep-alive agent.
-* If keep-alive agent detects time-outs, it notifies the
+* If a keep-alive agent detects time-outs, it notifies the
fault management entity through a callback function.
-The following sections provide some explanation of the code aspects
+The following sections provide explanation of the code aspects
that are specific to the Keep Alive sample application.
The keepalive functionality is initialized with a struct
@@ -114,7 +114,7 @@ is configured to run every check_period milliseconds.
:end-before: >8 End of issuing the pings keepalive_dispatch_pings().
:dedent: 2
-The rest of the initialization and run-time path follows
+The rest of the initialization and run-time paths follow
the same paths as the L2 forwarding application. The only
addition to the main processing loop is the mark alive
functionality and the example random failures.
diff --git a/doc/guides/sample_app_ug/l2_forward_crypto.rst b/doc/guides/sample_app_ug/l2_forward_crypto.rst
index ce49eab96f..c9226ce578 100644
--- a/doc/guides/sample_app_ug/l2_forward_crypto.rst
+++ b/doc/guides/sample_app_ug/l2_forward_crypto.rst
@@ -6,20 +6,21 @@
L2 Forwarding with Crypto Sample Application
============================================
-The L2 Forwarding with Crypto (l2fwd-crypto) sample application is a simple example of packet processing using
-the Data Plane Development Kit (DPDK), in conjunction with the Cryptodev library.
+The L2 Forwarding with Crypto (l2fwd-crypto) sample application is a simple example
+of packet processing using the Data Plane Development Kit (DPDK) in conjunction with
+the Cryptodev library.
Overview
--------
The L2 Forwarding with Crypto sample application performs a crypto operation (cipher/hash)
-specified by the user from command line (or using the default values),
+specified by the user from the command line (or using the default values),
with a crypto device capable of doing that operation,
for each packet that is received on an RX_PORT and performs L2 forwarding.
-The destination port is the adjacent port from the enabled portmask, that is,
-if the first four ports are enabled (portmask 0xf),
+The destination port is the adjacent port from the enabled portmask.
+If the first four ports are enabled (portmask 0xf),
ports 0 and 1 forward into each other, and ports 2 and 3 forward into each other.
-Also, if MAC addresses updating is enabled, the MAC addresses are affected as follows:
+If the MAC addresses updating is enabled, the MAC addresses are affected as follows:
* The source MAC address is replaced by the TX_PORT MAC address
@@ -28,7 +29,7 @@ Also, if MAC addresses updating is enabled, the MAC addresses are affected as fo
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 ``l2fwd-crypt`` sub-directory.
@@ -161,7 +162,7 @@ the specified crypto operation are available on application initialization.
This means that HW crypto device/s must be bound to a DPDK driver or
a SW crypto device/s (virtual crypto PMD) must be created (using --vdev).
-To run the application in linux environment with 2 lcores, 2 ports and 2 crypto devices, issue the command:
+To run the application in Linux environment with 2 lcores, 2 ports and 2 crypto devices, issue the command:
.. code-block:: console
@@ -199,12 +200,12 @@ from reception until transmission.
Encryption flow through the L2 Forwarding with Crypto Application
-The following sections provide some explanation of the application.
+The following sections provide explanation of the application.
Crypto operation specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-All the packets received in all the ports get transformed by the crypto device/s
+All the packets received in all the ports get transformed by the crypto devices
(ciphering and/or authentication).
The crypto operation to be performed on the packet is parsed from the command line.
(Go to "Running the Application" section for all the options.)
@@ -228,16 +229,16 @@ There are two methods to pass keys, IV and ADD from the command line:
--cipher_key_random_size 16
**Note**:
- If full key is passed (first method) and the size is passed as well (second method),
+ If the full key is passed (first method) and the size is passed as well (second method),
the latter will be ignored.
-Size of these keys are checked (regardless the method), before starting the app,
+The size of these keys are checked (regardless of the method) before starting the app,
to make sure that it is supported by the crypto devices.
Crypto device initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Once the encryption operation is defined, crypto devices are initialized.
+Once the encryption operation is defined, the crypto devices are initialized.
The crypto devices must be either bound to a DPDK driver (if they are physical devices)
or created using the EAL option --vdev (if they are virtual devices),
when running the application.
@@ -278,7 +279,7 @@ Session creation
~~~~~~~~~~~~~~~~
The crypto operation has a crypto session associated to it, which contains
-information such as the transform chain to perform (e.g. ciphering then hashing),
+information such as the transform chain to perform (e.g. ciphering then hashing)
pointers to the keys, lengths... etc.
This session is created and is later attached to the crypto operation:
diff --git a/doc/guides/sample_app_ug/l2_forward_job_stats.rst b/doc/guides/sample_app_ug/l2_forward_job_stats.rst
index 349ad56ec6..f90da8ee6c 100644
--- a/doc/guides/sample_app_ug/l2_forward_job_stats.rst
+++ b/doc/guides/sample_app_ug/l2_forward_job_stats.rst
@@ -19,10 +19,11 @@ Overview
The L2 Forwarding sample application, which can operate in real and virtualized environments,
performs L2 forwarding for each packet that is received.
-The destination port is the adjacent port from the enabled portmask, that is,
-if the first four ports are enabled (portmask 0xf),
+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.
-Also, the MAC addresses are affected as follows:
+
+The MAC addresses are affected as follows:
* The source MAC address is replaced by the TX port MAC address
@@ -51,8 +52,8 @@ Virtual Function Setup Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This application can use the virtual function available in the system and
-therefore can be used in a virtual machine without passing through
-the whole Network Device into a guest machine in a virtualized scenario.
+can be used in a virtual machine without passing through
+the whole Network Device into a guest machine when in a virtualized scenario.
The virtual functions can be enabled in the host machine or the hypervisor with the respective physical function driver.
For example, in a Linux* host machine, it is possible to enable a virtual function using the following command:
@@ -65,15 +66,17 @@ This command enables two Virtual Functions on each of Physical Function of the N
with two physical ports in the PCI configuration space.
It is important to note that enabled Virtual Function 0 and 2 would belong to Physical Function 0
and Virtual Function 1 and 3 would belong to Physical Function 1,
-in this case enabling a total of four Virtual Functions.
+enabling a total of four Virtual Functions (in this case).
+
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 ``l2fwd-jobstats`` sub-directory.
+
Running the Application
-----------------------
@@ -91,8 +94,8 @@ where,
* l: Use locale thousands separator when formatting big numbers.
-To run the application in linux environment with 4 lcores, 16 ports, 8 RX queues per lcore and
-thousands separator printing, issue the command:
+To run the application in a linux environment with 4 lcores, 16 ports, 8 RX queues per lcore and
+thousands separator printing, issue the command:
.. code-block:: console
@@ -101,22 +104,24 @@ thousands separator printing, issue the command:
Refer to the *DPDK Getting Started Guide* for general information on running applications
and the Environment Abstraction Layer (EAL) options.
+
Explanation
-----------
-The following sections provide some explanation of the code.
+The following sections provide explanation of the code.
+
Command Line Arguments
~~~~~~~~~~~~~~~~~~~~~~
-The L2 Forwarding sample application takes specific parameters,
+The L2 Forwarding sample application takes specific parameters
in addition to Environment Abstraction Layer (EAL) arguments
(see `Running the Application`_).
The preferred way to parse parameters is to use the getopt() function,
since it is part of a well-defined and portable library.
The parsing of arguments is done in the l2fwd_parse_args() function.
-The method of argument parsing is not described here.
+This method of argument parsing is not described here.
Refer to the *glibc getopt(3)* man page for details.
EAL arguments are parsed first, then application-specific arguments.
@@ -255,7 +260,7 @@ Main loop
~~~~~~~~~
The forwarding path is reworked comparing to original L2 Forwarding application.
-In the l2fwd_main_loop() function three loops are placed.
+In the l2fwd_main_loop() function, three loops are placed.
.. literalinclude:: ../../../examples/l2fwd-jobstats/main.c
:language: c
@@ -263,15 +268,20 @@ In the l2fwd_main_loop() function three loops are placed.
:end-before: >8 End of minimize impact of stats reading.
:dedent: 1
-First infinite for loop is to minimize impact of stats reading. Lock is only locked/unlocked when asked.
+The first infinite for loop is to minimize impact of stats reading. Lock is only locked/unlocked
+when asked.
+
+Second inner while loop do the whole jobs management. When any job is ready,
+the use rte_timer_manage() is used to call the job handler.
-Second inner while loop do the whole jobs management. When any job is ready, the use rte_timer_manage() is used to call the job handler.
-In this place functions l2fwd_fwd_job() and l2fwd_flush_job() are called when needed.
-Then rte_jobstats_context_finish() is called to mark loop end - no other jobs are ready to execute. By this time stats are ready to be read
+In this place, functions l2fwd_fwd_job() and l2fwd_flush_job() are called when needed.
+Then, rte_jobstats_context_finish() is called to mark loop end - no other jobs are ready to execute.
+By this time, stats are ready to be read
and if stats_read_pending is set, loop breaks allowing stats to be read.
-Third do-while loop is the idle job (idle stats counter). Its only purpose is monitoring if any job is ready or stats job read is pending
-for this lcore. Statistics from this part of code is considered as the headroom available for additional processing.
+Third do-while loop is the idle job (idle stats counter). Its only purpose is monitoring if any job is
+ready or stats job read is pending for this lcore. Statistics from this part of the code is considered as
+the headroom available for additional processing.
Receive, Process and Transmit Packets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -291,7 +301,7 @@ The processing is very simple: process the TX port from the RX port, then replac
The rte_eth_rx_burst() function writes the mbuf pointers in a local table and returns the number of available mbufs in the table.
-After first read second try is issued.
+After first read, a second try is issued.
.. literalinclude:: ../../../examples/l2fwd-jobstats/main.c
:language: c
@@ -299,7 +309,7 @@ After first read second try is issued.
:end-before: >8 End of read second try.
:dedent: 1
-This second read is important to give job stats library a feedback how many packets was processed.
+This second read is important to give the job stats library feedback of how many packets were processed.
.. literalinclude:: ../../../examples/l2fwd-jobstats/main.c
:language: c
@@ -307,8 +317,8 @@ This second read is important to give job stats library a feedback how many pack
:end-before: >8 End of adjust period time in which we are running.
:dedent: 1
-To maximize performance exactly MAX_PKT_BURST is expected (the target value) to be read for each l2fwd_fwd_job() call.
-If total_nb_rx is smaller than target value job->period will be increased. If it is greater the period will be decreased.
+To maximize performance, exactly MAX_PKT_BURST is expected (the target value) to be read for each l2fwd_fwd_job() call.
+If total_nb_rx is smaller than target value job->period will be increased. If it is greater, the period will be decreased.
.. note::
diff --git a/doc/guides/sample_app_ug/rxtx_callbacks.rst b/doc/guides/sample_app_ug/rxtx_callbacks.rst
index f06c5c866a..ddec20cf69 100644
--- a/doc/guides/sample_app_ug/rxtx_callbacks.rst
+++ b/doc/guides/sample_app_ug/rxtx_callbacks.rst
@@ -4,24 +4,29 @@
RX/TX Callbacks Sample Application
==================================
+
+Overview
+--------
+
The RX/TX Callbacks sample application is a packet forwarding application that
demonstrates the use of user defined callbacks on received and transmitted
packets. The application performs a simple latency check, using callbacks, to
-determine the time packets spend within the application.
+determine the time that packets spend within the application.
-In the sample application a user defined callback is applied to all received
+In the sample application, a user defined callback is applied to all received
packets to add a timestamp. A separate callback is applied to all packets
-prior to transmission to calculate the elapsed time, in CPU cycles.
+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 since the packet was timestamped in hardware,
+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.
+
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 ``rxtx_callbacks`` sub-directory.
@@ -66,8 +71,8 @@ The main difference is in the user defined ``port_init()`` function where the
callbacks are added. This is explained in the next section:
-The Port Initialization Function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Port Initialization Function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The main functional part of the port initialization is shown below with
comments:
@@ -122,5 +127,5 @@ packets prior to transmission:
The ``calc_latency()`` function accumulates the total number of packets and
the total number of cycles used. Once more than 100 million packets have been
-transmitted the average cycle count per packet is printed out and the counters
+transmitted, the average cycle count per packet is printed out and the counters
are reset.
diff --git a/doc/guides/sample_app_ug/skeleton.rst b/doc/guides/sample_app_ug/skeleton.rst
index 08ddd7aa59..cb7ff6da4b 100644
--- a/doc/guides/sample_app_ug/skeleton.rst
+++ b/doc/guides/sample_app_ug/skeleton.rst
@@ -7,14 +7,17 @@ Basic Forwarding Sample Application
The Basic Forwarding sample application is a simple *skeleton* example of a
forwarding application.
-It is intended as a demonstration of the basic components of a DPDK forwarding
-application. For more detailed implementations see the L2 and L3 forwarding
+Overview
+--------
+
+This application demonstrates the basic components of a DPDK forwarding
+application. For more detailed implementations, see the L2 and L3 forwarding
sample applications.
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 ``skeleton`` sub-directory.
@@ -28,7 +31,7 @@ To run the example in a ``linux`` environment:
./<build_dir>/examples/dpdk-skeleton -l 1 -n 4
Refer to *DPDK Getting Started Guide* for general information on running
-applications and the Environment Abstraction Layer (EAL) options.
+applications and Environment Abstraction Layer (EAL) options.
Explanation
@@ -47,8 +50,8 @@ The Main Function
The ``main()`` function performs the initialization and calls the execution
threads for each lcore.
-The first task is to initialize the Environment Abstraction Layer (EAL). The
-``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
+The first task is to initialize the Environment Abstraction Layer (EAL).
+The ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
function. The value returned is the number of parsed arguments:
.. literalinclude:: ../../../examples/skeleton/basicfwd.c
@@ -80,7 +83,7 @@ The ``main()`` function also initializes all the ports using the user defined
:dedent: 1
Once the initialization is complete, the application is ready to launch a
-function on an lcore. In this example ``lcore_main()`` is called on a single
+function on an lcore. In this example, ``lcore_main()`` is called on a single
lcore.
@@ -93,9 +96,8 @@ lcore.
The ``lcore_main()`` function is explained below.
-
-The Port Initialization Function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Port Initialization Function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The main functional part of the port initialization used in the Basic
Forwarding application is shown below:
@@ -108,7 +110,7 @@ Forwarding application is shown below:
The Ethernet ports are configured with default settings using the
``rte_eth_dev_configure()`` function.
-For this example the ports are set up with 1 RX and 1 TX queue using the
+In this example, the ports are set up with 1 RX and 1 TX queue using the
``rte_eth_rx_queue_setup()`` and ``rte_eth_tx_queue_setup()`` functions.
The Ethernet port is then started:
@@ -120,7 +122,7 @@ The Ethernet port is then started:
:dedent: 1
-Finally the RX port is set in promiscuous mode:
+Finally, the RX port is set in promiscuous mode:
.. literalinclude:: ../../../examples/skeleton/basicfwd.c
:language: c
@@ -132,8 +134,8 @@ Finally the RX port is set in promiscuous mode:
The Lcores Main
~~~~~~~~~~~~~~~
-As we saw above the ``main()`` function calls an application function on the
-available lcores. For the Basic Forwarding application the lcore function
+As we saw above, the ``main()`` function calls an application function on the
+available lcores. For the Basic Forwarding application, the lcore function
looks like the following:
.. literalinclude:: ../../../examples/skeleton/basicfwd.c
--
2.34.1
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2024-11-29 22:04 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-10-21 23:42 [PATCH] doc: reword sample app guides Nandini Persad
2024-11-29 22:04 ` Thomas Monjalon
-- strict thread matches above, loose matches on Subject: below --
2024-10-10 2:51 Nandini Persad
2024-10-06 22:45 Nandini Persad
2024-10-06 19:44 Nandini Persad
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).