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

[Stephen Hemminger]

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 at 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