From mboxrd@z Thu Jan 1 00:00:00 1970 From: Shreyansh Jain Subject: Re: [PATCH v5] doc: document NIC features Date: Wed, 26 Jul 2017 10:38:52 +0530 Message-ID: References: <20170707172110.42136-1-ferruh.yigit@intel.com> <20170720092303.97525-1-ferruh.yigit@intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8"; format=flowed Content-Transfer-Encoding: 7bit Cc: John McNamara , , Olivier Matz To: Ferruh Yigit Return-path: Received: from NAM01-SN1-obe.outbound.protection.outlook.com (mail-sn1nam01on0063.outbound.protection.outlook.com [104.47.32.63]) by dpdk.org (Postfix) with ESMTP id 995CA2629 for ; Wed, 26 Jul 2017 06:58:58 +0200 (CEST) In-Reply-To: <20170720092303.97525-1-ferruh.yigit@intel.com> Content-Language: en-US List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Hello Ferruh, Some trivial comments inline. On Thursday 20 July 2017 02:53 PM, Ferruh Yigit wrote: > Document NIC features, add more information about them and add more > implementation related support. > > Signed-off-by: Ferruh Yigit > Signed-off-by: John McNamara > Reviewed-by: Andrew Rybchenko > --- > Cc: Olivier Matz > > v5: > * Add flow_type_rss_offloads and RTE_PMD_REGISTER_KMOD_DEP > > v4: > * Apply review comments from Andrew Rybchenko > * Add tags to the information, to clarify in, out, related data. > > v3: > * received updates from John, Thanks! > > v2: > * Add more details, mbuf and API fields > * Formatting added > > TODO: > - Not all features all fully documented, need help from community > > - Instead of having a new file, it would be nice to auto generate this > file from defaults.ini, and perhaps add extra information as comment to > that file. > > - Some features are implementing eth_dev_ops and some are updates in > Rx/Tx path. These features can be grouped together. > > - A link from overview file per feature would be nice. > --- > doc/guides/nics/overview.rst | 4 + > doc/guides/nics/overview_features.rst | 861 ++++++++++++++++++++++++++++++++++ > 2 files changed, 865 insertions(+) > create mode 100644 doc/guides/nics/overview_features.rst > > diff --git a/doc/guides/nics/overview.rst b/doc/guides/nics/overview.rst > index 757a3c901..2412ed7ec 100644 > --- a/doc/guides/nics/overview.rst > +++ b/doc/guides/nics/overview.rst > @@ -27,6 +27,8 @@ > (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE > OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. > > +.. _nic_overview: > + > Overview of Networking Drivers > ============================== > > @@ -48,6 +50,8 @@ There are more differences between drivers regarding some internal properties, > portability or even documentation availability. > Most of these differences are summarized below. > > +More detail about features can be found :ref:`here `. > + > .. _table_net_pmd_features: > > .. include:: overview_table.txt > diff --git a/doc/guides/nics/overview_features.rst b/doc/guides/nics/overview_features.rst > new file mode 100644 > index 000000000..11a1f9a0a > --- /dev/null > +++ b/doc/guides/nics/overview_features.rst > @@ -0,0 +1,861 @@ > +.. BSD LICENSE > + Copyright(c) 2017 Intel Corporation. All rights reserved. > + All rights reserved. > + > + Redistribution and use in source and binary forms, with or without > + modification, are permitted provided that the following conditions > + are met: > + > + * Redistributions of source code must retain the above copyright > + notice, this list of conditions and the following disclaimer. > + * Redistributions in binary form must reproduce the above copyright > + notice, this list of conditions and the following disclaimer in > + the documentation and/or other materials provided with the > + distribution. > + * Neither the name of Intel Corporation nor the names of its > + contributors may be used to endorse or promote products derived > + from this software without specific prior written permission. > + > + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS > + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT > + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR > + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT > + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, > + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT > + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, > + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY > + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT > + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE > + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. > + > +:orphan: > + > +.. _nic_overview_features: > + > +Overview features > +================= > + > +This section explains the supported features that are listed in the > +:ref:`nic_overview`. > + > +As a guide to implementers it also shows the structs where the features are > +defined and the APIs that can be use to get/set the values. > + > +Following tags used for feature details, these are from driver point of view: > + > +``[uses]`` : Driver uses some kind of input from the application. > + > +``[implements]`` : Driver implements a functionality. > + > +``[provides]`` : Driver provides some kind of data to the application. It is possible > +to provide data by implementing some function, but "provides" used > +for cases provided data can't be represented simply by a function. Above statement needs rephrasing: .. but "provides" *is* used for cases *where* provided data .." > + > +``[related]`` : Related API with that feature. > + > + > +.. _nic_features_speed_capabilities: > + > +Speed capabilities > +------------------ > + > +Supports getting the speed capabilities that the current device is capable of. > + > +* **[provides] rte_eth_dev_info**: ``speed_capa:ETH_LINK_SPEED_*``. > +* **[related] API**: ``rte_eth_dev_info_get()``. > + > + > +.. _nic_features_link_status: > + [...] > + > +RSS hash > +-------- > + > +Supports RSS hashing on RX. > + > +* **[uses] user config**: ``dev_conf.rxmode.mq_mode`` = ``ETH_MQ_RX_RSS_FLAG``. > +* **[provides] rte_eth_dev_info**: ``flow_type_rss_offloads``. > +* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_RSS_H()ASH``, ``mbuf.rss``. ^^^^^^^^^^^^ looks like a stray pair of '()' here > + > + > +.. _nic_features_rss_key_update: > + > +RSS key update > +-------------- > + > +Supports configuration of Receive Side Scaling (RSS) hash computation. Updating > +Receive Side Scaling (RSS) hash key. > + > +* **[implements] eth_dev_ops**: ``rss_hash_update``, ``rss_hash_conf_get``. > +* **[provides] rte_eth_dev_info**: ``hash_key_size``. > +* **[related] API**: ``rte_eth_dev_rss_hash_update()``, > + ``rte_eth_dev_rss_hash_conf_get()``. > + > + > +.. _nic_features_rss_reta_update: > + > +RSS reta update > +--------------- > + > +Supports updating Redirection Table of the Receive Side Scaling (RSS). > + > +* **[implements] eth_dev_ops**: ``reta_update``, ``reta_query``. > +* **[provides] rte_eth_dev_info**: ``reta_size``. > +* **[related] API**: ``rte_eth_dev_rss_reta_update()``, ``rte_eth_dev_rss_reta_query()``. > + > + > +.. _nic_features_vmdq: > + > +VMDq > +---- > + > +Supports Virtual Machine Device Queues (VMDq). > + > +* **[uses] user config**: ``dev_conf.rxmode.mq_mode`` = ``ETH_MQ_RX_VMDQ_FLAG``. > + > + > +.. _nic_features_sriov: > + > +SR-IOV > +------ > + > +Driver supports creating Virtual Functions. Can this be added here? * **[provides] rte_eth_dev_data**: ``sriov`` not sure how to mention [related] for ``rte_eth_dev_sriov``. In all other cases, only API is being connected with [related]. > + > + > +.. _nic_features_dcb: > + > +DCB > +--- > + > +Supports Data Center Bridging (DCB). > + > +* **[uses] user config**: ``dev_conf.rxmode.mq_mode`` = ``ETH_MQ_RX_DCB_FLAG``. > +* **[implements] eth_dev_ops**: ``get_dcb_info``. > +* **[related] API**: ``rte_eth_dev_get_dcb_info()``. > + > + > +.. _nic_features_vlan_filter: > + [...] regards, Shreyansh