[dpdk-dev] [RFC] doc: document NIC features

[dpdk-dev] [RFC] doc: document NIC features

[Ferruh Yigit]

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

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.

Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
---
 doc/guides/nics/overview_features.rst | 396 ++++++++++++++++++++++++++++++++++
 1 file changed, 396 insertions(+)
 create mode 100644 doc/guides/nics/overview_features.rst

diff --git a/doc/guides/nics/overview_features.rst b/doc/guides/nics/overview_features.rst
new file mode 100644
index 0000000..26c83b6
--- /dev/null
+++ b/doc/guides/nics/overview_features.rst
@@ -0,0 +1,396 @@
+..  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.
+
+Overview features
+=================
+
+Speed capabilities
+------------------
+eth_dev_ops: dev_infos_get:speed_capa
+
+Driver advertise the speed capabilities that the current device capable to offer.
+
+
+Link status
+-----------
+eth_dev_ops: link_update
+
+
+Link status event
+-----------------
+rte_pci_driver.drv_flags = RTE_PCI_DRV_INTR_LSC
+
+
+Removal event
+-------------
+rte_pci_driver.drv_flags = RTE_PCI_DRV_INTR_RMV
+
+
+Queue status event
+------------------
+eth_dev_ops: link_update
+
+
+Rx interrupt
+------------
+eth_dev_ops: rx_queue_intr_enable, rx_queue_intr_disable
+
+
+Free Tx mbuf on demand
+----------------------
+eth_dev_ops: tx_done_cleanup
+
+
+Queue start/stop
+----------------
+eth_dev_ops: rx_queue_start, rx_queue_stop, tx_queue_start, tx_queue_stop
+
+
+MTU update
+----------
+eth_dev_ops: mtu_set
+
+
+Jumbo frame
+-----------
+
+
+Scattered Rx
+------------
+
+
+LRO
+---
+Large Receive Offload.
+
+
+TSO
+---
+TCP Segmentation Offloading.
+
+
+Promiscuous mode
+----------------
+eth_dev_ops: promiscuous_enable, promiscuous_disable
+
+
+Allmulticast mode
+-----------------
+eth_dev_ops: allmulticast_enable, allmulticast_disable
+
+
+Unicast MAC filter
+------------------
+eth_dev_ops: mac_addr_add, mac_addr_remove
+
+
+Multicast MAC filter
+--------------------
+eth_dev_ops: set_mc_addr_list
+
+
+RSS hash
+--------
+eth_dev_ops: rss_hash_update, rss_hash_conf_get
+
+
+RSS key update
+--------------
+eth_dev_ops: rss_hash_update, rss_hash_conf_get
+
+
+RSS reta update
+---------------
+eth_dev_ops: reta_update, reta_query
+
+
+VMDq
+----
+
+
+SR-IOV
+------
+
+
+DCB
+---
+eth_dev_ops: get_dcb_info
+
+
+VLAN filter
+-----------
+eth_dev_ops: vlan_filter_set
+
+
+Ethertype filter
+----------------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_ETHERTYPE
+
+
+N-tuple filter
+--------------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_NTUPLE
+
+
+SYN filter
+----------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_SYN
+
+
+Tunnel filter
+-------------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_TUNNEL
+
+
+Flexible filter
+---------------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_FLEXIBLE
+
+
+Hash filter
+-----------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_HASH
+
+
+Flow director
+-------------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_FDIR
+
+
+Flow control
+------------
+eth_dev_ops: flow_ctrl_get, flow_ctrl_set, priority_flow_ctrl_set
+
+
+Flow API
+--------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_GENERIC
+rte_flow_ops: *
+
+
+Rate limitation
+---------------
+eth_dev_ops: set_queue_rate_limit
+
+
+Traffic mirroring
+-----------------
+eth_dev_ops: mirror_rule_set, mirror_rule_reset
+
+
+CRC offload
+-----------
+
+
+VLAN offload
+------------
+eth_dev_ops: vlan_offload_set
+
+
+QinQ offload
+------------
+
+
+L3 checksum offload
+-------------------
+
+
+L4 checksum offload
+-------------------
+
+
+MACsec offload
+--------------
+
+
+Inner L3 checksum
+-----------------
+
+
+Inner L4 checksum
+-----------------
+
+
+Packet type parsing
+-------------------
+eth_dev_ops: dev_supported_ptypes_get
+
+
+Timesync
+--------
+eth_dev_ops: timesync_enable, timesync_disable
+eth_dev_ops: timesync_read_rx_timestamp, timesync_read_tx_timestamp
+eth_dev_ops: timesync_adjust_time, timesync_read_time, timesync_write_time
+
+
+
+Rx descriptor status
+--------------------
+eth_dev_ops: rx_descriptor_status
+
+Check the status of a Rx descriptor.
+
+
+Tx descriptor status
+--------------------
+eth_dev_ops: tx_descriptor_status
+
+Check the status of a Tx descriptor.
+
+
+Basic stats
+-----------
+eth_dev_ops: stats_get, stats_reset
+
+Basic statistics, same for all drivers.
+
+
+Extended stats
+--------------
+eth_dev_ops: xstats_get, xstats_reset, xstats_get_names
+eth_dev_ops: xstats_get_by_id, xstats_get_names_by_id
+
+Extended statistics, changes from driver to driver.
+
+
+Stats per queue
+---------------
+eth_dev_ops: queue_stats_mapping_set
+
+
+FW version
+----------
+eth_dev_ops: fw_version_get
+
+
+EEPROM dump
+-----------
+eth_dev_ops: get_eeprom_length, get_eeprom, set_eeprom
+
+
+Registers dump
+--------------
+eth_dev_ops: get_reg
+
+
+Multiprocess aware
+------------------
+
+
+BSD nic_uio
+-----------
+
+
+Linux UIO
+---------
+Works with igb_uio kernel module.
+
+
+Linux VFIO
+----------
+Works with vfio-pci kernel module.
+
+
+Other kdrv
+----------
+
+
+ARMv7
+-----
+defconfig_arm-armv7a-\*-\*
+
+Support armv7 architecture.
+
+
+ARMv8
+-----
+defconfig_arm64-armv8a-\*-\*
+
+Support armv7 architecture.
+
+
+Power8
+------
+defconfig_ppc_64-power8-\*-\*
+
+Support PowerPC architecture.
+
+
+x86-32
+------
+defconfig_x86_x32-native-\*-\*
+defconfig_i686-native-\*-\*
+
+Support 32bits x86 architecture.
+
+
+x86-64
+------
+defconfig_x86_64-native-\*-\*
+
+Support 64bits x86 architecture.
+
+
+Usage doc
+---------
+doc/guides/nics/\*.rst
+
+
+Design doc
+----------
+
+
+Perf doc
+--------
+
+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_setup
+rx_queue_release
+rx_queue_count
+rx_descriptor_done
+tx_queue_setup
+tx_queue_release
+dev_led_on
+dev_led_off
+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
+bypass\*
+
-- 
2.9.3

[dpdk-dev] [PATCH] doc: document NIC features

[Ferruh Yigit]

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

Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
---

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          |   2 +
 doc/guides/nics/overview_features.rst | 610 ++++++++++++++++++++++++++++++++++
 2 files changed, 612 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..8eb5de533 100644
--- a/doc/guides/nics/overview.rst
+++ b/doc/guides/nics/overview.rst
@@ -48,6 +48,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..0648e82d3
--- /dev/null
+++ b/doc/guides/nics/overview_features.rst
@@ -0,0 +1,610 @@
+..  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
+=================
+
+.. _nic_features_speed_capabilities:
+
+Speed capabilities
+------------------
+
+eth_dev_ops: dev_infos_get:speed_capa
+
+Advertise the speed capabilities that the current device capable to offer.
+
+
+.. _nic_features_link_status:
+
+Link status
+-----------
+eth_dev_ops: link_update
+
+Getting link speed, duplex mode and state (up/down) support.
+
+
+.. _nic_features_link_status_event:
+
+Link status event
+-----------------
+user config requires: dev_conf.intr_conf.lsc
+rte_pci_driver.drv_flags = RTE_PCI_DRV_INTR_LSC
+
+Link Status Change interrupts support.
+
+
+.. _nic_features_removal_event:
+
+Removal event
+-------------
+user config requires: dev_conf.intr_conf.rmv
+rte_pci_driver.drv_flags = RTE_PCI_DRV_INTR_RMV
+
+Device removal interrupts support.
+
+
+.. _nic_features_queue_status_event:
+
+Queue status event
+------------------
+eth_dev_ops: link_update
+
+
+.. _nic_features_rx_interrupt:
+
+Rx interrupt
+------------
+eth_dev_ops: rx_queue_intr_enable, rx_queue_intr_disable
+
+Rx interrupts support.
+
+
+.. _nic_features_free_tx_mbuf_on_demand:
+
+Free Tx mbuf on demand
+----------------------
+eth_dev_ops: tx_done_cleanup
+
+Forcing free consumed buffers on Tx ring support.
+
+
+.. _nic_features_queue_start_stop:
+
+Queue start/stop
+----------------
+eth_dev_ops: rx_queue_start, rx_queue_stop, tx_queue_start, tx_queue_stop
+
+start/stop specified Rx/Tx queue of a port.
+
+
+.. _nic_features_mtu_update:
+
+MTU update
+----------
+eth_dev_ops: mtu_set
+
+Updating port MTU support.
+
+
+.. _nic_features_jumbo_frame:
+
+Jumbo frame
+-----------
+
+Receiving jumbo frames support.
+
+
+.. _nic_features_scattered_rx:
+
+Scattered Rx
+------------
+
+Receiving segmented mbufs support.
+
+
+.. _nic_features_lro:
+
+LRO
+---
+Large Receive Offload.
+
+
+.. _nic_features_tso:
+
+TSO
+---
+TCP Segmentation Offloading.
+
+
+.. _nic_features_promiscuous_mode:
+
+Promiscuous mode
+----------------
+eth_dev_ops: promiscuous_enable, promiscuous_disable
+
+enable/disable port promiscuous mode.
+
+
+.. _nic_features_allmulticast_mode:
+
+Allmulticast mode
+-----------------
+eth_dev_ops: allmulticast_enable, allmulticast_disable
+
+enable/disable receiving multicast frames.
+
+
+.. _nic_features_unicast_mac_filter:
+
+Unicast MAC filter
+------------------
+eth_dev_ops: mac_addr_add, mac_addr_remove
+
+Adding MAC address to enable whitelist filtering to accept packets.
+
+
+.. _nic_features_multicast_mac_filter:
+
+Multicast MAC filter
+--------------------
+eth_dev_ops: set_mc_addr_list
+
+Setting the list of multicast addresses to filter.
+
+
+.. _nic_features_rss_hash:
+
+RSS hash
+--------
+eth_dev_ops: rss_hash_update, rss_hash_conf_get
+
+Configuration of Receive Side Scaling (RSS) hash computation.
+
+
+.. _nic_features_rss_key_update:
+
+RSS key update
+--------------
+eth_dev_ops: rss_hash_update, rss_hash_conf_get
+
+Updating Receive Side Scaling (RSS) hash key.
+
+.. _nic_features_rss_reta_update:
+
+RSS reta update
+---------------
+eth_dev_ops: reta_update, reta_query
+
+Updating Redirection Table of the Receive Side Scaling (RSS).
+
+
+.. _nic_features_vmdq:
+
+VMDq
+----
+
+Virtual Machine Device Queues (VMDq) support.
+
+
+.. _nic_features_sriov:
+
+SR-IOV
+------
+
+Driver supports creating Virtual Functions.
+
+
+.. _nic_features_dcb:
+
+DCB
+---
+eth_dev_ops: get_dcb_info
+
+Data Center Bridging (DCB) support.
+
+
+.. _nic_features_vlan_filter:
+
+VLAN filter
+-----------
+eth_dev_ops: vlan_filter_set
+
+Filtering of a VLAN Tag Identifier.
+
+
+.. _nic_features_ethertype_filter:
+
+Ethertype filter
+----------------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_ETHERTYPE
+
+
+.. _nic_features_ntuple_filter:
+
+N-tuple filter
+--------------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_NTUPLE
+
+
+.. _nic_features_syn_filter:
+
+SYN filter
+----------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_SYN
+
+
+.. _nic_features_tunnel_filter:
+
+Tunnel filter
+-------------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_TUNNEL
+
+
+.. _nic_features_filexible_filter:
+
+Flexible filter
+---------------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_FLEXIBLE
+
+
+.. _nic_features_hash_filter:
+
+Hash filter
+-----------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_HASH
+
+
+.. _nic_features_flow_director:
+
+Flow director
+-------------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_FDIR
+
+
+.. _nic_features_flow_control:
+
+Flow control
+------------
+eth_dev_ops: flow_ctrl_get, flow_ctrl_set, priority_flow_ctrl_set
+
+Configuring link flow control.
+
+
+.. _nic_features_flow_api:
+
+Flow API
+--------
+eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_GENERIC
+rte_flow_ops: *
+
+Generic filtering API support.
+
+
+.. _nic_features_rate_limitation:
+
+Rate limitation
+---------------
+eth_dev_ops: set_queue_rate_limit
+
+Tx rate limitation for a queue.
+
+
+.. _nic_features_traffic_mirroring:
+
+Traffic mirroring
+-----------------
+eth_dev_ops: mirror_rule_set, mirror_rule_reset
+
+Adding traffic mirroring rule support.
+
+
+.. _nic_features_crc_offload:
+
+CRC offload
+-----------
+
+
+.. _nic_features_vlan_offload:
+
+VLAN offload
+------------
+eth_dev_ops: vlan_offload_set
+
+
+.. _nic_features_qinq_offload:
+
+QinQ offload
+------------
+
+
+.. _nic_features_l3_checksum_offload:
+
+L3 checksum offload
+-------------------
+
+
+.. _nic_features_l4_checksum_offload:
+
+L4 checksum offload
+-------------------
+
+
+.. _nic_features_macsec_offload:
+
+MACsec offload
+--------------
+
+
+.. _nic_features_inner_l3_checksum:
+
+Inner L3 checksum
+-----------------
+
+
+.. _nic_features_inner_l4_checksum:
+
+Inner L4 checksum
+-----------------
+
+
+.. _nic_features_packet_type_parsing:
+
+Packet type parsing
+-------------------
+eth_dev_ops: dev_supported_ptypes_get
+
+Packet type parsing and returns list of supported types.
+
+.. _nic_features_timesync:
+
+Timesync
+--------
+eth_dev_ops: timesync_enable, timesync_disable
+eth_dev_ops: timesync_read_rx_timestamp, timesync_read_tx_timestamp
+eth_dev_ops: timesync_adjust_time, timesync_read_time, timesync_write_time
+
+
+
+.. _nic_features_rx_descriptor_status:
+
+Rx descriptor status
+--------------------
+eth_dev_ops: rx_descriptor_status
+
+Check the status of a Rx descriptor.
+
+
+.. _nic_features_tx_descriptor_status:
+
+Tx descriptor status
+--------------------
+eth_dev_ops: tx_descriptor_status
+
+Check the status of a Tx descriptor.
+
+
+.. _nic_features_basic_stats:
+
+Basic stats
+-----------
+eth_dev_ops: stats_get, stats_reset
+
+Basic statistics, same for all drivers.
+
+
+.. _nic_features_extended_stats:
+
+Extended stats
+--------------
+eth_dev_ops: xstats_get, xstats_reset, xstats_get_names
+eth_dev_ops: xstats_get_by_id, xstats_get_names_by_id
+
+Extended statistics, changes from driver to driver.
+
+
+.. _nic_features_stats_per_queue:
+
+Stats per queue
+---------------
+eth_dev_ops: queue_stats_mapping_set
+
+Ability to get stats per queue.
+
+
+.. _nic_features_fw_version:
+
+FW version
+----------
+eth_dev_ops: fw_version_get
+
+Get device hardware firmware information.
+
+
+.. _nic_features_eeprom_dump:
+
+EEPROM dump
+-----------
+eth_dev_ops: get_eeprom_length, get_eeprom, set_eeprom
+
+Get device eeprom data.
+
+
+.. _nic_features_register_dump:
+
+Registers dump
+--------------
+eth_dev_ops: get_reg
+
+Get device registers.
+
+
+.. _nic_features_led:
+
+LED
+---
+eth_dev_ops: dev_led_on, dev_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
+----------
+
+
+.. _nic_features_armv7:
+
+ARMv7
+-----
+defconfig_arm-armv7a-\*-\*
+
+Support armv7 architecture.
+
+
+.. _nic_features_armv8:
+
+ARMv8
+-----
+defconfig_arm64-armv8a-\*-\*
+
+Support armv8a (64bit) architecture.
+
+
+.. _nic_features_power8:
+
+Power8
+------
+defconfig_ppc_64-power8-\*-\*
+
+Support PowerPC architecture.
+
+
+.. _nic_features_x86-32:
+
+x86-32
+------
+defconfig_x86_x32-native-\*-\*
+defconfig_i686-native-\*-\*
+
+Support 32bits x86 architecture.
+
+
+.. _nic_features_x86-64:
+
+x86-64
+------
+defconfig_x86_64-native-\*-\*
+
+Support 64bits x86 architecture.
+
+
+.. _nic_features_usage_doc:
+
+Usage doc
+---------
+doc/guides/nics/\*.rst
+
+Documentation describes usage.
+
+
+.. _nic_features_design_doc:
+
+Design doc
+----------
+
+doc/guides/nics/\*.rst
+
+Documentation describes design.
+
+.. _nic_features_perf_doc:
+
+Perf doc
+--------
+http://dpdk.org/doc/perf/*
+
+Document performance values.
+
+.. _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_setup
+rx_queue_release
+rx_queue_count
+rx_descriptor_done
+tx_queue_setup
+tx_queue_release
+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
-- 
2.13.0

[dpdk-dev] [PATCH v2] doc: document NIC features

[Ferruh Yigit]

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

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

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          |   2 +
 doc/guides/nics/overview_features.rst | 816 ++++++++++++++++++++++++++++++++++
 2 files changed, 818 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..8eb5de533 100644
--- a/doc/guides/nics/overview.rst
+++ b/doc/guides/nics/overview.rst
@@ -48,6 +48,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..72ecf6aa4
--- /dev/null
+++ b/doc/guides/nics/overview_features.rst
@@ -0,0 +1,816 @@
+..  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
+=================
+
+.. _nic_features_speed_capabilities:
+
+Speed capabilities
+------------------
+::
+
+  eth_dev_ops: dev_infos_get:speed_capa
+  API: rte_eth_dev_info_get
+
+Advertise the speed capabilities that the current device is capable to offer.
+
+
+.. _nic_features_link_status:
+
+Link status
+-----------
+::
+
+  eth_dev_ops: link_update
+  API: rte_eth_link_get, rte_eth_link_get_nowait
+
+Getting link speed, duplex mode and state (up/down) support.
+
+
+.. _nic_features_link_status_event:
+
+Link status event
+-----------------
+::
+
+  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
+
+Link Status Change interrupts support.
+
+
+.. _nic_features_removal_event:
+
+Removal event
+-------------
+::
+
+  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
+
+Device removal interrupts support.
+
+
+.. _nic_features_queue_status_event:
+
+Queue status event
+------------------
+::
+
+  rte_eth_event_type: RTE_ETH_EVENT_QUEUE_STATE
+
+Queue enable/disable events.
+
+
+.. _nic_features_rx_interrupt:
+
+Rx interrupt
+------------
+::
+
+  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
+
+Rx interrupts support.
+
+
+.. _nic_features_free_tx_mbuf_on_demand:
+
+Free Tx mbuf on demand
+----------------------
+::
+
+  eth_dev_ops: tx_done_cleanup
+  API: rte_eth_tx_done_cleanup
+
+Forcing free consumed buffers on Tx ring support.
+
+
+.. _nic_features_queue_start_stop:
+
+Queue start/stop
+----------------
+::
+
+  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
+
+start/stop specified Rx/Tx queue of a port.
+
+
+.. _nic_features_mtu_update:
+
+MTU update
+----------
+::
+
+  eth_dev_ops: mtu_set
+  API: rte_eth_dev_set_mtu, rte_eth_dev_get_mtu
+
+Updating port MTU support.
+
+
+.. _nic_features_jumbo_frame:
+
+Jumbo frame
+-----------
+::
+
+  user config: dev_conf.rxmode.jumbo_frame, dev_conf.rxmode.max_rx_pkt_len
+
+Receiving jumbo frames support.
+
+
+.. _nic_features_scattered_rx:
+
+Scattered Rx
+------------
+::
+
+  user config: dev_conf.rxmode.enable_scatter
+
+Receiving segmented mbufs support.
+
+
+.. _nic_features_lro:
+
+LRO
+---
+::
+
+  user config: dev_conf.rxmode.enable_lro
+  mbuf: mbuf.ol_flags:PKT_RX_LRO, mbuf.tso_segsz
+
+Large Receive Offload.
+
+
+.. _nic_features_tso:
+
+TSO
+---
+::
+
+  mbuf: mbuf.ol_flags:PKT_TX_TCP_SEG
+
+TCP Segmentation Offloading.
+
+
+.. _nic_features_promiscuous_mode:
+
+Promiscuous mode
+----------------
+::
+
+  eth_dev_ops: promiscuous_enable, promiscuous_disable
+  API: rte_eth_promiscuous_enable, rte_eth_promiscuous_disable, rte_eth_promiscuous_get
+
+enable/disable port promiscuous mode.
+
+
+.. _nic_features_allmulticast_mode:
+
+Allmulticast mode
+-----------------
+::
+
+  eth_dev_ops: allmulticast_enable, allmulticast_disable
+  API: rte_eth_allmulticast_enable, rte_eth_allmulticast_disable, rte_eth_allmulticast_get
+
+enable/disable receiving multicast frames.
+
+
+.. _nic_features_unicast_mac_filter:
+
+Unicast MAC filter
+------------------
+::
+
+  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
+
+Adding MAC address to enable whitelist filtering to accept packets.
+
+
+.. _nic_features_multicast_mac_filter:
+
+Multicast MAC filter
+--------------------
+::
+
+  eth_dev_ops: set_mc_addr_list
+  API: rte_eth_dev_set_mc_addr_list
+
+Setting the list of multicast addresses to filter.
+
+
+.. _nic_features_rss_hash:
+
+RSS hash
+--------
+::
+
+  user config: dev_conf.rxmode.mq_mode = ETH_MQ_RX_RSS_FLAG
+  mbuf: mbuf.ol_flags:PKT_RX_RSS_HASH, mbuf.rss
+
+Driver sets rss field of mbuf on reception.
+
+
+.. _nic_features_rss_key_update:
+
+RSS key update
+--------------
+::
+
+  eth_dev_ops: rss_hash_update, rss_hash_conf_get
+  API: rte_eth_dev_rss_hash_update, rte_eth_dev_rss_hash_conf_get
+
+Configuration of Receive Side Scaling (RSS) hash computation.
+Updating Receive Side Scaling (RSS) hash key.
+
+.. _nic_features_rss_reta_update:
+
+RSS reta update
+---------------
+::
+
+  eth_dev_ops: reta_update, reta_query
+  API: rte_eth_dev_rss_reta_update, rte_eth_dev_rss_reta_query
+
+Updating Redirection Table of the Receive Side Scaling (RSS).
+
+
+.. _nic_features_vmdq:
+
+VMDq
+----
+::
+
+  user config: dev_conf.rxmode.mq_mode = ETH_MQ_RX_VMDQ_FLAG
+
+Virtual Machine Device Queues (VMDq) support.
+
+
+.. _nic_features_sriov:
+
+SR-IOV
+------
+
+Driver supports creating Virtual Functions.
+
+
+.. _nic_features_dcb:
+
+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
+
+Data Center Bridging (DCB) support.
+
+
+.. _nic_features_vlan_filter:
+
+VLAN filter
+-----------
+::
+
+  eth_dev_ops: vlan_filter_set
+  API: rte_eth_dev_vlan_filter
+
+Filtering of a VLAN Tag Identifier.
+
+
+.. _nic_features_ethertype_filter:
+
+Ethertype filter
+----------------
+::
+
+  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
+--------------
+::
+
+  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
+----------
+::
+
+  eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_SYN
+  API: rte_eth_dev_filter_ctrl, rte_eth_dev_filter_supported
+
+TCP syn filter.
+
+
+.. _nic_features_tunnel_filter:
+
+Tunnel filter
+-------------
+::
+
+  eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_TUNNEL
+  API: rte_eth_dev_filter_ctrl, rte_eth_dev_filter_supported
+
+
+.. _nic_features_filexible_filter:
+
+Flexible 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
+-----------
+::
+
+  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
+-------------
+::
+
+  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
+------------
+::
+
+  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
+
+Configuring link flow control.
+
+
+.. _nic_features_flow_api:
+
+Flow API
+--------
+::
+
+  eth_dev_ops: filter_ctrl:RTE_ETH_FILTER_GENERIC
+  rte_flow_ops: *
+
+Generic filtering API support for implementing various above filters.
+
+
+.. _nic_features_rate_limitation:
+
+Rate limitation
+---------------
+::
+
+  eth_dev_ops: set_queue_rate_limit
+  API: rte_eth_set_queue_rate_limit
+
+Tx rate limitation for a queue.
+
+
+.. _nic_features_traffic_mirroring:
+
+Traffic mirroring
+-----------------
+::
+
+  eth_dev_ops: mirror_rule_set, mirror_rule_reset
+  API: rte_eth_mirror_rule_set, rte_eth_mirror_rule_reset
+
+Adding traffic mirroring rule support.
+
+
+.. _nic_features_crc_offload:
+
+CRC offload
+-----------
+::
+
+  user config: dev_conf.rxmode.hw_strip_crc
+
+CRC stripping by hardware.
+
+
+.. _nic_features_vlan_offload:
+
+VLAN offload
+------------
+::
+
+  user config: dev_conf.rxmode.hw_vlan_strip
+  user config: dev_conf.rxmode.hw_vlan_filter
+  user config: 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
+
+
+.. _nic_features_qinq_offload:
+
+QinQ offload
+------------
+::
+
+  mbuf: mbuf.ol_flags:PKT_RX_QINQ_STRIPPED, mbuf.vlan_tci, mbuf.vlan_tci_outer
+  mbuf: mbuf.ol_flags:PKT_TX_QINQ_PKT
+
+
+.. _nic_features_l3_checksum_offload:
+
+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: mbuf.ol_flags:PKT_TX_IP_CKSUM
+  mbuf: mbuf.ol_flags:PKT_TX_IPV4|PKT_TX_IPV6
+
+
+.. _nic_features_l4_checksum_offload:
+
+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: mbuf.ol_flags:PKT_TX_IPV4|PKT_TX_IPV6
+  mbuf: mbuf.ol_flags:PKT_TX_L4_NO_CKSUM|PKT_TX_TCP_CKSUM|PKT_TX_SCTP_CKSUM|PKT_TX_UDP_CKSUM
+
+
+.. _nic_features_macsec_offload:
+
+MACsec offload
+--------------
+::
+
+  mbuf: mbuf.ol_flags:PKT_TX_MACSEC
+
+
+.. _nic_features_inner_l3_checksum:
+
+Inner L3 checksum
+-----------------
+
+
+.. _nic_features_inner_l4_checksum:
+
+Inner L4 checksum
+-----------------
+
+
+.. _nic_features_packet_type_parsing:
+
+Packet type parsing
+-------------------
+::
+
+  eth_dev_ops: dev_supported_ptypes_get
+  API: rte_eth_dev_get_supported_ptypes
+
+Packet type parsing and returns list of supported types.
+
+.. _nic_features_timesync:
+
+Timesync
+--------
+::
+
+  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
+
+IEEE1588/802.1AS timestamping support.
+
+.. _nic_features_rx_descriptor_status:
+
+Rx descriptor status
+--------------------
+::
+
+  eth_dev_ops: rx_descriptor_status
+  API: rte_eth_rx_descriptor_status
+  eth_dev_ops: rx_descriptor_done
+  API: rte_eth_rx_descriptor_done
+
+Check the status of a Rx descriptor.
+
+When rx_descriptor_status used, status can be Available, Done or Unavailable.
+When rx_descriptor_done used, status can be DD bit is set or DD bit is not set.
+
+
+.. _nic_features_tx_descriptor_status:
+
+Tx descriptor status
+--------------------
+::
+
+  eth_dev_ops: tx_descriptor_status
+  API: rte_eth_tx_descriptor_status
+
+Check the status of a Tx descriptor. Status can be Full, Done, Unavailable.
+
+
+.. _nic_features_basic_stats:
+
+Basic stats
+-----------
+::
+
+  eth_dev_ops: stats_get, stats_reset
+  API: rte_eth_stats_get, rte_eth_stats_reset
+
+Basic statistics, same for all drivers:
+ipackets, opackets, ibytes, obytes,
+imissed, ierrors, oerrors, rx_nombuf
+
+And per queue stats:
+q_ipackets, q_opackets, q_ibytes, q_obytes, q_errors
+
+
+.. _nic_features_extended_stats:
+
+Extended stats
+--------------
+::
+
+  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
+
+Extended statistics, changes from driver to driver.
+
+
+.. _nic_features_stats_per_queue:
+
+Stats per queue
+---------------
+::
+
+  eth_dev_ops: queue_stats_mapping_set
+  API: rte_eth_dev_set_rx_queue_stats_mapping, rte_eth_dev_set_tx_queue_stats_mapping
+
+Configure per queue stat counter mapping.
+
+
+.. _nic_features_fw_version:
+
+FW version
+----------
+::
+
+  eth_dev_ops: fw_version_get
+  API: rte_eth_dev_fw_version_get
+
+Get device hardware firmware information.
+
+
+.. _nic_features_eeprom_dump:
+
+EEPROM dump
+-----------
+::
+
+  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
+
+Get/Set device eeprom data.
+
+
+.. _nic_features_register_dump:
+
+Registers dump
+--------------
+::
+
+  eth_dev_ops: get_reg
+  API: rte_eth_dev_get_reg_info
+
+Retrieve device registers and register attributes (number of registers and register size).
+
+
+.. _nic_features_led:
+
+LED
+---
+::
+
+  eth_dev_ops: dev_led_on, dev_led_off
+  API: rte_eth_led_on, rte_eth_led_off
+
+Turn on/off SW controllable LED on a device.
+
+
+.. _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
+-----
+::
+
+  defconfig_arm-armv7a-\*-\*
+
+Support armv7 architecture.
+
+
+.. _nic_features_armv8:
+
+ARMv8
+-----
+::
+
+  defconfig_arm64-armv8a-\*-\*
+
+Support armv8a (64bit) architecture.
+
+
+.. _nic_features_power8:
+
+Power8
+------
+::
+
+  defconfig_ppc_64-power8-\*-\*
+
+Support PowerPC architecture.
+
+
+.. _nic_features_x86-32:
+
+x86-32
+------
+::
+
+  defconfig_x86_x32-native-\*-\*
+  defconfig_i686-native-\*-\*
+
+Support 32bits x86 architecture.
+
+
+.. _nic_features_x86-64:
+
+x86-64
+------
+::
+
+  defconfig_x86_64-native-\*-\*
+
+Support 64bits x86 architecture.
+
+
+.. _nic_features_usage_doc:
+
+Usage doc
+---------
+::
+
+  doc/guides/nics/\*.rst
+
+Documentation describes usage.
+
+
+.. _nic_features_design_doc:
+
+Design doc
+----------
+::
+
+  doc/guides/nics/\*.rst
+
+Documentation describes design.
+
+
+.. _nic_features_perf_doc:
+
+Perf doc
+--------
+::
+
+  dpdk.org/doc/perf/*
+
+Document performance values.
+
+
+
+.. _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
-- 
2.13.0

Re: [dpdk-dev] [PATCH v2] doc: document NIC features

[Mcnamara, John]

> -----Original Message-----
> From: Yigit, Ferruh
> Sent: Thursday, June 22, 2017 8:03 PM
> To: Mcnamara, John <john.mcnamara@intel.com>
> Cc: dev@dpdk.org; Yigit, Ferruh <ferruh.yigit@intel.com>; Thomas Monjalon
> <thomas@monjalon.net>; Olivier Matz <olivier.matz@6wind.com>
> Subject: [PATCH v2] 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>

This is a good idea and a good start. I'll send you some additions you can use
for a V2. Agreed that it would be good to get more community input for this.

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

[Ferruh Yigit]

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

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()``.
+
+
+.. _nic_features_jumbo_frame:
+
+Jumbo frame
+-----------
+
+Supports Rx jumbo frames.
+
+
+* **user config**: ``dev_conf.rxmode.jumbo_frame``,
+  ``dev_conf.rxmode.max_rx_pkt_len``.
+
+
+.. _nic_features_scattered_rx:
+
+Scattered Rx
+------------
+
+Supports receiving segmented mbufs.
+
+* **user config**: ``dev_conf.rxmode.enable_scatter``.
+
+
+.. _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``.
+
+
+.. _nic_features_tso:
+
+TSO
+---
+
+Supports TCP Segmentation Offloading.
+
+* **mbuf**: ``mbuf.ol_flags:PKT_TX_TCP_SEG``.
+
+
+.. _nic_features_promiscuous_mode:
+
+Promiscuous mode
+----------------
+
+Supports enabling/disabling promiscuous mode for a port.
+
+* **API**: ``rte_eth_promiscuous_enable()``, ``rte_eth_promiscuous_disable()``,
+  ``rte_eth_promiscuous_get()``.
+
+
+.. _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()``.
+
+
+.. _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``.
+* **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()``.
+
+.. _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()``.
+
+
+.. _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.
+
+
+.. _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()``.
+
+
+.. _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()``.
+
+
+.. _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``.
+
+
+.. _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``.
+
+
+.. _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``.
+
+
+.. _nic_features_macsec_offload:
+
+MACsec offload
+--------------
+
+Supports MACsec.
+
+* **mbuf**: ``mbuf.ol_flags:PKT_TX_MACSEC``.
+
+
+.. _nic_features_inner_l3_checksum:
+
+Inner L3 checksum
+-----------------
+
+Supports inner packet L3 checksum.
+
+.. _nic_features_inner_l4_checksum:
+
+Inner L4 checksum
+-----------------
+
+Supports inner packet L4 checksum.
+
+
+.. _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``
-- 
2.13.0

Re: [dpdk-dev] [PATCH v3] doc: document NIC features

[Mcnamara, John]

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

Re: [dpdk-dev] [PATCH v3] doc: document NIC features

[Andrew Rybchenko]

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``

Re: [dpdk-dev] [PATCH v3] doc: document NIC features

[Ferruh Yigit]

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

Re: [dpdk-dev] [PATCH v3] doc: document NIC features

[Thomas Monjalon]

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.

Re: [dpdk-dev] [PATCH v3] doc: document NIC features

[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?

Re: [dpdk-dev] [PATCH v3] doc: document NIC features

[Thomas Monjalon]

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.

Re: [dpdk-dev] [PATCH v3] doc: document NIC features

[Ferruh Yigit]

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.

Re: [dpdk-dev] [PATCH v3] doc: document NIC features

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

Regards,
Keith

Re: [dpdk-dev] [PATCH v3] doc: document NIC features

[Thomas Monjalon]

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.

Re: [dpdk-dev] [PATCH v3] doc: document NIC features

[Wiles, Keith]

> 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

Re: [dpdk-dev] [PATCH v3] doc: document NIC features

[Ferruh Yigit]

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.

<...>

Re: [dpdk-dev] [PATCH v3] doc: document NIC features

[Andrew Rybchenko]

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.

> <...>

<...>

[dpdk-dev] [PATCH v4] doc: document NIC features

[Ferruh Yigit]

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>

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 | 858 ++++++++++++++++++++++++++++++++++
 2 files changed, 862 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..c0ec10e69
--- /dev/null
+++ b/doc/guides/nics/overview_features.rst
@@ -0,0 +1,858 @@
+..  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.
+
+``[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:
+
+Link status
+-----------
+
+Supports getting the link speed, duplex mode and link state (up/down).
+
+* **[implements] eth_dev_ops**: ``link_update``.
+* **[provides]   rte_eth_dev_data**: ``dev_link``.
+* **[related]    API**: ``rte_eth_link_get()``, ``rte_eth_link_get_nowait()``.
+
+
+.. _nic_features_link_status_event:
+
+Link status event
+-----------------
+
+Supports Link Status Change interrupts.
+
+* **[uses]     user config**: ``dev_conf.intr_conf.lsc``.
+* **[uses]     rte_eth_dev_data**: ``dev_flags:RTE_ETH_DEV_INTR_LSC``.
+* **[uses]     rte_eth_event_type**: ``RTE_ETH_EVENT_INTR_LSC``.
+* **[provides] rte_pci_driver.drv_flags**: ``RTE_PCI_DRV_INTR_LSC``.
+* **[provides] rte_eth_dev_data**: ``dev_link``.
+* **[related]  API**: ``rte_eth_link_get()``, ``rte_eth_link_get_nowait()``.
+
+
+.. _nic_features_removal_event:
+
+Removal event
+-------------
+
+Supports device removal interrupts.
+
+* **[uses]     user config**: ``dev_conf.intr_conf.rmv``.
+* **[uses]     rte_eth_dev_data**: ``dev_flags:RTE_ETH_DEV_INTR_RMV``.
+* **[uses]     rte_eth_event_type**: ``RTE_ETH_EVENT_INTR_RMV``.
+* **[provides] rte_pci_driver.drv_flags**: ``RTE_PCI_DRV_INTR_RMV``.
+
+
+.. _nic_features_queue_status_event:
+
+Queue status event
+------------------
+
+Supports queue enable/disable events.
+
+* **[uses] rte_eth_event_type**: ``RTE_ETH_EVENT_QUEUE_STATE``.
+
+
+.. _nic_features_rx_interrupt:
+
+Rx interrupt
+------------
+
+Supports Rx interrupts.
+
+* **[uses]       user config**: ``dev_conf.intr_conf.rxq``.
+* **[implements] eth_dev_ops**: ``rx_queue_intr_enable``, ``rx_queue_intr_disable``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``tx_done_cleanup``.
+* **[related] 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.
+
+* **[implements] eth_dev_ops**: ``rx_queue_start``, ``rx_queue_stop``, ``tx_queue_start``,
+  ``tx_queue_stop``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``mtu_set``.
+* **[implements] rte_eth_dev_data**: ``mtu``.
+* **[provides]   rte_eth_dev_info**: ``max_rx_pktlen``.
+* **[related]    API**: ``rte_eth_dev_set_mtu()``, ``rte_eth_dev_get_mtu()``.
+
+
+.. _nic_features_jumbo_frame:
+
+Jumbo frame
+-----------
+
+Supports Rx jumbo frames.
+
+* **[uses]    user config**: ``dev_conf.rxmode.jumbo_frame``,
+  ``dev_conf.rxmode.max_rx_pkt_len``.
+* **[related] rte_eth_dev_info**: ``max_rx_pktlen``.
+* **[related] API**: ``rte_eth_dev_set_mtu()``.
+
+
+.. _nic_features_scattered_rx:
+
+Scattered Rx
+------------
+
+Supports receiving segmented mbufs.
+
+* **[uses]       user config**: ``dev_conf.rxmode.enable_scatter``.
+* **[implements] datapath**: ``Scattered Rx function``.
+* **[implements] rte_eth_dev_data**: ``scattered_rx``.
+* **[provides]   eth_dev_ops**: ``rxq_info_get:scattered_rx``.
+
+
+.. _nic_features_lro:
+
+LRO
+---
+
+Supports Large Receive Offload.
+
+* **[uses]       user config**: ``dev_conf.rxmode.enable_lro``.
+* **[implements] datapath**: ``LRO functionality``.
+* **[implements] rte_eth_dev_data**: ``lro``.
+* **[provides]   mbuf**: ``mbuf.ol_flags:PKT_RX_LRO``, ``mbuf.tso_segsz``.
+* **[provides]   rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_TCP_LRO``.
+
+
+.. _nic_features_tso:
+
+TSO
+---
+
+Supports TCP Segmentation Offloading.
+
+* **[uses] rte_eth_desc_lim**: ``nb_seg_max``, ``nb_mtu_seg_max``.
+* **[uses] mbuf**: ``mbuf.ol_flags:PKT_TX_TCP_SEG``.
+* **[implements] datapath**: ``TSO functionality``.
+* **[provides] rte_eth_dev_info**: ``tx_offload_capa:DEV_TX_OFFLOAD_TCP_TSO,DEV_TX_OFFLOAD_UDP_TSO``.
+
+
+.. _nic_features_promiscuous_mode:
+
+Promiscuous mode
+----------------
+
+Supports enabling/disabling promiscuous mode for a port.
+
+* **[implements] eth_dev_ops**: ``promiscuous_enable``, ``promiscuous_disable``.
+* **[implements] rte_eth_dev_data**: ``promiscuous``.
+* **[related]    API**: ``rte_eth_promiscuous_enable()``, ``rte_eth_promiscuous_disable()``,
+  ``rte_eth_promiscuous_get()``.
+
+
+.. _nic_features_allmulticast_mode:
+
+Allmulticast mode
+-----------------
+
+Supports enabling/disabling receiving multicast frames.
+
+* **[implements] eth_dev_ops**: ``allmulticast_enable``, ``allmulticast_disable``.
+* **[implements] rte_eth_dev_data**: ``all_multicast``.
+* **[related]    API**: ``rte_eth_allmulticast_enable()``,
+  ``rte_eth_allmulticast_disable()``, ``rte_eth_allmulticast_get()``.
+
+
+.. _nic_features_unicast_mac_filter:
+
+Unicast MAC filter
+------------------
+
+Supports adding MAC addresses to enable whitelist filtering to accept packets.
+
+* **[implements] eth_dev_ops**: ``mac_addr_set``, ``mac_addr_add``, ``mac_addr_remove``.
+* **[implements] rte_eth_dev_data**: ``mac_addrs``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``set_mc_addr_list``.
+* **[related]    API**: ``rte_eth_dev_set_mc_addr_list()``.
+
+
+.. _nic_features_rss_hash:
+
+RSS hash
+--------
+
+Supports RSS hashing on RX.
+
+* **[uses]     user config**: ``dev_conf.rxmode.mq_mode`` = ``ETH_MQ_RX_RSS_FLAG``.
+* **[provides] 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.
+
+* **[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.
+
+
+.. _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:
+
+VLAN filter
+-----------
+
+Supports filtering of a VLAN Tag identifier.
+
+* **[uses]       user config**: ``dev_conf.rxmode.hw_vlan_filter``.
+* **[implements] eth_dev_ops**: ``vlan_filter_set``.
+* **[related]    API**: ``rte_eth_dev_vlan_filter()``.
+
+
+.. _nic_features_ethertype_filter:
+
+Ethertype filter
+----------------
+
+Supports filtering on Ethernet type.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_ETHERTYPE``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+.. _nic_features_ntuple_filter:
+
+N-tuple filter
+--------------
+
+Supports filtering on N-tuple values.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_NTUPLE``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_syn_filter:
+
+SYN filter
+----------
+
+Supports TCP syn filtering.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_SYN``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_tunnel_filter:
+
+Tunnel filter
+-------------
+
+Supports tunnel filtering.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_TUNNEL``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_FLEXIBLE``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_hash_filter:
+
+Hash filter
+-----------
+
+Supports Hash filtering.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_HASH``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_flow_director:
+
+Flow director
+-------------
+
+Supports Flow Director style filtering to queues.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_FDIR``.
+* **[provides]   mbuf**: ``mbuf.ol_flags:`` ``PKT_RX_FDIR``, ``PKT_RX_FDIR_ID``,
+  ``PKT_RX_FDIR_FLX``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_flow_control:
+
+Flow control
+------------
+
+Supports configuring link flow control.
+
+* **[implements] eth_dev_ops**: ``flow_ctrl_get``, ``flow_ctrl_set``,
+  ``priority_flow_ctrl_set``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_GENERIC``.
+* **[implements] rte_flow_ops**: All.
+
+
+.. _nic_features_rate_limitation:
+
+Rate limitation
+---------------
+
+Supports Tx rate limitation for a queue.
+
+* **[implements] eth_dev_ops**: ``set_queue_rate_limit``.
+* **[related]    API**: ``rte_eth_set_queue_rate_limit()``.
+
+
+.. _nic_features_traffic_mirroring:
+
+Traffic mirroring
+-----------------
+
+Supports adding traffic mirroring rules.
+
+* **[implements] eth_dev_ops**: ``mirror_rule_set``, ``mirror_rule_reset``.
+* **[related]    API**: ``rte_eth_mirror_rule_set()``, ``rte_eth_mirror_rule_reset()``.
+
+
+.. _nic_features_crc_offload:
+
+CRC offload
+-----------
+
+Supports CRC stripping by hardware.
+
+* **[uses] user config**: ``dev_conf.rxmode.hw_strip_crc``.
+
+
+.. _nic_features_vlan_offload:
+
+VLAN offload
+------------
+
+Supports VLAN offload to hardware.
+
+* **[uses]       user config**: ``dev_conf.rxmode.hw_vlan_strip``,
+  ``dev_conf.rxmode.hw_vlan_filter``, ``dev_conf.rxmode.hw_vlan_extend``.
+* **[implements] eth_dev_ops**: ``vlan_offload_set``.
+* **[provides]   mbuf**: ``mbuf.ol_flags:PKT_RX_VLAN_STRIPPED``, ``mbuf.vlan_tci``.
+* **[provides]   rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_VLAN_STRIP``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_VLAN_INSERT``.
+* **[related]    API**: ``rte_eth_dev_set_vlan_offload()``,
+  ``rte_eth_dev_get_vlan_offload()``.
+
+
+.. _nic_features_qinq_offload:
+
+QinQ offload
+------------
+
+Supports QinQ (queue in queue) offload.
+
+* **[uses] mbuf**: ``mbuf.ol_flags:PKT_TX_QINQ_PKT``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_QINQ_STRIPPED``, ``mbuf.vlan_tci``,
+   ``mbuf.vlan_tci_outer``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_QINQ_STRIP``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_QINQ_INSERT``.
+
+
+.. _nic_features_l3_checksum_offload:
+
+L3 checksum offload
+-------------------
+
+Supports L3 checksum offload.
+
+* **[uses]     user config**: ``dev_conf.rxmode.hw_ip_checksum``.
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_IP_CKSUM``,
+  ``mbuf.ol_flags:PKT_TX_IPV4`` | ``PKT_TX_IPV6``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_IP_CKSUM_UNKNOWN`` |
+  ``PKT_RX_IP_CKSUM_BAD`` | ``PKT_RX_IP_CKSUM_GOOD`` |
+  ``PKT_RX_IP_CKSUM_NONE``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_IPV4_CKSUM``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_IPV4_CKSUM``.
+
+
+.. _nic_features_l4_checksum_offload:
+
+L4 checksum offload
+-------------------
+
+Supports L4 checksum offload.
+
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_IPV4`` | ``PKT_TX_IPV6``,
+  ``mbuf.ol_flags:PKT_TX_L4_NO_CKSUM`` | ``PKT_TX_TCP_CKSUM`` |
+  ``PKT_TX_SCTP_CKSUM`` | ``PKT_TX_UDP_CKSUM``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_L4_CKSUM_UNKNOWN`` |
+  ``PKT_RX_L4_CKSUM_BAD`` | ``PKT_RX_L4_CKSUM_GOOD`` |
+  ``PKT_RX_L4_CKSUM_NONE``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_UDP_CKSUM,DEV_RX_OFFLOAD_TCP_CKSUM``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_UDP_CKSUM,DEV_TX_OFFLOAD_TCP_CKSUM,DEV_TX_OFFLOAD_SCTP_CKSUM``.
+
+
+.. _nic_features_macsec_offload:
+
+MACsec offload
+--------------
+
+Supports MACsec.
+
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_MACSEC``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_MACSEC_STRIP``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_MACSEC_INSERT``.
+
+
+.. _nic_features_inner_l3_checksum:
+
+Inner L3 checksum
+-----------------
+
+Supports inner packet L3 checksum.
+
+
+.. _nic_features_inner_l4_checksum:
+
+Inner L4 checksum
+-----------------
+
+Supports inner packet L4 checksum.
+
+
+.. _nic_features_packet_type_parsing:
+
+Packet type parsing
+-------------------
+
+Supports packet type parsing and returns a list of supported types.
+
+* **[implements] eth_dev_ops**: ``dev_supported_ptypes_get``.
+* **[related]    API**: ``rte_eth_dev_get_supported_ptypes()``.
+
+
+.. _nic_features_timesync:
+
+Timesync
+--------
+
+Supports IEEE1588/802.1AS timestamping.
+
+* **[implements] eth_dev_ops**: ``timesync_enable``, ``timesync_disable``
+  ``timesync_read_rx_timestamp``, ``timesync_read_tx_timestamp``,
+  ``timesync_adjust_time``, ``timesync_read_time``, ``timesync_write_time``.
+* **[related]    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".
+
+* **[implements] eth_dev_ops**: ``rx_descriptor_status``.
+* **[related]    API**: ``rte_eth_rx_descriptor_status()``.
+* **[implements] eth_dev_ops**: ``rx_descriptor_done``.
+* **[related]    API**: ``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."
+
+* **[implements] eth_dev_ops**: ``tx_descriptor_status``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``stats_get``, ``stats_reset``.
+* **[related]    API**: ``rte_eth_stats_get``, ``rte_eth_stats_reset()``.
+
+
+.. _nic_features_extended_stats:
+
+Extended stats
+--------------
+
+Supports Extended Statistics, changes from driver to driver.
+
+* **[implements] eth_dev_ops**: ``xstats_get``, ``xstats_reset``, ``xstats_get_names``.
+* **[implements] eth_dev_ops**: ``xstats_get_by_id``, ``xstats_get_names_by_id``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``queue_stats_mapping_set``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``fw_version_get``.
+* **[related]    API**: ``rte_eth_dev_fw_version_get()``.
+
+
+.. _nic_features_eeprom_dump:
+
+EEPROM dump
+-----------
+
+Supports getting/setting device eeprom data.
+
+* **[implements] eth_dev_ops**: ``get_eeprom_length``, ``get_eeprom``, ``set_eeprom``.
+* **[related]    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).
+
+* **[implements] eth_dev_ops**: ``get_reg``.
+* **[related]    API**: ``rte_eth_dev_get_reg_info()``.
+
+
+.. _nic_features_led:
+
+LED
+---
+
+Supports turning on/off a software controllable LED on a device.
+
+* **[implements] eth_dev_ops**: ``dev_led_on``, ``dev_led_off``.
+* **[related]    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``
-- 
2.13.0

Re: [dpdk-dev] [PATCH v4] doc: document NIC features

[Andrew Rybchenko]

On 07/07/2017 08:21 PM, Ferruh Yigit wrote:
> 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>

Reviewed-by: Andrew Rybchenko <arybchenko@solarflare.com>

Few minor questions/notes below.

> ---
> Cc: Olivier Matz <olivier.matz@6wind.com>
>
> 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 | 858 ++++++++++++++++++++++++++++++++++
>   2 files changed, 862 insertions(+)
>   create mode 100644 doc/guides/nics/overview_features.rst

<...>

> +.. _nic_features_rss_hash:
> +
> +RSS hash
> +--------
> +
> +Supports RSS hashing on RX.
> +
> +* **[uses]     user config**: ``dev_conf.rxmode.mq_mode`` = ``ETH_MQ_RX_RSS_FLAG``.
> +* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_RSS_H()ASH``, ``mbuf.rss``.

Is it indented that dev_info.flow_type_rss_offloads not mentioned here?

<...>

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

As I understand outer checksum (PKT_RX_EIP_CKSUM_BAD for Rx) and 
IPv4/IPv6 flags and
offload capabilities should be mentioned here. If ourter flags are set, 
it means that usual checksum
flags corresponds to inner packet.

<...>

> +
> +.. _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".
> +
> +* **[implements] eth_dev_ops**: ``rx_descriptor_status``.
> +* **[related]    API**: ``rte_eth_rx_descriptor_status()``.
> +* **[implements] eth_dev_ops**: ``rx_descriptor_done``.
> +* **[related]    API**: ``rte_eth_rx_descriptor_done()``.

I'm not sure if _done API should be mentioned here. If yes, may be 
status of the _done
API should be highlighted (as far as I remember it was ideas to remove it).

<...>

> +
> +.. _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.

Should we mention that PMD provides RTE_PMD_REGISTER_KMOD_DEP with 
corresponding kernel module listed.

<...>

Re: [dpdk-dev] [PATCH v4] doc: document NIC features

[Ferruh Yigit]

On 7/8/2017 10:47 AM, Andrew Rybchenko wrote:
> On 07/07/2017 08:21 PM, Ferruh Yigit wrote:
>> 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>
> 
> Reviewed-by: Andrew Rybchenko <arybchenko@solarflare.com>
> 
> Few minor questions/notes below.
> 
>> ---
>> Cc: Olivier Matz <olivier.matz@6wind.com>
>>
>> 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 | 858 ++++++++++++++++++++++++++++++++++
>>   2 files changed, 862 insertions(+)
>>   create mode 100644 doc/guides/nics/overview_features.rst
> 
> <...>
> 
>> +.. _nic_features_rss_hash:
>> +
>> +RSS hash
>> +--------
>> +
>> +Supports RSS hashing on RX.
>> +
>> +* **[uses]     user config**: ``dev_conf.rxmode.mq_mode`` = ``ETH_MQ_RX_RSS_FLAG``.
>> +* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_RSS_H()ASH``, ``mbuf.rss``.
> 
> Is it indented that dev_info.flow_type_rss_offloads not mentioned here?

I will add it.

> 
> <...>
> 
>> +
>> +.. _nic_features_inner_l3_checksum:
>> +
>> +Inner L3 checksum
>> +-----------------
>> +
>> +Supports inner packet L3 checksum.
>> +
>> +
>> +.. _nic_features_inner_l4_checksum:
>> +
>> +Inner L4 checksum
>> +-----------------
>> +
>> +Supports inner packet L4 checksum.
>> +
> 
> As I understand outer checksum (PKT_RX_EIP_CKSUM_BAD for Rx) and 
> IPv4/IPv6 flags and
> offload capabilities should be mentioned here. If ourter flags are set, 
> it means that usual checksum
> flags corresponds to inner packet.

I am not sure about these two, that is why I tend to left empty for now,
will update later.

> 
> <...>
> 
>> +
>> +.. _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".
>> +
>> +* **[implements] eth_dev_ops**: ``rx_descriptor_status``.
>> +* **[related]    API**: ``rte_eth_rx_descriptor_status()``.
>> +* **[implements] eth_dev_ops**: ``rx_descriptor_done``.
>> +* **[related]    API**: ``rte_eth_rx_descriptor_done()``.
> 
> I'm not sure if _done API should be mentioned here. If yes, may be 
> status of the _done
> API should be highlighted (as far as I remember it was ideas to remove it).

Both looks like valid APIs right now, there is no deprecation note
(__rte_deprecated) on _done API.

Description of feature briefly mentions status values.

> 
> <...>
> 
>> +
>> +.. _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.
> 
> Should we mention that PMD provides RTE_PMD_REGISTER_KMOD_DEP with 
> corresponding kernel module listed.

Agreed, good to mention about it.

I will send a new version.

> 
> <...>
> 

[dpdk-dev] [PATCH v5] doc: document NIC features

[Ferruh Yigit]

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>
Reviewed-by: Andrew Rybchenko <arybchenko@solarflare.com>
---
Cc: Olivier Matz <olivier.matz@6wind.com>

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 <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..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.
+
+``[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:
+
+Link status
+-----------
+
+Supports getting the link speed, duplex mode and link state (up/down).
+
+* **[implements] eth_dev_ops**: ``link_update``.
+* **[provides]   rte_eth_dev_data**: ``dev_link``.
+* **[related]    API**: ``rte_eth_link_get()``, ``rte_eth_link_get_nowait()``.
+
+
+.. _nic_features_link_status_event:
+
+Link status event
+-----------------
+
+Supports Link Status Change interrupts.
+
+* **[uses]     user config**: ``dev_conf.intr_conf.lsc``.
+* **[uses]     rte_eth_dev_data**: ``dev_flags:RTE_ETH_DEV_INTR_LSC``.
+* **[uses]     rte_eth_event_type**: ``RTE_ETH_EVENT_INTR_LSC``.
+* **[provides] rte_pci_driver.drv_flags**: ``RTE_PCI_DRV_INTR_LSC``.
+* **[provides] rte_eth_dev_data**: ``dev_link``.
+* **[related]  API**: ``rte_eth_link_get()``, ``rte_eth_link_get_nowait()``.
+
+
+.. _nic_features_removal_event:
+
+Removal event
+-------------
+
+Supports device removal interrupts.
+
+* **[uses]     user config**: ``dev_conf.intr_conf.rmv``.
+* **[uses]     rte_eth_dev_data**: ``dev_flags:RTE_ETH_DEV_INTR_RMV``.
+* **[uses]     rte_eth_event_type**: ``RTE_ETH_EVENT_INTR_RMV``.
+* **[provides] rte_pci_driver.drv_flags**: ``RTE_PCI_DRV_INTR_RMV``.
+
+
+.. _nic_features_queue_status_event:
+
+Queue status event
+------------------
+
+Supports queue enable/disable events.
+
+* **[uses] rte_eth_event_type**: ``RTE_ETH_EVENT_QUEUE_STATE``.
+
+
+.. _nic_features_rx_interrupt:
+
+Rx interrupt
+------------
+
+Supports Rx interrupts.
+
+* **[uses]       user config**: ``dev_conf.intr_conf.rxq``.
+* **[implements] eth_dev_ops**: ``rx_queue_intr_enable``, ``rx_queue_intr_disable``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``tx_done_cleanup``.
+* **[related] 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.
+
+* **[implements] eth_dev_ops**: ``rx_queue_start``, ``rx_queue_stop``, ``tx_queue_start``,
+  ``tx_queue_stop``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``mtu_set``.
+* **[implements] rte_eth_dev_data**: ``mtu``.
+* **[provides]   rte_eth_dev_info**: ``max_rx_pktlen``.
+* **[related]    API**: ``rte_eth_dev_set_mtu()``, ``rte_eth_dev_get_mtu()``.
+
+
+.. _nic_features_jumbo_frame:
+
+Jumbo frame
+-----------
+
+Supports Rx jumbo frames.
+
+* **[uses]    user config**: ``dev_conf.rxmode.jumbo_frame``,
+  ``dev_conf.rxmode.max_rx_pkt_len``.
+* **[related] rte_eth_dev_info**: ``max_rx_pktlen``.
+* **[related] API**: ``rte_eth_dev_set_mtu()``.
+
+
+.. _nic_features_scattered_rx:
+
+Scattered Rx
+------------
+
+Supports receiving segmented mbufs.
+
+* **[uses]       user config**: ``dev_conf.rxmode.enable_scatter``.
+* **[implements] datapath**: ``Scattered Rx function``.
+* **[implements] rte_eth_dev_data**: ``scattered_rx``.
+* **[provides]   eth_dev_ops**: ``rxq_info_get:scattered_rx``.
+
+
+.. _nic_features_lro:
+
+LRO
+---
+
+Supports Large Receive Offload.
+
+* **[uses]       user config**: ``dev_conf.rxmode.enable_lro``.
+* **[implements] datapath**: ``LRO functionality``.
+* **[implements] rte_eth_dev_data**: ``lro``.
+* **[provides]   mbuf**: ``mbuf.ol_flags:PKT_RX_LRO``, ``mbuf.tso_segsz``.
+* **[provides]   rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_TCP_LRO``.
+
+
+.. _nic_features_tso:
+
+TSO
+---
+
+Supports TCP Segmentation Offloading.
+
+* **[uses] rte_eth_desc_lim**: ``nb_seg_max``, ``nb_mtu_seg_max``.
+* **[uses] mbuf**: ``mbuf.ol_flags:PKT_TX_TCP_SEG``.
+* **[implements] datapath**: ``TSO functionality``.
+* **[provides] rte_eth_dev_info**: ``tx_offload_capa:DEV_TX_OFFLOAD_TCP_TSO,DEV_TX_OFFLOAD_UDP_TSO``.
+
+
+.. _nic_features_promiscuous_mode:
+
+Promiscuous mode
+----------------
+
+Supports enabling/disabling promiscuous mode for a port.
+
+* **[implements] eth_dev_ops**: ``promiscuous_enable``, ``promiscuous_disable``.
+* **[implements] rte_eth_dev_data**: ``promiscuous``.
+* **[related]    API**: ``rte_eth_promiscuous_enable()``, ``rte_eth_promiscuous_disable()``,
+  ``rte_eth_promiscuous_get()``.
+
+
+.. _nic_features_allmulticast_mode:
+
+Allmulticast mode
+-----------------
+
+Supports enabling/disabling receiving multicast frames.
+
+* **[implements] eth_dev_ops**: ``allmulticast_enable``, ``allmulticast_disable``.
+* **[implements] rte_eth_dev_data**: ``all_multicast``.
+* **[related]    API**: ``rte_eth_allmulticast_enable()``,
+  ``rte_eth_allmulticast_disable()``, ``rte_eth_allmulticast_get()``.
+
+
+.. _nic_features_unicast_mac_filter:
+
+Unicast MAC filter
+------------------
+
+Supports adding MAC addresses to enable whitelist filtering to accept packets.
+
+* **[implements] eth_dev_ops**: ``mac_addr_set``, ``mac_addr_add``, ``mac_addr_remove``.
+* **[implements] rte_eth_dev_data**: ``mac_addrs``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``set_mc_addr_list``.
+* **[related]    API**: ``rte_eth_dev_set_mc_addr_list()``.
+
+
+.. _nic_features_rss_hash:
+
+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``.
+
+
+.. _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.
+
+
+.. _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:
+
+VLAN filter
+-----------
+
+Supports filtering of a VLAN Tag identifier.
+
+* **[uses]       user config**: ``dev_conf.rxmode.hw_vlan_filter``.
+* **[implements] eth_dev_ops**: ``vlan_filter_set``.
+* **[related]    API**: ``rte_eth_dev_vlan_filter()``.
+
+
+.. _nic_features_ethertype_filter:
+
+Ethertype filter
+----------------
+
+Supports filtering on Ethernet type.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_ETHERTYPE``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+.. _nic_features_ntuple_filter:
+
+N-tuple filter
+--------------
+
+Supports filtering on N-tuple values.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_NTUPLE``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_syn_filter:
+
+SYN filter
+----------
+
+Supports TCP syn filtering.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_SYN``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_tunnel_filter:
+
+Tunnel filter
+-------------
+
+Supports tunnel filtering.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_TUNNEL``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_FLEXIBLE``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_hash_filter:
+
+Hash filter
+-----------
+
+Supports Hash filtering.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_HASH``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_flow_director:
+
+Flow director
+-------------
+
+Supports Flow Director style filtering to queues.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_FDIR``.
+* **[provides]   mbuf**: ``mbuf.ol_flags:`` ``PKT_RX_FDIR``, ``PKT_RX_FDIR_ID``,
+  ``PKT_RX_FDIR_FLX``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_flow_control:
+
+Flow control
+------------
+
+Supports configuring link flow control.
+
+* **[implements] eth_dev_ops**: ``flow_ctrl_get``, ``flow_ctrl_set``,
+  ``priority_flow_ctrl_set``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_GENERIC``.
+* **[implements] rte_flow_ops**: All.
+
+
+.. _nic_features_rate_limitation:
+
+Rate limitation
+---------------
+
+Supports Tx rate limitation for a queue.
+
+* **[implements] eth_dev_ops**: ``set_queue_rate_limit``.
+* **[related]    API**: ``rte_eth_set_queue_rate_limit()``.
+
+
+.. _nic_features_traffic_mirroring:
+
+Traffic mirroring
+-----------------
+
+Supports adding traffic mirroring rules.
+
+* **[implements] eth_dev_ops**: ``mirror_rule_set``, ``mirror_rule_reset``.
+* **[related]    API**: ``rte_eth_mirror_rule_set()``, ``rte_eth_mirror_rule_reset()``.
+
+
+.. _nic_features_crc_offload:
+
+CRC offload
+-----------
+
+Supports CRC stripping by hardware.
+
+* **[uses] user config**: ``dev_conf.rxmode.hw_strip_crc``.
+
+
+.. _nic_features_vlan_offload:
+
+VLAN offload
+------------
+
+Supports VLAN offload to hardware.
+
+* **[uses]       user config**: ``dev_conf.rxmode.hw_vlan_strip``,
+  ``dev_conf.rxmode.hw_vlan_filter``, ``dev_conf.rxmode.hw_vlan_extend``.
+* **[implements] eth_dev_ops**: ``vlan_offload_set``.
+* **[provides]   mbuf**: ``mbuf.ol_flags:PKT_RX_VLAN_STRIPPED``, ``mbuf.vlan_tci``.
+* **[provides]   rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_VLAN_STRIP``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_VLAN_INSERT``.
+* **[related]    API**: ``rte_eth_dev_set_vlan_offload()``,
+  ``rte_eth_dev_get_vlan_offload()``.
+
+
+.. _nic_features_qinq_offload:
+
+QinQ offload
+------------
+
+Supports QinQ (queue in queue) offload.
+
+* **[uses] mbuf**: ``mbuf.ol_flags:PKT_TX_QINQ_PKT``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_QINQ_STRIPPED``, ``mbuf.vlan_tci``,
+   ``mbuf.vlan_tci_outer``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_QINQ_STRIP``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_QINQ_INSERT``.
+
+
+.. _nic_features_l3_checksum_offload:
+
+L3 checksum offload
+-------------------
+
+Supports L3 checksum offload.
+
+* **[uses]     user config**: ``dev_conf.rxmode.hw_ip_checksum``.
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_IP_CKSUM``,
+  ``mbuf.ol_flags:PKT_TX_IPV4`` | ``PKT_TX_IPV6``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_IP_CKSUM_UNKNOWN`` |
+  ``PKT_RX_IP_CKSUM_BAD`` | ``PKT_RX_IP_CKSUM_GOOD`` |
+  ``PKT_RX_IP_CKSUM_NONE``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_IPV4_CKSUM``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_IPV4_CKSUM``.
+
+
+.. _nic_features_l4_checksum_offload:
+
+L4 checksum offload
+-------------------
+
+Supports L4 checksum offload.
+
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_IPV4`` | ``PKT_TX_IPV6``,
+  ``mbuf.ol_flags:PKT_TX_L4_NO_CKSUM`` | ``PKT_TX_TCP_CKSUM`` |
+  ``PKT_TX_SCTP_CKSUM`` | ``PKT_TX_UDP_CKSUM``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_L4_CKSUM_UNKNOWN`` |
+  ``PKT_RX_L4_CKSUM_BAD`` | ``PKT_RX_L4_CKSUM_GOOD`` |
+  ``PKT_RX_L4_CKSUM_NONE``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_UDP_CKSUM,DEV_RX_OFFLOAD_TCP_CKSUM``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_UDP_CKSUM,DEV_TX_OFFLOAD_TCP_CKSUM,DEV_TX_OFFLOAD_SCTP_CKSUM``.
+
+
+.. _nic_features_macsec_offload:
+
+MACsec offload
+--------------
+
+Supports MACsec.
+
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_MACSEC``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_MACSEC_STRIP``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_MACSEC_INSERT``.
+
+
+.. _nic_features_inner_l3_checksum:
+
+Inner L3 checksum
+-----------------
+
+Supports inner packet L3 checksum.
+
+
+.. _nic_features_inner_l4_checksum:
+
+Inner L4 checksum
+-----------------
+
+Supports inner packet L4 checksum.
+
+
+.. _nic_features_packet_type_parsing:
+
+Packet type parsing
+-------------------
+
+Supports packet type parsing and returns a list of supported types.
+
+* **[implements] eth_dev_ops**: ``dev_supported_ptypes_get``.
+* **[related]    API**: ``rte_eth_dev_get_supported_ptypes()``.
+
+
+.. _nic_features_timesync:
+
+Timesync
+--------
+
+Supports IEEE1588/802.1AS timestamping.
+
+* **[implements] eth_dev_ops**: ``timesync_enable``, ``timesync_disable``
+  ``timesync_read_rx_timestamp``, ``timesync_read_tx_timestamp``,
+  ``timesync_adjust_time``, ``timesync_read_time``, ``timesync_write_time``.
+* **[related]    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".
+
+* **[implements] eth_dev_ops**: ``rx_descriptor_status``.
+* **[related]    API**: ``rte_eth_rx_descriptor_status()``.
+* **[implements] eth_dev_ops**: ``rx_descriptor_done``.
+* **[related]    API**: ``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."
+
+* **[implements] eth_dev_ops**: ``tx_descriptor_status``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``stats_get``, ``stats_reset``.
+* **[related]    API**: ``rte_eth_stats_get``, ``rte_eth_stats_reset()``.
+
+
+.. _nic_features_extended_stats:
+
+Extended stats
+--------------
+
+Supports Extended Statistics, changes from driver to driver.
+
+* **[implements] eth_dev_ops**: ``xstats_get``, ``xstats_reset``, ``xstats_get_names``.
+* **[implements] eth_dev_ops**: ``xstats_get_by_id``, ``xstats_get_names_by_id``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``queue_stats_mapping_set``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``fw_version_get``.
+* **[related]    API**: ``rte_eth_dev_fw_version_get()``.
+
+
+.. _nic_features_eeprom_dump:
+
+EEPROM dump
+-----------
+
+Supports getting/setting device eeprom data.
+
+* **[implements] eth_dev_ops**: ``get_eeprom_length``, ``get_eeprom``, ``set_eeprom``.
+* **[related]    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).
+
+* **[implements] eth_dev_ops**: ``get_reg``.
+* **[related]    API**: ``rte_eth_dev_get_reg_info()``.
+
+
+.. _nic_features_led:
+
+LED
+---
+
+Supports turning on/off a software controllable LED on a device.
+
+* **[implements] eth_dev_ops**: ``dev_led_on``, ``dev_led_off``.
+* **[related]    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.
+
+* **[provides] RTE_PMD_REGISTER_KMOD_DEP**: ``igb_uio``.
+
+.. _nic_features_linux_vfio:
+
+Linux VFIO
+----------
+
+Works with ``vfio-pci`` kernel module.
+
+* **[provides] RTE_PMD_REGISTER_KMOD_DEP**: ``vfio-pci``.
+
+.. _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``
-- 
2.13.0

Re: [dpdk-dev] [PATCH v5] doc: document NIC features

[Shreyansh Jain]

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 <ferruh.yigit@intel.com>
> Signed-off-by: John McNamara <john.mcnamara@intel.com>
> Reviewed-by: Andrew Rybchenko <arybchenko@solarflare.com>
> ---
> Cc: Olivier Matz <olivier.matz@6wind.com>
> 
> 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 <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..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

Re: [dpdk-dev] [PATCH v5] doc: document NIC features

[Ferruh Yigit]

On 7/26/2017 6:08 AM, Shreyansh Jain wrote:
> Hello Ferruh,
> 
> Some trivial comments inline.

Hi Shreyansh,

Thank you for the review, I will send a new version.

Thanks,
ferruh

> 
> 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 <ferruh.yigit@intel.com>
>> Signed-off-by: John McNamara <john.mcnamara@intel.com>
>> Reviewed-by: Andrew Rybchenko <arybchenko@solarflare.com>
<...>

[dpdk-dev] [PATCH v6] doc: document NIC features

[Ferruh Yigit]

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>
Reviewed-by: Andrew Rybchenko <arybchenko@solarflare.com>
---
Cc: Olivier Matz <olivier.matz@6wind.com>

v6:
* Apply code review comments and minor updates.
* Add new feature "Lock-free Tx queue".
* Add more data for "Inner L3 checksum".

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 | 887 ++++++++++++++++++++++++++++++++++
 2 files changed, 891 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..5fe36d1c0
--- /dev/null
+++ b/doc/guides/nics/overview_features.rst
@@ -0,0 +1,887 @@
+..  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" is used
+for cases where provided data can't be represented simply by a function.
+
+``[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:
+
+Link status
+-----------
+
+Supports getting the link speed, duplex mode and link state (up/down).
+
+* **[implements] eth_dev_ops**: ``link_update``.
+* **[implements] rte_eth_dev_data**: ``dev_link``.
+* **[related]    API**: ``rte_eth_link_get()``, ``rte_eth_link_get_nowait()``.
+
+
+.. _nic_features_link_status_event:
+
+Link status event
+-----------------
+
+Supports Link Status Change interrupts.
+
+* **[uses]       user config**: ``dev_conf.intr_conf.lsc``.
+* **[uses]       rte_eth_dev_data**: ``dev_flags:RTE_ETH_DEV_INTR_LSC``.
+* **[uses]       rte_eth_event_type**: ``RTE_ETH_EVENT_INTR_LSC``.
+* **[implements] rte_eth_dev_data**: ``dev_link``.
+* **[provides]   rte_pci_driver.drv_flags**: ``RTE_PCI_DRV_INTR_LSC``.
+* **[related]    API**: ``rte_eth_link_get()``, ``rte_eth_link_get_nowait()``.
+
+
+.. _nic_features_removal_event:
+
+Removal event
+-------------
+
+Supports device removal interrupts.
+
+* **[uses]     user config**: ``dev_conf.intr_conf.rmv``.
+* **[uses]     rte_eth_dev_data**: ``dev_flags:RTE_ETH_DEV_INTR_RMV``.
+* **[uses]     rte_eth_event_type**: ``RTE_ETH_EVENT_INTR_RMV``.
+* **[provides] rte_pci_driver.drv_flags**: ``RTE_PCI_DRV_INTR_RMV``.
+
+
+.. _nic_features_queue_status_event:
+
+Queue status event
+------------------
+
+Supports queue enable/disable events.
+
+* **[uses] rte_eth_event_type**: ``RTE_ETH_EVENT_QUEUE_STATE``.
+
+
+.. _nic_features_rx_interrupt:
+
+Rx interrupt
+------------
+
+Supports Rx interrupts.
+
+* **[uses]       user config**: ``dev_conf.intr_conf.rxq``.
+* **[implements] eth_dev_ops**: ``rx_queue_intr_enable``, ``rx_queue_intr_disable``.
+* **[related]    API**: ``rte_eth_dev_rx_intr_enable()``, ``rte_eth_dev_rx_intr_disable()``.
+
+
+.. _nic_features_lock-free_tx_queue:
+
+Lock-free Tx queue
+------------------
+
+Supports Rx interrupts.
+
+If a PMD advertises DEV_TX_OFFLOAD_MT_LOCKFREE capable, multiple threads can
+invoke rte_eth_tx_burst() concurrently on the same Tx queue without SW lock.
+
+* **[provides] rte_eth_dev_info**: ``tx_offload_capa:DEV_TX_OFFLOAD_MT_LOCKFREE``.
+* **[related]  API**: ``rte_eth_tx_burst()``.
+
+
+.. _nic_features_free_tx_mbuf_on_demand:
+
+Free Tx mbuf on demand
+----------------------
+
+Supports freeing consumed buffers on a Tx ring.
+
+* **[implements] eth_dev_ops**: ``tx_done_cleanup``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``rx_queue_start``, ``rx_queue_stop``, ``tx_queue_start``,
+  ``tx_queue_stop``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``mtu_set``.
+* **[implements] rte_eth_dev_data**: ``mtu``.
+* **[provides]   rte_eth_dev_info**: ``max_rx_pktlen``.
+* **[related]    API**: ``rte_eth_dev_set_mtu()``, ``rte_eth_dev_get_mtu()``.
+
+
+.. _nic_features_jumbo_frame:
+
+Jumbo frame
+-----------
+
+Supports Rx jumbo frames.
+
+* **[uses]    user config**: ``dev_conf.rxmode.jumbo_frame``,
+  ``dev_conf.rxmode.max_rx_pkt_len``.
+* **[related] rte_eth_dev_info**: ``max_rx_pktlen``.
+* **[related] API**: ``rte_eth_dev_set_mtu()``.
+
+
+.. _nic_features_scattered_rx:
+
+Scattered Rx
+------------
+
+Supports receiving segmented mbufs.
+
+* **[uses]       user config**: ``dev_conf.rxmode.enable_scatter``.
+* **[implements] datapath**: ``Scattered Rx function``.
+* **[implements] rte_eth_dev_data**: ``scattered_rx``.
+* **[provides]   eth_dev_ops**: ``rxq_info_get:scattered_rx``.
+* **[related]    eth_dev_ops**: ``rx_pkt_burst``.
+
+
+.. _nic_features_lro:
+
+LRO
+---
+
+Supports Large Receive Offload.
+
+* **[uses]       user config**: ``dev_conf.rxmode.enable_lro``.
+* **[implements] datapath**: ``LRO functionality``.
+* **[implements] rte_eth_dev_data**: ``lro``.
+* **[provides]   mbuf**: ``mbuf.ol_flags:PKT_RX_LRO``, ``mbuf.tso_segsz``.
+* **[provides]   rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_TCP_LRO``.
+
+
+.. _nic_features_tso:
+
+TSO
+---
+
+Supports TCP Segmentation Offloading.
+
+* **[uses]       rte_eth_desc_lim**: ``nb_seg_max``, ``nb_mtu_seg_max``.
+* **[uses]       mbuf**: ``mbuf.ol_flags:PKT_TX_TCP_SEG``.
+* **[uses]       mbuf**: ``mbuf.tso_segsz``, ``mbuf.l2_len``, ``mbuf.l3_len``, ``mbuf.l4_len``.
+* **[implements] datapath**: ``TSO functionality``.
+* **[provides]   rte_eth_dev_info**: ``tx_offload_capa:DEV_TX_OFFLOAD_TCP_TSO,DEV_TX_OFFLOAD_UDP_TSO``.
+
+
+.. _nic_features_promiscuous_mode:
+
+Promiscuous mode
+----------------
+
+Supports enabling/disabling promiscuous mode for a port.
+
+* **[implements] eth_dev_ops**: ``promiscuous_enable``, ``promiscuous_disable``.
+* **[implements] rte_eth_dev_data**: ``promiscuous``.
+* **[related]    API**: ``rte_eth_promiscuous_enable()``, ``rte_eth_promiscuous_disable()``,
+  ``rte_eth_promiscuous_get()``.
+
+
+.. _nic_features_allmulticast_mode:
+
+Allmulticast mode
+-----------------
+
+Supports enabling/disabling receiving multicast frames.
+
+* **[implements] eth_dev_ops**: ``allmulticast_enable``, ``allmulticast_disable``.
+* **[implements] rte_eth_dev_data**: ``all_multicast``.
+* **[related]    API**: ``rte_eth_allmulticast_enable()``,
+  ``rte_eth_allmulticast_disable()``, ``rte_eth_allmulticast_get()``.
+
+
+.. _nic_features_unicast_mac_filter:
+
+Unicast MAC filter
+------------------
+
+Supports adding MAC addresses to enable whitelist filtering to accept packets.
+
+* **[implements] eth_dev_ops**: ``mac_addr_set``, ``mac_addr_add``, ``mac_addr_remove``.
+* **[implements] rte_eth_dev_data**: ``mac_addrs``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``set_mc_addr_list``.
+* **[related]    API**: ``rte_eth_dev_set_mc_addr_list()``.
+
+
+.. _nic_features_rss_hash:
+
+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_HASH``, ``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.
+
+* **[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.
+
+* **[implements] rte_eth_dev_data**: ``sriov``.
+
+.. _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:
+
+VLAN filter
+-----------
+
+Supports filtering of a VLAN Tag identifier.
+
+* **[uses]       user config**: ``dev_conf.rxmode.hw_vlan_filter``.
+* **[implements] eth_dev_ops**: ``vlan_filter_set``.
+* **[related]    API**: ``rte_eth_dev_vlan_filter()``.
+
+
+.. _nic_features_ethertype_filter:
+
+Ethertype filter
+----------------
+
+Supports filtering on Ethernet type.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_ETHERTYPE``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+.. _nic_features_ntuple_filter:
+
+N-tuple filter
+--------------
+
+Supports filtering on N-tuple values.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_NTUPLE``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_syn_filter:
+
+SYN filter
+----------
+
+Supports TCP syn filtering.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_SYN``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_tunnel_filter:
+
+Tunnel filter
+-------------
+
+Supports tunnel filtering.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_TUNNEL``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_FLEXIBLE``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_hash_filter:
+
+Hash filter
+-----------
+
+Supports Hash filtering.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_HASH``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_flow_director:
+
+Flow director
+-------------
+
+Supports Flow Director style filtering to queues.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_FDIR``.
+* **[provides]   mbuf**: ``mbuf.ol_flags:`` ``PKT_RX_FDIR``, ``PKT_RX_FDIR_ID``,
+  ``PKT_RX_FDIR_FLX``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_flow_control:
+
+Flow control
+------------
+
+Supports configuring link flow control.
+
+* **[implements] eth_dev_ops**: ``flow_ctrl_get``, ``flow_ctrl_set``,
+  ``priority_flow_ctrl_set``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_GENERIC``.
+* **[implements] rte_flow_ops**: ``All``.
+
+
+.. _nic_features_rate_limitation:
+
+Rate limitation
+---------------
+
+Supports Tx rate limitation for a queue.
+
+* **[implements] eth_dev_ops**: ``set_queue_rate_limit``.
+* **[related]    API**: ``rte_eth_set_queue_rate_limit()``.
+
+
+.. _nic_features_traffic_mirroring:
+
+Traffic mirroring
+-----------------
+
+Supports adding traffic mirroring rules.
+
+* **[implements] eth_dev_ops**: ``mirror_rule_set``, ``mirror_rule_reset``.
+* **[related]    API**: ``rte_eth_mirror_rule_set()``, ``rte_eth_mirror_rule_reset()``.
+
+
+.. _nic_features_crc_offload:
+
+CRC offload
+-----------
+
+Supports CRC stripping by hardware.
+
+* **[uses] user config**: ``dev_conf.rxmode.hw_strip_crc``.
+
+
+.. _nic_features_vlan_offload:
+
+VLAN offload
+------------
+
+Supports VLAN offload to hardware.
+
+* **[uses]       user config**: ``dev_conf.rxmode.hw_vlan_strip``,
+  ``dev_conf.rxmode.hw_vlan_filter``, ``dev_conf.rxmode.hw_vlan_extend``.
+* **[implements] eth_dev_ops**: ``vlan_offload_set``.
+* **[provides]   mbuf**: ``mbuf.ol_flags:PKT_RX_VLAN_STRIPPED``, ``mbuf.vlan_tci``.
+* **[provides]   rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_VLAN_STRIP``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_VLAN_INSERT``.
+* **[related]    API**: ``rte_eth_dev_set_vlan_offload()``,
+  ``rte_eth_dev_get_vlan_offload()``.
+
+
+.. _nic_features_qinq_offload:
+
+QinQ offload
+------------
+
+Supports QinQ (queue in queue) offload.
+
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_QINQ_PKT``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_QINQ_STRIPPED``, ``mbuf.vlan_tci``,
+   ``mbuf.vlan_tci_outer``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_QINQ_STRIP``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_QINQ_INSERT``.
+
+
+.. _nic_features_l3_checksum_offload:
+
+L3 checksum offload
+-------------------
+
+Supports L3 checksum offload.
+
+* **[uses]     user config**: ``dev_conf.rxmode.hw_ip_checksum``.
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_IP_CKSUM``,
+  ``mbuf.ol_flags:PKT_TX_IPV4`` | ``PKT_TX_IPV6``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_IP_CKSUM_UNKNOWN`` |
+  ``PKT_RX_IP_CKSUM_BAD`` | ``PKT_RX_IP_CKSUM_GOOD`` |
+  ``PKT_RX_IP_CKSUM_NONE``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_IPV4_CKSUM``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_IPV4_CKSUM``.
+
+
+.. _nic_features_l4_checksum_offload:
+
+L4 checksum offload
+-------------------
+
+Supports L4 checksum offload.
+
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_IPV4`` | ``PKT_TX_IPV6``,
+  ``mbuf.ol_flags:PKT_TX_L4_NO_CKSUM`` | ``PKT_TX_TCP_CKSUM`` |
+  ``PKT_TX_SCTP_CKSUM`` | ``PKT_TX_UDP_CKSUM``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_L4_CKSUM_UNKNOWN`` |
+  ``PKT_RX_L4_CKSUM_BAD`` | ``PKT_RX_L4_CKSUM_GOOD`` |
+  ``PKT_RX_L4_CKSUM_NONE``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_UDP_CKSUM,DEV_RX_OFFLOAD_TCP_CKSUM``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_UDP_CKSUM,DEV_TX_OFFLOAD_TCP_CKSUM,DEV_TX_OFFLOAD_SCTP_CKSUM``.
+
+
+.. _nic_features_macsec_offload:
+
+MACsec offload
+--------------
+
+Supports MACsec.
+
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_MACSEC``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_MACSEC_STRIP``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_MACSEC_INSERT``.
+
+
+.. _nic_features_inner_l3_checksum:
+
+Inner L3 checksum
+-----------------
+
+Supports inner packet L3 checksum.
+
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_IP_CKSUM``,
+  ``mbuf.ol_flags:PKT_TX_IPV4`` | ``PKT_TX_IPV6``,
+  ``mbuf.ol_flags:PKT_TX_OUTER_IP_CKSUM``,
+  ``mbuf.ol_flags:PKT_TX_OUTER_IPV4`` | ``PKT_TX_OUTER_IPV6``.
+* **[uses]     mbuf**: ``mbuf.outer_l2_len``, ``mbuf.outer_l3_len``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_EIP_CKSUM_BAD``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_OUTER_IPV4_CKSUM``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_OUTER_IPV4_CKSUM``.
+
+
+.. _nic_features_inner_l4_checksum:
+
+Inner L4 checksum
+-----------------
+
+Supports inner packet L4 checksum.
+
+
+.. _nic_features_packet_type_parsing:
+
+Packet type parsing
+-------------------
+
+Supports packet type parsing and returns a list of supported types.
+
+* **[implements] eth_dev_ops**: ``dev_supported_ptypes_get``.
+* **[related]    API**: ``rte_eth_dev_get_supported_ptypes()``.
+
+
+.. _nic_features_timesync:
+
+Timesync
+--------
+
+Supports IEEE1588/802.1AS timestamping.
+
+* **[implements] eth_dev_ops**: ``timesync_enable``, ``timesync_disable``
+  ``timesync_read_rx_timestamp``, ``timesync_read_tx_timestamp``,
+  ``timesync_adjust_time``, ``timesync_read_time``, ``timesync_write_time``.
+* **[related]    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".
+
+* **[implements] eth_dev_ops**: ``rx_descriptor_status``.
+* **[related]    API**: ``rte_eth_rx_descriptor_status()``.
+* **[implements] eth_dev_ops**: ``rx_descriptor_done``.
+* **[related]    API**: ``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."
+
+* **[implements] eth_dev_ops**: ``tx_descriptor_status``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``stats_get``, ``stats_reset``.
+* **[related]    API**: ``rte_eth_stats_get``, ``rte_eth_stats_reset()``.
+
+
+.. _nic_features_extended_stats:
+
+Extended stats
+--------------
+
+Supports Extended Statistics, changes from driver to driver.
+
+* **[implements] eth_dev_ops**: ``xstats_get``, ``xstats_reset``, ``xstats_get_names``.
+* **[implements] eth_dev_ops**: ``xstats_get_by_id``, ``xstats_get_names_by_id``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``queue_stats_mapping_set``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``fw_version_get``.
+* **[related]    API**: ``rte_eth_dev_fw_version_get()``.
+
+
+.. _nic_features_eeprom_dump:
+
+EEPROM dump
+-----------
+
+Supports getting/setting device eeprom data.
+
+* **[implements] eth_dev_ops**: ``get_eeprom_length``, ``get_eeprom``, ``set_eeprom``.
+* **[related]    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).
+
+* **[implements] eth_dev_ops**: ``get_reg``.
+* **[related]    API**: ``rte_eth_dev_get_reg_info()``.
+
+
+.. _nic_features_led:
+
+LED
+---
+
+Supports turning on/off a software controllable LED on a device.
+
+* **[implements] eth_dev_ops**: ``dev_led_on``, ``dev_led_off``.
+* **[related]    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.
+
+* **[provides] RTE_PMD_REGISTER_KMOD_DEP**: ``igb_uio``.
+
+.. _nic_features_linux_vfio:
+
+Linux VFIO
+----------
+
+Works with ``vfio-pci`` kernel module.
+
+* **[provides] RTE_PMD_REGISTER_KMOD_DEP**: ``vfio-pci``.
+
+.. _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``
-- 
2.13.0

Re: [dpdk-dev] [PATCH v6] doc: document NIC features

[Shreyansh Jain]

On Tuesday 01 August 2017 08:53 PM, Ferruh Yigit wrote:
> 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>
> Reviewed-by: Andrew Rybchenko <arybchenko@solarflare.com>
> ---
> Cc: Olivier Matz <olivier.matz@6wind.com>
> 
Signed-off-by: Shreyansh Jain <shreyansh.jain@nxp.com>

Re: [dpdk-dev] [PATCH v6] doc: document NIC features

[Shreyansh Jain]

On Thursday 03 August 2017 02:26 PM, Shreyansh Jain wrote:
> On Tuesday 01 August 2017 08:53 PM, Ferruh Yigit wrote:
>> 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>
>> Reviewed-by: Andrew Rybchenko <arybchenko@solarflare.com>
>> ---
>> Cc: Olivier Matz <olivier.matz@6wind.com>
>>
> Signed-off-by: Shreyansh Jain <shreyansh.jain@nxp.com>
> 

My BAD. I am too low on coffee. Sorry.

Acked-by: Shreyansh Jain <shreyansh.jain@nxp.com>

Re: [dpdk-dev] [PATCH v6] doc: document NIC features

[Mcnamara, John]

> -----Original Message-----
> From: Yigit, Ferruh
> Sent: Tuesday, August 1, 2017 4:23 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 v6] 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>
> Reviewed-by: Andrew Rybchenko <arybchenko@solarflare.com>


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

Re: [dpdk-dev] [PATCH v6] doc: document NIC features

[Thomas Monjalon]

01/08/2017 17:23, Ferruh Yigit:
> +:orphan:
> +
> +.. _nic_overview_features:

Why have you done an orphan page?
I think it should be in doc/guides/nics/overview.rst 

Re: [dpdk-dev] [PATCH v6] doc: document NIC features

[Ferruh Yigit]

On 8/3/2017 11:57 PM, Thomas Monjalon wrote:
> 01/08/2017 17:23, Ferruh Yigit:
>> +:orphan:
>> +
>> +.. _nic_overview_features:
> 
> Why have you done an orphan page?
> I think it should be in doc/guides/nics/overview.rst 

There is a link from nics/overview.rst to this file. But this file is
not in the index and not making it orphan is causing a build warning.

Re: [dpdk-dev] [PATCH v6] doc: document NIC features

[Thomas Monjalon]

04/08/2017 10:56, Ferruh Yigit:
> On 8/3/2017 11:57 PM, Thomas Monjalon wrote:
> > 01/08/2017 17:23, Ferruh Yigit:
> >> +:orphan:
> >> +
> >> +.. _nic_overview_features:
> > 
> > Why have you done an orphan page?
> > I think it should be in doc/guides/nics/overview.rst 
> 
> There is a link from nics/overview.rst to this file. But this file is
> not in the index and not making it orphan is causing a build warning.

But why creating a new page?
It could be below the table in overview.rst.

Re: [dpdk-dev] [PATCH v6] doc: document NIC features

[Ferruh Yigit]

On 8/4/2017 10:32 AM, Thomas Monjalon wrote:
> 04/08/2017 10:56, Ferruh Yigit:
>> On 8/3/2017 11:57 PM, Thomas Monjalon wrote:
>>> 01/08/2017 17:23, Ferruh Yigit:
>>>> +:orphan:
>>>> +
>>>> +.. _nic_overview_features:
>>>
>>> Why have you done an orphan page?
>>> I think it should be in doc/guides/nics/overview.rst 
>>
>> There is a link from nics/overview.rst to this file. But this file is
>> not in the index and not making it orphan is causing a build warning.
> 
> But why creating a new page?
> It could be below the table in overview.rst.

Overview page is mostly just a table, this is more simple and clean I
believe.

Instead, I was thinking to be able to find a way to make each feature
name a link to its description in this file.

Re: [dpdk-dev] [PATCH v6] doc: document NIC features

[Thomas Monjalon]

04/08/2017 12:04, Ferruh Yigit:
> On 8/4/2017 10:32 AM, Thomas Monjalon wrote:
> > 04/08/2017 10:56, Ferruh Yigit:
> >> On 8/3/2017 11:57 PM, Thomas Monjalon wrote:
> >>> 01/08/2017 17:23, Ferruh Yigit:
> >>>> +:orphan:
> >>>> +
> >>>> +.. _nic_overview_features:
> >>>
> >>> Why have you done an orphan page?
> >>> I think it should be in doc/guides/nics/overview.rst 
> >>
> >> There is a link from nics/overview.rst to this file. But this file is
> >> not in the index and not making it orphan is causing a build warning.
> > 
> > But why creating a new page?
> > It could be below the table in overview.rst.
> 
> Overview page is mostly just a table, this is more simple and clean I
> believe.
> 
> Instead, I was thinking to be able to find a way to make each feature
> name a link to its description in this file.

Could we have a link to a section in the same page?

My main concern is that orphan page is weird in sphinx.
And from a usability point of view, users prefer looking for pages
from the menu at the left.

Re: [dpdk-dev] [PATCH v6] doc: document NIC features

[Mcnamara, John]

> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas@monjalon.net]
> Sent: Friday, August 4, 2017 10:32 AM
> To: Yigit, Ferruh <ferruh.yigit@intel.com>
> Cc: dev@dpdk.org; Mcnamara, John <john.mcnamara@intel.com>; Olivier Matz
> <olivier.matz@6wind.com>
> Subject: Re: [dpdk-dev] [PATCH v6] doc: document NIC features
> 
> 04/08/2017 10:56, Ferruh Yigit:
> > On 8/3/2017 11:57 PM, Thomas Monjalon wrote:
> > > 01/08/2017 17:23, Ferruh Yigit:
> > >> +:orphan:
> > >> +
> > >> +.. _nic_overview_features:
> > >
> > > Why have you done an orphan page?
> > > I think it should be in doc/guides/nics/overview.rst
> >
> > There is a link from nics/overview.rst to this file. But this file is
> > not in the index and not making it orphan is causing a build warning.
> 
> But why creating a new page?
> It could be below the table in overview.rst.

For me it makes more sense on a separate page. It isn't really overview material.

However, thinking about it again I think that it should be included in the index
instead of using the :orphan: directive. Maybe after the compilation chapter/page.

John

Re: [dpdk-dev] [PATCH v6] doc: document NIC features

[Ferruh Yigit]

On 8/4/2017 12:11 PM, Mcnamara, John wrote:
>> -----Original Message-----
>> From: Thomas Monjalon [mailto:thomas@monjalon.net]
>> Sent: Friday, August 4, 2017 10:32 AM
>> To: Yigit, Ferruh <ferruh.yigit@intel.com>
>> Cc: dev@dpdk.org; Mcnamara, John <john.mcnamara@intel.com>; Olivier Matz
>> <olivier.matz@6wind.com>
>> Subject: Re: [dpdk-dev] [PATCH v6] doc: document NIC features
>>
>> 04/08/2017 10:56, Ferruh Yigit:
>>> On 8/3/2017 11:57 PM, Thomas Monjalon wrote:
>>>> 01/08/2017 17:23, Ferruh Yigit:
>>>>> +:orphan:
>>>>> +
>>>>> +.. _nic_overview_features:
>>>>
>>>> Why have you done an orphan page?
>>>> I think it should be in doc/guides/nics/overview.rst
>>>
>>> There is a link from nics/overview.rst to this file. But this file is
>>> not in the index and not making it orphan is causing a build warning.
>>
>> But why creating a new page?
>> It could be below the table in overview.rst.
> 
> For me it makes more sense on a separate page. It isn't really overview material.
> 
> However, thinking about it again I think that it should be included in the index
> instead of using the :orphan: directive. Maybe after the compilation chapter/page.

I will send a new version that has been included into index.

Thanks,
ferruh

> 
> John
> 

[dpdk-dev] [PATCH v7] doc: document NIC features

[Ferruh Yigit]

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>
Reviewed-by: Andrew Rybchenko <arybchenko@solarflare.com>
Acked-by: Shreyansh Jain <shreyansh.jain@nxp.com>
---
Cc: Olivier Matz <olivier.matz@6wind.com>

v7:
* Rename file
* Add to the index
* Minor updates.

v6:
* Apply code review comments and minor updates.
* Add new feature "Lock-free Tx queue".
* Add more data for "Inner L3 checksum".

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/features.rst | 892 +++++++++++++++++++++++++++++++++++++++++++
 doc/guides/nics/index.rst    |   1 +
 doc/guides/nics/overview.rst |   4 +
 3 files changed, 897 insertions(+)
 create mode 100644 doc/guides/nics/features.rst

diff --git a/doc/guides/nics/features.rst b/doc/guides/nics/features.rst
new file mode 100644
index 000000000..faea61efb
--- /dev/null
+++ b/doc/guides/nics/features.rst
@@ -0,0 +1,892 @@
+..  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.
+
+.. _nic_features:
+
+Features Overview
+=================
+
+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" is used
+for cases where provided data can't be represented simply by a function.
+
+``[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:
+
+Link status
+-----------
+
+Supports getting the link speed, duplex mode and link state (up/down).
+
+* **[implements] eth_dev_ops**: ``link_update``.
+* **[implements] rte_eth_dev_data**: ``dev_link``.
+* **[related]    API**: ``rte_eth_link_get()``, ``rte_eth_link_get_nowait()``.
+
+
+.. _nic_features_link_status_event:
+
+Link status event
+-----------------
+
+Supports Link Status Change interrupts.
+
+* **[uses]       user config**: ``dev_conf.intr_conf.lsc``.
+* **[uses]       rte_eth_dev_data**: ``dev_flags:RTE_ETH_DEV_INTR_LSC``.
+* **[uses]       rte_eth_event_type**: ``RTE_ETH_EVENT_INTR_LSC``.
+* **[implements] rte_eth_dev_data**: ``dev_link``.
+* **[provides]   rte_pci_driver.drv_flags**: ``RTE_PCI_DRV_INTR_LSC``.
+* **[related]    API**: ``rte_eth_link_get()``, ``rte_eth_link_get_nowait()``.
+
+
+.. _nic_features_removal_event:
+
+Removal event
+-------------
+
+Supports device removal interrupts.
+
+* **[uses]     user config**: ``dev_conf.intr_conf.rmv``.
+* **[uses]     rte_eth_dev_data**: ``dev_flags:RTE_ETH_DEV_INTR_RMV``.
+* **[uses]     rte_eth_event_type**: ``RTE_ETH_EVENT_INTR_RMV``.
+* **[provides] rte_pci_driver.drv_flags**: ``RTE_PCI_DRV_INTR_RMV``.
+
+
+.. _nic_features_queue_status_event:
+
+Queue status event
+------------------
+
+Supports queue enable/disable events.
+
+* **[uses] rte_eth_event_type**: ``RTE_ETH_EVENT_QUEUE_STATE``.
+
+
+.. _nic_features_rx_interrupt:
+
+Rx interrupt
+------------
+
+Supports Rx interrupts.
+
+* **[uses]       user config**: ``dev_conf.intr_conf.rxq``.
+* **[implements] eth_dev_ops**: ``rx_queue_intr_enable``, ``rx_queue_intr_disable``.
+* **[related]    API**: ``rte_eth_dev_rx_intr_enable()``, ``rte_eth_dev_rx_intr_disable()``.
+
+
+.. _nic_features_lock-free_tx_queue:
+
+Lock-free Tx queue
+------------------
+
+If a PMD advertises DEV_TX_OFFLOAD_MT_LOCKFREE capable, multiple threads can
+invoke rte_eth_tx_burst() concurrently on the same Tx queue without SW lock.
+
+* **[provides] rte_eth_dev_info**: ``tx_offload_capa:DEV_TX_OFFLOAD_MT_LOCKFREE``.
+* **[related]  API**: ``rte_eth_tx_burst()``.
+
+
+.. _nic_features_free_tx_mbuf_on_demand:
+
+Free Tx mbuf on demand
+----------------------
+
+Supports freeing consumed buffers on a Tx ring.
+
+* **[implements] eth_dev_ops**: ``tx_done_cleanup``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``rx_queue_start``, ``rx_queue_stop``, ``tx_queue_start``,
+  ``tx_queue_stop``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``mtu_set``.
+* **[implements] rte_eth_dev_data**: ``mtu``.
+* **[provides]   rte_eth_dev_info**: ``max_rx_pktlen``.
+* **[related]    API**: ``rte_eth_dev_set_mtu()``, ``rte_eth_dev_get_mtu()``.
+
+
+.. _nic_features_jumbo_frame:
+
+Jumbo frame
+-----------
+
+Supports Rx jumbo frames.
+
+* **[uses]    user config**: ``dev_conf.rxmode.jumbo_frame``,
+  ``dev_conf.rxmode.max_rx_pkt_len``.
+* **[related] rte_eth_dev_info**: ``max_rx_pktlen``.
+* **[related] API**: ``rte_eth_dev_set_mtu()``.
+
+
+.. _nic_features_scattered_rx:
+
+Scattered Rx
+------------
+
+Supports receiving segmented mbufs.
+
+* **[uses]       user config**: ``dev_conf.rxmode.enable_scatter``.
+* **[implements] datapath**: ``Scattered Rx function``.
+* **[implements] rte_eth_dev_data**: ``scattered_rx``.
+* **[provides]   eth_dev_ops**: ``rxq_info_get:scattered_rx``.
+* **[related]    eth_dev_ops**: ``rx_pkt_burst``.
+
+
+.. _nic_features_lro:
+
+LRO
+---
+
+Supports Large Receive Offload.
+
+* **[uses]       user config**: ``dev_conf.rxmode.enable_lro``.
+* **[implements] datapath**: ``LRO functionality``.
+* **[implements] rte_eth_dev_data**: ``lro``.
+* **[provides]   mbuf**: ``mbuf.ol_flags:PKT_RX_LRO``, ``mbuf.tso_segsz``.
+* **[provides]   rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_TCP_LRO``.
+
+
+.. _nic_features_tso:
+
+TSO
+---
+
+Supports TCP Segmentation Offloading.
+
+* **[uses]       rte_eth_desc_lim**: ``nb_seg_max``, ``nb_mtu_seg_max``.
+* **[uses]       mbuf**: ``mbuf.ol_flags:PKT_TX_TCP_SEG``.
+* **[uses]       mbuf**: ``mbuf.tso_segsz``, ``mbuf.l2_len``, ``mbuf.l3_len``, ``mbuf.l4_len``.
+* **[implements] datapath**: ``TSO functionality``.
+* **[provides]   rte_eth_dev_info**: ``tx_offload_capa:DEV_TX_OFFLOAD_TCP_TSO,DEV_TX_OFFLOAD_UDP_TSO``.
+
+
+.. _nic_features_promiscuous_mode:
+
+Promiscuous mode
+----------------
+
+Supports enabling/disabling promiscuous mode for a port.
+
+* **[implements] eth_dev_ops**: ``promiscuous_enable``, ``promiscuous_disable``.
+* **[implements] rte_eth_dev_data**: ``promiscuous``.
+* **[related]    API**: ``rte_eth_promiscuous_enable()``, ``rte_eth_promiscuous_disable()``,
+  ``rte_eth_promiscuous_get()``.
+
+
+.. _nic_features_allmulticast_mode:
+
+Allmulticast mode
+-----------------
+
+Supports enabling/disabling receiving multicast frames.
+
+* **[implements] eth_dev_ops**: ``allmulticast_enable``, ``allmulticast_disable``.
+* **[implements] rte_eth_dev_data**: ``all_multicast``.
+* **[related]    API**: ``rte_eth_allmulticast_enable()``,
+  ``rte_eth_allmulticast_disable()``, ``rte_eth_allmulticast_get()``.
+
+
+.. _nic_features_unicast_mac_filter:
+
+Unicast MAC filter
+------------------
+
+Supports adding MAC addresses to enable whitelist filtering to accept packets.
+
+* **[implements] eth_dev_ops**: ``mac_addr_set``, ``mac_addr_add``, ``mac_addr_remove``.
+* **[implements] rte_eth_dev_data**: ``mac_addrs``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``set_mc_addr_list``.
+* **[related]    API**: ``rte_eth_dev_set_mc_addr_list()``.
+
+
+.. _nic_features_rss_hash:
+
+RSS hash
+--------
+
+Supports RSS hashing on RX.
+
+* **[uses]     user config**: ``dev_conf.rxmode.mq_mode`` = ``ETH_MQ_RX_RSS_FLAG``.
+* **[uses]     user config**: ``dev_conf.rx_adv_conf.rss_conf``.
+* **[provides] rte_eth_dev_info**: ``flow_type_rss_offloads``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_RSS_HASH``, ``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.
+
+* **[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``.
+* **[uses] user config**: ``dev_conf.rx_adv_conf.vmdq_dcb_conf``.
+* **[uses] user config**: ``dev_conf.rx_adv_conf.vmdq_rx_conf``.
+* **[uses] user config**: ``dev_conf.tx_adv_conf.vmdq_dcb_tx_conf``.
+* **[uses] user config**: ``dev_conf.tx_adv_conf.vmdq_tx_conf``.
+
+
+.. _nic_features_sriov:
+
+SR-IOV
+------
+
+Driver supports creating Virtual Functions.
+
+* **[implements] rte_eth_dev_data**: ``sriov``.
+
+.. _nic_features_dcb:
+
+DCB
+---
+
+Supports Data Center Bridging (DCB).
+
+* **[uses]       user config**: ``dev_conf.rxmode.mq_mode`` = ``ETH_MQ_RX_DCB_FLAG``.
+* **[uses]       user config**: ``dev_conf.rx_adv_conf.vmdq_dcb_conf``.
+* **[uses]       user config**: ``dev_conf.rx_adv_conf.dcb_rx_conf``.
+* **[uses]       user config**: ``dev_conf.tx_adv_conf.vmdq_dcb_tx_conf``.
+* **[uses]       user config**: ``dev_conf.tx_adv_conf.vmdq_tx_conf``.
+* **[implements] eth_dev_ops**: ``get_dcb_info``.
+* **[related]    API**: ``rte_eth_dev_get_dcb_info()``.
+
+
+.. _nic_features_vlan_filter:
+
+VLAN filter
+-----------
+
+Supports filtering of a VLAN Tag identifier.
+
+* **[uses]       user config**: ``dev_conf.rxmode.hw_vlan_filter``.
+* **[implements] eth_dev_ops**: ``vlan_filter_set``.
+* **[related]    API**: ``rte_eth_dev_vlan_filter()``.
+
+
+.. _nic_features_ethertype_filter:
+
+Ethertype filter
+----------------
+
+Supports filtering on Ethernet type.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_ETHERTYPE``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+.. _nic_features_ntuple_filter:
+
+N-tuple filter
+--------------
+
+Supports filtering on N-tuple values.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_NTUPLE``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_syn_filter:
+
+SYN filter
+----------
+
+Supports TCP syn filtering.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_SYN``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_tunnel_filter:
+
+Tunnel filter
+-------------
+
+Supports tunnel filtering.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_TUNNEL``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_FLEXIBLE``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_hash_filter:
+
+Hash filter
+-----------
+
+Supports Hash filtering.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_HASH``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_flow_director:
+
+Flow director
+-------------
+
+Supports Flow Director style filtering to queues.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_FDIR``.
+* **[provides]   mbuf**: ``mbuf.ol_flags:`` ``PKT_RX_FDIR``, ``PKT_RX_FDIR_ID``,
+  ``PKT_RX_FDIR_FLX``.
+* **[related]    API**: ``rte_eth_dev_filter_ctrl()``, ``rte_eth_dev_filter_supported()``.
+
+
+.. _nic_features_flow_control:
+
+Flow control
+------------
+
+Supports configuring link flow control.
+
+* **[implements] eth_dev_ops**: ``flow_ctrl_get``, ``flow_ctrl_set``,
+  ``priority_flow_ctrl_set``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``filter_ctrl:RTE_ETH_FILTER_GENERIC``.
+* **[implements] rte_flow_ops**: ``All``.
+
+
+.. _nic_features_rate_limitation:
+
+Rate limitation
+---------------
+
+Supports Tx rate limitation for a queue.
+
+* **[implements] eth_dev_ops**: ``set_queue_rate_limit``.
+* **[related]    API**: ``rte_eth_set_queue_rate_limit()``.
+
+
+.. _nic_features_traffic_mirroring:
+
+Traffic mirroring
+-----------------
+
+Supports adding traffic mirroring rules.
+
+* **[implements] eth_dev_ops**: ``mirror_rule_set``, ``mirror_rule_reset``.
+* **[related]    API**: ``rte_eth_mirror_rule_set()``, ``rte_eth_mirror_rule_reset()``.
+
+
+.. _nic_features_crc_offload:
+
+CRC offload
+-----------
+
+Supports CRC stripping by hardware.
+
+* **[uses] user config**: ``dev_conf.rxmode.hw_strip_crc``.
+
+
+.. _nic_features_vlan_offload:
+
+VLAN offload
+------------
+
+Supports VLAN offload to hardware.
+
+* **[uses]       user config**: ``dev_conf.rxmode.hw_vlan_strip``,
+  ``dev_conf.rxmode.hw_vlan_filter``, ``dev_conf.rxmode.hw_vlan_extend``.
+* **[implements] eth_dev_ops**: ``vlan_offload_set``.
+* **[provides]   mbuf**: ``mbuf.ol_flags:PKT_RX_VLAN_STRIPPED``, ``mbuf.vlan_tci``.
+* **[provides]   rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_VLAN_STRIP``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_VLAN_INSERT``.
+* **[related]    API**: ``rte_eth_dev_set_vlan_offload()``,
+  ``rte_eth_dev_get_vlan_offload()``.
+
+
+.. _nic_features_qinq_offload:
+
+QinQ offload
+------------
+
+Supports QinQ (queue in queue) offload.
+
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_QINQ_PKT``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_QINQ_STRIPPED``, ``mbuf.vlan_tci``,
+   ``mbuf.vlan_tci_outer``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_QINQ_STRIP``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_QINQ_INSERT``.
+
+
+.. _nic_features_l3_checksum_offload:
+
+L3 checksum offload
+-------------------
+
+Supports L3 checksum offload.
+
+* **[uses]     user config**: ``dev_conf.rxmode.hw_ip_checksum``.
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_IP_CKSUM``,
+  ``mbuf.ol_flags:PKT_TX_IPV4`` | ``PKT_TX_IPV6``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_IP_CKSUM_UNKNOWN`` |
+  ``PKT_RX_IP_CKSUM_BAD`` | ``PKT_RX_IP_CKSUM_GOOD`` |
+  ``PKT_RX_IP_CKSUM_NONE``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_IPV4_CKSUM``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_IPV4_CKSUM``.
+
+
+.. _nic_features_l4_checksum_offload:
+
+L4 checksum offload
+-------------------
+
+Supports L4 checksum offload.
+
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_IPV4`` | ``PKT_TX_IPV6``,
+  ``mbuf.ol_flags:PKT_TX_L4_NO_CKSUM`` | ``PKT_TX_TCP_CKSUM`` |
+  ``PKT_TX_SCTP_CKSUM`` | ``PKT_TX_UDP_CKSUM``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_L4_CKSUM_UNKNOWN`` |
+  ``PKT_RX_L4_CKSUM_BAD`` | ``PKT_RX_L4_CKSUM_GOOD`` |
+  ``PKT_RX_L4_CKSUM_NONE``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_UDP_CKSUM,DEV_RX_OFFLOAD_TCP_CKSUM``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_UDP_CKSUM,DEV_TX_OFFLOAD_TCP_CKSUM,DEV_TX_OFFLOAD_SCTP_CKSUM``.
+
+
+.. _nic_features_macsec_offload:
+
+MACsec offload
+--------------
+
+Supports MACsec.
+
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_MACSEC``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_MACSEC_STRIP``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_MACSEC_INSERT``.
+
+
+.. _nic_features_inner_l3_checksum:
+
+Inner L3 checksum
+-----------------
+
+Supports inner packet L3 checksum.
+
+* **[uses]     mbuf**: ``mbuf.ol_flags:PKT_TX_IP_CKSUM``,
+  ``mbuf.ol_flags:PKT_TX_IPV4`` | ``PKT_TX_IPV6``,
+  ``mbuf.ol_flags:PKT_TX_OUTER_IP_CKSUM``,
+  ``mbuf.ol_flags:PKT_TX_OUTER_IPV4`` | ``PKT_TX_OUTER_IPV6``.
+* **[uses]     mbuf**: ``mbuf.outer_l2_len``, ``mbuf.outer_l3_len``.
+* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_EIP_CKSUM_BAD``.
+* **[provides] rte_eth_dev_info**: ``rx_offload_capa:DEV_RX_OFFLOAD_OUTER_IPV4_CKSUM``,
+  ``tx_offload_capa:DEV_TX_OFFLOAD_OUTER_IPV4_CKSUM``.
+
+
+.. _nic_features_inner_l4_checksum:
+
+Inner L4 checksum
+-----------------
+
+Supports inner packet L4 checksum.
+
+
+.. _nic_features_packet_type_parsing:
+
+Packet type parsing
+-------------------
+
+Supports packet type parsing and returns a list of supported types.
+
+* **[implements] eth_dev_ops**: ``dev_supported_ptypes_get``.
+* **[related]    API**: ``rte_eth_dev_get_supported_ptypes()``.
+
+
+.. _nic_features_timesync:
+
+Timesync
+--------
+
+Supports IEEE1588/802.1AS timestamping.
+
+* **[implements] eth_dev_ops**: ``timesync_enable``, ``timesync_disable``
+  ``timesync_read_rx_timestamp``, ``timesync_read_tx_timestamp``,
+  ``timesync_adjust_time``, ``timesync_read_time``, ``timesync_write_time``.
+* **[related]    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".
+
+* **[implements] eth_dev_ops**: ``rx_descriptor_status``.
+* **[related]    API**: ``rte_eth_rx_descriptor_status()``.
+* **[implements] eth_dev_ops**: ``rx_descriptor_done``.
+* **[related]    API**: ``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."
+
+* **[implements] eth_dev_ops**: ``tx_descriptor_status``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``stats_get``, ``stats_reset``.
+* **[related]    API**: ``rte_eth_stats_get``, ``rte_eth_stats_reset()``.
+
+
+.. _nic_features_extended_stats:
+
+Extended stats
+--------------
+
+Supports Extended Statistics, changes from driver to driver.
+
+* **[implements] eth_dev_ops**: ``xstats_get``, ``xstats_reset``, ``xstats_get_names``.
+* **[implements] eth_dev_ops**: ``xstats_get_by_id``, ``xstats_get_names_by_id``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``queue_stats_mapping_set``.
+* **[related]    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.
+
+* **[implements] eth_dev_ops**: ``fw_version_get``.
+* **[related]    API**: ``rte_eth_dev_fw_version_get()``.
+
+
+.. _nic_features_eeprom_dump:
+
+EEPROM dump
+-----------
+
+Supports getting/setting device eeprom data.
+
+* **[implements] eth_dev_ops**: ``get_eeprom_length``, ``get_eeprom``, ``set_eeprom``.
+* **[related]    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).
+
+* **[implements] eth_dev_ops**: ``get_reg``.
+* **[related]    API**: ``rte_eth_dev_get_reg_info()``.
+
+
+.. _nic_features_led:
+
+LED
+---
+
+Supports turning on/off a software controllable LED on a device.
+
+* **[implements] eth_dev_ops**: ``dev_led_on``, ``dev_led_off``.
+* **[related]    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.
+
+* **[provides] RTE_PMD_REGISTER_KMOD_DEP**: ``igb_uio``.
+
+.. _nic_features_linux_vfio:
+
+Linux VFIO
+----------
+
+Works with ``vfio-pci`` kernel module.
+
+* **[provides] RTE_PMD_REGISTER_KMOD_DEP**: ``vfio-pci``.
+
+.. _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``
diff --git a/doc/guides/nics/index.rst b/doc/guides/nics/index.rst
index 17eaaf4c3..36f4f3ff5 100644
--- a/doc/guides/nics/index.rst
+++ b/doc/guides/nics/index.rst
@@ -36,6 +36,7 @@ Network Interface Controller Drivers
     :numbered:
 
     overview
+    features
     build_and_test
     ark
     avp
diff --git a/doc/guides/nics/overview.rst b/doc/guides/nics/overview.rst
index 757a3c901..dc56784ae 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_features>`.
+
 .. _table_net_pmd_features:
 
 .. include:: overview_table.txt
-- 
2.13.3

Re: [dpdk-dev] [PATCH v7] doc: document NIC features

[Mcnamara, John]

> -----Original Message-----
> From: Yigit, Ferruh
> Sent: Friday, August 4, 2017 2:06 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 v7] 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>
> Reviewed-by: Andrew Rybchenko <arybchenko@solarflare.com>
> Acked-by: Shreyansh Jain <shreyansh.jain@nxp.com>

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

Re: [dpdk-dev] [PATCH v7] doc: document NIC features

[Thomas Monjalon]

04/08/2017 15:06, Ferruh Yigit:
> 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>
> Reviewed-by: Andrew Rybchenko <arybchenko@solarflare.com>
> Acked-by: Shreyansh Jain <shreyansh.jain@nxp.com>
> ---
> --- /dev/null
> +++ b/doc/guides/nics/features.rst
> +.. _nic_features:
> +
> +Features Overview
> +=================
> +
> +This section explains the supported features that are listed in the
> +:ref:`nic_overview`.
[...]
> --- a/doc/guides/nics/overview.rst
> +++ b/doc/guides/nics/overview.rst
> +.. _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_features>`.

No need of adding explicit ref to link to the beginning of a document.
I replace them with :doc: tag.

With this small update, applied, thanks