[dpdk-dev] [PATCH v1 2/3] doc: add vDPA feature table

[Tiwei Bie]

On Tue, Jan 07, 2020 at 06:39:36PM +0100, Maxime Coquelin wrote:
> On 12/25/19 4:19 PM, Matan Azrad wrote:
> > Add vDPA devices features table and explanation.
> > 
> > Any vDPA driver can add its own supported features by ading a new ini
> > file to the features directory in doc/guides/vdpadevs/features.
> > 
> > Signed-off-by: Matan Azrad <matan at mellanox.com>
> > ---
> >  doc/guides/conf.py                        |  5 +++
> >  doc/guides/vdpadevs/features/default.ini  | 55 ++++++++++++++++++++++++++
> >  doc/guides/vdpadevs/features_overview.rst | 65 +++++++++++++++++++++++++++++++
> >  doc/guides/vdpadevs/index.rst             |  1 +
> >  4 files changed, 126 insertions(+)
> >  create mode 100644 doc/guides/vdpadevs/features/default.ini
> >  create mode 100644 doc/guides/vdpadevs/features_overview.rst
> > 
> > diff --git a/doc/guides/conf.py b/doc/guides/conf.py
> > index 0892c06..c368fa5 100644
> > --- a/doc/guides/conf.py
> > +++ b/doc/guides/conf.py
> > @@ -401,6 +401,11 @@ def setup(app):
> >                              'Features',
> >                              'Features availability in compression drivers',
> >                              'Feature')
> > +    table_file = dirname(__file__) + '/vdpadevs/overview_feature_table.txt'
> > +    generate_overview_table(table_file, 1,
> > +                            'Features',
> > +                            'Features availability in vDPA drivers',
> > +                            'Feature')
> >  
> >      if LooseVersion(sphinx_version) < LooseVersion('1.3.1'):
> >          print('Upgrade sphinx to version >= 1.3.1 for '
> > diff --git a/doc/guides/vdpadevs/features/default.ini b/doc/guides/vdpadevs/features/default.ini
> > new file mode 100644
> > index 0000000..a3e0bc7
> > --- /dev/null
> > +++ b/doc/guides/vdpadevs/features/default.ini
> > @@ -0,0 +1,55 @@
> > +;
> > +; Features of a default vDPA driver.
> > +;
> > +; This file defines the features that are valid for inclusion in
> > +; the other driver files and also the order that they appear in
> > +; the features table in the documentation. The feature description
> > +; string should not exceed feature_str_len defined in conf.py.
> > +;
> 
> I think some entries below could be removed for vDPA.

+1

> 
> > +[Features]
> > +csum                 =
> > +guest csum           =
> > +mac                  =
> > +gso                  =
> > +guest tso4           =
> > +guest tso6           =
> > +ecn                  =
> > +ufo                  =
> > +host tso4            =
> > +host tso6            =
> > +mrg rxbuf            =
> > +ctrl vq              =
> > +ctrl rx              =
> > +any layout           =
> > +guest announce       =
> > +mq                   =
> > +version 1            =
> > +log all              =
> > +protocol features    =

We may not need to list this. The proto * would imply it.

> > +indirect desc        =
> > +event idx            =
> > +mtu                  =
> > +in_order             =
> > +IOMMU platform       =
> > +packed               =
> > +proto mq             =
> > +proto log shmfd      =
> > +proto rarp           =
> > +proto reply ack      =
> > +proto slave req      =

Ditto. This feature is to be used by other features.
Features like host notifier would imply it.

> > +proto crypto session =

We don't need to list this before we officially support
the crypto vDPA device.

> > +proto host notifier  =
> > +proto pagefault      =
> > +Multiprocess aware   =

There is no support for this in library currently.
To support it, we need to sync vhost fds and messages
among processes.

> > +BSD nic_uio          =
> > +Linux UIO            =
> 
> E.g. UIO, which cannot be used since vDPA requires an IOMMU.
> 
> > +Linux VFIO           =
> > +Other kdrv           =
> > +ARMv7                =
> > +ARMv8                =
> > +Power8               =
> > +x86-32               =
> > +x86-64               =
> > +Usage doc            =
> > +Design doc           =
> > +Perf doc             =
> > \ No newline at end of file
> > diff --git a/doc/guides/vdpadevs/features_overview.rst b/doc/guides/vdpadevs/features_overview.rst
> > new file mode 100644
> > index 0000000..c7745b7
> > --- /dev/null
> > +++ b/doc/guides/vdpadevs/features_overview.rst
> > @@ -0,0 +1,65 @@
> > +..  SPDX-License-Identifier: BSD-3-Clause
> > +    Copyright 2019 Mellanox Technologies, Ltd
> > +
> > +Overview of vDPA drivers features
> > +=================================
> > +
> > +This section explains the supported features that are listed in the table below.
> > +
> > +  * csum - Device can handle packets with partial checksum.
> > +  * guest csum - Guest can handle packets with partial checksum.
> > +  * mac - Device has given MAC address.
> > +  * gso - Device can handle packets with any GSO type.
> > +  * guest tso4 - Guest can receive TSOv4.
> > +  * guest tso6 - Guest can receive TSOv6.
> > +  * ecn - Device can receive TSO with ECN.
> > +  * ufo - Device can receive UFO.
> > +  * host tso4 - Device can receive TSOv4.
> > +  * host tso6 - Device can receive TSOv6.
> > +  * mrg rxbuf - Guest can merge receive buffers.
> > +  * ctrl vq - Control channel is available.
> > +  * ctrl rx - Control channel RX mode support.
> > +  * any layout - Device can handle any descriptor layout.
> > +  * guest announce - Guest can send gratuitous packets.
> > +  * mq - Device supports Receive Flow Steering.
> > +  * version 1 - v1.0 compliant.
> > +  * log all - Device can log all write descriptors (live migration).
> > +  * protocol features - Protocol features negotiation support.
> > +  * indirect desc - Indirect buffer descriptors support.
> > +  * event idx - Support for avail_idx and used_idx fields.
> > +  * mtu - Host can advise the guest with its maximum supported MTU.
> > +  * in_order - Device can use descriptors in ring order.
> > +  * IOMMU platform - Device support IOMMU addresses.
> > +  * packed - Device support packed virtio queues.
> > +  * proto mq - Support the number of queues query.
> > +  * proto log shmfd - Guest support setting log base.
> > +  * proto rarp - Host can broadcast a fake RARP after live migration.
> > +  * proto reply ack - Host support requested operation status ack. 
> > +  * proto slave req - Allow the slave to make requests to the master.
> > +  * proto crypto session - Support crypto session creation.
> > +  * proto host notifier - Host can register memory region based host notifiers.
> > +  * proto pagefault - Slave expose page-fault FD for migration process.
> > +  * Multiprocess aware - Driver can be used for primary-secondary process model.
> > +  * BSD nic_uio - BSD ``nic_uio`` module supported.
> > +  * Linux UIO - Works with ``igb_uio`` kernel module.
> > +  * Linux VFIO - Works with ``vfio-pci`` kernel module.
> > +  * Other kdrv - Kernel module other than above ones supported.
> > +  * ARMv7 - Support armv7 architecture.
> > +  * ARMv8 - Support armv8a (64bit) architecture.
> > +  * Power8 - Support PowerPC architecture.
> > +  * x86-32 - Support 32bits x86 architecture.
> > +  * x86-64 - Support 64bits x86 architecture.
> > +  * Usage doc - Documentation describes usage, In ``doc/guides/vdpadevs/``.
> > +  * Design doc - Documentation describes design. In ``doc/guides/vdpadevs/``.
> > +  * Perf doc - Documentation describes performance values, In ``doc/perf/``.
> > +
> > +
> > +
> > +.. _table_vdpa_pmd_features:
> > +
> > +.. include:: overview_feature_table.txt
> > +
> > +.. Note::
> > +
> > +   Features marked with "P" are partially supported. Refer to the appropriate
> > +   driver guide in the following sections for details.
> > diff --git a/doc/guides/vdpadevs/index.rst b/doc/guides/vdpadevs/index.rst
> > index d69dc91..89e2b03 100644
> > --- a/doc/guides/vdpadevs/index.rst
> > +++ b/doc/guides/vdpadevs/index.rst
> > @@ -11,3 +11,4 @@ which can be used from an application through vhost API.
> >      :maxdepth: 2
> >      :numbered:
> >  
> > +    features_overview
> > 
>