From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
by inbox.dpdk.org (Postfix) with ESMTP id 6D630A0553;
Fri, 10 Jun 2022 17:36:07 +0200 (CEST)
Received: from [217.70.189.124] (localhost [127.0.0.1])
by mails.dpdk.org (Postfix) with ESMTP id 328B142B6C;
Fri, 10 Jun 2022 17:36:00 +0200 (CEST)
Received: from mga04.intel.com (mga04.intel.com [192.55.52.120])
by mails.dpdk.org (Postfix) with ESMTP id 4185C42B6C
for <dev@dpdk.org>; Fri, 10 Jun 2022 17:35:58 +0200 (CEST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple;
d=intel.com; i=@intel.com; q=dns/txt; s=Intel;
t=1654875358; x=1686411358;
h=from:to:cc:subject:date:message-id:in-reply-to:
references:mime-version:content-transfer-encoding;
bh=CMc4LufIXW6efKJTm//sSVSO7PVgBMdOuyNeLRYUgqo=;
b=hIcan9JYpOPoxIeHvYPkb7cY7v3m9FoxcMz/L+6zdZhmyf8d2lgNdhFk
WLa98VFkRaoDipVZZPhz1MNef6XndkvVVpY/wwojBl5h1DzaJZnMZF0Ej
iCDXTgmjrl/QkJXga8UiU9jcBpRiwttHODjqvmDpAwYuF6MH3KyEoldy5
ovyNgN3an7LRGz9WyYf8+xgmjLsRZou9paynag7ISZMaBFYxKdygw/RXr
ZTn14i3vk83NkzU5UgZboot0bJ86q85dbvDxPBLGMlz+y0TW2lO1M1GQR
Zk1z1PyP+Y6rVdCew2ENdIx9thVujWBSJlHf/34gHpwE4vu0MBIUa2JsN w==;
X-IronPort-AV: E=McAfee;i="6400,9594,10374"; a="276439978"
X-IronPort-AV: E=Sophos;i="5.91,290,1647327600"; d="scan'208";a="276439978"
Received: from orsmga008.jf.intel.com ([10.7.209.65])
by fmsmga104.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;
10 Jun 2022 08:35:57 -0700
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.91,290,1647327600"; d="scan'208";a="610761251"
Received: from silpixa00401385.ir.intel.com (HELO
silpixa00401385.ger.corp.intel.com.) ([10.237.223.181])
by orsmga008.jf.intel.com with ESMTP; 10 Jun 2022 08:35:56 -0700
From: Bruce Richardson <bruce.richardson@intel.com>
To: dev@dpdk.org
Cc: Maxime Coquelin <maxime.coquelin@redhat.com>,
Chenbo Xia <chenbo.xia@intel.com>,
Bruce Richardson <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
Date: Fri, 10 Jun 2022 16:35:34 +0100
Message-Id: <20220610153535.659076-4-bruce.richardson@intel.com>
X-Mailer: git-send-email 2.34.1
In-Reply-To: <20220610153535.659076-1-bruce.richardson@intel.com>
References: <20220527162659.129022-1-bruce.richardson@intel.com>
<20220610153535.659076-1-bruce.richardson@intel.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
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#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.
--
2.34.1