[PATCH 07/29] doc/guides: improve VMDq sample application documentation

Stephen Hemminger
2026-01-14T22:25:51Z

Revise VMDq and VMDq/DCB Forwarding sample documentation for clarity,
accuracy, and compliance with technical writing standards.

Common changes to both files:
- Add technology overview sections explaining VMDq hardware packet sorting
- Fix contradictory statements about command-line options
- Create dedicated Command-Line Options sections
- Add Supported Configurations sections for hardware details
- Improve sentence structure and readability
- Fix RST formatting issues
- Convert warnings to RST note directives

vmdq_forwarding.rst:
- Update application name from vmdq_app to dpdk-vmdq

vmdq_dcb_forwarding.rst:
- Add DCB/QoS explanation using VLAN user priority fields
- Correct typo: "VMD queues" -> "VMDq queues"
- Correct capitalization: "linux" -> "Linux"
- Add sub-headings for traffic class and MAC address sections

The technology context is based on Intel's VMDq Technology paper and
helps readers understand hardware-based packet classification benefits
in virtualized environments.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
.../sample_app_ug/vmdq_dcb_forwarding.rst | 193 +++++++++++-------
doc/guides/sample_app_ug/vmdq_forwarding.rst | 144 +++++++------
2 files changed, 207 insertions(+), 130 deletions(-)

diff --git a/doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst b/doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst
index efb133c11c..9d01901f0c 100644
--- a/doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst
+++ b/doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst
@@ -1,150 +1,197 @@
.. SPDX-License-Identifier: BSD-3-Clause
Copyright(c) 2010-2014 Intel Corporation.

-VMDQ and DCB Forwarding Sample Application
+VMDq and DCB Forwarding Sample Application
==========================================

-The VMDQ and DCB Forwarding sample application is a simple example of packet processing using the DPDK.
-The application performs L2 forwarding using VMDQ and DCB to divide the incoming traffic into queues.
-The traffic splitting is performed in hardware by the VMDQ and DCB features of the Intel® 82599 and X710/XL710 Ethernet Controllers.
+The VMDq and DCB Forwarding sample application demonstrates packet processing using the DPDK.
+The application performs L2 forwarding using Intel VMDq (Virtual Machine Device Queues) combined
+with DCB (Data Center Bridging) to divide incoming traffic into queues. The traffic splitting
+is performed in hardware by the VMDq and DCB features of Intel 82599 and X710/XL710
+Ethernet Controllers.

Overview
--------

-This sample application can be used as a starting point for developing a new application that is based on the DPDK and
-uses VMDQ and DCB for traffic partitioning.
+This sample application can serve as a starting point for developing DPDK applications
+that use VMDq and DCB for traffic partitioning.

-The VMDQ and DCB filters work on MAC and VLAN traffic to divide the traffic into input queues on the basis of the Destination MAC
-address, VLAN ID and VLAN user priority fields.
-VMDQ filters split the traffic into 16 or 32 groups based on the Destination MAC and VLAN ID.
-Then, DCB places each packet into one of queues within that group, based upon the VLAN user priority field.
+About VMDq and DCB Technology
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-All traffic is read from a single incoming port (port 0) and output on port 1, without any processing being performed.
-With Intel® 82599 NIC, for example, the traffic is split into 128 queues on input, where each thread of the application reads from
-multiple queues. When run with 8 threads, that is, with the -c FF option, each thread receives and forwards packets from 16 queues.
+VMDq is a silicon-level technology that offloads network I/O packet sorting from the
+Virtual Machine Monitor (VMM) to the network controller hardware. This reduces CPU
+overhead in virtualized environments by performing Layer 2 classification in hardware.

-As supplied, the sample application configures the VMDQ feature to have 32 pools with 4 queues each as indicated in :numref:`figure_vmdq_dcb_example`.
-The Intel® 82599 10 Gigabit Ethernet Controller NIC also supports the splitting of traffic into 16 pools of 8 queues. While the
-Intel® X710 or XL710 Ethernet Controller NICs support many configurations of VMDQ pools of 4 or 8 queues each. For simplicity, only 16
-or 32 pools is supported in this sample. And queues numbers for each VMDQ pool can be changed by setting RTE_LIBRTE_I40E_QUEUE_NUM_PER_VM
-in config/rte_config.h file.
-The nb-pools, nb-tcs and enable-rss parameters can be passed on the command line, after the EAL parameters:
+DCB (Data Center Bridging) extends VMDq by adding Quality of Service (QoS) support.
+DCB uses the VLAN user priority field (also called Priority Code Point or PCP) to
+classify packets into different traffic classes, enabling bandwidth allocation and
+priority-based queuing.

-.. code-block:: console
+How VMDq and DCB Filtering Works
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The VMDq and DCB filters work together on MAC and VLAN traffic to divide packets into
+input queues:
+
+1. **VMDq filtering**: Splits traffic into 16 or 32 groups based on the destination
+ MAC address and VLAN ID.
+
+2. **DCB classification**: Places each packet into one of the queues within its VMDq
+ group based on the VLAN user priority field.

- ./<build_dir>/examples/dpdk-vmdq_dcb [EAL options] -- -p PORTMASK --nb-pools NP --nb-tcs TC --enable-rss
+All traffic is read from a single incoming port (port 0) and output on port 1 without
+modification. For the Intel 82599 NIC, traffic is split into 128 queues on input.
+Each application thread reads from multiple queues. When running with 8 threads
+(using the ``-c FF`` option), each thread receives and forwards packets from 16 queues.

-where, NP can be 16 or 32, TC can be 4 or 8, rss is disabled by default.
+:numref:`figure_vmdq_dcb_example` illustrates the packet flow through the application.

.. _figure_vmdq_dcb_example:

.. figure:: img/vmdq_dcb_example.*

- Packet Flow Through the VMDQ and DCB Sample Application
+ Packet Flow Through the VMDq and DCB Sample Application

+Supported Configurations
+~~~~~~~~~~~~~~~~~~~~~~~~

-In Linux* user space, the application can display statistics with the number of packets received on each queue.
-To have the application display the statistics, send a SIGHUP signal to the running application process.
+The sample application supports the following configurations:

-The VMDQ and DCB Forwarding sample application is in many ways simpler than the L2 Forwarding application
-(see :doc:`l2_forward_real_virtual`)
-as it performs unidirectional L2 forwarding of packets from one port to a second port.
-No command-line options are taken by this application apart from the standard EAL command-line options.
+- **Intel 82599 10 Gigabit Ethernet Controller**: 32 pools with 4 queues each (default),
+ or 16 pools with 8 queues each.
+
+- **Intel X710/XL710 Ethernet Controllers**: Multiple configurations of VMDq pools
+ with 4 or 8 queues each. For simplicity, this sample supports only 16 or 32 pools.
+ The number of queues per VMDq pool can be changed by setting
+ ``RTE_LIBRTE_I40E_QUEUE_NUM_PER_VM`` in ``config/rte_config.h``.

.. note::

- Since VMD queues are being used for VMM, this application works correctly
- when VTd is disabled in the BIOS or Linux* kernel (intel_iommu=off).
+ Since VMDq queues are used for virtual machine management, this application works
+ correctly when VT-d is disabled in the BIOS or Linux kernel (``intel_iommu=off``).

Compiling the Application
-------------------------

-
-
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.

The application is located in the ``vmdq_dcb`` sub-directory.

Running the Application
-----------------------

-To run the example in a linux environment:
+To run the example in a Linux environment:
+
+.. code-block:: console
+
+ ./<build_dir>/examples/dpdk-vmdq_dcb -l 0-3 -- -p 0x3 --nb-pools 32 --nb-tcs 4
+
+Command-Line Options
+~~~~~~~~~~~~~~~~~~~~
+
+The following application-specific options are available after the EAL parameters:
+
+``-p PORTMASK``
+ Hexadecimal bitmask of ports to configure.
+
+``--nb-pools NP``
+ Number of VMDq pools. Valid values are 16 or 32.
+
+``--nb-tcs TC``
+ Number of traffic classes. Valid values are 4 or 8.
+
+``--enable-rss``
+ Enable Receive Side Scaling. RSS is disabled by default.
+
+Example:

.. code-block:: console

- user@target:~$ ./<build_dir>/examples/dpdk-vmdq_dcb -l 0-3 -- -p 0x3 --nb-pools 32 --nb-tcs 4
+ ./<build_dir>/examples/dpdk-vmdq_dcb [EAL options] -- -p 0x3 --nb-pools 32 --nb-tcs 4 --enable-rss

-Refer to the *DPDK Getting Started Guide* for general information on running applications and
-the Environment Abstraction Layer (EAL) options.
+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 explain the code structure.

Initialization
~~~~~~~~~~~~~~

-The EAL, driver and PCI configuration is performed largely as in the L2 Forwarding sample application,
-as is the creation of the mbuf pool.
-See :doc:`l2_forward_real_virtual`.
-Where this example application differs is in the configuration of the NIC port for RX.
+The EAL, driver, and PCI configuration is performed similarly to the L2 Forwarding sample
+application, as is the creation of the mbuf pool. See :doc:`l2_forward_real_virtual` for details.
+
+This example application differs in the configuration of the NIC port for RX. The VMDq and
+DCB hardware features are configured at port initialization time by setting appropriate values
+in the ``rte_eth_conf`` structure passed to the ``rte_eth_dev_configure()`` API.

-The VMDQ and DCB hardware feature is configured at port initialization time by setting the appropriate values in the
-rte_eth_conf structure passed to the rte_eth_dev_configure() API.
-Initially in the application,
-a default structure is provided for VMDQ and DCB configuration to be filled in later by the application.
+Initially, the application provides a default structure for VMDq and DCB configuration:

.. literalinclude:: ../../../examples/vmdq_dcb/main.c
:language: c
:start-after: Empty vmdq+dcb configuration structure. Filled in programmatically. 8<
:end-before: >8 End of empty vmdq+dcb configuration structure.

-The get_eth_conf() function fills in an rte_eth_conf structure with the appropriate values,
-based on the global vlan_tags array,
-and dividing up the possible user priority values equally among the individual queues
-(also referred to as traffic classes) within each pool. With Intel® 82599 NIC,
-if the number of pools is 32, then the user priority fields are allocated 2 to a queue.
-If 16 pools are used, then each of the 8 user priority fields is allocated to its own queue within the pool.
-With Intel® X710/XL710 NICs, if number of tcs is 4, and number of queues in pool is 8,
-then the user priority fields are allocated 2 to one tc, and a tc has 2 queues mapping to it, then
-RSS will determine the destination queue in 2.
-For the VLAN IDs, each one can be allocated to possibly multiple pools of queues,
-so the pools parameter in the rte_eth_vmdq_dcb_conf structure is specified as a bitmask value.
-For destination MAC, each VMDQ pool will be assigned with a MAC address. In this sample, each VMDQ pool
-is assigned to the MAC like 52:54:00:12:<port_id>:<pool_id>, that is,
-the MAC of VMDQ pool 2 on port 1 is 52:54:00:12:01:02.
+Traffic Class and Queue Assignment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``get_eth_conf()`` function fills in the ``rte_eth_conf`` structure with appropriate
+values based on the global ``vlan_tags`` array. The function divides user priority values
+among individual queues (traffic classes) within each pool.
+
+For Intel 82599 NICs:
+
+- With 32 pools: User priority fields are allocated 2 per queue.
+- With 16 pools: Each of the 8 user priority fields is allocated to its own queue.
+
+For Intel X710/XL710 NICs:
+
+- With 4 traffic classes and 8 queues per pool: User priority fields are allocated
+ 2 per traffic class, with 2 queues mapped to each traffic class. RSS determines
+ the destination queue within each traffic class.
+
+For VLAN IDs, each ID can be allocated to multiple pools of queues, so the ``pools``
+parameter in the ``rte_eth_vmdq_dcb_conf`` structure is specified as a bitmask.

.. literalinclude:: ../../../examples/vmdq_dcb/main.c
:language: c
:start-after: Dividing up the possible user priority values. 8<
:end-before: >8 End of dividing up the possible user priority values.

+MAC Address Assignment
+^^^^^^^^^^^^^^^^^^^^^^
+
+Each VMDq pool is assigned a MAC address using the format ``52:54:00:12:<port_id>:<pool_id>``.
+For example, VMDq pool 2 on port 1 uses the MAC address ``52:54:00:12:01:02``.
+
.. literalinclude:: ../../../examples/vmdq_dcb/main.c
:language: c
:start-after: Set mac for each pool. 8<
:end-before: >8 End of set mac for each pool.
:dedent: 1

-Once the network port has been initialized using the correct VMDQ and DCB values,
-the initialization of the port's RX and TX hardware rings is performed similarly to that
-in the L2 Forwarding sample application.
+After the network port is initialized with VMDq and DCB values, the port's RX and TX
+hardware rings are initialized similarly to the L2 Forwarding sample application.
See :doc:`l2_forward_real_virtual` for more information.

Statistics Display
~~~~~~~~~~~~~~~~~~

-When run in a linux environment,
-the VMDQ and DCB Forwarding sample application can display statistics showing the number of packets read from each RX queue.
-This is provided by way of a signal handler for the SIGHUP signal,
-which simply prints to standard output the packet counts in grid form.
-Each row of the output is a single pool with the columns being the queue number within that pool.
+When running in a Linux environment, the application can display statistics showing the
+number of packets read from each RX queue. The application uses a signal handler for the
+SIGHUP signal that prints packet counts in grid form, with each row representing a single
+pool and each column representing a queue number within that pool.

-To generate the statistics output, use the following command:
+To generate the statistics output:

.. code-block:: console

- user@host$ sudo killall -HUP vmdq_dcb_app
+ sudo killall -HUP dpdk-vmdq_dcb
+
+.. note::

-Please note that the statistics output will appear on the terminal where the vmdq_dcb_app is running,
-rather than the terminal from which the HUP signal was sent.
+ The statistics output appears on the terminal where the application is running,
+ not on the terminal from which the HUP signal was sent.
diff --git a/doc/guides/sample_app_ug/vmdq_forwarding.rst b/doc/guides/sample_app_ug/vmdq_forwarding.rst
index c998a5a223..f100d965cd 100644
--- a/doc/guides/sample_app_ug/vmdq_forwarding.rst
+++ b/doc/guides/sample_app_ug/vmdq_forwarding.rst
@@ -2,50 +2,60 @@
Copyright(c) 2020 Intel Corporation.

VMDq Forwarding Sample Application
-==========================================
+==================================

-The VMDq Forwarding sample application is a simple example of packet processing using the DPDK.
-The application performs L2 forwarding using VMDq to divide the incoming traffic into queues.
-The traffic splitting is performed in hardware by the VMDq feature of the Intel® 82599 and X710/XL710 Ethernet Controllers.
+The VMDq Forwarding sample application demonstrates packet processing using the DPDK.
+The application performs L2 forwarding using Intel VMDq (Virtual Machine Device Queues)
+to divide incoming traffic into queues. The traffic splitting is performed in hardware
+by the VMDq feature of Intel 82599 and X710/XL710 Ethernet Controllers.

Overview
--------

-This sample application can be used as a starting point for developing a new application that is based on the DPDK and
-uses VMDq for traffic partitioning.
+This sample application can serve as a starting point for developing DPDK applications
+that use VMDq for traffic partitioning.

-VMDq filters split the incoming packets up into different "pools" - each with its own set of RX queues - based upon
-the MAC address and VLAN ID within the VLAN tag of the packet.
+About VMDq Technology
+~~~~~~~~~~~~~~~~~~~~~

-All traffic is read from a single incoming port and output on another port, without any processing being performed.
-With Intel® 82599 NIC, for example, the traffic is split into 128 queues on input, where each thread of the application reads from
-multiple queues. When run with 8 threads, that is, with the -c FF option, each thread receives and forwards packets from 16 queues.
+VMDq is a silicon-level technology designed to improve network I/O performance in
+virtualized environments. In traditional virtualized systems, the Virtual Machine Monitor
+(VMM) must sort incoming packets and route them to the correct virtual machine, consuming
+significant CPU cycles. VMDq offloads this packet sorting to the network controller hardware,
+freeing CPU resources for application workloads.

-As supplied, the sample application configures the VMDq feature to have 32 pools with 4 queues each.
-The Intel® 82599 10 Gigabit Ethernet Controller NIC also supports the splitting of traffic into 16 pools of 2 queues.
-While the Intel® X710 or XL710 Ethernet Controller NICs support many configurations of VMDq pools of 4 or 8 queues each.
-And queues numbers for each VMDq pool can be changed by setting RTE_LIBRTE_I40E_QUEUE_NUM_PER_VM
-in config/rte_config.h file.
-The nb-pools and enable-rss parameters can be passed on the command line, after the EAL parameters:
+When packets arrive at a VMDq-enabled network adapter, a Layer 2 classifier in the controller
+sorts packets based on MAC addresses and VLAN tags, then places each packet in the receive
+queue assigned to the appropriate destination. This hardware-based pre-sorting reduces the
+overhead of software-based virtual switches.

-.. code-block:: console
+How VMDq Filtering Works
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+VMDq filters split incoming packets into different pools, each with its own set of RX queues,
+based on the MAC address and VLAN ID within the VLAN tag of the packet.

- ./<build_dir>/examples/dpdk-vmdq [EAL options] -- -p PORTMASK --nb-pools NP --enable-rss
+All traffic is read from a single incoming port and output on another port without modification.
+For the Intel 82599 NIC, traffic is split into 128 queues on input. Each application thread
+reads from multiple queues. When running with 8 threads (using the ``-c FF`` option), each
+thread receives and forwards packets from 16 queues.

-where, NP can be 8, 16 or 32, rss is disabled by default.
+Supported Configurations
+~~~~~~~~~~~~~~~~~~~~~~~~

-In Linux* user space, the application can display statistics with the number of packets received on each queue.
-To have the application display the statistics, send a SIGHUP signal to the running application process.
+The sample application supports the following configurations:

-The VMDq Forwarding sample application is in many ways simpler than the L2 Forwarding application
-(see :doc:`l2_forward_real_virtual`)
-as it performs unidirectional L2 forwarding of packets from one port to a second port.
-No command-line options are taken by this application apart from the standard EAL command-line options.
+- **Intel 82599 10 Gigabit Ethernet Controller**: 32 pools with 4 queues each (default),
+ or 16 pools with 2 queues each.
+
+- **Intel X710/XL710 Ethernet Controllers**: Multiple configurations of VMDq pools
+ with 4 or 8 queues each. The number of queues per VMDq pool can be changed by setting
+ ``RTE_LIBRTE_I40E_QUEUE_NUM_PER_VM`` in ``config/rte_config.h``.

Compiling the Application
-------------------------

-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.

The application is located in the ``vmdq`` sub-directory.

@@ -56,40 +66,60 @@ To run the example in a Linux environment:

.. code-block:: console

- user@target:~$ ./<build_dir>/examples/dpdk-vmdq -l 0-3 -- -p 0x3 --nb-pools 16
+ ./<build_dir>/examples/dpdk-vmdq -l 0-3 -- -p 0x3 --nb-pools 16
+
+Command-Line Options
+~~~~~~~~~~~~~~~~~~~~
+
+The following application-specific options are available after the EAL parameters:
+
+``-p PORTMASK``
+ Hexadecimal bitmask of ports to configure.
+
+``--nb-pools NP``
+ Number of VMDq pools. Valid values are 8, 16, or 32.
+
+``--enable-rss``
+ Enable Receive Side Scaling. RSS is disabled by default.

-Refer to the *DPDK Getting Started Guide* for general information on running applications and
-the Environment Abstraction Layer (EAL) options.
+Example:
+
+.. code-block:: console
+
+ ./<build_dir>/examples/dpdk-vmdq [EAL options] -- -p 0x3 --nb-pools 32 --enable-rss
+
+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 explain the code structure.

Initialization
~~~~~~~~~~~~~~

-The EAL, driver and PCI configuration is performed largely as in the L2 Forwarding sample application,
-as is the creation of the mbuf pool.
-See :doc:`l2_forward_real_virtual`.
-Where this example application differs is in the configuration of the NIC port for RX.
+The EAL, driver, and PCI configuration is performed similarly to the L2 Forwarding sample
+application, as is the creation of the mbuf pool. See :doc:`l2_forward_real_virtual` for details.

-The VMDq hardware feature is configured at port initialization time by setting the appropriate values in the
-rte_eth_conf structure passed to the rte_eth_dev_configure() API.
-Initially in the application,
-a default structure is provided for VMDq configuration to be filled in later by the application.
+This example application differs in the configuration of the NIC port for RX. The VMDq
+hardware feature is configured at port initialization time by setting appropriate values
+in the ``rte_eth_conf`` structure passed to the ``rte_eth_dev_configure()`` API.
+
+Initially, the application provides a default structure for VMDq configuration:

.. literalinclude:: ../../../examples/vmdq/main.c
:language: c
:start-after: Default structure for VMDq. 8<
:end-before: >8 End of Empty vdmq configuration structure.

-The get_eth_conf() function fills in an rte_eth_conf structure with the appropriate values,
-based on the global vlan_tags array.
-For the VLAN IDs, each one can be allocated to possibly multiple pools of queues.
-For destination MAC, each VMDq pool will be assigned with a MAC address. In this sample, each VMDq pool
-is assigned to the MAC like 52:54:00:12:<port_id>:<pool_id>, that is,
-the MAC of VMDq pool 2 on port 1 is 52:54:00:12:01:02.
+The ``get_eth_conf()`` function fills in the ``rte_eth_conf`` structure with appropriate
+values based on the global ``vlan_tags`` array. Each VLAN ID can be allocated to multiple
+pools of queues.
+
+For destination MAC addresses, each VMDq pool is assigned a MAC address using the format
+``52:54:00:12:<port_id>:<pool_id>``. For example, VMDq pool 2 on port 1 uses the MAC address
+``52:54:00:12:01:02``.

.. literalinclude:: ../../../examples/vmdq/main.c
:language: c
@@ -106,25 +136,25 @@ the MAC of VMDq pool 2 on port 1 is 52:54:00:12:01:02.
:start-after: Building correct configuration for vdmq. 8<
:end-before: >8 End of get_eth_conf.

-Once the network port has been initialized using the correct VMDq values,
-the initialization of the port's RX and TX hardware rings is performed similarly to that
-in the L2 Forwarding sample application.
+After the network port is initialized with VMDq values, the port's RX and TX hardware rings
+are initialized similarly to the L2 Forwarding sample application.
See :doc:`l2_forward_real_virtual` for more information.

Statistics Display
~~~~~~~~~~~~~~~~~~

-When run in a Linux environment,
-the VMDq Forwarding sample application can display statistics showing the number of packets read from each RX queue.
-This is provided by way of a signal handler for the SIGHUP signal,
-which simply prints to standard output the packet counts in grid form.
-Each row of the output is a single pool with the columns being the queue number within that pool.
+When running in a Linux environment, the application can display statistics showing the
+number of packets read from each RX queue. The application uses a signal handler for the
+SIGHUP signal that prints packet counts in grid form, with each row representing a single
+pool and each column representing a queue number within that pool.

-To generate the statistics output, use the following command:
+To generate the statistics output:

.. code-block:: console

- user@host$ sudo killall -HUP vmdq_app
+ sudo killall -HUP dpdk-vmdq
+
+.. note::

-Please note that the statistics output will appear on the terminal where the vmdq_app is running,
-rather than the terminal from which the HUP signal was sent.
+ The statistics output appears on the terminal where the application is running,
+ not on the terminal from which the HUP signal was sent.
--
2.51.0