doc: add vDPA features table

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>

diff --git a/.gitignore b/.gitignore
index 9741ba0..2acb459 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,7 @@ doc/guides/cryptodevs/overview_auth_table.txt
 doc/guides/cryptodevs/overview_aead_table.txt
 doc/guides/cryptodevs/overview_asym_table.txt
 doc/guides/compressdevs/overview_feature_table.txt
+doc/guides/vdpadevs/overview_feature_table.txt
 
 # ignore generated ctags/cscope files
 cscope.out.po

diff --git a/doc/guides/conf.py b/doc/guides/conf.py
index 0892c06..c368fa5 100644 (file)
--- 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 (file)
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 (file)
index 0000000..eb7eb3b
--- /dev/null
+++ b/doc/guides/vdpadevs/features_overview.rst
@@ -0,0 +1,155 @@
+..  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``.
+
+
+References
+==========
+
+  * `OASIS: Virtual I/O Device (VIRTIO) Version 1.1 <https://docs.oasis-open.org/virtio/virtio/v1.1/csprd01/virtio-v1.1-csprd01.html>`_
+  * `QEMU: Vhost-user Protocol <https://qemu.weilnetz.de/doc/interop/vhost-user.html>`_
+
+
+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 caae5ea..fd07af6 100644 (file)
--- a/doc/guides/vdpadevs/index.rst
+++ b/doc/guides/vdpadevs/index.rst
@@ -10,3 +10,5 @@ which can be used from an application through vhost API.
 .. toctree::
     :maxdepth: 2
     :numbered:
+
+    features_overview