From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id 8057D3252 for ; Thu, 22 Jun 2017 21:02:41 +0200 (CEST) Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by orsmga103.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 22 Jun 2017 12:02:40 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.39,373,1493708400"; d="scan'208";a="117680746" Received: from silpixa00372839.ir.intel.com (HELO silpixa00372839.ger.corp.intel.com) ([10.237.222.154]) by fmsmga005.fm.intel.com with ESMTP; 22 Jun 2017 12:02:38 -0700 From: Ferruh Yigit To: John McNamara Cc: dev@dpdk.org, Ferruh Yigit , Thomas Monjalon , Olivier Matz Date: Thu, 22 Jun 2017 20:02:33 +0100 Message-Id: <20170622190233.67933-1-ferruh.yigit@intel.com> X-Mailer: git-send-email 2.13.0 In-Reply-To: <20170621132540.92448-1-ferruh.yigit@intel.com> References: <20170621132540.92448-1-ferruh.yigit@intel.com> Subject: [dpdk-dev] [PATCH v2] doc: document NIC features X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 22 Jun 2017 19:02:42 -0000 Document NIC features, add more information about them and add more implementation related support. Signed-off-by: Ferruh Yigit --- Cc: Olivier Matz 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 `. + .. _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