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

[Maxime Coquelin <maxime.coquelin@redhat.com>]

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@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.

> +[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    =
> +indirect desc        =
> +event idx            =
> +mtu                  =
> +in_order             =
> +IOMMU platform       =
> +packed               =
> +proto mq             =
> +proto log shmfd      =
> +proto rarp           =
> +proto reply ack      =
> +proto slave req      =
> +proto crypto session =
> +proto host notifier  =
> +proto pagefault      =
> +Multiprocess aware   =
> +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
>