[PATCH v2 1/2] doc/howto: rework section on virtio-user as exception path

[Bruce Richardson]

On Mon, May 30, 2022 at 06:33:14AM +0100, Xia, Chenbo wrote:
> Hi Bruce,
> 
> > -----Original Message-----
> > From: Richardson, Bruce <bruce.richardson at intel.com>
> > Sent: Saturday, May 28, 2022 12:37 AM
> > To: dev at dpdk.org
> > Cc: Maxime Coquelin <maxime.coquelin at redhat.com>; Xia, Chenbo
> > <chenbo.xia at intel.com>; Richardson, Bruce <bruce.richardson at intel.com>
> > Subject: [PATCH v2 1/2] doc/howto: rework section on virtio-user as
> > exception path
> >
> > This patch extensively reworks the howto guide on using virtio-user for
> > exception packets. Changes include:
> >
> > * 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.
> >
> > Signed-off-by: Bruce Richardson <bruce.richardson at intel.com>
> >
> > ---
> > v2: fix checkpatch warnings
> > ---
> >  .../howto/virtio_user_as_exceptional_path.rst | 159 +++++++++++-------
> 
> I agree with the renaming. And should we rename this file, and if possible, the
> attached img too.
> 

I wasn't sure of the value of doing such a rename - afraid it might clobber
up the git history. I'll add it as a separate patch in a v3.

> >  1 file changed, 100 insertions(+), 59 deletions(-)
> >
> > diff --git a/doc/guides/howto/virtio_user_as_exceptional_path.rst
> > b/doc/guides/howto/virtio_user_as_exceptional_path.rst
> > index ec021af399..100376c32d 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 @@
> >
> >  .. _virtio_user_as_exceptional_path:
> >
> > -Virtio_user as Exceptional Path
> > -===============================
> > +Virtio_user as Exception Path
> > +=============================
> >
> > -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.
> >
> > -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 the
> > kernel stack.
> > +
> > +This solution has a number of advantages over alternatives such as KNI:
> >
> >  *   Maintenance
> >
> >      All kernel modules needed by this solution, vhost and vhost-net
> > (kernel),
> > -    are upstreamed and extensively used kernel module.
> > +    are upstreamed and extensively used.
> >
> >  *   Features
> >
> > -    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.
> >
> >  *   Performance
> >
> > -    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.
> >
> > -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`.
> >
> >  .. _figure_virtio_user_as_exceptional_path:
> >
> >  .. figure:: img/virtio_user_as_exceptional_path.*
> >
> > -   Overview of a DPDK app using virtio-user as exceptional path
> > +   Overview of a DPDK app using virtio-user as exception path
> > +
> >
> > +Example Usage With Testpmd
> > +---------------------------
> >
> > -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.
> >
> > -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:
> >
> > -#.  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`.
> >
> > -    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.
> >
> > -#.  Run testpmd.
> > +#.  Run testpmd to forward packets from NIC to kernel,
> > +    passing in a suitable list of logical cores to run on  (``-
> > l``.parameter),
> 
> This '.' should be a space?
>
Thanks, good catch.