[PATCH 14/29] doc/guides: improve vDPA sample application guide

Stephen Hemminger
2026-01-14T22:26:38Z

Improve the vDPA sample application documentation:
- add Overview section for better document structure
- use consistent capitalization of vDPA
- replace contractions with full forms
- fix grammar and improve sentence clarity
- use proper article usage and punctuation
- replace abbreviations with full phrases

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
doc/guides/sample_app_ug/vdpa.rst | 71 +++++++++++++++++--------------
1 file changed, 38 insertions(+), 33 deletions(-)

diff --git a/doc/guides/sample_app_ug/vdpa.rst b/doc/guides/sample_app_ug/vdpa.rst
index cd3ec99054..ec25a57183 100644
--- a/doc/guides/sample_app_ug/vdpa.rst
+++ b/doc/guides/sample_app_ug/vdpa.rst
@@ -4,41 +4,45 @@
Vdpa Sample Application
=======================

-The vdpa sample application creates vhost-user sockets by using the
-vDPA backend. vDPA stands for vhost Data Path Acceleration which utilizes
-virtio ring compatible devices to serve virtio driver directly to enable
-datapath acceleration. As vDPA driver can help to set up vhost datapath,
-this application doesn't need to launch dedicated worker threads for vhost
+Overview
+--------
+
+The vDPA sample application creates vhost-user sockets by using the
+vDPA backend. vDPA (vhost Data Path Acceleration) uses virtio ring
+compatible devices to serve a virtio driver directly, enabling
+datapath acceleration. A vDPA driver can help to set up the vhost datapath.
+This application does not need dedicated worker threads for vhost
enqueue/dequeue operations.

-Testing steps
--------------
+The following shows how to start VMs with a vDPA vhost-user
+backend and verify network connection and live migration.

-This section shows the steps of how to start VMs with vDPA vhost-user
-backend and verify network connection & live migration.
+Compiling the Application
+-------------------------

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

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

-Start the vdpa example
+Running the Application
+-----------------------
+
+Start the vDPA Example
~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: console

./dpdk-vdpa [EAL options] -- [--client] [--interactive|-i] or [--iface SOCKET_PATH]

-where
+where:

-* --client means running vdpa app in client mode, in the client mode, QEMU needs
- to run as the server mode and take charge of socket file creation.
-* --iface specifies the path prefix of the UNIX domain socket file, e.g.
- /tmp/vhost-user-, then the socket files will be named as /tmp/vhost-user-<n>
- (n starts from 0).
-* --interactive means run the vDPA sample in interactive mode:
+* --client runs the vdpa application in client mode. In client mode, QEMU
+ runs as the server and is responsible for socket file creation.
+* --iface specifies the path prefix of the UNIX domain socket file (for example,
+ /tmp/vhost-user-). The socket files are named /tmp/vhost-user-<n>
+ where n starts from 0.
+* --interactive runs the vDPA sample in interactive mode with the following
+ commands:

#. help: show help message

@@ -50,7 +54,7 @@ where

#. quit: unregister vhost driver and exit the application

-Take IFCVF driver for example:
+The following example uses the IFCVF driver:

.. code-block:: console

@@ -59,13 +63,13 @@ Take IFCVF driver for example:
-- --interactive

.. note::
- Here 0000:06:00.3 and 0000:06:00.4 refer to virtio ring compatible devices,
- and we need to bind vfio-pci to them before running vdpa sample.
+ Here 0000:06:00.3 and 0000:06:00.4 refer to virtio ring compatible devices.
+ Bind vfio-pci to them before running the vdpa sample:

* modprobe vfio-pci
* ./usertools/dpdk-devbind.py -b vfio-pci 06:00.3 06:00.4

-Then we can create 2 vdpa ports in interactive cmdline.
+Then, create two vdpa ports in the interactive command line.

.. code-block:: console

@@ -92,24 +96,25 @@ Start the VMs
-netdev type=vhost-user,id=vdpa,chardev=char0 \
-device virtio-net-pci,netdev=vdpa,mac=00:aa:bb:cc:dd:ee,page-per-vq=on \

-After the VMs launches, we can login the VMs and configure the ip, verify the
+After the VMs launch, log into the VMs and configure the IP address to verify
network connection via ping or netperf.

.. note::
- Suggest to use QEMU 3.0.0 which extends vhost-user for vDPA.
+ QEMU 3.0.0 or later is recommended as it extends vhost-user for vDPA.

Live Migration
~~~~~~~~~~~~~~
-vDPA supports cross-backend live migration, user can migrate SW vhost backend
-VM to vDPA backend VM and vice versa. Here are the detailed steps. Assume A is
-the source host with SW vhost VM and B is the destination host with vDPA.
+vDPA supports cross-backend live migration. Users can migrate a SW vhost
+backend VM to a vDPA backend VM and vice versa. The following are the
+detailed steps. Assume A is the source host with the SW vhost VM and B is
+the destination host with vDPA.

-#. Start vdpa sample and launch a VM with exact same parameters as the VM on A,
- in migration-listen mode:
+#. Start the vdpa sample and launch a VM with the same parameters as the VM
+ on A, in migration-listen mode:

.. code-block:: console

- B: <qemu-command-line> -incoming tcp:0:4444 (or other PORT))
+ B: <qemu-command-line> -incoming tcp:0:4444 (or other PORT)

#. Start the migration (on source host):

--
2.51.0