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 DA1F4A0545;
Fri, 27 May 2022 18:36:56 +0200 (CEST)
Received: from [217.70.189.124] (localhost [127.0.0.1])
by mails.dpdk.org (Postfix) with ESMTP id 15E99427F6;
Fri, 27 May 2022 18:36:54 +0200 (CEST)
Received: from mga02.intel.com (mga02.intel.com [134.134.136.20])
by mails.dpdk.org (Postfix) with ESMTP id F414A427F5
for <dev@dpdk.org>; Fri, 27 May 2022 18:36:51 +0200 (CEST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple;
d=intel.com; i=@intel.com; q=dns/txt; s=Intel;
t=1653669412; x=1685205412;
h=from:to:cc:subject:date:message-id:in-reply-to:
references:mime-version:content-transfer-encoding;
bh=qzPht+Y7EtZyl9Z84/LBapQGKSTxoA7jjd3k6xmTgfk=;
b=Yit3eZTK6EM/QzNm0FyVPQd69TJxFlzFfGMP+m3Hlw2hyQymrkiTmOiB
eno0gmdWFOECvfiMFXKwg4c1bAMEHX+pWlwZEd7/neOH8/NZ2OLuIUnDJ
ddf0/y9d0qgYCptW3x2vGjA+JgJMnnDE8XU8YWYROl2+bi3OUg+RUz7oy
dnCMkQuI9WRdqEulaYkgCzRoFXK+vnjavj8Tl8ARg7nMIiIkGU4z5GirU
MsDQOlXtOo1t7JsuOjade7nRaYciNOWTIRYhhqXW0YmtQVy7AsQjTA+n0
Otpghivo6KuTUjgYqBgAIGhhSsH33By6WmYsPEW2Oam3sStJ0rrmF7+W/ w==;
X-IronPort-AV: E=McAfee;i="6400,9594,10360"; a="262139748"
X-IronPort-AV: E=Sophos;i="5.91,256,1647327600"; d="scan'208";a="262139748"
Received: from orsmga007.jf.intel.com ([10.7.209.58])
by orsmga101.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;
27 May 2022 09:36:51 -0700
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.91,256,1647327600"; d="scan'208";a="574920063"
Received: from silpixa00401385.ir.intel.com (HELO
silpixa00401385.ger.corp.intel.com) ([10.237.222.171])
by orsmga007.jf.intel.com with ESMTP; 27 May 2022 09:36:50 -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>
Subject: [PATCH v2 2/2] doc/howto: add code example to virtio-user exception
path doc
Date: Fri, 27 May 2022 17:36:43 +0100
Message-Id: <20220527163643.130679-2-bruce.richardson@intel.com>
X-Mailer: git-send-email 2.34.1
In-Reply-To: <20220527163643.130679-1-bruce.richardson@intel.com>
References: <20220527162659.129022-1-bruce.richardson@intel.com>
<20220527163643.130679-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>
---
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#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