diff mbox series

[v3,3/4] doc/howto: add code example to virtio-user exception path doc

Message ID 20220610153535.659076-4-bruce.richardson@intel.com (mailing list archive)
State Accepted, archived
Delegated to: Maxime Coquelin
Headers show
Series Enhance docs on virtio-user as KNI replacement | expand

Checks

Context Check Description
ci/checkpatch success coding style OK

Commit Message

Bruce Richardson June 10, 2022, 3:35 p.m. UTC
The HOWTO guide for using virtio-user as an exception path to the kernel
only provided an example of how testpmd may be used for that purpose.
However, a real application wanting to use virtio-user as exception path
would likely want to create such devices from code within the app
itself. Therefore, we update the doc with instructions and a code
snippet showing how this may be done.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Stephen Hemminger <stephen@networkplumber.org>
---
 .../howto/virtio_user_as_exception_path.rst   | 55 +++++++++++++++++++
 1 file changed, 55 insertions(+)

--
2.34.1

Comments

Xia, Chenbo June 15, 2022, 1:47 a.m. UTC | #1
> -----Original Message-----
> From: Richardson, Bruce <bruce.richardson@intel.com>
> Sent: Friday, June 10, 2022 11:36 PM
> To: dev@dpdk.org
> Cc: Maxime Coquelin <maxime.coquelin@redhat.com>; Xia, Chenbo
> <chenbo.xia@intel.com>; Richardson, Bruce <bruce.richardson@intel.com>;
> Stephen Hemminger <stephen@networkplumber.org>
> Subject: [PATCH v3 3/4] doc/howto: add code example to virtio-user
> exception path doc
> 
> The HOWTO guide for using virtio-user as an exception path to the kernel
> only provided an example of how testpmd may be used for that purpose.
> However, a real application wanting to use virtio-user as exception path
> would likely want to create such devices from code within the app
> itself. Therefore, we update the doc with instructions and a code
> snippet showing how this may be done.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> Acked-by: Stephen Hemminger <stephen@networkplumber.org>
> ---
>  .../howto/virtio_user_as_exception_path.rst   | 55 +++++++++++++++++++
>  1 file changed, 55 insertions(+)
> 
> diff --git a/doc/guides/howto/virtio_user_as_exception_path.rst
> b/doc/guides/howto/virtio_user_as_exception_path.rst
> index a7f0d366fe..2af1778578 100644
> --- a/doc/guides/howto/virtio_user_as_exception_path.rst
> +++ b/doc/guides/howto/virtio_user_as_exception_path.rst
> @@ -157,3 +157,58 @@ For example:
>          /path/to/dpdk-testpmd --vdev=virtio_user0,path=/dev/vhost-
> net,queues=2,queue_size=1024 -- \
>              -i --tx-offloads=0x002c --enable-lro --txq=2 --rxq=2 --
> txd=1024 --rxd=1024
> 
> +
> +Creating Virtio-User Ports within an Application
> +------------------------------------------------
> +
> +To use virtio-user ports within an application,
> +it is not necessary to explicitly initialize those ports using EAL
> arguments at startup.
> +Instead, one can use the generic EAL API
> +`rte_eal_hotplug_add
> <https://doc.dpdk.org/api/rte__dev_8h.html#ad32e8eebf1f81ef9f290cb296b0c90
> bb>`_
> +function to create a new instance at startup.
> +For example, to create a basic virtio-user port, the following code could
> be used:
> +
> +.. code-block:: C
> +
> +   rte_eal_hotplug_add("vdev", "virtio_user0", "path=/dev/vhost-net");
> +
> +A fuller code example is shown below, where a virtio-user port, and hence
> kernel netdev,
> +is created for each NIC port discovered by DPDK.
> +Each virtio-user port is given the MAC address of its matching physical
> port
> +(assuming app was run without vdev args on commandline, so all ports
> auto-discovered are HW ones).
> +These new virtio-user netdevs will appear in the kernel port listings as
> ``virtio_user0``,
> +``virtio_user1``, etc.,
> +based on the names passed in as ``iface=`` via the ``portargs`` parameter.
> +
> +.. code-block:: C
> +
> +    nb_ports = rte_eth_dev_count_avail();
> +
> +    /* Create a vhost_user port for each physical port */
> +    unsigned port_count = 0;
> +    RTE_ETH_FOREACH_DEV(portid) {
> +        char portname[32];
> +        char portargs[256];
> +        struct rte_ether_addr addr = {0};
> +
> +        /* don't create virtio_user ports for other virtio_user ports */
> +        if (++port_count > nb_ports)
> +            break;
> +
> +        /* get mac address of physical port to use as mac of virtio_user
> port */
> +        rte_eth_macaddr_get(portid, &addr);
> +
> +        /* set the name and arguments */
> +        snprintf(portname, sizeof(portname), "virtio_user%u", portid);
> +        snprintf(portargs, sizeof(portargs),
> +                "path=/dev/vhost-
> net,queues=1,queue_size=%u,iface=%s,mac=" RTE_ETHER_ADDR_PRT_FMT,
> +                RX_RING_SIZE, portname, RTE_ETHER_ADDR_BYTES(&addr));
> +
> +        /* add the vdev for virtio_user */
> +        if (rte_eal_hotplug_add("vdev", portname, portargs) < 0)
> +            rte_exit(EXIT_FAILURE, "Cannot create paired port for
> port %u\n", portid);
> +
> +    }
> +
> +Once these virtio-user ports have been created in the loop, all ports,
> both physical and virtual,
> +may be initialized and used as normal in the application.
> --
> 2.34.1

Acked-by: Chenbo Xia <chenbo.xia@intel.com>
Maxime Coquelin July 7, 2022, 3:50 p.m. UTC | #2
On 6/10/22 17:35, Bruce Richardson wrote:
> The HOWTO guide for using virtio-user as an exception path to the kernel
> only provided an example of how testpmd may be used for that purpose.
> However, a real application wanting to use virtio-user as exception path
> would likely want to create such devices from code within the app
> itself. Therefore, we update the doc with instructions and a code
> snippet showing how this may be done.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> Acked-by: Stephen Hemminger <stephen@networkplumber.org>
> ---
>   .../howto/virtio_user_as_exception_path.rst   | 55 +++++++++++++++++++
>   1 file changed, 55 insertions(+)
> 

Nice addition!

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

Thanks,
Maxime
diff mbox series

Patch

diff --git a/doc/guides/howto/virtio_user_as_exception_path.rst b/doc/guides/howto/virtio_user_as_exception_path.rst
index a7f0d366fe..2af1778578 100644
--- a/doc/guides/howto/virtio_user_as_exception_path.rst
+++ b/doc/guides/howto/virtio_user_as_exception_path.rst
@@ -157,3 +157,58 @@  For example:
         /path/to/dpdk-testpmd --vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 -- \
             -i --tx-offloads=0x002c --enable-lro --txq=2 --rxq=2 --txd=1024 --rxd=1024

+
+Creating Virtio-User Ports within an Application
+------------------------------------------------
+
+To use virtio-user ports within an application,
+it is not necessary to explicitly initialize those ports using EAL arguments at startup.
+Instead, one can use the generic EAL API
+`rte_eal_hotplug_add <https://doc.dpdk.org/api/rte__dev_8h.html#ad32e8eebf1f81ef9f290cb296b0c90bb>`_
+function to create a new instance at startup.
+For example, to create a basic virtio-user port, the following code could be used:
+
+.. code-block:: C
+
+   rte_eal_hotplug_add("vdev", "virtio_user0", "path=/dev/vhost-net");
+
+A fuller code example is shown below, where a virtio-user port, and hence kernel netdev,
+is created for each NIC port discovered by DPDK.
+Each virtio-user port is given the MAC address of its matching physical port
+(assuming app was run without vdev args on commandline, so all ports auto-discovered are HW ones).
+These new virtio-user netdevs will appear in the kernel port listings as ``virtio_user0``,
+``virtio_user1``, etc.,
+based on the names passed in as ``iface=`` via the ``portargs`` parameter.
+
+.. code-block:: C
+
+    nb_ports = rte_eth_dev_count_avail();
+
+    /* Create a vhost_user port for each physical port */
+    unsigned port_count = 0;
+    RTE_ETH_FOREACH_DEV(portid) {
+        char portname[32];
+        char portargs[256];
+        struct rte_ether_addr addr = {0};
+
+        /* don't create virtio_user ports for other virtio_user ports */
+        if (++port_count > nb_ports)
+            break;
+
+        /* get mac address of physical port to use as mac of virtio_user port */
+        rte_eth_macaddr_get(portid, &addr);
+
+        /* set the name and arguments */
+        snprintf(portname, sizeof(portname), "virtio_user%u", portid);
+        snprintf(portargs, sizeof(portargs),
+                "path=/dev/vhost-net,queues=1,queue_size=%u,iface=%s,mac=" RTE_ETHER_ADDR_PRT_FMT,
+                RX_RING_SIZE, portname, RTE_ETHER_ADDR_BYTES(&addr));
+
+        /* add the vdev for virtio_user */
+        if (rte_eal_hotplug_add("vdev", portname, portargs) < 0)
+            rte_exit(EXIT_FAILURE, "Cannot create paired port for port %u\n", portid);
+
+    }
+
+Once these virtio-user ports have been created in the loop, all ports, both physical and virtual,
+may be initialized and used as normal in the application.