X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fnics%2Fsfc_efx.rst;h=cf1269cc031a8a2eacb1406a48876444bc7afc8b;hb=3da4060a3070e9bb7bbc2ee75224b340d4460f25;hp=f2e410fea00342acfbb7101ef7555149e508f91d;hpb=a9825ccf5bb8873b2aef9c502d3a1ef9c8231ad2;p=dpdk.git diff --git a/doc/guides/nics/sfc_efx.rst b/doc/guides/nics/sfc_efx.rst index f2e410fea0..cf1269cc03 100644 --- a/doc/guides/nics/sfc_efx.rst +++ b/doc/guides/nics/sfc_efx.rst @@ -1,36 +1,17 @@ -.. BSD LICENSE - Copyright (c) 2016 Solarflare Communications Inc. - All rights reserved. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2019-2021 Xilinx, Inc. + Copyright(c) 2016-2019 Solarflare Communications Inc. This software was jointly developed between OKTET Labs (under contract for Solarflare) and Solarflare Communications, Inc. - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - - 1. Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - 2. 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. - - 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. - Solarflare libefx-based Poll Mode Driver ======================================== -The SFC EFX PMD (**librte_pmd_sfc_efx**) provides poll mode driver support -for **Solarflare SFN7xxx and SFN8xxx** family of 10/40 Gbps adapters. +The SFC EFX PMD (**librte_net_sfc_efx**) provides poll mode driver support +for **Solarflare SFN7xxx and SFN8xxx** family of 10/40 Gbps adapters, +**Solarflare XtremeScale X2xxx** family of 10/25/40/50/100 Gbps adapters and +**Alveo SN1000 SmartNICs** family of 10/25/40/50/100 Gbps adapters. SFC EFX PMD has support for the latest Linux and FreeBSD operating systems. More information can be found at `Solarflare Communications website @@ -48,6 +29,8 @@ SFC EFX PMD has support for: - IPv4/IPv6 TCP/UDP transmit checksum offload +- Inner IPv4/IPv6 TCP/UDP transmit checksum offload + - Port hardware statistics - Extended statistics (see Solarflare Server Adapter User's Guide for @@ -63,12 +46,14 @@ SFC EFX PMD has support for: - Allmulticast mode -- TCP segmentation offload (TSO) +- TCP segmentation offload (TSO) including VXLAN and GENEVE encapsulated - Multicast MAC filter - IPv4/IPv6 TCP/UDP receive checksum offload +- Inner IPv4/IPv6 TCP/UDP receive checksum offload + - Received packet type information - Receive side scaling (RSS) @@ -77,24 +62,26 @@ SFC EFX PMD has support for: - Scattered Rx DMA for packet that are larger that a single Rx descriptor +- Receive queue interrupts + - Deferred receive and transmit queue start - Transmit VLAN insertion (if running firmware variant supports it) - Flow API +- Loopback + +- SR-IOV PF + Non-supported Features ---------------------- The features not yet supported include: -- Receive queue interupts - - Priority-based flow control -- Loopback - - Configurable RX CRC stripping (always stripped) - Header split on receive @@ -116,37 +103,204 @@ required in the receive buffer. It should be taken into account when mbuf pool for receive is created. +Equal stride super-buffer mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the receive queue uses equal stride super-buffer DMA mode, one HW Rx +descriptor carries many Rx buffers which contiguously follow each other +with some stride (equal to total size of rte_mbuf as mempool object). +Each Rx buffer is an independent rte_mbuf. +However dedicated mempool manager must be used when mempool for the Rx +queue is created. The manager must support dequeue of the contiguous +block of objects and provide mempool info API to get the block size. + +Another limitation of a equal stride super-buffer mode, imposed by the +firmware, is that it allows for a single RSS context. + + +Tunnels support +--------------- + +NVGRE, VXLAN and GENEVE tunnels are supported on SFN8xxx and X2xxx family +adapters with full-feature firmware variant running. +**sfboot** should be used to configure NIC to run full-feature firmware variant. +See Solarflare Server Adapter User's Guide for details. + +SFN8xxx and X2xxx family adapters provide either inner or outer packet classes. +If adapter firmware advertises support for tunnels then the PMD +configures the hardware to report inner classes, and outer classes are +not reported in received packets. +However, for VXLAN and GENEVE tunnels the PMD does report UDP as the +outer layer 4 packet type. + +SFN8xxx and X2xxx family adapters report GENEVE packets as VXLAN. +If UDP ports are configured for only one tunnel type then it is safe to +treat VXLAN packet type indication as the corresponding UDP tunnel type. + + Flow API support ---------------- Supported attributes: - Ingress +- Transfer -Supported pattern items: +Supported pattern items (***non-transfer*** rules): - VOID -- ETH (exact match of source/destination addresses, EtherType) +- ETH (exact match of source/destination addresses, individual/group match + of destination address, EtherType in the outer frame and exact match of + destination addresses, individual/group match of destination address in + the inner frame) + +- VLAN (exact match of VID, double-tagging is supported) + +- IPV4 (exact match of source/destination addresses, + IP transport protocol) -Supported actions: +- IPV6 (exact match of source/destination addresses, + IP transport protocol) + +- TCP (exact match of source/destination ports) + +- UDP (exact match of source/destination ports) + +- VXLAN (exact match of VXLAN network identifier) + +- GENEVE (exact match of virtual network identifier, only Ethernet (0x6558) + protocol type is supported) + +- NVGRE (exact match of virtual subnet ID) + +Supported actions (***non-transfer*** rules): - VOID - QUEUE +- RSS + +- DROP + +- FLAG (supported only with ef10_essb Rx datapath) + +- MARK (supported only with ef10_essb Rx datapath) + +Supported pattern items (***transfer*** rules): + +- PORT_ID (cannot repeat; conflicts with other traffic source items) + +- PHY_PORT (cannot repeat; conflicts with other traffic source items) + +- PF (cannot repeat; conflicts with other traffic source items) + +- VF (cannot repeat; conflicts with other traffic source items) + +- ETH + +- VLAN (double-tagging is supported) + +- IPV4 (source/destination addresses, IP transport protocol, + type of service, time to live) + +- IPV6 (source/destination addresses, IP transport protocol, + traffic class, hop limit) + +- TCP (source/destination ports, TCP header length + TCP flags) + +- UDP (source/destination ports) + +- VXLAN (exact match of VXLAN network identifier) + +- GENEVE (exact match of virtual network identifier) + +- NVGRE (exact match of virtual subnet ID) + +Supported actions (***transfer*** rules): + +- OF_POP_VLAN + +- OF_PUSH_VLAN + +- OF_VLAN_SET_VID + +- OF_VLAN_SET_PCP + +- FLAG + +- MARK + +- PHY_PORT + +- PF + +- VF + +- PORT_ID + +- DROP + Validating flow rules depends on the firmware variant. +The :ref:`flow_isolated_mode` is supported. + +The implementation is natively thread-safe. + +Ethernet destination individual/group match +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ethernet item supports I/G matching, if only the corresponding bit is set +in the mask of destination address. If destination address in the spec is +multicast, it matches all multicast (and broadcast) packets, otherwise it +matches unicast packets that are not filtered by other flow rules. + +Exceptions to flow rules +~~~~~~~~~~~~~~~~~~~~~~~~ + +There is a list of exceptional flow rule patterns which will not be +accepted by the PMD. A pattern will be rejected if at least one of the +conditions is met: + +- Filtering by IPv4 or IPv6 EtherType without pattern items of internet + layer and above. + +- The last item is IPV4 or IPV6, and it's empty. + +- Filtering by TCP or UDP IP transport protocol without pattern items of + transport layer and above. + +- The last item is TCP or UDP, and it's empty. + Supported NICs -------------- +- Xilinx Adapters: + + - Alveo SN1022 SmartNIC + +- Solarflare XtremeScale Adapters: + + - Solarflare X2522 Dual Port SFP28 10/25GbE Adapter + + - Solarflare X2541 Single Port QSFP28 10/25G/100G Adapter + + - Solarflare X2542 Dual Port QSFP28 10/25G/100G Adapter + - Solarflare Flareon [Ultra] Server Adapters: - Solarflare SFN8522 Dual Port SFP+ Server Adapter + - Solarflare SFN8522M Dual Port SFP+ Server Adapter + + - Solarflare SFN8042 Dual Port QSFP+ Server Adapter + - Solarflare SFN8542 Dual Port QSFP+ Server Adapter + - Solarflare SFN8722 Dual Port SFP+ OCP Server Adapter + - Solarflare SFN7002F Dual Port SFP+ Server Adapter - Solarflare SFN7004F Quad Port SFP+ Server Adapter @@ -181,17 +335,15 @@ Pre-Installation Configuration ------------------------------ -Config File Options -~~~~~~~~~~~~~~~~~~~ +Build Options +~~~~~~~~~~~~~ -The following options can be modified in the ``.config`` file. -Please note that enabling debugging options may affect system performance. +The following build-time options may be enabled on build time using +``-Dc_args=`` meson argument (e.g. ``-Dc_args=-DRTE_LIBRTE_SFC_EFX_DEBUG``). -- ``CONFIG_RTE_LIBRTE_SFC_EFX_PMD`` (default **y**) - - Enable compilation of Solarflare libefx-based poll-mode driver. +Please note that enabling debugging options may affect system performance. -- ``CONFIG_RTE_LIBRTE_SFC_EFX_DEBUG`` (default **n**) +- ``RTE_LIBRTE_SFC_EFX_DEBUG`` (undefined by default) Enable compilation of the extra run-time consistency checks. @@ -200,24 +352,131 @@ Per-Device Parameters ~~~~~~~~~~~~~~~~~~~~~ The following per-device parameters can be passed via EAL PCI device -whitelist option like "-w 02:00.0,arg1=value1,...". +allow option like "-a 02:00.0,arg1=value1,...". Case-insensitive 1/y/yes/on or 0/n/no/off may be used to specify boolean parameters value. +- ``class`` [net|vdpa] (default **net**) + + Choose the mode of operation of ef100 device. + **net** device will work as network device and will be probed by net/sfc driver. + **vdpa** device will work as vdpa device and will be probed by vdpa/sfc driver. + If this parameter is not specified then ef100 device will operate as + network device. + +- ``rx_datapath`` [auto|efx|ef10|ef10_essb] (default **auto**) + + Choose receive datapath implementation. + **auto** allows the driver itself to make a choice based on firmware + features available and required by the datapath implementation. + **efx** chooses libefx-based datapath which supports Rx scatter. + Supported for SFN7xxx, SFN8xxx and X2xxx family adapters only. + **ef10** chooses EF10 (SFN7xxx, SFN8xxx, X2xxx) native datapath which is + more efficient than libefx-based and provides richer packet type + classification. + **ef10_essb** chooses SFNX2xxx equal stride super-buffer datapath + which may be used on DPDK firmware variant only + (see notes about its limitations above). + **ef100** chooses EF100 native datapath which is the only supported + Rx datapath for EF100 architecture based NICs. + +- ``tx_datapath`` [auto|efx|ef10|ef10_simple|ef100] (default **auto**) + + Choose transmit datapath implementation. + **auto** allows the driver itself to make a choice based on firmware + features available and required by the datapath implementation. + **efx** chooses libefx-based datapath which supports VLAN insertion + (full-feature firmware variant only), TSO and multi-segment mbufs. + Mbuf segments may come from different mempools, and mbuf reference + counters are treated responsibly. + Supported for SFN7xxx, SFN8xxx and X2xxx family adapters only. + **ef10** chooses EF10 (SFN7xxx, SFN8xxx, X2xxx) native datapath which is + more efficient than libefx-based but has no VLAN insertion support yet. + Mbuf segments may come from different mempools, and mbuf reference + counters are treated responsibly. + **ef10_simple** chooses EF10 (SFN7xxx, SFN8xxx, X2xxx) native datapath which + is even more faster then **ef10** but does not support multi-segment + mbufs, disallows multiple mempools and neglects mbuf reference counters. + **ef100** chooses EF100 native datapath which supports multi-segment + mbufs, VLAN insertion, inner/outer IPv4 and TCP/UDP checksum and TCP + segmentation offloads including VXLAN and GENEVE IPv4/IPv6 tunnels. + - ``perf_profile`` [auto|throughput|low-latency] (default **throughput**) - Choose hardware tunning to be optimized for either throughput or + Choose hardware tuning to be optimized for either throughput or low-latency. **auto** allows NIC firmware to make a choice based on - installed licences and firmware variant configured using **sfboot**. - -- ``debug_init`` [bool] (default **n**) - - Enable extra logging during device intialization and startup. - -- ``mcdi_logging`` [bool] (default **n**) - - Enable extra logging of the communication with the NIC's management CPU. - The logging is done using RTE_LOG() with INFO level and PMD type. - The format is consumed by the Solarflare netlogdecode cross-platform tool. + installed licenses and firmware variant configured using **sfboot**. + +- ``stats_update_period_ms`` [long] (default **1000**) + + Adjust period in milliseconds to update port hardware statistics. + The accepted range is 0 to 65535. The value of **0** may be used + to disable periodic statistics update. One should note that it's + only possible to set an arbitrary value on SFN8xxx and X2xxx provided that + firmware version is 6.2.1.1033 or higher, otherwise any positive + value will select a fixed update period of **1000** milliseconds + +- ``fw_variant`` [dont-care|full-feature|ultra-low-latency| + capture-packed-stream|dpdk] (default **dont-care**) + + Choose the preferred firmware variant to use. + The parameter is supported for SFN7xxX, SFN8xxx and X2xxx families only. + In order for the selected option to have an effect, the **sfboot** utility + must be configured with the **auto** firmware-variant option. + The preferred firmware variant applies to all ports on the NIC. + **dont-care** ensures that the driver can attach to an unprivileged function. + The datapath firmware type to use is controlled by the **sfboot** + utility. + **full-feature** chooses full featured firmware. + **ultra-low-latency** chooses firmware with fewer features but lower latency. + **capture-packed-stream** chooses firmware for SolarCapture packed stream + mode. + **dpdk** chooses DPDK firmware with equal stride super-buffer Rx mode + for higher Rx packet rate and packet marks support and firmware subvariant + without checksumming on transmit for higher Tx packet rate if + checksumming is not required. + +- ``rxd_wait_timeout_ns`` [long] (default **200 us**) + + Adjust timeout in nanoseconds to head-of-line block to wait for + Rx descriptors. + The accepted range is 0 to 400 ms. + Flow control should be enabled to make it work. + The value of **0** disables it and packets are dropped immediately. + When a packet is dropped because of no Rx descriptors, + ``rx_nodesc_drop_cnt`` counter grows. + The feature is supported only by the DPDK firmware variant when equal + stride super-buffer Rx mode is used. + + +Dynamic Logging Parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +One may leverage EAL option "--log-level" to change default levels +for the log types supported by the driver. The option is used with +an argument typically consisting of two parts separated by a colon. + +Level value is the last part which takes a symbolic name (or integer). +Log type is the former part which may shell match syntax. +Depending on the choice of the expression, the given log level may +be used either for some specific log type or for a subset of types. + +SFC EFX PMD provides the following log types available for control: + +- ``pmd.net.sfc.driver`` (default level is **notice**) + + Affects driver-wide messages unrelated to any particular devices. + +- ``pmd.net.sfc.main`` (default level is **notice**) + + Matches a subset of per-port log types registered during runtime. + A full name for a particular type may be obtained by appending a + dot and a PCI device identifier (``XXXX:XX:XX.X``) to the prefix. + +- ``pmd.net.sfc.mcdi`` (default level is **notice**) + + Extra logging of the communication with the NIC's management CPU. + The format of the log is consumed by the Solarflare netlogdecode + cross-platform tool. May be managed per-port, as explained above.