[v2,2/2] doc/howto: add code example to virtio-user exception path doc
Checks
Commit Message
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>
---
v2: fix http link to https
---
.../howto/virtio_user_as_exceptional_path.rst | 55 +++++++++++++++++++
1 file changed, 55 insertions(+)
Comments
On Fri, 27 May 2022 17:36:43 +0100
Bruce Richardson <bruce.richardson@intel.com> 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>
> -----Original Message-----
> From: Richardson, Bruce <bruce.richardson@intel.com>
> Sent: Saturday, May 28, 2022 12:37 AM
> To: dev@dpdk.org
> Cc: Maxime Coquelin <maxime.coquelin@redhat.com>; Xia, Chenbo
> <chenbo.xia@intel.com>; Richardson, Bruce <bruce.richardson@intel.com>
> Subject: [PATCH v2 2/2] 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>
>
> ---
>
> v2: fix http link to https
> ---
> .../howto/virtio_user_as_exceptional_path.rst | 55 +++++++++++++++++++
> 1 file changed, 55 insertions(+)
>
> diff --git a/doc/guides/howto/virtio_user_as_exceptional_path.rst
> b/doc/guides/howto/virtio_user_as_exceptional_path.rst
> index 100376c32d..45d4ebd284 100644
> --- a/doc/guides/howto/virtio_user_as_exceptional_path.rst
> +++ b/doc/guides/howto/virtio_user_as_exceptional_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``,
You mean vhost_tap netdev here? Or?
Thanks,
Chenbo
> +``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
On Mon, May 30, 2022 at 06:44:27AM +0100, Xia, Chenbo wrote:
> > -----Original Message-----
> > From: Richardson, Bruce <bruce.richardson@intel.com>
> > Sent: Saturday, May 28, 2022 12:37 AM
> > To: dev@dpdk.org
> > Cc: Maxime Coquelin <maxime.coquelin@redhat.com>; Xia, Chenbo
> > <chenbo.xia@intel.com>; Richardson, Bruce <bruce.richardson@intel.com>
> > Subject: [PATCH v2 2/2] 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>
> >
> > ---
> >
> > v2: fix http link to https
> > ---
> > .../howto/virtio_user_as_exceptional_path.rst | 55 +++++++++++++++++++
> > 1 file changed, 55 insertions(+)
> >
> > diff --git a/doc/guides/howto/virtio_user_as_exceptional_path.rst
> > b/doc/guides/howto/virtio_user_as_exceptional_path.rst
> > index 100376c32d..45d4ebd284 100644
> > --- a/doc/guides/howto/virtio_user_as_exceptional_path.rst
> > +++ b/doc/guides/howto/virtio_user_as_exceptional_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``,
>
> You mean vhost_tap netdev here? Or?
>
Yes, I am referring to the vhost tap port. If you look at the code below,
the parameters provide the name of the kernel netdev to be the same as the
name of the vdev created, meaning any ports will appear as "vhost_user0",
"vhost_user1" etc. in your ip-link/ifconfig listings.
/Bruce
>
> > +``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
>
@@ -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.