[dpdk-dev,v3] doc: document NIC features

  Document NIC features, add more information about them and add more
implementation related support.

Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
Signed-off-by: John McNamara <john.mcnamara@intel.com>
---
Cc: Olivier Matz <olivier.matz@6wind.com>

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 | 808 ++++++++++++++++++++++++++++++++++
 2 files changed, 812 insertions(+)
 create mode 100644 doc/guides/nics/overview_features.rst
  

> -----Original Message-----
> From: Yigit, Ferruh
> Sent: Wednesday, July 5, 2017 2:20 PM
> To: Mcnamara, John <john.mcnamara@intel.com>
> Cc: dev@dpdk.org; Yigit, Ferruh <ferruh.yigit@intel.com>; Olivier Matz
> <olivier.matz@6wind.com>
> Subject: [PATCH v3] doc: document NIC features
> 
> Document NIC features, add more information about them and add more
> implementation related support.
> 
> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
> Signed-off-by: John McNamara <john.mcnamara@intel.com>

Acked-by: John McNamara <john.mcnamara@intel.com>
  

On 07/05/2017 04:20 PM, Ferruh Yigit wrote:
> Document NIC features, add more information about them and add more
> implementation related support.

It is very useful information and very good start.
I think it would be very useful to explain how PMD advertises support of 
the feature and
how application or further layers like bonding PMD can find out if the 
feature is supported.

Also some PMDs have few implementations of the datapath (like vector and 
usual). Ideally
we need common way to highlight it. May be it is OK that control path 
features are duplicated
in this case, but ideally it should be expressed somehow.

Below I'll add information which would be useful from my point of view. 
We have written
our PMD not long time ago and it was not easy to find all related data 
structure members
and flags.

> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
> Signed-off-by: John McNamara <john.mcnamara@intel.com>
> ---
> Cc: Olivier Matz <olivier.matz@6wind.com>
>
> 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 | 808 ++++++++++++++++++++++++++++++++++
>   2 files changed, 812 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 <NIC_Overview_Features>`.
> +
>   .. _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..2598c6cd2
> --- /dev/null
> +++ b/doc/guides/nics/overview_features.rst
> @@ -0,0 +1,808 @@
> +..  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.
> +
> +
> +.. _nic_features_speed_capabilities:
> +
> +Speed capabilities
> +------------------
> +
> +Supports getting the speed capabilities that the current device is capable of.
> +
> +* **rte_eth_dev_info**: ``speed_capa``.
> +* **API**: ``rte_eth_dev_info_get()``.
> +
> +.. _nic_features_link_status:
> +
> +Link status
> +-----------
> +
> +Supports getting the link speed, duplex mode and link state (up/down).
> +
> +* **eth_dev_ops**: ``link_update``.
> +* **API**: ``rte_eth_link_get()``, ``rte_eth_link_get_nowait()``.
> +
> +
> +.. _nic_features_link_status_event:
> +
> +Link status event
> +-----------------
> +
> +Supports Link Status Change interrupts.
> +
> +* **user config**: ``dev_conf.intr_conf.lsc``.
> +* **rte_pci_driver.drv_flags**: ``RTE_PCI_DRV_INTR_LSC``.
> +* **rte_eth_event_type**: ``RTE_ETH_EVENT_INTR_LSC``.
> +* **API**: ``rte_eth_link_get()``, ``rte_eth_link_get_nowait()``.
> +
> +
> +.. _nic_features_removal_event:
> +
> +Removal event
> +-------------
> +
> +Supports device removal interrupts.
> +
> +* **user config**: ``dev_conf.intr_conf.rmv``.
> +* **rte_pci_driver.drv_flags**: ``RTE_PCI_DRV_INTR_RMV``.
> +* **rte_eth_event_type**: ``RTE_ETH_EVENT_INTR_RMV``.
> +
> +
> +.. _nic_features_queue_status_event:
> +
> +Queue status event
> +------------------
> +
> +Supports queue enable/disable events.
> +
> +* **rte_eth_event_type**: ``RTE_ETH_EVENT_QUEUE_STATE``.
> +
> +
> +.. _nic_features_rx_interrupt:
> +
> +Rx interrupt
> +------------
> +
> +Supports Rx interrupts.
> +
> +* **user config**: ``dev_conf.intr_conf.rxq``.
> +* **eth_dev_ops**: ``rx_queue_intr_enable``, ``rx_queue_intr_disable``.
> +* **API**: ``rte_eth_dev_rx_intr_enable()``, ``rte_eth_dev_rx_intr_disable()``.
> +
> +
> +.. _nic_features_free_tx_mbuf_on_demand:
> +
> +Free Tx mbuf on demand
> +----------------------
> +
> +Supports freeing consumed buffers on a Tx ring.
> +
> +* **eth_dev_ops**: ``tx_done_cleanup``.
> +* **API**: ``rte_eth_tx_done_cleanup()``.
> +
> +
> +.. _nic_features_queue_start_stop:
> +
> +Queue start/stop
> +----------------
> +
> +Supports starting/stopping a specific Rx/Tx queue of a port.
> +
> +* **eth_dev_ops**: ``rx_queue_start``, ``rx_queue_stop``, ``tx_queue_start``,
> +  ``tx_queue_stop``.
> +* **API**: ``rte_eth_dev_rx_queue_start()``, ``rte_eth_dev_rx_queue_stop()``,
> +  ``rte_eth_dev_tx_queue_start()``, ``rte_eth_dev_tx_queue_stop()``.
> +
> +
> +.. _nic_features_mtu_update:
> +
> +MTU update
> +----------
> +
> +Supports updating port MTU.
> +
> +* **eth_dev_ops**: ``mtu_set``.
> +* **API**: ``rte_eth_dev_set_mtu()``, ``rte_eth_dev_get_mtu()``.

May be it would be useful to mention that dev_info has max_rx_pktlen to 
advertise supported maximum.
Also rte_eth_dev_data->mtu should be mentioned here.

> +
> +
> +.. _nic_features_jumbo_frame:
> +
> +Jumbo frame
> +-----------
> +
> +Supports Rx jumbo frames.
> +
> +
> +* **user config**: ``dev_conf.rxmode.jumbo_frame``,
> +  ``dev_conf.rxmode.max_rx_pkt_len``.

May be it would be useful to mention dev_info->max_rx_pktlen here as well.

> +
> +
> +.. _nic_features_scattered_rx:
> +
> +Scattered Rx
> +------------
> +
> +Supports receiving segmented mbufs.
> +
> +* **user config**: ``dev_conf.rxmode.enable_scatter``.

It would be useful to mention scattered_rx in dev_info and rxq_info and 
clarify meaning.

> +
> +
> +.. _nic_features_lro:
> +
> +LRO
> +---
> +
> +Supports Large Receive Offload.
> +
> +* **user config**: ``dev_conf.rxmode.enable_lro``.
> +* **mbuf**: ``mbuf.ol_flags:PKT_RX_LRO``, ``mbuf.tso_segsz``.

DEV_RX_OFFLOAD_TCP_LRO in rx_offload_capa
rte_eth_dev_data->lro should be mentioned here.

> +
> +
> +.. _nic_features_tso:
> +
> +TSO
> +---
> +
> +Supports TCP Segmentation Offloading.
> +
> +* **mbuf**: ``mbuf.ol_flags:PKT_TX_TCP_SEG``.

DEV_TX_OFFLOAD_*_TSO in tx_offload_capa
Is support of one TSO option sufficient to say Yes?
Should nb_seg_max and nb_mtu_seg_max from rte_eth_desc_lim be mentioned 
here?

> +
> +
> +.. _nic_features_promiscuous_mode:
> +
> +Promiscuous mode
> +----------------
> +
> +Supports enabling/disabling promiscuous mode for a port.
> +

eth_dev_ops missing

> +* **API**: ``rte_eth_promiscuous_enable()``, ``rte_eth_promiscuous_disable()``,
> +  ``rte_eth_promiscuous_get()``.

rte_eth_dev_data->promiscuous should be mentioned here.

> +
> +
> +.. _nic_features_allmulticast_mode:
> +
> +Allmulticast mode
> +-----------------
> +
> +Supports enabling/disabling receiving multicast frames.
> +
> +* **eth_dev_ops**: ``allmulticast_enable``, ``allmulticast_disable``.
> +* **API**: ``rte_eth_allmulticast_enable()``,
> +  ``rte_eth_allmulticast_disable()``, ``rte_eth_allmulticast_get()``.

rte_eth_dev_data->all_multicast should be mentioned here.

> +
> +
> +.. _nic_features_unicast_mac_filter:
> +
> +Unicast MAC filter
> +------------------
> +
> +Supports adding MAC addresses to enable whitelist filtering to accept packets.
> +
> +* **eth_dev_ops**: ``mac_addr_set``, ``mac_addr_add``, ``mac_addr_remove``.
> +* **API**: ``rte_eth_dev_default_mac_addr_set()``,
> +  ``rte_eth_dev_mac_addr_add()``, ``rte_eth_dev_mac_addr_remove()``,
> +  ``rte_eth_macaddr_get()``.
> +
> +
> +.. _nic_features_multicast_mac_filter:
> +
> +Multicast MAC filter
> +--------------------
> +
> +Supports setting multicast addresses to filter.
> +
> +* **eth_dev_ops**: ``set_mc_addr_list``.
> +* **API**: ``rte_eth_dev_set_mc_addr_list()``.
> +
> +
> +.. _nic_features_rss_hash:
> +
> +RSS hash
> +--------
> +
> +Supports RSS hashing on RX.
> +
> +* **user config**: ``dev_conf.rxmode.mq_mode`` = ``ETH_MQ_RX_RSS_FLAG``.

dev_conf.rx_adv_conf.rss_conf should be mentioned
What about dev_info.flow_type_rss_offloads ?

> +* **mbuf**: ``mbuf.ol_flags:PKT_RX_RSS_H()ASH``, ``mbuf.rss``.
> +
> +
> +.. _nic_features_rss_key_update:
> +
> +RSS key update
> +--------------
> +
> +Supports configuration of Receive Side Scaling (RSS) hash computation. Updating
> +Receive Side Scaling (RSS) hash key.
> +
> +* **eth_dev_ops**: ``rss_hash_update``, ``rss_hash_conf_get``.
> +* **API**: ``rte_eth_dev_rss_hash_update()``,
> +  ``rte_eth_dev_rss_hash_conf_get()``.

dev_info.hash_key_size

> +
> +.. _nic_features_rss_reta_update:
> +
> +RSS reta update
> +---------------
> +
> +Supports updating Redirection Table of the Receive Side Scaling (RSS).
> +
> +* **eth_dev_ops**: ``reta_update``, ``reta_query``.
> +* **API**: ``rte_eth_dev_rss_reta_update()``, ``rte_eth_dev_rss_reta_query()``.

dev_info.reta_size

> +
> +
> +.. _nic_features_vmdq:
> +
> +VMDq
> +----
> +
> +Supports Virtual Machine Device Queues (VMDq).
> +
> +* **user config**: ``dev_conf.rxmode.mq_mode`` = ``ETH_MQ_RX_VMDQ_FLAG``.
> +
> +
> +.. _nic_features_sriov:
> +
> +SR-IOV
> +------
> +
> +Driver supports creating Virtual Functions.

Does it mean VFs control or PMD can work on VF?

> +
> +
> +.. _nic_features_dcb:
> +
> +DCB
> +---
> +
> +Supports Data Center Bridging (DCB).
> +
> +* **user config**: ``dev_conf.rxmode.mq_mode`` = ``ETH_MQ_RX_DCB_FLAG``.
> +* **eth_dev_ops**: ``get_dcb_info``.
> +* **API**: ``rte_eth_dev_get_dcb_info()``.
> +
> +
> +.. _nic_features_vlan_filter:
> +
> +VLAN filter
> +-----------
> +
> +Supports filtering of a VLAN Tag identifier.
> +
> +* **eth_dev_ops**: ``vlan_filter_set``.
> +* **API**: ``rte_eth_dev_vlan_filter()``.

dev_conf.rxmode.hw_vlan_filter ?

It should be clarified the difference to VLAN offload, since 
hw_vlan_filter is mentioned below.

> +
> +
> +.. _nic_features_ethertype_filter:
> +
> +Ethertype filter
> +----------------
> +
> +Supports filtering on Ethernet type.
> +
> +* **eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_ETHERTYPE``.
> +* **API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
> +
> +
> +.. _nic_features_ntuple_filter:
> +
> +N-tuple filter
> +--------------
> +
> +Supports filtering on N-tuple values.
> +
> +* **eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_NTUPLE``.
> +* **API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
> +
> +
> +.. _nic_features_syn_filter:
> +
> +SYN filter
> +----------
> +
> +Supports TCP syn filtering.
> +
> +* **eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_SYN``.
> +* **API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
> +
> +
> +.. _nic_features_tunnel_filter:
> +
> +Tunnel filter
> +-------------
> +
> +Supports tunnel filtering.
> +
> +* **eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_TUNNEL``.
> +* **API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
> +
> +
> +.. _nic_features_flexible_filter:
> +
> +Flexible filter
> +---------------
> +
> +Supports a flexible (non-tuple or Ethertype) filter.
> +
> +* **eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_FLEXIBLE``.
> +* **API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
> +
> +
> +.. _nic_features_hash_filter:
> +
> +Hash filter
> +-----------
> +
> +Supports Hash filtering.
> +
> +* **eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_HASH``.
> +* **API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
> +
> +
> +.. _nic_features_flow_director:
> +
> +Flow director
> +-------------
> +
> +Supports Flow Director style filtering to queues.
> +
> +* **eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_FDIR``.
> +* **mbuf**: ``mbuf.ol_flags:`` ``PKT_RX_FDIR``, ``PKT_RX_FDIR_ID``,
> +  ``PKT_RX_FDIR_FLX``.
> +* **API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
> +
> +
> +.. _nic_features_flow_control:
> +
> +Flow control
> +------------
> +
> +Supports configuring link flow control.
> +
> +* **eth_dev_ops**: ``flow_ctrl_get``, ``flow_ctrl_set``,
> +  ``priority_flow_ctrl_set``.
> +* **API**: ``rte_eth_dev_flow_ctrl_get()``, ``rte_eth_dev_flow_ctrl_set()``,
> +  ``rte_eth_dev_priority_flow_ctrl_set()``.
> +
> +
> +.. _nic_features_flow_api:
> +
> +Flow API
> +--------
> +
> +Supports the DPDK Flow API for generic filtering.
> +
> +* **eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_GENERIC``.
> +* **rte_flow_ops**: All.
> +
> +
> +.. _nic_features_rate_limitation:
> +
> +Rate limitation
> +---------------
> +
> +Supports Tx rate limitation for a queue.
> +
> +* **eth_dev_ops**: ``set_queue_rate_limit``.
> +* **API**: ``rte_eth_set_queue_rate_limit()``.
> +
> +
> +.. _nic_features_traffic_mirroring:
> +
> +Traffic mirroring
> +-----------------
> +
> +Supports adding traffic mirroring rules.
> +
> +* **eth_dev_ops**: ``mirror_rule_set``, ``mirror_rule_reset``.
> +* **API**: ``rte_eth_mirror_rule_set()``, ``rte_eth_mirror_rule_reset()``.
> +
> +
> +.. _nic_features_crc_offload:
> +
> +CRC offload
> +-----------
> +
> +Supports CRC stripping by hardware.
> +
> +* **user config**: ``dev_conf.rxmode.hw_strip_crc``.
> +
> +
> +.. _nic_features_vlan_offload:
> +
> +VLAN offload
> +------------
> +
> +Supports VLAN offload to hardware.
> +
> +* **user config**: ``dev_conf.rxmode.hw_vlan_strip``,
> +  ``dev_conf.rxmode.hw_vlan_filter``, ``dev_conf.rxmode.hw_vlan_extend``.
> +* **mbuf**: ``mbuf.ol_flags:PKT_RX_VLAN_STRIPPED``, ``mbuf.vlan_tci``.
> +* **eth_dev_ops**: ``vlan_offload_set``.
> +* **API**: ``rte_eth_dev_set_vlan_offload()``,
> +  ``rte_eth_dev_get_vlan_offload()``.

DEV_RX_OFFLOAD_VLAN_STRIP, DEV_TX_OFFLOAD_VLAN_INSERT should be mentioned

> +
> +
> +.. _nic_features_qinq_offload:
> +
> +QinQ offload
> +------------
> +
> +Supports QinQ (queue in queue) offload.
> +
> +* **mbuf**: ``mbuf.ol_flags:PKT_RX_QINQ_STRIPPED``, ``mbuf.vlan_tci``,
> +   ``mbuf.vlan_tci_outer``, ``mbuf.ol_flags:PKT_TX_QINQ_PKT``.

DEV_RX_OFFLOAD_QINQ_STRIP and DEV_TX_OFFLOAD_QINQ_INSERT should be mentioned

> +
> +
> +.. _nic_features_l3_checksum_offload:
> +
> +L3 checksum offload
> +-------------------
> +
> +Supports L3 checksum offload.
> +
> +* **user config**: ``dev_conf.rxmode.hw_ip_checksum``.
> +* **mbuf**: ``mbuf.ol_flags:PKT_RX_IP_CKSUM_UNKNOWN`` |
> +  ``PKT_RX_IP_CKSUM_BAD`` | ``PKT_RX_IP_CKSUM_GOOD`` |
> +  ``PKT_RX_IP_CKSUM_NONE``, ``mbuf.ol_flags:PKT_TX_IP_CKSUM``,
> +  ``mbuf.ol_flags:PKT_TX_IPV4`` | ``PKT_TX_IPV6``.
> +

DEV_RX_OFFLOAD_IPV4_CKSUM and DEV_TX_OFFLOAD_IPV4_CKSUM should be mentioned.

> +
> +.. _nic_features_l4_checksum_offload:
> +
> +L4 checksum offload
> +-------------------
> +
> +Supports L4 checksum offload.
> +
> +* **mbuf**: ``mbuf.ol_flags:PKT_RX_L4_CKSUM_UNKNOWN`` |
> +  ``PKT_RX_L4_CKSUM_BAD`` | ``PKT_RX_L4_CKSUM_GOOD`` |
> +  ``PKT_RX_L4_CKSUM_NONE``, ``mbuf.ol_flags:PKT_TX_IPV4`` | ``PKT_TX_IPV6``,
> +  ``wmbuf.ol_flags:PKT_TX_L4_NO_CKSUM`` | ``PKT_TX_TCP_CKSUM`` |
> +  ``PKT_TX_SCTP_CKSUM`` | ``PKT_TX_UDP_CKSUM``.

rx_offload_capa and tx_offlaod_capa flags should be mentioned

> +
> +
> +.. _nic_features_macsec_offload:
> +
> +MACsec offload
> +--------------
> +
> +Supports MACsec.
> +
> +* **mbuf**: ``mbuf.ol_flags:PKT_TX_MACSEC``.

rx_offload_capa and tx_offlaod_capa flags should be mentioned

> +
> +
> +.. _nic_features_inner_l3_checksum:
> +
> +Inner L3 checksum
> +-----------------
> +
> +Supports inner packet L3 checksum.

rx_offload_capa and tx_offlaod_capa flags should be mentioned

> +
> +.. _nic_features_inner_l4_checksum:
> +
> +Inner L4 checksum
> +-----------------
> +
> +Supports inner packet L4 checksum.

rx_offload_capa and tx_offlaod_capa flags should be mentioned

> +
> +
> +.. _nic_features_packet_type_parsing:
> +
> +Packet type parsing
> +-------------------
> +
> +Supports packet type parsing and returns a list of supported types.
> +
> +* **eth_dev_ops**: ``dev_supported_ptypes_get``.
> +* **API**: ``rte_eth_dev_get_supported_ptypes()``.
> +
> +
> +.. _nic_features_timesync:
> +
> +Timesync
> +--------
> +
> +Supports IEEE1588/802.1AS timestamping.
> +
> +* **eth_dev_ops**: ``timesync_enable``, ``timesync_disable``
> +  ``timesync_read_rx_timestamp``, ``timesync_read_tx_timestamp``,
> +  ``timesync_adjust_time``, ``timesync_read_time``, ``timesync_write_time``.
> +* **API**: ``rte_eth_timesync_enable()``, ``rte_eth_timesync_disable()``,
> +  ``rte_eth_timesync_read_rx_timestamp()``,
> +  ``rte_eth_timesync_read_tx_timestamp``, ``rte_eth_timesync_adjust_time()``,
> +  ``rte_eth_timesync_read_time()``, ``rte_eth_timesync_write_time()``.
> +
> +
> +.. _nic_features_rx_descriptor_status:
> +
> +Rx descriptor status
> +--------------------
> +
> +Supports check the status of a Rx descriptor. When ``rx_descriptor_status`` is
> +used, status can be "Available", "Done" or "Unavailable". When
> +``rx_descriptor_done`` is used, status can be "DD bit is set" or "DD bit is
> +not set".
> +
> +* **eth_dev_ops**: ``rx_descriptor_status``.
> +* **eth_dev_ops**: ``rx_descriptor_done``.
> +* **API**: ``rte_eth_rx_descriptor_status()``, ``rte_eth_rx_descriptor_done()``.
> +
> +
> +.. _nic_features_tx_descriptor_status:
> +
> +Tx descriptor status
> +--------------------
> +
> +Supports checking the status of a Tx descriptor. Status can be "Full", "Done"
> +or "Unavailable."
> +
> +* **eth_dev_ops**: ``tx_descriptor_status``.
> +* **API**: ``rte_eth_tx_descriptor_status()``.
> +
> +
> +.. _nic_features_basic_stats:
> +
> +Basic stats
> +-----------
> +
> +Support basic statistics such as: ipackets, opackets, ibytes, obytes,
> +imissed, ierrors, oerrors, rx_nombuf.
> +
> +And per queue stats: q_ipackets, q_opackets, q_ibytes, q_obytes, q_errors.
> +
> +These apply to all drivers.
> +
> +* **eth_dev_ops**: ``stats_get``, ``stats_reset``.
> +* **API**: ``rte_eth_stats_get``, ``rte_eth_stats_reset()``.
> +
> +
> +.. _nic_features_extended_stats:
> +
> +Extended stats
> +--------------
> +
> +Supports Extended Statistics, changes from driver to driver.
> +
> +* **eth_dev_ops**: ``xstats_get``, ``xstats_reset``, ``xstats_get_names``.
> +* **eth_dev_ops**: ``xstats_get_by_id``, ``xstats_get_names_by_id``.
> +* **API**: ``rte_eth_xstats_get()``, ``rte_eth_xstats_reset()``,
> +  ``rte_eth_xstats_get_names``, ``rte_eth_xstats_get_by_id()``,
> +  ``rte_eth_xstats_get_names_by_id()``, ``rte_eth_xstats_get_id_by_name()``.
> +
> +
> +
> +.. _nic_features_stats_per_queue:
> +
> +Stats per queue
> +---------------
> +
> +Supports configuring per-queue stat counter mapping.
> +
> +* **eth_dev_ops**: ``queue_stats_mapping_set``.
> +* **API**: ``rte_eth_dev_set_rx_queue_stats_mapping()``,
> +  ``rte_eth_dev_set_tx_queue_stats_mapping()``.
> +
> +
> +.. _nic_features_fw_version:
> +
> +FW version
> +----------
> +
> +Supports getting device hardware firmware information.
> +
> +* **eth_dev_ops**: ``fw_version_get``.
> +* **API**: ``rte_eth_dev_fw_version_get()``.
> +
> +
> +.. _nic_features_eeprom_dump:
> +
> +EEPROM dump
> +-----------
> +
> +Supports getting/setting device eeprom data.
> +
> +* **eth_dev_ops**: ``get_eeprom_length``, ``get_eeprom``, ``set_eeprom``.
> +* **API**: ``rte_eth_dev_get_eeprom_length()``, ``rte_eth_dev_get_eeprom()``,
> +  ``rte_eth_dev_set_eeprom()``.
> +
> +
> +.. _nic_features_register_dump:
> +
> +Registers dump
> +--------------
> +
> +Supports retrieving device registers and registering attributes (number of
> +registers and register size).
> +
> +* **eth_dev_ops**: ``get_reg``.
> +* **API**: ``rte_eth_dev_get_reg_info()``.
> +
> +
> +.. _nic_features_led:
> +
> +LED
> +---
> +
> +Supports turning on/off a software controllable LED on a device.
> +
> +* **eth_dev_ops**: ``dev_led_on``, ``dev_led_off``.
> +* **API**: ``rte_eth_led_on()``, ``rte_eth_led_off()``.
> +
> +
> +.. _nic_features_multiprocess_aware:
> +
> +Multiprocess aware
> +------------------
> +
> +Driver can be used for primary-secondary process model.
> +
> +
> +.. _nic_features_bsd_nic_uio:
> +
> +BSD nic_uio
> +-----------
> +
> +BSD ``nic_uio`` module supported.
> +
> +
> +.. _nic_features_linux_uio:
> +
> +Linux UIO
> +---------
> +
> +Works with ``igb_uio`` kernel module.
> +
> +
> +.. _nic_features_linux_vfio:
> +
> +Linux VFIO
> +----------
> +
> +Works with ``vfio-pci`` kernel module.
> +
> +
> +.. _nic_features_other_kdrv:
> +
> +Other kdrv
> +----------
> +
> +Kernel module other than above ones supported.
> +
> +
> +.. _nic_features_armv7:
> +
> +ARMv7
> +-----
> +
> +Support armv7 architecture.
> +
> +Use ``defconfig_arm-armv7a-*-*``.
> +
> +
> +.. _nic_features_armv8:
> +
> +ARMv8
> +-----
> +
> +Support armv8a (64bit) architecture.
> +
> +Use ``defconfig_arm64-armv8a-*-*``
> +
> +
> +.. _nic_features_power8:
> +
> +Power8
> +------
> +
> +Support PowerPC architecture.
> +
> +Use ``defconfig_ppc_64-power8-*-*``
> +
> +.. _nic_features_x86-32:
> +
> +x86-32
> +------
> +
> +Support 32bits x86 architecture.
> +
> +Use ``defconfig_x86_x32-native-*-*`` and ``defconfig_i686-native-*-*``.
> +
> +
> +.. _nic_features_x86-64:
> +
> +x86-64
> +------
> +
> +Support 64bits x86 architecture.
> +
> +Use ``defconfig_x86_64-native-*-*``.
> +
> +
> +.. _nic_features_usage_doc:
> +
> +Usage doc
> +---------
> +
> +Documentation describes usage.
> +
> +See ``doc/guides/nics/\*.rst``
> +
> +
> +.. _nic_features_design_doc:
> +
> +Design doc
> +----------
> +
> +Documentation describes design.
> +
> +See ``doc/guides/nics/\*.rst``.
> +
> +
> +.. _nic_features_perf_doc:
> +
> +Perf doc
> +--------
> +
> +Documentation describes performance values.
> +
> +See ``dpdk.org/doc/perf/*``.
> +
> +
> +
> +.. _nic_features_other:
> +
> +Other dev ops not represented by a Feature
> +------------------------------------------
> +
> +* ``rxq_info_get``
> +* ``txq_info_get``
> +* ``vlan_tpid_set``
> +* ``vlan_strip_queue_set``
> +* ``vlan_pvid_set``
> +* ``rx_queue_count``
> +* ``l2_tunnel_offload_set``
> +* ``uc_hash_table_set``
> +* ``uc_all_hash_table_set``
> +* ``udp_tunnel_port_add``
> +* ``udp_tunnel_port_del``
> +* ``l2_tunnel_eth_type_conf``
> +* ``l2_tunnel_offload_set``
> +* ``tx_pkt_prepare``
  

Hi Andrew,

On 7/7/2017 11:55 AM, Andrew Rybchenko wrote:
> On 07/05/2017 04:20 PM, Ferruh Yigit wrote:
>> Document NIC features, add more information about them and add more
>> implementation related support.
> 
> It is very useful information and very good start.

Thanks for review, I rely on more comments to have more comprehensive
document.

> I think it would be very useful to explain how PMD advertises support of 
> the feature and
> how application or further layers like bonding PMD can find out if the 
> feature is supported.

I agree this should be documented and may not be clear right now, but
not sure if it should be in this document, I would prefer this document
just documents the NIC features we are advertising.

Let's think where this information may fit.

> 
> Also some PMDs have few implementations of the datapath (like vector and 
> usual). Ideally
> we need common way to highlight it. May be it is OK that control path 
> features are duplicated
> in this case, but ideally it should be expressed somehow.

I agree different datapath implementations can be documented better, I
just don't know how to do ...

For some drivers there are multiple vector implementations and the
feature set for them is not clear. And as you said control features are
duplicated in the table.

Perhaps control and datapath features can be separated.

Or as Thomas suggested sometime ago, vector and scalar version can be
merged into one in the table and feature can be marked as supported if
both scalar and vector has support for it. But this is not solving
multiple vector implementation problem.

Overall this is something needs some more thinking on it, any comment
welcome.

> 
> Below I'll add information which would be useful from my point of view. 

I will update the document with below comments and send a new version of
patch.

Thanks,
ferruh
  

07/07/2017 15:37, Ferruh Yigit:
> On 7/7/2017 11:55 AM, Andrew Rybchenko wrote:
> > Also some PMDs have few implementations of the datapath (like vector and 
> > usual). Ideally
> > we need common way to highlight it. May be it is OK that control path 
> > features are duplicated
> > in this case, but ideally it should be expressed somehow.
> 
> I agree different datapath implementations can be documented better, I
> just don't know how to do ...
> 
> For some drivers there are multiple vector implementations and the
> feature set for them is not clear. And as you said control features are
> duplicated in the table.
> 
> Perhaps control and datapath features can be separated.
> 
> Or as Thomas suggested sometime ago, vector and scalar version can be
> merged into one in the table and feature can be marked as supported if
> both scalar and vector has support for it. But this is not solving
> multiple vector implementation problem.

Yes it is the way to go.
The features should not be different from a datapath implementation to
another one. So they must be merged in only one column.
If a feature is not supported in every datapaths of a driver, it should
be marked as partially supported... and the developers must implement it.
  

On 7/7/2017 2:53 PM, Thomas Monjalon wrote:
> 07/07/2017 15:37, Ferruh Yigit:
>> On 7/7/2017 11:55 AM, Andrew Rybchenko wrote:
>>> Also some PMDs have few implementations of the datapath (like vector and 
>>> usual). Ideally
>>> we need common way to highlight it. May be it is OK that control path 
>>> features are duplicated
>>> in this case, but ideally it should be expressed somehow.
>>
>> I agree different datapath implementations can be documented better, I
>> just don't know how to do ...
>>
>> For some drivers there are multiple vector implementations and the
>> feature set for them is not clear. And as you said control features are
>> duplicated in the table.
>>
>> Perhaps control and datapath features can be separated.
>>
>> Or as Thomas suggested sometime ago, vector and scalar version can be
>> merged into one in the table and feature can be marked as supported if
>> both scalar and vector has support for it. But this is not solving
>> multiple vector implementation problem.
> 
> Yes it is the way to go.
> The features should not be different from a datapath implementation to
> another one. So they must be merged in only one column.
> If a feature is not supported in every datapaths of a driver, it should
> be marked as partially supported... and the developers must implement it.

But for example for i40e, there are altivec, neon and sse vector
implementations, how should we document this?
  

07/07/2017 15:57, Ferruh Yigit:
> On 7/7/2017 2:53 PM, Thomas Monjalon wrote:
> > 07/07/2017 15:37, Ferruh Yigit:
> >> On 7/7/2017 11:55 AM, Andrew Rybchenko wrote:
> >>> Also some PMDs have few implementations of the datapath (like vector and 
> >>> usual). Ideally
> >>> we need common way to highlight it. May be it is OK that control path 
> >>> features are duplicated
> >>> in this case, but ideally it should be expressed somehow.
> >>
> >> I agree different datapath implementations can be documented better, I
> >> just don't know how to do ...
> >>
> >> For some drivers there are multiple vector implementations and the
> >> feature set for them is not clear. And as you said control features are
> >> duplicated in the table.
> >>
> >> Perhaps control and datapath features can be separated.
> >>
> >> Or as Thomas suggested sometime ago, vector and scalar version can be
> >> merged into one in the table and feature can be marked as supported if
> >> both scalar and vector has support for it. But this is not solving
> >> multiple vector implementation problem.
> > 
> > Yes it is the way to go.
> > The features should not be different from a datapath implementation to
> > another one. So they must be merged in only one column.
> > If a feature is not supported in every datapaths of a driver, it should
> > be marked as partially supported... and the developers must implement it.
> 
> But for example for i40e, there are altivec, neon and sse vector
> implementations, how should we document this?

They are all only one i40 driver. It should offer the same features
regardless of the platform it runs on.
So it should be only one column in the table.
  

On 7/7/2017 3:02 PM, Thomas Monjalon wrote:
> 07/07/2017 15:57, Ferruh Yigit:
>> On 7/7/2017 2:53 PM, Thomas Monjalon wrote:
>>> 07/07/2017 15:37, Ferruh Yigit:
>>>> On 7/7/2017 11:55 AM, Andrew Rybchenko wrote:
>>>>> Also some PMDs have few implementations of the datapath (like vector and 
>>>>> usual). Ideally
>>>>> we need common way to highlight it. May be it is OK that control path 
>>>>> features are duplicated
>>>>> in this case, but ideally it should be expressed somehow.
>>>>
>>>> I agree different datapath implementations can be documented better, I
>>>> just don't know how to do ...
>>>>
>>>> For some drivers there are multiple vector implementations and the
>>>> feature set for them is not clear. And as you said control features are
>>>> duplicated in the table.
>>>>
>>>> Perhaps control and datapath features can be separated.
>>>>
>>>> Or as Thomas suggested sometime ago, vector and scalar version can be
>>>> merged into one in the table and feature can be marked as supported if
>>>> both scalar and vector has support for it. But this is not solving
>>>> multiple vector implementation problem.
>>>
>>> Yes it is the way to go.
>>> The features should not be different from a datapath implementation to
>>> another one. So they must be merged in only one column.
>>> If a feature is not supported in every datapaths of a driver, it should
>>> be marked as partially supported... and the developers must implement it.
>>
>> But for example for i40e, there are altivec, neon and sse vector
>> implementations, how should we document this?
> 
> They are all only one i40 driver. It should offer the same features
> regardless of the platform it runs on.
> So it should be only one column in the table.

If one platform does not implements a feature, it will cause feature
will be documented as partial independent from other platform's status,
this is unfair for the ones implemented it.
  

> On Jul 7, 2017, at 9:13 AM, Ferruh Yigit <ferruh.yigit@intel.com> wrote:
> 
> On 7/7/2017 3:02 PM, Thomas Monjalon wrote:
>> 07/07/2017 15:57, Ferruh Yigit:
>>> On 7/7/2017 2:53 PM, Thomas Monjalon wrote:
>>>> 07/07/2017 15:37, Ferruh Yigit:
>>>>> On 7/7/2017 11:55 AM, Andrew Rybchenko wrote:
>>>>>> Also some PMDs have few implementations of the datapath (like vector and 
>>>>>> usual). Ideally
>>>>>> we need common way to highlight it. May be it is OK that control path 
>>>>>> features are duplicated
>>>>>> in this case, but ideally it should be expressed somehow.
>>>>> 
>>>>> I agree different datapath implementations can be documented better, I
>>>>> just don't know how to do ...
>>>>> 
>>>>> For some drivers there are multiple vector implementations and the
>>>>> feature set for them is not clear. And as you said control features are
>>>>> duplicated in the table.
>>>>> 
>>>>> Perhaps control and datapath features can be separated.
>>>>> 
>>>>> Or as Thomas suggested sometime ago, vector and scalar version can be
>>>>> merged into one in the table and feature can be marked as supported if
>>>>> both scalar and vector has support for it. But this is not solving
>>>>> multiple vector implementation problem.
>>>> 
>>>> Yes it is the way to go.
>>>> The features should not be different from a datapath implementation to
>>>> another one. So they must be merged in only one column.
>>>> If a feature is not supported in every datapaths of a driver, it should
>>>> be marked as partially supported... and the developers must implement it.
>>> 
>>> But for example for i40e, there are altivec, neon and sse vector
>>> implementations, how should we document this?
>> 
>> They are all only one i40 driver. It should offer the same features
>> regardless of the platform it runs on.
>> So it should be only one column in the table.
> 
> If one platform does not implements a feature, it will cause feature
> will be documented as partial independent from other platform's status,
> this is unfair for the ones implemented it.

+1

If a single PMD supports different platforms, then we need to be able to identify these NICs plus show the features.
Having multiple lines in a table is not difficult and helps identify exactly what is supported on all platforms.

Regards,
Keith
  

On 7/7/2017 11:55 AM, Andrew Rybchenko wrote:
<...>

>> +TSO
>> +---
>> +
>> +Supports TCP Segmentation Offloading.
>> +
>> +* **mbuf**: ``mbuf.ol_flags:PKT_TX_TCP_SEG``.
> 
> DEV_TX_OFFLOAD_*_TSO in tx_offload_capa
> Is support of one TSO option sufficient to say Yes?

This is common question for a few offload features, like ones that can
be valid for Rx and Tx path, I guess feature should be "Yes" if all are
supported, otherwise "P(artial)".

But this is hard to trace and if marked as "P", makes hard to figure out
what is supported.

<...>

>> +SR-IOV
>> +------
>> +
>> +Driver supports creating Virtual Functions.
> 
> Does it mean VFs control or PMD can work on VF?

I don't know. This option is not very clear, and need to be agreed on.

If this is to say driver controls VF, for some drivers PF and VF version
documented separately already, so this feature becomes redundant.

And for some drivers, same driver supports both PF and VF, and
represented as single column in table, so how you can use this field?

I thought this is to say device has SR-IOV support, for that case this
only makes sense for PF drivers and VF shouldn't set this.

Target is to provide some kind of useful information about device, what
it can be for this case?

<...>

>> +VLAN filter
>> +-----------
>> +
>> +Supports filtering of a VLAN Tag identifier.
>> +
>> +* **eth_dev_ops**: ``vlan_filter_set``.
>> +* **API**: ``rte_eth_dev_vlan_filter()``.
> 
> dev_conf.rxmode.hw_vlan_filter ?
> 
> It should be clarified the difference to VLAN offload, since 
> hw_vlan_filter is mentioned below.

dev_conf.rxmode.hw_vlan_filter looks like used in the
rte_eth_dev_set_vlan_offload() API.

I am confused about "vlan filter" and "vlan offload". I need to check
implementation more to be able to clarify it, but for now keeping option
in other feature.

<...>
  

On 07/07/2017 06:06 PM, Ferruh Yigit wrote:
> On 7/7/2017 11:55 AM, Andrew Rybchenko wrote:
> <...>
>
>>> +TSO
>>> +---
>>> +
>>> +Supports TCP Segmentation Offloading.
>>> +
>>> +* **mbuf**: ``mbuf.ol_flags:PKT_TX_TCP_SEG``.
>> DEV_TX_OFFLOAD_*_TSO in tx_offload_capa
>> Is support of one TSO option sufficient to say Yes?
> This is common question for a few offload features, like ones that can
> be valid for Rx and Tx path, I guess feature should be "Yes" if all are
> supported, otherwise "P(artial)".

IMHO, it would be more informative to have separate features for TCP, 
UDP and
encapsulated TSO offloads.

Otherwise when a new TSO offload flag is added, it should change all Y to P
(and update PMDs documentation to provide details).

> But this is hard to trace and if marked as "P", makes hard to figure out
> what is supported.

Ideally for all "P" it should be a hyperlink to PMD documentation section
which provides details.

> <...>

<...>
  

07/07/2017 16:20, Wiles, Keith:
> 
> > On Jul 7, 2017, at 9:13 AM, Ferruh Yigit <ferruh.yigit@intel.com> wrote:
> > 
> > On 7/7/2017 3:02 PM, Thomas Monjalon wrote:
> >> 07/07/2017 15:57, Ferruh Yigit:
> >>> On 7/7/2017 2:53 PM, Thomas Monjalon wrote:
> >>>> 07/07/2017 15:37, Ferruh Yigit:
> >>>>> On 7/7/2017 11:55 AM, Andrew Rybchenko wrote:
> >>>>>> Also some PMDs have few implementations of the datapath (like vector and 
> >>>>>> usual). Ideally
> >>>>>> we need common way to highlight it. May be it is OK that control path 
> >>>>>> features are duplicated
> >>>>>> in this case, but ideally it should be expressed somehow.
> >>>>> 
> >>>>> I agree different datapath implementations can be documented better, I
> >>>>> just don't know how to do ...
> >>>>> 
> >>>>> For some drivers there are multiple vector implementations and the
> >>>>> feature set for them is not clear. And as you said control features are
> >>>>> duplicated in the table.
> >>>>> 
> >>>>> Perhaps control and datapath features can be separated.
> >>>>> 
> >>>>> Or as Thomas suggested sometime ago, vector and scalar version can be
> >>>>> merged into one in the table and feature can be marked as supported if
> >>>>> both scalar and vector has support for it. But this is not solving
> >>>>> multiple vector implementation problem.
> >>>> 
> >>>> Yes it is the way to go.
> >>>> The features should not be different from a datapath implementation to
> >>>> another one. So they must be merged in only one column.
> >>>> If a feature is not supported in every datapaths of a driver, it should
> >>>> be marked as partially supported... and the developers must implement it.
> >>> 
> >>> But for example for i40e, there are altivec, neon and sse vector
> >>> implementations, how should we document this?
> >> 
> >> They are all only one i40 driver. It should offer the same features
> >> regardless of the platform it runs on.
> >> So it should be only one column in the table.
> > 
> > If one platform does not implements a feature, it will cause feature
> > will be documented as partial independent from other platform's status,
> > this is unfair for the ones implemented it.
> 
> +1
> 
> If a single PMD supports different platforms, then we need to be able to identify these NICs plus show the features.
> Having multiple lines in a table is not difficult and helps identify exactly what is supported on all platforms.

No, you miss the point.
I don't care about the table, it is just a tool to target uniform
implementation. DPDK must be multi-platform. It means an application
relying on a feature must work when changing the CPU.

If a PMD maintainer wants its features advertised as fully supported,
he must reject partial datapath implementation.
It is fair because it is the maintainer's choice.
  

> On Jul 7, 2017, at 3:37 PM, Thomas Monjalon <thomas@monjalon.net> wrote:

> 

> 07/07/2017 16:20, Wiles, Keith:

>> 

>>> On Jul 7, 2017, at 9:13 AM, Ferruh Yigit <ferruh.yigit@intel.com> wrote:

>>> 

>>> On 7/7/2017 3:02 PM, Thomas Monjalon wrote:

>>>> 07/07/2017 15:57, Ferruh Yigit:

>>>>> On 7/7/2017 2:53 PM, Thomas Monjalon wrote:

>>>>>> 07/07/2017 15:37, Ferruh Yigit:

>>>>>>> On 7/7/2017 11:55 AM, Andrew Rybchenko wrote:

>>>>>>>> Also some PMDs have few implementations of the datapath (like vector and 

>>>>>>>> usual). Ideally

>>>>>>>> we need common way to highlight it. May be it is OK that control path 

>>>>>>>> features are duplicated

>>>>>>>> in this case, but ideally it should be expressed somehow.

>>>>>>> 

>>>>>>> I agree different datapath implementations can be documented better, I

>>>>>>> just don't know how to do ...

>>>>>>> 

>>>>>>> For some drivers there are multiple vector implementations and the

>>>>>>> feature set for them is not clear. And as you said control features are

>>>>>>> duplicated in the table.

>>>>>>> 

>>>>>>> Perhaps control and datapath features can be separated.

>>>>>>> 

>>>>>>> Or as Thomas suggested sometime ago, vector and scalar version can be

>>>>>>> merged into one in the table and feature can be marked as supported if

>>>>>>> both scalar and vector has support for it. But this is not solving

>>>>>>> multiple vector implementation problem.

>>>>>> 

>>>>>> Yes it is the way to go.

>>>>>> The features should not be different from a datapath implementation to

>>>>>> another one. So they must be merged in only one column.

>>>>>> If a feature is not supported in every datapaths of a driver, it should

>>>>>> be marked as partially supported... and the developers must implement it.

>>>>> 

>>>>> But for example for i40e, there are altivec, neon and sse vector

>>>>> implementations, how should we document this?

>>>> 

>>>> They are all only one i40 driver. It should offer the same features

>>>> regardless of the platform it runs on.

>>>> So it should be only one column in the table.

>>> 

>>> If one platform does not implements a feature, it will cause feature

>>> will be documented as partial independent from other platform's status,

>>> this is unfair for the ones implemented it.

>> 

>> +1

>> 

>> If a single PMD supports different platforms, then we need to be able to identify these NICs plus show the features.

>> Having multiple lines in a table is not difficult and helps identify exactly what is supported on all platforms.

> 

> No, you miss the point.

> I don't care about the table, it is just a tool to target uniform

> implementation. DPDK must be multi-platform. It means an application

> relying on a feature must work when changing the CPU.


I guess I am not following this point if you change a CPU from ARM to IA then I am sure a number of features stop working or the NIC can not build at all. I am sure that is not what you meant. If a NIC supports a feature, but may not support that feature in all CPU’s of the same family then ‘P’ seems reasonable, but it does not really help the developer without more details. 

I wrote a big reply here, but I figured I would trim down to this statement. We are trying to put 20 pounds(pick your favorite measurement) of ‘stuff’ in to a 5 pound bag :-)

I ‘really’ appreciate the effort it took to build this table plus it will be hard to keep current. The table may have to be broken into multiple tables or figure out how to add all of the possible CPU classes in each Arch ARM, IA, Power... A top table which helps the user move to the next table and then next table till he finds all of the right set of CPU Arch, Class and NIC features plus let’s not forget the OS type.

I agree the table is not your point, but the table does become the point when you start talking about what is supported in what Arch/Class/NIC/OS as the table is only 2D, maybe a 3D table :-) (like d3js.org)

> 

> If a PMD maintainer wants its features advertised as fully supported,

> he must reject partial datapath implementation.

> It is fair because it is the maintainer's choice.



Regards,
Keith