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 100FDA0548;
	Wed, 15 Jun 2022 03:44:57 +0200 (CEST)
Received: from [217.70.189.124] (localhost [127.0.0.1])
	by mails.dpdk.org (Postfix) with ESMTP id E9B8040222;
	Wed, 15 Jun 2022 03:44:56 +0200 (CEST)
Received: from mga18.intel.com (mga18.intel.com [134.134.136.126])
 by mails.dpdk.org (Postfix) with ESMTP id 39A6D40220;
 Wed, 15 Jun 2022 03:44:55 +0200 (CEST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple;
 d=intel.com; i=@intel.com; q=dns/txt; s=Intel;
 t=1655257495; x=1686793495;
 h=from:to:cc:subject:date:message-id:references:
 in-reply-to:content-transfer-encoding:mime-version;
 bh=iZm+cwFvP+GjjWH7118RMAD/06hW+2u128aNzasXUcU=;
 b=IC7RBOyD6WpySrH2ucB9m8kMP+RJzM7UwqwOB/rMHIqQmaogif7B0nYS
 Ulgqzz+B60SLbU73QVe90iwaDuIu2PcFMJk/B9INkJggrTNj+yAwe5f8r
 1XMI1GUcdtovFEefSQ4NMu4dAdT+3JGuFP9lmCzTkn7beXbSHMC863MVn
 L2hoOxDyO0l0dsW2MHiAoVsMcQZy/vJzJjT8PAfNpuHXcP/yz7MWK1E1C
 tZnkHziub5MBidMR7TtxdR+wQiqLAiFpE7QkYq7u352nAS2i9BYhwUYa7
 ZotMGyNvH0J3Y4rWm4AjtV37ymibnkFQDBydSetkdsqQeCTNdMfQDTiPk g==;
X-IronPort-AV: E=McAfee;i="6400,9594,10378"; a="261827138"
X-IronPort-AV: E=Sophos;i="5.91,300,1647327600"; d="scan'208";a="261827138"
Received: from orsmga005.jf.intel.com ([10.7.209.41])
 by orsmga106.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;
 14 Jun 2022 18:44:54 -0700
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.91,300,1647327600"; d="scan'208";a="762227461"
Received: from fmsmsx601.amr.corp.intel.com ([10.18.126.81])
 by orsmga005.jf.intel.com with ESMTP; 14 Jun 2022 18:44:54 -0700
Received: from fmsmsx608.amr.corp.intel.com (10.18.126.88) by
 fmsmsx601.amr.corp.intel.com (10.18.126.81) with Microsoft SMTP Server
 (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id
 15.1.2308.27; Tue, 14 Jun 2022 18:44:53 -0700
Received: from fmsmsx612.amr.corp.intel.com (10.18.126.92) by
 fmsmsx608.amr.corp.intel.com (10.18.126.88) with Microsoft SMTP Server
 (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id
 15.1.2308.27; Tue, 14 Jun 2022 18:44:53 -0700
Received: from fmsedg601.ED.cps.intel.com (10.1.192.135) by
 fmsmsx612.amr.corp.intel.com (10.18.126.92) with Microsoft SMTP Server
 (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id
 15.1.2308.27 via Frontend Transport; Tue, 14 Jun 2022 18:44:53 -0700
Received: from NAM12-DM6-obe.outbound.protection.outlook.com (104.47.59.175)
 by edgegateway.intel.com (192.55.55.70) with Microsoft SMTP Server
 (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id
 15.1.2308.27; Tue, 14 Jun 2022 18:44:52 -0700
ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none;
 b=IrHUVmxlLMaXFdcXUzB2Ik4OvkSsS5Df50oK584oxrsHBkNnE8v2tuMAKvt02pZsZls+naSjGKAo9K3aQivNOSQEfJOn3c49F6PyRoeWyVzVTFIwMOvAIXcz08fQWZ/LRwhfb9JiCz/8Pzqmvl8ajPNwaKoWeLZ6cgsjb/NzSM3dGyImyNoMbHmcMAWUmDVz/6CN6bRbNsWToZT7Z7YRpROzDWMQhrVFyLP0uWLWqB97GUhfownkzgrw6jGsF/h6e1GKA19i5GuL6XcdFw+91JWHHJjda8fi016rVZctU/En28UgGnt6Fo1oN9q38TgDzA/nR6UBn4UaGDKIYHaUXw==
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; 
 s=arcselector9901;
 h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1;
 bh=Q32d+RAEStdMPuHD35EF1h886I+2Tafwir3Z67C8fx0=;
 b=TRQuwQf4PkhpGfunjkYPBdcHUNRuCxlCOS8TaN47OhMcK6+AzdxcyfguWDj4lSlpvIX98vL+hyitqNHU92IRcxbZV3Z974Wfy73cuYp99XYEzuez2LgIuOc6nt/BX3ri8nBo/3yyn6Jk011so2kc9u7pUtEi5mP5jiWWJjrtsS6P7hja4phsUbVDvA/Dhqni11F04nJu6SFQxYYaZl4gKiC5ulV5PanMCWQzpoOyroAXq1VSjF9NtVJC/oLROvH1Cx4oqVPttPQyas1L/mdJEKB5GcFUF1PBwQN9rJQjkjuPkYx9hJEqqZgSlxqiL70ghkA+Wyd7Uv1/w6WitJuwew==
ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass
 smtp.mailfrom=intel.com; dmarc=pass action=none header.from=intel.com;
 dkim=pass header.d=intel.com; arc=none
Received: from SN6PR11MB3504.namprd11.prod.outlook.com (2603:10b6:805:d0::17)
 by MWHPR1101MB2365.namprd11.prod.outlook.com (2603:10b6:300:74::12)
 with Microsoft SMTP Server (version=TLS1_2,
 cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5332.13; Wed, 15 Jun
 2022 01:44:45 +0000
Received: from SN6PR11MB3504.namprd11.prod.outlook.com
 ([fe80::54a0:2dbc:18b7:2aa9]) by SN6PR11MB3504.namprd11.prod.outlook.com
 ([fe80::54a0:2dbc:18b7:2aa9%7]) with mapi id 15.20.5332.020; Wed, 15 Jun 2022
 01:44:45 +0000
From: "Xia, Chenbo" <chenbo.xia@intel.com>
To: "Richardson, Bruce" <bruce.richardson@intel.com>, "dev@dpdk.org"
 <dev@dpdk.org>
CC: Maxime Coquelin <maxime.coquelin@redhat.com>, "stable@dpdk.org"
 <stable@dpdk.org>
Subject: RE: [PATCH v3 1/4] doc/howto: rework section on virtio-user as
 exception path
Thread-Topic: [PATCH v3 1/4] doc/howto: rework section on virtio-user as
 exception path
Thread-Index: AQHYfN/C2Vc5bW1KC0a3v2zNZby4Na1PuKxQ
Date: Wed, 15 Jun 2022 01:44:45 +0000
Message-ID: <SN6PR11MB35041853BA10D8840B3EB8869CAD9@SN6PR11MB3504.namprd11.prod.outlook.com>
References: <20220527162659.129022-1-bruce.richardson@intel.com>
 <20220610153535.659076-1-bruce.richardson@intel.com>
 <20220610153535.659076-2-bruce.richardson@intel.com>
In-Reply-To: <20220610153535.659076-2-bruce.richardson@intel.com>
Accept-Language: en-US, zh-CN
Content-Language: en-US
X-MS-Has-Attach: 
X-MS-TNEF-Correlator: 
authentication-results: dkim=none (message not signed)
 header.d=none;dmarc=none action=none header.from=intel.com;
x-ms-publictraffictype: Email
x-ms-office365-filtering-correlation-id: 10bafe86-5027-429d-c756-08da4e70a019
x-ms-traffictypediagnostic: MWHPR1101MB2365:EE_
x-ld-processed: 46c98d88-e344-4ed4-8496-4ed7712e255d,ExtAddr
x-microsoft-antispam-prvs: <MWHPR1101MB2365595D7E1D7F1A4D7374C09CAD9@MWHPR1101MB2365.namprd11.prod.outlook.com>
x-ms-exchange-senderadcheck: 1
x-ms-exchange-antispam-relay: 0
x-microsoft-antispam: BCL:0;
x-microsoft-antispam-message-info: q22IOFsbBWWwDgNVdtajiMbrwyh7GGk0ilu/mgt2j7DLNatmzsOGVhs4wvSzalCN/zbDvrY1AgLyHScPkA5pihMfdpIih/d5Y69SNI9cBxjfFj4i/WboN6ewraslFyPqAHtoPXTUsD3ZBJKCdNgXXT8WIcVLWZp29HI6EUcszr1aOWNDtR8HLZe23KEclXKcSzrbsSUXDinq/BL0GJ5slrl/7xfdJOxH7i/PHJeMX15M0TCEOH91MawvvHIQRMUeu9tMu/ghIJKOgEiJRot7L6zcHGyVgK9CC5P/SmjQ9MlVvVwO7LSGvArtNyxVj0quD4MB2DGdHZuh9dgahhDHn7h3duu6HLnHwrJKfszbDM6Wjo0niU+2LrGxYT/ZVMS3Wr57tJwB9HK7kzBkG+Ba0xG12lZNiSmWuP4R38d/Qx1NBaRuGY5ZPXY8Q17EtPvtLyRRylv6QFNEETXZfvkFvuKUQHbdHgx8SAbXUMLFtJxHTtfOlai/hZ5EJao3jneaCS8salEERRyi8RTek46ylnE0a28WDdIqAne2pflkfMxOurfullS9lblfT4TCUIZk5Y5Yo4nmsjKLQoz2pkWHOIySsPpaZ7t6zDlBKnaxtePLS2+bkXaUzQX0f8ZwI0/P33c/IY1jofuv22oR6fhZqP1z2V6uP9lMRHOEbUK+sNntLNP4+tziOwpZPTHUnoQ51RCR76HjcepWUMyQBfcDaer7wNtiCchbqofvNDYJRbCkNUXRN9RQwLJP/7jWsBFZOECc9rK5W80tMYbU4WBxZPwZHgW1B24L1dD9zev/u6c=
x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:;
 IPV:NLI; SFV:NSPM; H:SN6PR11MB3504.namprd11.prod.outlook.com; PTR:; CAT:NONE;
 SFS:(13230016)(366004)(52536014)(9686003)(30864003)(7696005)(6506007)(26005)(8936002)(53546011)(54906003)(71200400001)(64756008)(4326008)(110136005)(66946007)(66446008)(76116006)(8676002)(5660300002)(66556008)(66476007)(38070700005)(316002)(86362001)(82960400001)(508600001)(122000001)(186003)(83380400001)(2906002)(33656002)(38100700002)(55016003);
 DIR:OUT; SFP:1102; 
x-ms-exchange-antispam-messagedata-chunkcount: 1
x-ms-exchange-antispam-messagedata-0: =?us-ascii?Q?RsUjBNACNjmtWBs4qGzGjmmBNKRFuPR/itdoVBSIyuYTTfJ4Pb4DrUsEGCtV?=
 =?us-ascii?Q?QsiySPAeN0lRX0ynTKy5izputMNK+PsRhOxlJyFRI85/KX9Sd+y/IkPKyaP3?=
 =?us-ascii?Q?Bjv1TVnByNRxvtzEuADc2S8Mi7eepyRQWhIsXC0+xiSo74chY33AqG+BPSzD?=
 =?us-ascii?Q?7QWa7mXvgrkWN6LDiEibl14OdLSHpOaIJD88aOHwJZtJDg2XQ2xEAQhbW3x4?=
 =?us-ascii?Q?M/iK6UYo8zvUDSe6VHutnVtAQnvKCkl2zdoMN6EevAO01cPp+7Lpsu6uqbwh?=
 =?us-ascii?Q?0UrC/GdiUgMYGYMhRkdvT/MPGyQTZbC8ipvsuzJsSjp2MdRLU8U0fpJ/JdHO?=
 =?us-ascii?Q?C6DGelXTCvgpVIgqOv+mUYFAGgvoHX2UqDXeku+G6Ef7zMKfusLrBN+dnGI3?=
 =?us-ascii?Q?3aiQEaJAkWi6AvoA2CTJ6Szag1llTkEq4lc6AomHleZn4YSmlPLRod6zdLaG?=
 =?us-ascii?Q?62Q5dupKL6QhiER2MiSBVtSdIRA3irXNWwILhVERejus7Q6HzpRARQQKFYLd?=
 =?us-ascii?Q?2RcFhTQrAsIJBa53p3HkTA9tskP0TijZZ5T89vJ04AjgzQ+kuIkTcJZEqDX2?=
 =?us-ascii?Q?ba5jRQysRMEVH6SeqRVcIXi9teWFNaJlyCvpLjHjo0o2xhy/m+ZC4FcaWgXb?=
 =?us-ascii?Q?F0SYEWpO/dPalFZcMUH6EcT7lVJy8Qf6LmiltZu4HK0bz1dEGCTkd2vXtHsj?=
 =?us-ascii?Q?U231w753iQQIv8WW8UZeYgs0AcGn6iVdvg5dIsDb5RPd6IsXkPtQEa5HaAqI?=
 =?us-ascii?Q?Il59YRGctgBC54+Pd7tpTDXjyXogGTmry3WLIj0zcmcUIpyJeVspBbZ2EJLK?=
 =?us-ascii?Q?YEEpxRDW/Q8EuiU50bMiLHLO8hKofCwap2eByWf0zHtZmB/Z5Sws6v0nldne?=
 =?us-ascii?Q?BmI9XIlDxpJdGX4VLVYNHDcSCbXSOHRIlkniLQvZZ/6lxUudyQvWkjY5Ojj3?=
 =?us-ascii?Q?QXLkQiMn0/AU+Q/8Ml26KeXOsCL/NOaRmg9Zc9KGPm74ABnXs9UdfdbFCdyE?=
 =?us-ascii?Q?xbwlIhnYhhb7p8OfkxLb6w+0B+RjGqiqWVGCLdWPxP3PVsgOO9sKjTcY1SGc?=
 =?us-ascii?Q?1Xf2bqPEwjYsiyEbeiKzyKm90hjTNzv96eil3YAIV/citj89gq4KYVM4l4bM?=
 =?us-ascii?Q?PyzLjy4UX3L7LsqMO96xQhQ1M0Rt86EkW6NdqsfV1Lmoq64e/onAsZ+FTGTR?=
 =?us-ascii?Q?OrGP98Pn7+hzRH381OAf0oBJS9h73eonO0SeM6cD/DO+D60XIPy/f5rLM6el?=
 =?us-ascii?Q?DNQnHP3nOnbYBzPFBgz5+FEK4+4JTwarwDQH92JtSC6lVjaYlZtX0MO+PwsR?=
 =?us-ascii?Q?DhwQkQ3TMTRO0pF33SID1C3a+/BIiyW1yl/5+JHdWlCLOb+bSBnODfWfhu47?=
 =?us-ascii?Q?wPPoNGRvsreMMAD8s7Lxlggbp/er9ps7Y9yseJz7Q0pfHp+JUGbS3i9Dp85y?=
 =?us-ascii?Q?EIhup98VD4MMOlw0Yqd7yCjak2skM+reE+rXcYx8ZKQSduhjcs9enTu/PF6N?=
 =?us-ascii?Q?14Kq4sMMY4IFP83qe6k2MB9Ne4gzMg1VwIWrdZRrStLffrr9rckKbtPZGumy?=
 =?us-ascii?Q?X4VnNNNb12IRZU498qFqQnjq2Z57k30qPR/HPfjE8WmRewDIWRhRh+NdwPP5?=
 =?us-ascii?Q?eTCYxs6zZbUwBcu69WNBclX0ACpwpiL/T8Q3qA3gDOOIlyXBX4PTD55tPWFJ?=
 =?us-ascii?Q?l5qRaUeWZ2ZnS88RHpA9zzzaIYVWxgwtR3Fb6efwHcrx3X29LQts2PyfVBe9?=
 =?us-ascii?Q?DAuB44yBLg=3D=3D?=
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-AuthSource: SN6PR11MB3504.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 10bafe86-5027-429d-c756-08da4e70a019
X-MS-Exchange-CrossTenant-originalarrivaltime: 15 Jun 2022 01:44:45.5537 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: 46c98d88-e344-4ed4-8496-4ed7712e255d
X-MS-Exchange-CrossTenant-mailboxtype: HOSTED
X-MS-Exchange-CrossTenant-userprincipalname: CEmap1Yu3X1AKo8eLqkHMUG5+4H9OfFS/8FyqJQ5DUTmzYxd1QDEJOk7FVn7uPFraXC9PiIu1JepAHtpyppYZA==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: MWHPR1101MB2365
X-OriginatorOrg: intel.com
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

Hi Bruce,

> -----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>;
> stable@dpdk.org
> Subject: [PATCH v3 1/4] doc/howto: rework section on virtio-user as
> exception path
>=20
> This patch extensively reworks the howto guide on using virtio-user for
> exception packets. Changes include:
>=20
> * rename "exceptional path" to "exception path"
> * remove references to uio and just reference vfio-pci
> * simplify testpmd command-lines, giving a basic usage example first
>   before adding on detail about checksum or TSO parameters
> * give a complete working example showing traffic flowing through the
>   whole system from a testpmd loopback using the created TAP netdev
> * replace use of "ifconfig" with Linux standard "ip" command
> * other general rewording.
>=20
> CC: stable@dpdk.org

Not sure you want to backport or not as there's no fixes tag.

For this patch:

Acked-by: Chenbo Xia <chenbo.xia@intel.com>

>=20
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
>=20
> ---
> V3:
> * fix error reported by Chenbo on review.
> * add stable on CC, since this rework could be applicable for older
>   releases too, if desired for backport.
> ---
>  .../howto/virtio_user_as_exceptional_path.rst | 159 +++++++++++-------
>  1 file changed, 100 insertions(+), 59 deletions(-)
>=20
> diff --git a/doc/guides/howto/virtio_user_as_exceptional_path.rst
> b/doc/guides/howto/virtio_user_as_exceptional_path.rst
> index ec021af399..3d3d1b1219 100644
> --- a/doc/guides/howto/virtio_user_as_exceptional_path.rst
> +++ b/doc/guides/howto/virtio_user_as_exceptional_path.rst
> @@ -3,116 +3,157 @@
>=20
>  .. _virtio_user_as_exceptional_path:
>=20
> -Virtio_user as Exceptional Path
> -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D
> +Virtio_user as Exception Path
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D
>=20
> -The virtual device, virtio-user, was originally introduced with vhost-
> user
> -backend, as a high performance solution for IPC (Inter-Process
> Communication)
> +.. note::
> +
> +   This solution is only applicable to Linux systems.
> +
> +The virtual device, virtio-user, was originally introduced with the
> vhost-user
> +backend as a high performance solution for IPC (Inter-Process
> Communication)
>  and user space container networking.
>=20
> -Virtio_user with vhost-kernel backend is a solution for exceptional path=
,
> -such as KNI which exchanges packets with kernel networking stack. This
> -solution is very promising in:
> +Beyond this originally intended use, virtio-user can be used in
> conjunction with the vhost-kernel
> +backend as a solution for dealing with exception path packets which need
> to be injected into the
> +Linux kernel for processing there.
> +In this regard, virtio-user and vhost in kernel space are an alternative
> to DPDK KNI for
> +transferring packets between a DPDK packet processing application and th=
e
> kernel stack.
> +
> +This solution has a number of advantages over alternatives such as KNI:
>=20
>  *   Maintenance
>=20
>      All kernel modules needed by this solution, vhost and vhost-net
> (kernel),
> -    are upstreamed and extensively used kernel module.
> +    are upstreamed and extensively used.
>=20
>  *   Features
>=20
> -    vhost-net is born to be a networking solution, which has lots of
> networking
> -    related features, like multi queue, tso, multi-seg mbuf, etc.
> +    vhost-net is designed to be a networking solution, and, as such, has
> lots of networking
> +    related features, such as multi queue support, TSO, multi-segment
> buffer support, etc.
>=20
>  *   Performance
>=20
> -    similar to KNI, this solution would use one or more kthreads to
> -    send/receive packets to/from user space DPDK applications, which has
> little
> -    impact on user space polling thread (except that it might enter into
> kernel
> -    space to wake up those kthreads if necessary).
> +    similar to KNI, this solution would uses one or more kthreads to
> +    send/receive packets to/from user space DPDK applications, which
> minimises the impact
> +    on the polling DPDK threads.
>=20
> -The overview of an application using virtio-user as exceptional path is
> shown
> +The overview of an application using virtio-user as exception path is
> shown
>  in :numref:`figure_virtio_user_as_exceptional_path`.
>=20
>  .. _figure_virtio_user_as_exceptional_path:
>=20
>  .. figure:: img/virtio_user_as_exceptional_path.*
>=20
> -   Overview of a DPDK app using virtio-user as exceptional path
> +   Overview of a DPDK app using virtio-user as exception path
> +
>=20
> +Example Usage With Testpmd
> +---------------------------
>=20
> -Sample Usage
> -------------
> +.. note::
> +
> +   These instruction assume that the vhost/vhost-net kernel modules are
> available and have already
> +   been loaded into the running kernel.
> +   It also assumes that the DPDK virtio driver has not been disabled in
> the DPDK build.
>=20
> -As a prerequisite, the vhost/vhost-net kernel CONFIG should be chosen
> before
> -compiling the kernel and those kernel modules should be inserted.
> +To run a simple test of virtio-user as exception path using testpmd:
>=20
> -#.  Compile DPDK and bind a physical NIC to igb_uio/uio_pci_generic/vfio=
-
> pci.
> +#.  Compile DPDK and bind a NIC to vfio-pci as documented
> in :ref:`linux_gsg_linux_drivers`.
>=20
> -    This physical NIC is for communicating with outside.
> +    This physical NIC is for communicating with the outside world,
> +    and serves as a packet source in this example.
>=20
> -#.  Run testpmd.
> +#.  Run testpmd to forward packets from NIC to kernel,
> +    passing in a suitable list of logical cores to run on  (``-l``
> parameter),
> +    and optionally the PCI address of the physical NIC to use (``-a``
> parameter).
> +    The virtio-user device for interfacing to the kernel is specified vi=
a
> a ``-vdev`` argument,
> +    taking the parameters described below.
>=20
>      .. code-block:: console
>=20
> -        $(testpmd) -l 2-3 -n 4 \
> -		--vdev=3Dvirtio_user0,path=3D/dev/vhost-net,queue_size=3D1024 \
> -		-- -i --tx-offloads=3D0x0000002c --enable-lro \
> -		--txd=3D1024 --rxd=3D1024
> +        /path/to/dpdk-testpmd -l <cores> -a <pci BDF> \
> +            --vdev=3Dvirtio_user0,path=3D/dev/vhost-
> net,queues=3D1,queue_size=3D1024
>=20
> -    This command runs testpmd with two ports, one physical NIC to
> communicate
> -    with outside, and one virtio-user to communicate with kernel.
> +    * ``path``
>=20
> -* ``--enable-lro``
> +       The path to the kernel vhost-net device.
>=20
> -    This is used to negotiate VIRTIO_NET_F_GUEST_TSO4 and
> -    VIRTIO_NET_F_GUEST_TSO6 feature so that large packets from kernel ca=
n
> be
> -    transmitted to DPDK application and further TSOed by physical NIC.
> +    * ``queue_size``
>=20
> -* ``queue_size``
> +       256 by default. To avoid shortage of descriptors, we can increase
> it to 1024.
>=20
> -    256 by default. To avoid shortage of descriptors, we can increase it
> to 1024.
> +    * ``queues``
>=20
> -* ``queues``
> +       Number of virt-queues. Each queue will be served by a kthread.
>=20
> -    Number of multi-queues. Each queue will be served by a kthread. For
> example:
> +#. Once testpmd is running, a new network interface - called ``tap0`` by
> default -
> +   will be present on the system.
> +   This should be configured with an IP address and then enabled for use=
:
>=20
>      .. code-block:: console
>=20
> -        $(testpmd) -l 2-3 -n 4 \
> -		--vdev=3Dvirtio_user0,path=3D/dev/vhost-
> net,queues=3D2,queue_size=3D1024 \
> -		-- -i --tx-offloads=3D0x0000002c --enable-lro \
> -		--txq=3D2 --rxq=3D2 --txd=3D1024 --rxd=3D1024
> +        ip addr add 192.168.1.1/24 dev tap0
> +        ip link set dev tap0 up
>=20
> -#. Enable Rx checksum offloads in testpmd:
> +#. To observe packet forwarding through the kernel,
> +   a second testpmd instance can be run on the system,
> +   taking packets from the kernel using an ``af_packet`` socket on the
> ``tap0`` interface.
>=20
> -    .. code-block:: console
> +   .. code-block:: console
>=20
> -        (testpmd) port stop 0
> -        (testpmd) port config 0 rx_offload tcp_cksum on
> -        (testpmd) port config 0 rx_offload udp_cksum on
> -        (testpmd) port start 0
> +       /path/to/dpdk-testpmd -l <cores> --vdev=3Dnet_af_packet0,iface=3D=
tap0
> --in-memory --no-pci
>=20
> -#. Start testpmd:
> +   When running this instance,
> +   we can use ``--in-memory`` flag to avoid hugepage naming conflicts
> with the previous instance,
> +   and we also use ``--no-pci`` flag to only use the ``af_packet``
> interface for all traffic forwarding.
>=20
> -    .. code-block:: console
> +#. Running traffic into the system through the NIC should see that
> traffic returned back again,
> +   having been forwarded through both testpmd instances.
> +   This can be confirmed by checking the testpmd statistics on testpmd
> exit.
>=20
> -        (testpmd) start
> +For more advanced use of virtio-user with testpmd in this scenario,
> +some other more advanced options may also be used.
> +For example:
>=20
> -#.  Configure IP address and start tap:
> +* ``--tx-offloads=3D0x02c``
> +
> +    This testpmd option enables TX offloads for UDP and TCP checksum on
> transmit,
> +    as well as TCP TSO support.
> +    The list of the offload flag values can be seen in header
> `rte_ethdev.h
> +    <https://doc.dpdk.org/api/rte__ethdev_8h.html>`_.
> +
> +* ``--enable-lro``
> +
> +    This testpmd option is used to negotiate VIRTIO_NET_F_GUEST_TSO4 and
> +    VIRTIO_NET_F_GUEST_TSO6 feature so that large packets from the kerne=
l
> can be
> +    transmitted to the DPDK application and further TSOed by physical NI=
C.
> +    If unsupported by the physical NIC, errors may be reported by testpm=
d
> with this option.
> +
> +
> +* Enabling Rx checksum offloads for physical port:
> +
> +   Within testpmd, you can enable and disable offloads on a per-port
> basis,
> +   rather than enabling them for both ports.
> +   For the physical NIC, it may be desirable to enable checksum offload
> on packet RX.
> +   This may be done as below, if testpmd is run with ``-i`` flag for
> interactive mode.
>=20
>      .. code-block:: console
>=20
> -        ifconfig tap0 1.1.1.1/24 up
> +        testpmd> port stop 0
> +        testpmd> port config 0 rx_offload tcp_cksum on
> +        testpmd> port config 0 rx_offload udp_cksum on
> +        testpmd> port start 0
>=20
> -.. note::
> +* Multiple queue support
>=20
> -    The tap device will be named tap0, tap1, etc, by kernel.
> +    Better performance may be achieved by using multiple queues,
> +    so that multiple kernel threads are handling the traffic on the
> kernel side.
> +    For example, to use 2 queues on both NIC and virtio ports,
> +    while also enabling TX offloads and LRO support:
>=20
> -Then, all traffic from physical NIC can be forwarded into kernel stack,
> and all
> -traffic on the tap0 can be sent out from physical NIC.
> +    .. code-block:: console
>=20
> -Limitations
> ------------
> +        /path/to/dpdk-testpmd --vdev=3Dvirtio_user0,path=3D/dev/vhost-
> net,queues=3D2,queue_size=3D1024 -- \
> +            -i --tx-offloads=3D0x002c --enable-lro --txq=3D2 --rxq=3D2 -=
-
> txd=3D1024 --rxd=3D1024
>=20
> -This solution is only available on Linux systems.
> --
> 2.34.1