[v2,2/3] doc: add vDPA feature table
diff mbox series

Message ID 1578567617-3541-3-git-send-email-matan@mellanox.com
State Accepted, archived
Delegated to: Thomas Monjalon
Headers show
Series
  • Introduce new class for vDPA device drivers
Related show

Checks

Context Check Description
ci/Intel-compilation success Compilation OK
ci/checkpatch success coding style OK

Commit Message

Matan Azrad Jan. 9, 2020, 11 a.m. UTC
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  | 50 +++++++++++++++++++++
 doc/guides/vdpadevs/features_overview.rst | 74 +++++++++++++++++++++++++++++++
 doc/guides/vdpadevs/index.rst             |  1 +
 4 files changed, 130 insertions(+)
 create mode 100644 doc/guides/vdpadevs/features/default.ini
 create mode 100644 doc/guides/vdpadevs/features_overview.rst

Comments

Thomas Monjalon Jan. 10, 2020, 6:26 p.m. UTC | #1
09/01/2020 12:00, Matan Azrad:
> +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).
> +  * 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 host notifier - Host can register memory region based host notifiers.
> +  * proto pagefault - Slave expose page-fault FD for migration process.
> +  * BSD nic_uio - BSD ``nic_uio`` module supported.
> +  * 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/``.

It may be appropriate to use the RST syntax for definitions:
	https://docutils.sourceforge.io/docs/user/rst/quickref.html#definition-lists

Andrew proposed to describe each feature with the same properties as for ethdev:
	http://code.dpdk.org/dpdk/latest/source/doc/guides/nics/features.rst
You replied that it would be redundant for each feature.
In order to be more specific, the ethdev feature properties are:
	- [uses] = input fields and constants
	- [implements] = dev_ops functions
	- [provides] = output fields
	- [related] = API function

The API is very simple:
	http://code.dpdk.org/dpdk/latest/source/lib/librte_vhost/rte_vdpa.h
The relevant dev_ops are written in the below note.

> +.. note::
> +
> +   Most of the features capabilities should be provided by the drivers via the
> +   next vDPA operations: ``get_features`` and ``get_protocol_features``.

I don't see what else can be filled in [uses], [implements] and [provides]
in the case of vDPA, so I suggest to keep it simple as it is.
Thomas Monjalon Jan. 13, 2020, 10:40 p.m. UTC | #2
09/01/2020 12:00, Matan Azrad:
> +Useful links
> +============
> +
> +  * `OASIS: Virtual I/O Device (VIRTIO) Version 1.1 <https://docs.oasis-open.org/virtio/virtio/v1.1/csprd01/virtio-v1.1-csprd01>`_.
> +  * `QEMU: Vhost-user Protocol <https://qemu.weilnetz.de/doc/interop/vhost-user>`_.

.html suffix is missing in these links.

Patch
diff mbox series

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..518e4f1
--- /dev/null
+++ b/doc/guides/vdpadevs/features/default.ini
@@ -0,0 +1,50 @@ 
+;
+; 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.
+;
+[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              =
+indirect desc        =
+event idx            =
+mtu                  =
+in_order             =
+IOMMU platform       =
+packed               =
+proto mq             =
+proto log shmfd      =
+proto rarp           =
+proto reply ack      =
+proto host notifier  =
+proto pagefault      =
+BSD nic_uio          =
+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..3ce1db1
--- /dev/null
+++ b/doc/guides/vdpadevs/features_overview.rst
@@ -0,0 +1,74 @@ 
+..  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).
+  * 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 host notifier - Host can register memory region based host notifiers.
+  * proto pagefault - Slave expose page-fault FD for migration process.
+  * BSD nic_uio - BSD ``nic_uio`` module supported.
+  * 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/``.
+
+.. note::
+
+   Most of the features capabilities should be provided by the drivers via the
+   next vDPA operations: ``get_features`` and ``get_protocol_features``.
+
+
+Useful links
+============
+
+  * `OASIS: Virtual I/O Device (VIRTIO) Version 1.1 <https://docs.oasis-open.org/virtio/virtio/v1.1/csprd01/virtio-v1.1-csprd01>`_.
+  * `QEMU: Vhost-user Protocol <https://qemu.weilnetz.de/doc/interop/vhost-user>`_.
+
+
+Features table
+==============
+
+.. _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