[PATCH v2] doc: document NIC features

[Ferruh Yigit <ferruh.yigit@intel.com>]

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