[5/6] doc: document packed virtqueue for virtio

Message ID 20190813020730.10038-6-tiwei.bie@intel.com
State Accepted
Delegated to: Maxime Coquelin
Headers show
Series
  • Some updates for virtio guide
Related show

Checks

Context Check Description
ci/Intel-compilation success Compilation OK
ci/checkpatch success coding style OK

Commit Message

Tiwei Bie Aug. 13, 2019, 2:07 a.m.
Document the packed virtqueue layout support in virtio net PMD.

Signed-off-by: Tiwei Bie <tiwei.bie@intel.com>
---
 doc/guides/nics/virtio.rst | 63 ++++++++++++++++++++++++++++----------
 1 file changed, 47 insertions(+), 16 deletions(-)

Comments

Maxime Coquelin Sept. 6, 2019, 1:21 p.m. | #1
On 8/13/19 4:07 AM, Tiwei Bie wrote:
> Document the packed virtqueue layout support in virtio net PMD.
> 
> Signed-off-by: Tiwei Bie <tiwei.bie@intel.com>
> ---
>  doc/guides/nics/virtio.rst | 63 ++++++++++++++++++++++++++++----------
>  1 file changed, 47 insertions(+), 16 deletions(-)
> 
> diff --git a/doc/guides/nics/virtio.rst b/doc/guides/nics/virtio.rst
> index 993e691f5..011954ff6 100644
> --- a/doc/guides/nics/virtio.rst
> +++ b/doc/guides/nics/virtio.rst
> @@ -24,15 +24,19 @@ standard qemu vhost back end and vhost kni back end.
>  Virtio Implementation in DPDK
>  -----------------------------
>  
> -For details about the virtio spec, refer to Virtio PCI Card Specification written by Rusty Russell.
> +For details about the virtio spec, refer to the latest
> +`VIRTIO (Virtual I/O) Device Specification
> +<https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio>`_.
>  
> -As a PMD, virtio provides packet reception and transmission callbacks virtio_recv_pkts and virtio_xmit_pkts.
> +As a PMD, virtio provides packet reception and transmission callbacks.
>  
> -In virtio_recv_pkts, index in range [vq->vq_used_cons_idx , vq->vq_ring.used->idx) in vring is available for virtio to burst out.
> +In Rx, packets described by the used descriptors in vring are available
> +for virtio to burst out.
>  
> -In virtio_xmit_pkts, same index range in vring is available for virtio to clean.
> -Virtio will enqueue to be transmitted packets into vring, advance the vq->vq_ring.avail->idx,
> -and then notify the host back end if necessary.
> +In Tx, packets described by the used descriptors in vring are available
> +for virtio to clean. Virtio will enqueue to be transmitted packets into
> +vring, make them available to the device, and then notify the host back
> +end if necessary.
>  
>  Features and Limitations of virtio PMD
>  --------------------------------------
> @@ -201,37 +205,52 @@ The packet transmission flow is:
>  Virtio PMD Rx/Tx Callbacks
>  --------------------------
>  
> -Virtio driver has 4 Rx callbacks and 2 Tx callbacks.
> +Virtio driver has 6 Rx callbacks and 3 Tx callbacks.
>  
>  Rx callbacks:
>  
>  #. ``virtio_recv_pkts``:
> -   Regular version without mergeable Rx buffer support.
> +   Regular version without mergeable Rx buffer support for split virtqueue.
>  
>  #. ``virtio_recv_mergeable_pkts``:
> -   Regular version with mergeable Rx buffer support.
> +   Regular version with mergeable Rx buffer support for split virtqueue.
>  
>  #. ``virtio_recv_pkts_vec``:
>     Vector version without mergeable Rx buffer support, also fixes the available
> -   ring indexes and uses vector instructions to optimize performance.
> +   ring indexes and uses vector instructions to optimize performance for split
> +   virtqueue.
>  
>  #. ``virtio_recv_pkts_inorder``:
> -   In-order version with mergeable and non-mergeable Rx buffer support.
> +   In-order version with mergeable and non-mergeable Rx buffer support
> +   for split virtqueue.
> +
> +#. ``virtio_recv_pkts_packed``:
> +   Regular and in-order version without mergeable Rx buffer support for
> +   packed virtqueue.
> +
> +#. ``virtio_recv_mergeable_pkts_packed``:
> +   Regular and in-order version with mergeable Rx buffer support for packed
> +   virtqueue.
>  
>  Tx callbacks:
>  
>  #. ``virtio_xmit_pkts``:
> -   Regular version.
> +   Regular version for split virtqueue.
>  
>  #. ``virtio_xmit_pkts_inorder``:
> -   In-order version.
> +   In-order version for split virtqueue.
> +
> +#. ``virtio_xmit_pkts_packed``:
> +   Regular and in-order version for packed virtqueue.
>  
>  By default, the non-vector callbacks are used:
>  
> -*   For Rx: If mergeable Rx buffers is disabled then ``virtio_recv_pkts`` is
> -    used; otherwise ``virtio_recv_mergeable_pkts``.
> +*   For Rx: If mergeable Rx buffers is disabled then ``virtio_recv_pkts``
> +    or ``virtio_recv_pkts_packed`` will be used, otherwise
> +    ``virtio_recv_mergeable_pkts`` or ``virtio_recv_mergeable_pkts_packed``
> +    will be used.
>  
> -*   For Tx: ``virtio_xmit_pkts``.
> +*   For Tx: ``virtio_xmit_pkts`` or ``virtio_xmit_pkts_packed`` will be used.
>  
>  
>  Vector callbacks will be used when:
> @@ -242,6 +261,8 @@ The corresponding callbacks are:
>  
>  *   For Rx: ``virtio_recv_pkts_vec``.
>  
> +There is no vector callbacks for packed virtqueue for now.
> +
>  
>  Example of using the vector version of the virtio poll mode driver in
>  ``testpmd``::
> @@ -250,10 +271,15 @@ Example of using the vector version of the virtio poll mode driver in
>  
>  In-order callbacks only work on simulated virtio user vdev.
>  
> +For split virtqueue:
> +
>  *   For Rx: If in-order is enabled then ``virtio_recv_pkts_inorder`` is used.
>  
>  *   For Tx: If in-order is enabled then ``virtio_xmit_pkts_inorder`` is used.
>  
> +For packed virtqueue, the default callbacks already support the
> +in-order feature.
> +
>  Interrupt mode
>  --------------
>  
> @@ -372,3 +398,8 @@ Below devargs are supported by the virtio-user vdev:
>  
>      It is used to enable virtio device in-order feature.
>      (Default: 1 (enabled))
> +
> +#.  ``packed_vq``:
> +
> +    It is used to enable virtio device packed virtqueue feature.
> +    (Default: 0 (disabled))
> 

Side note: One day, we may consider to enable it by default.

Reviewed-by: Maxime Coquelin <maxime.coquelin@redhat.com>

Patch

diff --git a/doc/guides/nics/virtio.rst b/doc/guides/nics/virtio.rst
index 993e691f5..011954ff6 100644
--- a/doc/guides/nics/virtio.rst
+++ b/doc/guides/nics/virtio.rst
@@ -24,15 +24,19 @@  standard qemu vhost back end and vhost kni back end.
 Virtio Implementation in DPDK
 -----------------------------
 
-For details about the virtio spec, refer to Virtio PCI Card Specification written by Rusty Russell.
+For details about the virtio spec, refer to the latest
+`VIRTIO (Virtual I/O) Device Specification
+<https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio>`_.
 
-As a PMD, virtio provides packet reception and transmission callbacks virtio_recv_pkts and virtio_xmit_pkts.
+As a PMD, virtio provides packet reception and transmission callbacks.
 
-In virtio_recv_pkts, index in range [vq->vq_used_cons_idx , vq->vq_ring.used->idx) in vring is available for virtio to burst out.
+In Rx, packets described by the used descriptors in vring are available
+for virtio to burst out.
 
-In virtio_xmit_pkts, same index range in vring is available for virtio to clean.
-Virtio will enqueue to be transmitted packets into vring, advance the vq->vq_ring.avail->idx,
-and then notify the host back end if necessary.
+In Tx, packets described by the used descriptors in vring are available
+for virtio to clean. Virtio will enqueue to be transmitted packets into
+vring, make them available to the device, and then notify the host back
+end if necessary.
 
 Features and Limitations of virtio PMD
 --------------------------------------
@@ -201,37 +205,52 @@  The packet transmission flow is:
 Virtio PMD Rx/Tx Callbacks
 --------------------------
 
-Virtio driver has 4 Rx callbacks and 2 Tx callbacks.
+Virtio driver has 6 Rx callbacks and 3 Tx callbacks.
 
 Rx callbacks:
 
 #. ``virtio_recv_pkts``:
-   Regular version without mergeable Rx buffer support.
+   Regular version without mergeable Rx buffer support for split virtqueue.
 
 #. ``virtio_recv_mergeable_pkts``:
-   Regular version with mergeable Rx buffer support.
+   Regular version with mergeable Rx buffer support for split virtqueue.
 
 #. ``virtio_recv_pkts_vec``:
    Vector version without mergeable Rx buffer support, also fixes the available
-   ring indexes and uses vector instructions to optimize performance.
+   ring indexes and uses vector instructions to optimize performance for split
+   virtqueue.
 
 #. ``virtio_recv_pkts_inorder``:
-   In-order version with mergeable and non-mergeable Rx buffer support.
+   In-order version with mergeable and non-mergeable Rx buffer support
+   for split virtqueue.
+
+#. ``virtio_recv_pkts_packed``:
+   Regular and in-order version without mergeable Rx buffer support for
+   packed virtqueue.
+
+#. ``virtio_recv_mergeable_pkts_packed``:
+   Regular and in-order version with mergeable Rx buffer support for packed
+   virtqueue.
 
 Tx callbacks:
 
 #. ``virtio_xmit_pkts``:
-   Regular version.
+   Regular version for split virtqueue.
 
 #. ``virtio_xmit_pkts_inorder``:
-   In-order version.
+   In-order version for split virtqueue.
+
+#. ``virtio_xmit_pkts_packed``:
+   Regular and in-order version for packed virtqueue.
 
 By default, the non-vector callbacks are used:
 
-*   For Rx: If mergeable Rx buffers is disabled then ``virtio_recv_pkts`` is
-    used; otherwise ``virtio_recv_mergeable_pkts``.
+*   For Rx: If mergeable Rx buffers is disabled then ``virtio_recv_pkts``
+    or ``virtio_recv_pkts_packed`` will be used, otherwise
+    ``virtio_recv_mergeable_pkts`` or ``virtio_recv_mergeable_pkts_packed``
+    will be used.
 
-*   For Tx: ``virtio_xmit_pkts``.
+*   For Tx: ``virtio_xmit_pkts`` or ``virtio_xmit_pkts_packed`` will be used.
 
 
 Vector callbacks will be used when:
@@ -242,6 +261,8 @@  The corresponding callbacks are:
 
 *   For Rx: ``virtio_recv_pkts_vec``.
 
+There is no vector callbacks for packed virtqueue for now.
+
 
 Example of using the vector version of the virtio poll mode driver in
 ``testpmd``::
@@ -250,10 +271,15 @@  Example of using the vector version of the virtio poll mode driver in
 
 In-order callbacks only work on simulated virtio user vdev.
 
+For split virtqueue:
+
 *   For Rx: If in-order is enabled then ``virtio_recv_pkts_inorder`` is used.
 
 *   For Tx: If in-order is enabled then ``virtio_xmit_pkts_inorder`` is used.
 
+For packed virtqueue, the default callbacks already support the
+in-order feature.
+
 Interrupt mode
 --------------
 
@@ -372,3 +398,8 @@  Below devargs are supported by the virtio-user vdev:
 
     It is used to enable virtio device in-order feature.
     (Default: 1 (enabled))
+
+#.  ``packed_vq``:
+
+    It is used to enable virtio device packed virtqueue feature.
+    (Default: 0 (disabled))