Skip to contentSkip to conversation

Some updates for virtio guide

PATCH In review Tiwei Bie 2 participants 14 messages Aug 13, 2019 – Sep 6, 2019 Network drivers

lore
Share & tools
lore

Tiwei Bie

author
#0 lore raw

cover Some updates for virtio guide

Tiwei Bie (6):
net/virtio: remove remaining simple Tx related stuff
doc: fix typo in virtio in-order Rx function name
doc: update the description for in-order Rx path
doc: document the devargs for virtio-user
doc: document packed virtqueue for virtio
doc: fix format for virtio guide

 doc/guides/nics/virtio.rst         | 118 ++++++++++++++++++++---------
 drivers/net/virtio/virtio_ethdev.h |   3 -
 2 files changed, 84 insertions(+), 37 deletions(-)
Signature · 1 line
2.17.1
author
#1 lore raw

PATCH 1/6 net/virtio: remove remaining simple Tx related stuff

The simple Tx path in virtio has been removed in below commit. This patch removes an undefined function declaration of simple Tx and all related descriptions in the doc.

Fixes 57f818963d80 ("net/virtio: remove simple Tx path")
---
 doc/guides/nics/virtio.rst         | 15 ++-------------
 drivers/net/virtio/virtio_ethdev.h |  3 ---
 2 files changed, 2 insertions(+), 16 deletions(-)
doc/guides/nics/virtio.rst +2 -13
index 2ae875cb4..da9cd6ba6 100644
@@ -201,7 +201,7 @@ The packet transmission flow is:
 Virtio PMD Rx/Tx Callbacks
 --------------------------
 
-Virtio driver has 4 Rx callbacks and 3 Tx callbacks.
+Virtio driver has 4 Rx callbacks and 2 Tx callbacks.
 
 Rx callbacks:
 
@@ -223,9 +223,6 @@ Tx callbacks:
 #. ``virtio_xmit_pkts``:
    Regular version.
 
-#. ``virtio_xmit_pkts_simple``:
-   Vector version fixes the available ring indexes to optimize performance.
-
 #. ``virtio_xmit_pkts_inorder``:
    In-order version.
 
@@ -239,25 +236,17 @@ By default, the non-vector callbacks are used:
 
 Vector callbacks will be used when:
 
-*   ``txmode.offloads`` is set to ``0x0``, which implies:
-
-    *   Single segment is specified.
-
-    *   No offload support is needed.
-
 *   Mergeable Rx buffers is disabled.
 
 The corresponding callbacks are:
 
 *   For Rx: ``virtio_recv_pkts_vec``.
 
-*   For Tx: ``virtio_xmit_pkts_simple``.
-
 
 Example of using the vector version of the virtio poll mode driver in
 ``testpmd``::
 
-   testpmd -l 0-2 -n 4 -- -i --tx-offloads=0x0 --rxq=1 --txq=1 --nb-cores=1
+   testpmd -l 0-2 -n 4 -- -i --rxq=1 --txq=1 --nb-cores=1
 
 In-order callbacks only work on simulated virtio user vdev.
 
drivers/net/virtio/virtio_ethdev.h +0 -3
index 20d331795..a10111758 100644
@@ -103,9 +103,6 @@ uint16_t virtio_xmit_pkts_inorder(void *tx_queue, struct rte_mbuf **tx_pkts,
 uint16_t virtio_recv_pkts_vec(void *rx_queue, struct rte_mbuf **rx_pkts,
 		uint16_t nb_pkts);
 
-uint16_t virtio_xmit_pkts_simple(void *tx_queue, struct rte_mbuf **tx_pkts,
-		uint16_t nb_pkts);
-
 int eth_virtio_dev_init(struct rte_eth_dev *eth_dev);
 
 void virtio_interrupt_handler(void *param);
Signature · 1 line
2.17.1
Reviewed-by on v1 1/6
#2 lore raw

Re: [dpdk-dev] [PATCH 1/6] net/virtio: remove remaining simple Tx related stuff

Quoted 4 lines · Tiwei Bie

The simple Tx path in virtio has been removed in below commit. This patch removes an undefined function declaration of simple Tx and all related descriptions in the doc.

Quoted 9 lines
Fixes 57f818963d80 ("net/virtio: remove simple Tx path")
---
 doc/guides/nics/virtio.rst         | 15 ++-------------
 drivers/net/virtio/virtio_ethdev.h |  3 ---
 2 files changed, 2 insertions(+), 16 deletions(-)
author
#3 lore raw

PATCH 2/6 doc: fix typo in virtio in-order Rx function name

In reply to Tiwei Bie

The Rx function that will be used when in-order is enabled should be virtio_recv_mergeable_pkts_inorder() instead of virtio_xmit_pkts_inorder().

Fixes 8f3bd7e8702d ("net/virtio: add in-order Rx/Tx into selection")
---
 doc/guides/nics/virtio.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
doc/guides/nics/virtio.rst +1 -1
index da9cd6ba6..08438d064 100644
@@ -251,7 +251,7 @@ Example of using the vector version of the virtio poll mode driver in
 In-order callbacks only work on simulated virtio user vdev.
 
 *   For Rx: If mergeable Rx buffers is enabled and in-order is enabled then
-    ``virtio_xmit_pkts_inorder`` is used.
+    ``virtio_recv_mergeable_pkts_inorder`` is used.
 
 *   For Tx: If in-order is enabled then ``virtio_xmit_pkts_inorder`` is used.
 
Signature · 1 line
2.17.1
Reviewed-by on v1 2/6
#4 lore raw

Re: [dpdk-dev] [PATCH 2/6] doc: fix typo in virtio in-order Rx function name

Quoted 11 lines · Tiwei Bie

The Rx function that will be used when in-order is enabled should be virtio_recv_mergeable_pkts_inorder() instead of virtio_xmit_pkts_inorder().

Fixes 8f3bd7e8702d ("net/virtio: add in-order Rx/Tx into selection")
---
 doc/guides/nics/virtio.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
author
#5 lore raw

PATCH 3/6 doc: update the description for in-order Rx path

In reply to Tiwei Bie

The virtio_recv_mergeable_pkts_inorder() has been renamed to virtio_recv_pkts_inorder() and added the non-mergeable support in below commit.

Fixes efcda13648d2 ("net/virtio: add non-mergeable support to in-order path")
---
 doc/guides/nics/virtio.rst | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)
doc/guides/nics/virtio.rst +3 -4
index 08438d064..b3c356856 100644
@@ -215,8 +215,8 @@ Rx callbacks:
    Vector version without mergeable Rx buffer support, also fixes the available
    ring indexes and uses vector instructions to optimize performance.
 
-#. ``virtio_recv_mergeable_pkts_inorder``:
-   In-order version with mergeable Rx buffer support.
+#. ``virtio_recv_pkts_inorder``:
+   In-order version with mergeable and non-mergeable Rx buffer support.
 
 Tx callbacks:
 
@@ -250,8 +250,7 @@ Example of using the vector version of the virtio poll mode driver in
 
 In-order callbacks only work on simulated virtio user vdev.
 
-*   For Rx: If mergeable Rx buffers is enabled and in-order is enabled then
-    ``virtio_recv_mergeable_pkts_inorder`` is used.
+*   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.
 
Signature · 1 line
2.17.1
Reviewed-by on v1 3/6
#6 lore raw

Re: [dpdk-dev] [PATCH 3/6] doc: update the description for in-order Rx path

Quoted 11 lines · Tiwei Bie

The virtio_recv_mergeable_pkts_inorder() has been renamed to virtio_recv_pkts_inorder() and added the non-mergeable support in below commit.

Fixes efcda13648d2 ("net/virtio: add non-mergeable support to in-order path")
---
 doc/guides/nics/virtio.rst | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)
author
#7 lore raw

PATCH 4/6 doc: document the devargs for virtio-user

In reply to Tiwei Bie

Document the devargs for virtio-user and also make it clear that these devargs are only available in virtio-user, i.e. not supported by the PCI virtio driver.

---
 doc/guides/nics/virtio.rst | 38 +++++++++++++++++++++++++++++++++++---
 1 file changed, 35 insertions(+), 3 deletions(-)
doc/guides/nics/virtio.rst +35 -3
index b3c356856..993e691f5 100644
@@ -322,7 +322,7 @@ Here we use l3fwd-power as an example to show how to get started.
 Virtio PMD arguments
 --------------------
 
-The user can specify below argument in devargs.
+Below devargs are supported by the PCI virtio driver:
 
 #.  ``vdpa``:
 
@@ -331,12 +331,44 @@ The user can specify below argument in devargs.
     a virtio device needs to work in vDPA mode.
     (Default: 0 (disabled))
 
-#. ``mrg_rxbuf``:
+Below devargs are supported by the virtio-user vdev:
+
+#.  ``path``:
+
+    It is used to specify a path to connect to vhost backend.
+
+#.  ``mac``:
+
+    It is used to specify the MAC address.
+
+#.  ``cq``:
+
+    It is used to enable the control queue. (Default: 0 (disabled))
+
+#.  ``queue_size``:
+
+    It is used to specify the queue size. (Default: 256)
+
+#.  ``queues``:
+
+    It is used to specify the queue number. (Default: 1)
+
+#.  ``iface``:
+
+    It is used to specify the host interface name for vhost-kernel
+    backend.
+
+#.  ``server``:
+
+    It is used to enable the server mode when using vhost-user backend.
+    (Default: 0 (disabled))
+
+#.  ``mrg_rxbuf``:
 
     It is used to enable virtio device mergeable Rx buffer feature.
     (Default: 1 (enabled))
 
-#. ``in_order``:
+#.  ``in_order``:
 
     It is used to enable virtio device in-order feature.
     (Default: 1 (enabled))
Signature · 1 line
2.17.1
Reviewed-by on v1 4/6
#8 lore raw

Re: [dpdk-dev] [PATCH 4/6] doc: document the devargs for virtio-user

Quoted 8 lines · Tiwei Bie

Document the devargs for virtio-user and also make it clear that these devargs are only available in virtio-user, i.e. not supported by the PCI virtio driver.

---
 doc/guides/nics/virtio.rst | 38 +++++++++++++++++++++++++++++++++++---
 1 file changed, 35 insertions(+), 3 deletions(-)
author
#9 lore raw

PATCH 5/6 doc: document packed virtqueue for virtio

In reply to Tiwei Bie

Document the packed virtqueue layout support in virtio net PMD.

---
 doc/guides/nics/virtio.rst | 63 ++++++++++++++++++++++++++++----------
 1 file changed, 47 insertions(+), 16 deletions(-)
doc/guides/nics/virtio.rst +47 -16
index 993e691f5..011954ff6 100644
@@ -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))
Signature · 1 line
2.17.1
Reviewed-by on v1 5/6
#10 lore raw

Re: [dpdk-dev] [PATCH 5/6] doc: document packed virtqueue for virtio

Quoted 127 lines · Tiwei Bie

Document the packed virtqueue layout support in virtio net PMD.

---
 doc/guides/nics/virtio.rst | 63 ++++++++++++++++++++++++++++----------
 1 file changed, 47 insertions(+), 16 deletions(-)
doc/guides/nics/virtio.rst +42 -16
index 993e691f5..011954ff6 100644
@@ -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
 --------------
 

doc/guides/nics/virtio.rst Below devargs are supported by the virtio-user vdev: · line 405

Quoted 8 lines
doc/guides/nics/virtio.rst +5 -0
@@ -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.

author
#11 lore raw

PATCH 6/6 doc: fix format for virtio guide

In reply to Tiwei Bie

This patch removes an unwanted empty line in a sentence.

Fixes 71afcefbd53e ("doc: update virtio ring size and header size")
---
 doc/guides/nics/virtio.rst | 1 -
 1 file changed, 1 deletion(-)
doc/guides/nics/virtio.rst +0 -1
index 011954ff6..bd0116176 100644
@@ -7,7 +7,6 @@ Poll Mode Driver for Emulated Virtio NIC
 Virtio is a para-virtualization framework initiated by IBM, and supported by KVM hypervisor.
 In the Data Plane Development Kit (DPDK),
 we provide a virtio Poll Mode Driver (PMD) as a software solution, comparing to SRIOV hardware solution,
-
 for fast guest VM to guest VM communication and guest VM to host communication.
 
 Vhost is a kernel acceleration module for virtio qemu backend.
Signature · 1 line
2.17.1
Reviewed-by on v1 6/6
#12 lore raw

Re: [dpdk-dev] [PATCH 6/6] doc: fix format for virtio guide

Quoted 16 lines · Tiwei Bie

This patch removes an unwanted empty line in a sentence.

Fixes 71afcefbd53e ("doc: update virtio ring size and header size")
---
 doc/guides/nics/virtio.rst | 1 -
 1 file changed, 1 deletion(-)
doc/guides/nics/virtio.rst +0 -0
index 011954ff6..bd0116176 100644

doc/guides/nics/virtio.rst Poll Mode Driver for Emulated Virtio NIC · line 12

Quoted 7 lines
doc/guides/nics/virtio.rst +0 -1
@@ -7,7 +7,6 @@ Poll Mode Driver for Emulated Virtio NIC
 Virtio is a para-virtualization framework initiated by IBM, and supported by KVM hypervisor.
 In the Data Plane Development Kit (DPDK),
 we provide a virtio Poll Mode Driver (PMD) as a software solution, comparing to SRIOV hardware solution,
-
 for fast guest VM to guest VM communication and guest VM to host communication.
 
 Vhost is a kernel acceleration module for virtio qemu backend.
#13 lore raw
In reply to Tiwei Bie
Quoted 8 lines · Tiwei Bie

Tiwei Bie (6):
net/virtio: remove remaining simple Tx related stuff
doc: fix typo in virtio in-order Rx function name
doc: update the description for in-order Rx path
doc: document the devargs for virtio-user
doc: document packed virtqueue for virtio
doc: fix format for virtio guide

Quoted 4 lines
 doc/guides/nics/virtio.rst         | 118 ++++++++++++++++++++---------
 drivers/net/virtio/virtio_ethdev.h |   3 -
 2 files changed, 84 insertions(+), 37 deletions(-)

Series applied to dpdk-next-virtio.

Thanks for taking care of the doc!
Maxime