diff options
Diffstat (limited to 'doc/guides/nics')
31 files changed, 1163 insertions, 125 deletions
diff --git a/doc/guides/nics/atlantic.rst b/doc/guides/nics/atlantic.rst new file mode 100644 index 00000000..80591b13 --- /dev/null +++ b/doc/guides/nics/atlantic.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 Aquantia Corporation. + +Aquantia Atlantic DPDK Driver +============================= + +Atlantic DPDK driver provides DPDK support for Aquantia's AQtion family of chipsets: AQC107/AQC108/AQC109 + +More information can be found at `Aquantia Official Website +<https://www.aquantia.com/products/client-connectivity/>`_. + +Supported features +^^^^^^^^^^^^^^^^^^ + +- Base L2 features +- Promiscuous mode +- Multicast mode +- Port statistics +- RSS (Receive Side Scaling) +- Checksum offload +- Jumbo Frame upto 16K + +Configuration Information +^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``CONFIG_RTE_LIBRTE_ATLANTIC_PMD`` (default ``y``) + +Application Programming Interface +--------------------------------- + +Limitations or Known issues +--------------------------- + +Statistics +~~~~~~~~~~ + +MTU setting +~~~~~~~~~~~ + +Atlantic NIC supports up to 16K jumbo frame size + +Supported Chipsets and NICs +--------------------------- + +- Aquantia AQtion AQC107 10 Gigabit Ethernet Controller +- Aquantia AQtion AQC108 5 Gigabit Ethernet Controller +- Aquantia AQtion AQC109 2.5 Gigabit Ethernet Controller diff --git a/doc/guides/nics/axgbe.rst b/doc/guides/nics/axgbe.rst index e30f4944..9b270a42 100644 --- a/doc/guides/nics/axgbe.rst +++ b/doc/guides/nics/axgbe.rst @@ -24,7 +24,7 @@ AXGBE PMD has support for: - Multicast mode - RSS (Receive Side Scaling) - Checksum offload -- Jumbo Frame upto 9K +- Jumbo Frame up to 9K Configuration Information diff --git a/doc/guides/nics/dpaa2.rst b/doc/guides/nics/dpaa2.rst index 66c03e10..e2f385d4 100644 --- a/doc/guides/nics/dpaa2.rst +++ b/doc/guides/nics/dpaa2.rst @@ -558,7 +558,7 @@ which are lower than logging ``level``. <dpdk app> <EAL args> --log-level=pmd.net.dpaa2:<level> -- ... -Using ``pmd.dpaa2`` as log matching criteria, all PMD logs can be enabled +Using ``pmd.net.dpaa2`` as log matching criteria, all PMD logs can be enabled which are lower than logging ``level``. Whitelisting & Blacklisting diff --git a/doc/guides/nics/ena.rst b/doc/guides/nics/ena.rst index d19912e9..34c48575 100644 --- a/doc/guides/nics/ena.rst +++ b/doc/guides/nics/ena.rst @@ -113,10 +113,6 @@ Configuration information * **CONFIG_RTE_LIBRTE_ENA_PMD** (default y): Enables or disables inclusion of the ENA PMD driver in the DPDK compilation. - - * **CONFIG_RTE_LIBRTE_ENA_DEBUG_INIT** (default y): Enables or disables debug - logging of device initialization within the ENA PMD driver. - * **CONFIG_RTE_LIBRTE_ENA_DEBUG_RX** (default n): Enables or disables debug logging of RX logic within the ENA PMD driver. @@ -187,11 +183,20 @@ Prerequisites ------------- #. Prepare the system as recommended by DPDK suite. This includes environment - variables, hugepages configuration, tool-chains and configuration + variables, hugepages configuration, tool-chains and configuration. + +#. ENA PMD can operate with ``vfio-pci`` or ``igb_uio`` driver. + +#. Insert ``vfio-pci`` or ``igb_uio`` kernel module using the command + ``modprobe vfio-pci`` or ``modprobe igb_uio`` respectively. + +#. For ``vfio-pci`` users only: + Please make sure that ``IOMMU`` is enabled in your system, + or use ``vfio`` driver in ``noiommu`` mode:: -#. Insert igb_uio kernel module using the command 'modprobe igb_uio' + echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode -#. Bind the intended ENA device to igb_uio module +#. Bind the intended ENA device to ``vfio-pci`` or ``igb_uio`` module. At this point the system should be ready to run DPDK applications. Once the diff --git a/doc/guides/nics/enetc.rst b/doc/guides/nics/enetc.rst new file mode 100644 index 00000000..8038bf20 --- /dev/null +++ b/doc/guides/nics/enetc.rst @@ -0,0 +1,110 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright 2018 NXP + +ENETC Poll Mode Driver +====================== + +The ENETC NIC PMD (**librte_pmd_enetc**) provides poll mode driver +support for the inbuilt NIC found in the **NXP LS1028** SoC. + +More information can be found at `NXP Official Website +<https://www.nxp.com/products/processors-and-microcontrollers/arm-based-processors-and-mcus/qoriq-layerscape-arm-processors/qoriq-layerscape-1028a-industrial-applications-processor:LS1028A>`_. + +ENETC +----- + +This section provides an overview of the NXP ENETC +and how it is integrated into the DPDK. + +Contents summary + +- ENETC overview +- ENETC features +- PCI bus driver +- NIC driver +- Supported ENETC SoCs +- Prerequisites +- Driver compilation and testing + +ENETC Overview +~~~~~~~~~~~~~~ + +ENETC is a PCI Integrated End Point(IEP). IEP implements +peripheral devices in an SoC such that software sees them as PCIe device. +ENETC is an evolution of BDR(Buffer Descriptor Ring) based networking +IPs. + +This infrastructure simplifies adding support for IEP and facilitates in following: + +- Device discovery and location +- Resource requirement discovery and allocation (e.g. interrupt assignment, + device register address) +- Event reporting + +ENETC Features +~~~~~~~~~~~~~~ + +- Link Status +- Packet type information + +NIC Driver (PMD) +~~~~~~~~~~~~~~~~ + +ENETC PMD is traditional DPDK PMD which provides necessary interface between +RTE framework and ENETC internal drivers. + +- Driver registers the device vendor table in PCI subsystem. +- RTE framework scans the PCI bus for connected devices. +- This scanning will invoke the probe function of ENETC driver. +- The probe function will set the basic device registers and also setups BD rings. +- On packet Rx the respective BD Ring status bit is set which is then used for + packet processing. +- Then Tx is done first followed by Rx. + +Supported ENETC SoCs +~~~~~~~~~~~~~~~~~~~~ + +- LS1028 + +Prerequisites +~~~~~~~~~~~~~ + +There are three main pre-requisities for executing ENETC PMD on a ENETC +compatible board: + +1. **ARM 64 Tool Chain** + + For example, the `*aarch64* Linaro Toolchain <https://releases.linaro.org/components/toolchain/binaries/7.3-2018.05/aarch64-linux-gnu/gcc-linaro-7.3.1-2018.05-i686_aarch64-linux-gnu.tar.xz>`_. + +2. **Linux Kernel** + + It can be obtained from `NXP's Github hosting <https://source.codeaurora.org/external/qoriq/qoriq-components/linux>`_. + +3. **Rootfile system** + + Any *aarch64* supporting filesystem can be used. For example, + Ubuntu 16.04 LTS (Xenial) or 18.04 (Bionic) userland which can be obtained + from `here <http://cdimage.ubuntu.com/ubuntu-base/releases/18.04/release/ubuntu-base-18.04.1-base-arm64.tar.gz>`_. + +The following dependencies are not part of DPDK and must be installed +separately: + +- **NXP Linux LSDK** + + NXP Layerscape software development kit (LSDK) includes support for family + of QorIQ® ARM-Architecture-based system on chip (SoC) processors + and corresponding boards. + + It includes the Linux board support packages (BSPs) for NXP SoCs, + a fully operational tool chain, kernel and board specific modules. + + LSDK and related information can be obtained from: `LSDK <https://www.nxp.com/support/developer-resources/run-time-software/linux-software-and-development-tools/layerscape-software-development-kit:LAYERSCAPE-SDK>`_ + +Driver compilation and testing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Follow instructions available in the document +:ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` +to launch **testpmd** + +To compile in performance mode, please set ``CONFIG_RTE_CACHE_LINE_SIZE=64`` diff --git a/doc/guides/nics/enic.rst b/doc/guides/nics/enic.rst index 438a83d5..746d8912 100644 --- a/doc/guides/nics/enic.rst +++ b/doc/guides/nics/enic.rst @@ -260,6 +260,12 @@ Generic Flow API is supported. The baseline support is: - Selectors: 'is', 'spec' and 'mask'. 'last' is not supported - In total, up to 64 bytes of mask is allowed across all headers +- **1400 and later series VICS with advanced filters enabled** + + All the above plus: + + - Action: count + More features may be added in future firmware and new versions of the VIC. Please refer to the release notes. @@ -345,6 +351,41 @@ suitable for others. Such applications may change the mode by setting applications such as OVS-DPDK performance benchmarks that utilize only the default VLAN and want to see only untagged packets. + +Vectorized Rx Handler +--------------------- + +ENIC PMD includes a version of the receive handler that is vectorized using +AVX2 SIMD instructions. It is meant for bulk, throughput oriented workloads +where reducing cycles/packet in PMD is a priority. In order to use the +vectorized handler, take the following steps. + +- Use a recent version of gcc, icc, or clang and build 64-bit DPDK. If + the compiler is known to support AVX2, DPDK build system + automatically compiles the vectorized handler. Otherwise, the + handler is not available. + +- Set ``devargs`` parameter ``enable-avx2-rx=1`` to explicitly request that + PMD consider the vectorized handler when selecting the receive handler. + For example:: + + -w 12:00.0,enable-avx2-rx=1 + + As the current implementation is intended for field trials, by default, the + vectorized handler is not considered (``enable-avx2-rx=0``). + +- Run on a UCS M4 or later server with CPUs that support AVX2. + +PMD selects the vectorized handler when the handler is compiled into +the driver, the user requests its use via ``enable-avx2-rx=1``, CPU +supports AVX2, and scatter Rx is not used. To verify that the +vectorized handler is selected, enable debug logging +(``--log-level=pmd,debug``) and check the following message. + +.. code-block:: console + + enic_use_vector_rx_handler use the non-scatter avx2 Rx handler + .. _enic_limitations: Limitations diff --git a/doc/guides/nics/features.rst b/doc/guides/nics/features.rst index cddc877d..3fa5cb74 100644 --- a/doc/guides/nics/features.rst +++ b/doc/guides/nics/features.rst @@ -513,8 +513,9 @@ CRC offload ----------- Supports CRC stripping by hardware. +A PMD assumed to support CRC stripping by default. PMD should advertise if it supports keeping CRC. -* **[uses] rte_eth_rxconf,rte_eth_rxmode**: ``offloads:DEV_RX_OFFLOAD_CRC_STRIP,DEV_RX_OFFLOAD_KEEP_CRC``. +* **[uses] rte_eth_rxconf,rte_eth_rxmode**: ``offloads:DEV_RX_OFFLOAD_KEEP_CRC``. .. _nic_features_vlan_offload: @@ -526,8 +527,9 @@ Supports VLAN offload to hardware. * **[uses] rte_eth_rxconf,rte_eth_rxmode**: ``offloads:DEV_RX_OFFLOAD_VLAN_STRIP,DEV_RX_OFFLOAD_VLAN_FILTER,DEV_RX_OFFLOAD_VLAN_EXTEND``. * **[uses] rte_eth_txconf,rte_eth_txmode**: ``offloads:DEV_TX_OFFLOAD_VLAN_INSERT``. +* **[uses] mbuf**: ``mbuf.ol_flags:PKT_TX_VLAN``, ``mbuf.vlan_tci``. * **[implements] eth_dev_ops**: ``vlan_offload_set``. -* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_VLAN_STRIPPED``, ``mbuf.vlan_tci``. +* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_VLAN_STRIPPED``, ``mbuf.ol_flags:PKT_RX_VLAN`` ``mbuf.vlan_tci``. * **[provides] rte_eth_dev_info**: ``rx_offload_capa,rx_queue_offload_capa:DEV_RX_OFFLOAD_VLAN_STRIP``, ``tx_offload_capa,tx_queue_offload_capa:DEV_TX_OFFLOAD_VLAN_INSERT``. * **[related] API**: ``rte_eth_dev_set_vlan_offload()``, @@ -543,9 +545,10 @@ Supports QinQ (queue in queue) offload. * **[uses] rte_eth_rxconf,rte_eth_rxmode**: ``offloads:DEV_RX_OFFLOAD_QINQ_STRIP``. * **[uses] rte_eth_txconf,rte_eth_txmode**: ``offloads:DEV_TX_OFFLOAD_QINQ_INSERT``. -* **[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``. +* **[uses] mbuf**: ``mbuf.ol_flags:PKT_TX_QINQ``, ``mbuf.vlan_tci_outer``. +* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_QINQ_STRIPPED``, ``mbuf.ol_flags:PKT_RX_QINQ``, + ``mbuf.ol_flags:PKT_RX_VLAN_STRIPPED``, ``mbuf.ol_flags:PKT_RX_VLAN`` + ``mbuf.vlan_tci``, ``mbuf.vlan_tci_outer``. * **[provides] rte_eth_dev_info**: ``rx_offload_capa,rx_queue_offload_capa:DEV_RX_OFFLOAD_QINQ_STRIP``, ``tx_offload_capa,tx_queue_offload_capa:DEV_TX_OFFLOAD_QINQ_INSERT``. @@ -561,6 +564,7 @@ Supports L3 checksum offload. * **[uses] rte_eth_txconf,rte_eth_txmode**: ``offloads:DEV_TX_OFFLOAD_IPV4_CKSUM``. * **[uses] mbuf**: ``mbuf.ol_flags:PKT_TX_IP_CKSUM``, ``mbuf.ol_flags:PKT_TX_IPV4`` | ``PKT_TX_IPV6``. +* **[uses] mbuf**: ``mbuf.l2_len``, ``mbuf.l3_len``. * **[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``. @@ -575,15 +579,16 @@ L4 checksum offload Supports L4 checksum offload. -* **[uses] rte_eth_rxconf,rte_eth_rxmode**: ``offloads:DEV_RX_OFFLOAD_UDP_CKSUM,DEV_RX_OFFLOAD_TCP_CKSUM``. +* **[uses] rte_eth_rxconf,rte_eth_rxmode**: ``offloads:DEV_RX_OFFLOAD_UDP_CKSUM,DEV_RX_OFFLOAD_TCP_CKSUM,DEV_RX_OFFLOAD_SCTP_CKSUM``. * **[uses] rte_eth_txconf,rte_eth_txmode**: ``offloads:DEV_TX_OFFLOAD_UDP_CKSUM,DEV_TX_OFFLOAD_TCP_CKSUM,DEV_TX_OFFLOAD_SCTP_CKSUM``. * **[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``. +* **[uses] mbuf**: ``mbuf.l2_len``, ``mbuf.l3_len``. * **[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,rx_queue_offload_capa:DEV_RX_OFFLOAD_UDP_CKSUM,DEV_RX_OFFLOAD_TCP_CKSUM``, +* **[provides] rte_eth_dev_info**: ``rx_offload_capa,rx_queue_offload_capa:DEV_RX_OFFLOAD_UDP_CKSUM,DEV_RX_OFFLOAD_TCP_CKSUM,DEV_RX_OFFLOAD_SCTP_CKSUM``, ``tx_offload_capa,tx_queue_offload_capa:DEV_TX_OFFLOAD_UDP_CKSUM,DEV_TX_OFFLOAD_TCP_CKSUM,DEV_TX_OFFLOAD_SCTP_CKSUM``. .. _nic_features_hw_timestamp: @@ -638,6 +643,16 @@ Inner L4 checksum Supports inner packet L4 checksum. +* **[uses] rte_eth_rxconf,rte_eth_rxmode**: ``offloads:DEV_RX_OFFLOAD_OUTER_UDP_CKSUM``. +* **[provides] mbuf**: ``mbuf.ol_flags:PKT_RX_OUTER_L4_CKSUM_UNKNOWN`` | + ``PKT_RX_OUTER_L4_CKSUM_BAD`` | ``PKT_RX_OUTER_L4_CKSUM_GOOD`` | ``PKT_RX_OUTER_L4_CKSUM_INVALID``. +* **[uses] rte_eth_txconf,rte_eth_txmode**: ``offloads:DEV_TX_OFFLOAD_OUTER_UDP_CKSUM``. +* **[uses] mbuf**: ``mbuf.ol_flags:PKT_TX_OUTER_IPV4`` | ``PKT_TX_OUTER_IPV6``. + ``mbuf.ol_flags:PKT_TX_OUTER_UDP_CKSUM``. +* **[uses] mbuf**: ``mbuf.outer_l2_len``, ``mbuf.outer_l3_len``. +* **[provides] rte_eth_dev_info**: ``rx_offload_capa,rx_queue_offload_capa:DEV_RX_OFFLOAD_OUTER_UDP_CKSUM``, + ``tx_offload_capa,tx_queue_offload_capa:DEV_TX_OFFLOAD_OUTER_UDP_CKSUM``. + .. _nic_features_packet_type_parsing: diff --git a/doc/guides/nics/features/atlantic.ini b/doc/guides/nics/features/atlantic.ini new file mode 100644 index 00000000..5ed095b1 --- /dev/null +++ b/doc/guides/nics/features/atlantic.ini @@ -0,0 +1,37 @@ +; +; Supported features of the 'atlantic' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Speed capabilities = Y +Link status = Y +Link status event = Y +Queue start/stop = Y +MTU update = Y +Jumbo frame = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +VLAN filter = Y +Flow control = Y +CRC offload = Y +VLAN offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Rx descriptor status = Y +Tx descriptor status = Y +Basic stats = Y +Extended stats = Y +Stats per queue = Y +FW version = Y +EEPROM dump = Y +Registers dump = Y +Linux UIO = Y +ARMv8 = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/ena.ini b/doc/guides/nics/features/ena.ini index 691c1e3d..aa6f05a7 100644 --- a/doc/guides/nics/features/ena.ini +++ b/doc/guides/nics/features/ena.ini @@ -23,5 +23,6 @@ Inner L4 checksum = Y Basic stats = Y Extended stats = Y Linux UIO = Y +Linux VFIO = Y x86-32 = Y x86-64 = Y diff --git a/doc/guides/nics/features/enetc.ini b/doc/guides/nics/features/enetc.ini new file mode 100644 index 00000000..69476a2a --- /dev/null +++ b/doc/guides/nics/features/enetc.ini @@ -0,0 +1,11 @@ +; +; Supported features of the 'enetc' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Packet type parsing = Y +Link status = Y +Linux VFIO = Y +ARMv8 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/failsafe.ini b/doc/guides/nics/features/failsafe.ini index 39ee5796..e3c4c08f 100644 --- a/doc/guides/nics/features/failsafe.ini +++ b/doc/guides/nics/features/failsafe.ini @@ -7,6 +7,9 @@ Link status = Y Link status event = Y Rx interrupt = Y +Queue start/stop = Y +Runtime Rx queue setup = Y +Runtime Tx queue setup = Y MTU update = Y Jumbo frame = Y Promiscuous mode = Y diff --git a/doc/guides/nics/features/mvneta.ini b/doc/guides/nics/features/mvneta.ini new file mode 100644 index 00000000..701eb03d --- /dev/null +++ b/doc/guides/nics/features/mvneta.ini @@ -0,0 +1,19 @@ +; +; Supported features of the 'mvneta' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Speed capabilities = Y +Link status = Y +MTU update = Y +Jumbo frame = Y +Promiscuous mode = Y +Unicast MAC filter = Y +CRC offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Basic stats = Y +ARMv8 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/netvsc.ini b/doc/guides/nics/features/netvsc.ini index 2ff6042b..f5dc1e78 100644 --- a/doc/guides/nics/features/netvsc.ini +++ b/doc/guides/nics/features/netvsc.ini @@ -6,6 +6,7 @@ [Features] Speed capabilities = P Link status = Y +Free Tx mbuf on demand = Y Queue start/stop = Y Scattered Rx = Y Promiscuous mode = Y diff --git a/doc/guides/nics/features/sfc_efx.ini b/doc/guides/nics/features/sfc_efx.ini index 8a497ee0..d1aa8331 100644 --- a/doc/guides/nics/features/sfc_efx.ini +++ b/doc/guides/nics/features/sfc_efx.ini @@ -9,6 +9,8 @@ Link status = Y Link status event = Y Fast mbuf free = Y Queue start/stop = Y +Runtime Rx queue setup = Y +Runtime Tx queue setup = Y MTU update = Y Jumbo frame = Y Scattered Rx = Y diff --git a/doc/guides/nics/fm10k.rst b/doc/guides/nics/fm10k.rst index d1391e99..764e089c 100644 --- a/doc/guides/nics/fm10k.rst +++ b/doc/guides/nics/fm10k.rst @@ -139,8 +139,7 @@ CRC striping ~~~~~~~~~~~~ The FM10000 family of NICs strip the CRC for every packets coming into the -host interface. So, CRC will be stripped even when ``DEV_RX_OFFLOAD_CRC_STRIP`` -in ``rxmode.offloads`` is NOT set in ``struct rte_eth_conf``. +host interface. So, keeping CRC is not supported. Maximum packet length ~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/guides/nics/i40e.rst b/doc/guides/nics/i40e.rst index 65d87f86..ab3928a6 100644 --- a/doc/guides/nics/i40e.rst +++ b/doc/guides/nics/i40e.rst @@ -163,6 +163,15 @@ Runtime Config Options Currently hot-plugging of representor ports is not supported so all required representors must be specified on the creation of the PF. +- ``Use latest supported vector`` (default ``disable``) + + Latest supported vector path may not always get the best perf so vector path was + recommended to use only on later platform. But users may want the latest vector path + since it can get better perf in some real work loading cases. So ``devargs`` param + ``use-latest-supported-vec`` is introduced, for example:: + + -w 84:00.0,use-latest-supported-vec=1 + Driver compilation and testing ------------------------------ @@ -421,6 +430,12 @@ functionality requires a NIC firmware version of 6.0 or greater. Current implementation supports GTP-C/GTP-U/PPPoE/PPPoL2TP, steering can be used with rte_flow API. +GTPv1 package is released, and it can be downloaded from +https://downloadcenter.intel.com/download/27587. + +PPPoE package is released, and it can be downloaded from +https://downloadcenter.intel.com/download/28040. + Load a profile which supports GTP and store backup profile: .. code-block:: console diff --git a/doc/guides/nics/img/mvpp2_tm.svg b/doc/guides/nics/img/mvpp2_tm.svg new file mode 100644 index 00000000..4aa92721 --- /dev/null +++ b/doc/guides/nics/img/mvpp2_tm.svg @@ -0,0 +1,71 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd"> +<svg width="16cm" height="4cm" viewBox="-1 -1 309 75" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> + <g> + <polyline style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" points="159.661,12.6759 141.655,12.6759 141.655,35.5606 88.1561,35.5606 88.1561,44.9245 "/> + <polygon style="fill: #000000" points="88.1561,49.4245 85.1561,43.4245 88.1561,44.9245 91.1561,43.4245 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" points="88.1561,49.4245 85.1561,43.4245 88.1561,44.9245 91.1561,43.4245 "/> + </g> + <g> + <polyline style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" points="159.661,12.6759 176.28,12.6759 176.28,35.5606 281.681,35.5606 281.681,44.9245 "/> + <polygon style="fill: #000000" points="281.681,49.4245 278.681,43.4245 281.681,44.9245 284.681,43.4245 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" points="281.681,49.4245 278.681,43.4245 281.681,44.9245 284.681,43.4245 "/> + </g> + <g> + <rect style="fill: #ffffff" x="126.066" y="0.98102" width="67.1901" height="23.3899"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="126.066" y="0.98102" width="67.1901" height="23.3899"/> + </g> + <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="159.661" y="17.1259"> + <tspan x="159.661" y="17.1259">Port N</tspan> + </text> + <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="304.581" y="68.168"> + <tspan x="304.581" y="68.168"></tspan> + </text> + <g> + <rect style="fill: #ffffff" x="62.5504" y="51.5478" width="51.2114" height="22.0925"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="62.5504" y="51.5478" width="51.2114" height="22.0925"/> + </g> + <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="88.1561" y="67.044"> + <tspan x="88.1561" y="67.044">Txq 0</tspan> + </text> + <g> + <rect style="fill: #ffffff" x="134.1" y="51.355" width="51.1213" height="22.478"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="134.1" y="51.355" width="51.1213" height="22.478"/> + </g> + <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="159.661" y="67.044"> + <tspan x="159.661" y="67.044">Txq 1</tspan> + </text> + <g> + <rect style="fill: #ffffff" x="256.416" y="51.5478" width="50.5306" height="22.0925"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="256.416" y="51.5478" width="50.5306" height="22.0925"/> + </g> + <text font-size="12.7998" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="281.681" y="67.044"> + <tspan x="281.681" y="67.044">Txq M</tspan> + </text> + <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="101.822" y="67.044"> + <tspan x="101.822" y="67.044"></tspan> + </text> + <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="-0.537645" y="17.1259"> + <tspan x="-0.537645" y="17.1259">Level 0:</tspan> + </text> + <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="-0.746688" y="67.044"> + <tspan x="-0.746688" y="67.044">Level 1:</tspan> + </text> + <g> + <ellipse style="fill: #000000" cx="207.645" cy="62.594" rx="0.425344" ry="0.425344"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="207.645" cy="62.594" rx="0.425344" ry="0.425344"/> + </g> + <g> + <ellipse style="fill: #000000" cx="219.525" cy="62.594" rx="0.425344" ry="0.425344"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="219.525" cy="62.594" rx="0.425344" ry="0.425344"/> + </g> + <g> + <ellipse style="fill: #000000" cx="231.405" cy="62.594" rx="0.425345" ry="0.425345"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="231.405" cy="62.594" rx="0.425345" ry="0.425345"/> + </g> + <g> + <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="159.661" y1="24.3709" x2="159.661" y2="45.737"/> + <polygon style="fill: #000000" points="159.661,50.237 156.661,44.237 159.661,45.737 162.661,44.237 "/> + <polygon style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" points="159.661,50.237 156.661,44.237 159.661,45.737 162.661,44.237 "/> + </g> +</svg> diff --git a/doc/guides/nics/index.rst b/doc/guides/nics/index.rst index 59f6063d..bb107ae5 100644 --- a/doc/guides/nics/index.rst +++ b/doc/guides/nics/index.rst @@ -12,6 +12,7 @@ Network Interface Controller Drivers features build_and_test ark + atlantic avp axgbe bnx2x @@ -21,6 +22,7 @@ Network Interface Controller Drivers dpaa2 e1000em ena + enetc enic fm10k i40e @@ -32,6 +34,7 @@ Network Interface Controller Drivers liquidio mlx4 mlx5 + mvneta mvpp2 netvsc nfp diff --git a/doc/guides/nics/ixgbe.rst b/doc/guides/nics/ixgbe.rst index 16d63902..1c294b06 100644 --- a/doc/guides/nics/ixgbe.rst +++ b/doc/guides/nics/ixgbe.rst @@ -200,6 +200,33 @@ There is no RTE API to add a VF's MAC address from the PF. On ixgbe, the ``rte_eth_dev_mac_addr_add()`` function can be used to add a VF's MAC address, as a workaround. +X550 does not support legacy interrupt mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Desccription +^^^^^^^^^^^^ +X550 cannot get interrupts if using ``uio_pci_generic`` module or using legacy +interrupt mode of ``igb_uio`` or ``vfio``. Because the errata of X550 states +that the Interrupt Status bit is not implemented. The errata is the item #22 +from `X550 spec update <https://www.intel.com/content/dam/www/public/us/en/ +documents/specification-updates/ethernet-x550-spec-update.pdf>`_ + +Implication +^^^^^^^^^^^ +When using ``uio_pci_generic`` module or using legacy interrupt mode of +``igb_uio`` or ``vfio``, the Interrupt Status bit would be checked if the +interrupt is coming. Since the bit is not implemented in X550, the irq cannot +be handled correctly and cannot report the event fd to DPDK apps. Then apps +cannot get interrupts and ``dmesg`` will show messages like ``irq #No.: `` +``nobody cared.`` + +Workaround +^^^^^^^^^^ +Do not bind the ``uio_pci_generic`` module in X550 NICs. +Do not bind ``igb_uio`` with legacy mode in X550 NICs. +Before binding ``vfio`` with legacy mode in X550 NICs, use ``modprobe vfio `` +``nointxmask=1`` to load ``vfio`` module if the intx is not shared with other +devices. Inline crypto processing support -------------------------------- diff --git a/doc/guides/nics/liquidio.rst b/doc/guides/nics/liquidio.rst index 87b42cdc..e2a38004 100644 --- a/doc/guides/nics/liquidio.rst +++ b/doc/guides/nics/liquidio.rst @@ -30,14 +30,6 @@ Please note that enabling debugging options may affect system performance. Toggle compilation of LiquidIO PMD. -- ``CONFIG_RTE_LIBRTE_LIO_DEBUG_DRIVER`` (default ``n``) - - Toggle display of generic debugging messages. - -- ``CONFIG_RTE_LIBRTE_LIO_DEBUG_INIT`` (default ``n``) - - Toggle display of initialization related messages. - - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_RX`` (default ``n``) Toggle display of receive fast path run-time messages. diff --git a/doc/guides/nics/mlx5.rst b/doc/guides/nics/mlx5.rst index 52e1213c..67696283 100644 --- a/doc/guides/nics/mlx5.rst +++ b/doc/guides/nics/mlx5.rst @@ -339,7 +339,12 @@ Run-time configuration When those offloads are requested the MPS send function will not be used. It is currently only supported on the ConnectX-4 Lx, ConnectX-5 and Bluefield - families of adapters. Enabled by default. + families of adapters. + On ConnectX-4 Lx the MPW is considered un-secure hence disabled by default. + Users which enable the MPW should be aware that application which provides incorrect + mbuf descriptors in the Tx burst can lead to serious errors in the host including, on some cases, + NIC to get stuck. + On ConnectX-5 and Bluefield the MPW is secure and enabled by default. - ``txq_mpw_hdr_dseg_en`` parameter [int] @@ -392,6 +397,13 @@ Run-time configuration Disabled by default. +- ``dv_flow_en`` parameter [int] + + A nonzero value enables the DV flow steering assuming it is supported + by the driver. + + Disabled by default. + - ``representor`` parameter [list] This parameter can be used to instantiate DPDK Ethernet devices from diff --git a/doc/guides/nics/mvneta.rst b/doc/guides/nics/mvneta.rst new file mode 100644 index 00000000..2132a819 --- /dev/null +++ b/doc/guides/nics/mvneta.rst @@ -0,0 +1,171 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 Marvell International Ltd. + Copyright(c) 2018 Semihalf. + All rights reserved. + +MVNETA Poll Mode Driver +======================= + +The MVNETA PMD (librte_pmd_mvneta) provides poll mode driver support +for the Marvell NETA 1/2.5 Gbps adapter. + +Detailed information about SoCs that use PPv2 can be obtained here: + +* https://www.marvell.com/embedded-processors/armada-3700/ + +.. Note:: + + Due to external dependencies, this driver is disabled by default. It must + be enabled manually by setting relevant configuration option manually. + Please refer to `Config File Options`_ section for further details. + + +Features +-------- + +Features of the MVNETA PMD are: + +- Start/stop +- tx/rx_queue_setup +- tx/rx_burst +- Speed capabilities +- Jumbo frame +- MTU update +- Promiscuous mode +- Unicast MAC filter +- Link status +- CRC offload +- L3 checksum offload +- L4 checksum offload +- Packet type parsing +- Basic stats + + +Limitations +----------- + +- Flushing vlans added for filtering is not possible due to MUSDK missing + functionality. Current workaround is to reset board so that NETA has a + chance to start in a sane state. + +Prerequisites +------------- + +- Custom Linux Kernel sources + + .. code-block:: console + + git clone https://github.com/MarvellEmbeddedProcessors/linux-marvell.git -b linux-4.4.120-armada-18.09 + + +- MUSDK (Marvell User-Space SDK) sources + + .. code-block:: console + + git clone https://github.com/MarvellEmbeddedProcessors/musdk-marvell.git -b musdk-armada-18.09 + + MUSDK is a light-weight library that provides direct access to Marvell's + NETA. Alternatively prebuilt MUSDK library can be + requested from `Marvell Extranet <https://extranet.marvell.com>`_. Once + approval has been granted, library can be found by typing ``musdk`` in + the search box. + + MUSDK must be configured with the following features: + + .. code-block:: console + + --enable-pp2=no --enable-neta + +- DPDK environment + + Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup + DPDK environment. + +Pre-Installation Configuration +------------------------------ + +Config File Options +~~~~~~~~~~~~~~~~~~~ + +The following options can be modified in the ``config`` file. + +- ``CONFIG_RTE_LIBRTE_MVNETA_PMD`` (default ``n``) + + Toggle compilation of the librte_pmd_mvneta driver. + +Runtime options +~~~~~~~~~~~~~~~ + +The following ``devargs`` options can be enabled at runtime. They must +be passed as part of EAL arguments. + +- ``iface`` (mandatory, with no default value) + + The name of port (owned by MUSDK) that should be enabled in DPDK. + This options can be repeated resulting in a list of ports to be + enabled. For instance below will enable ``eth0`` and ``eth1`` ports. + +.. code-block:: console + + ./testpmd --vdev=net_mvneta,iface=eth0,iface=eth1 \ + -c 3 -- -i --p 3 -a + + +Building DPDK +------------- + +Driver needs precompiled MUSDK library during compilation. + +.. code-block:: console + + export CROSS_COMPILE=<toolchain>/bin/aarch64-linux-gnu- + ./bootstrap + ./configure --host=aarch64-linux-gnu --enable-pp2=no --enable-neta + make install + +MUSDK will be installed to `usr/local` under current directory. +For the detailed build instructions please consult ``doc/musdk_get_started.txt``. + +Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with +the path to the MUSDK installation directory needs to be exported. + +.. code-block:: console + + export LIBMUSDK_PATH=<musdk>/usr/local + export CROSS=aarch64-linux-gnu- + make config T=arm64-armv8a-linuxapp-gcc + sed -ri 's,(MVNETA_PMD=)n,\1y,' build/.config + make + +Usage Example +------------- + +MVNETA PMD requires extra out of tree kernel modules to function properly. +`musdk_uio` and `mv_neta_uio` sources are part of the MUSDK. Please consult +``doc/musdk_get_started.txt`` for the detailed build instructions. + +.. code-block:: console + + insmod musdk_uio.ko + insmod mv_neta_uio.ko + +Additionally interfaces used by DPDK application need to be put up: + +.. code-block:: console + + ip link set eth0 up + ip link set eth1 up + +In order to run testpmd example application following command can be used: + +.. code-block:: console + + ./testpmd --vdev=net_mvneta,iface=eth0,iface=eth1 -c 3 -- \ + -i --p 3 -a --txd 256 --rxd 128 --rxq=1 --txq=1 --nb-cores=1 + + +In order to run l2fwd example application following command can be used: + +.. code-block:: console + + ./l2fwd --vdev=net_mvneta,iface=eth0,iface=eth1 -c 3 -- -T 1 -p 3 diff --git a/doc/guides/nics/mvpp2.rst b/doc/guides/nics/mvpp2.rst index 0408752c..82b9383e 100644 --- a/doc/guides/nics/mvpp2.rst +++ b/doc/guides/nics/mvpp2.rst @@ -56,7 +56,7 @@ Features of the MVPP2 PMD are: - Speed capabilities - Link status -- Queue start/stop +- Tx Queue start/stop - MTU update - Jumbo frame - Promiscuous mode @@ -70,11 +70,13 @@ Features of the MVPP2 PMD are: - L4 checksum offload - Packet type parsing - Basic stats -- Extended stats -- QoS +- :ref:`Extended stats <extstats>` - RX flow control -- TX queue start/stop - +- Scattered TX frames +- :ref:`QoS <qossupport>` +- :ref:`Flow API <flowapi>` +- :ref:`Traffic metering and policing <mtrapi>` +- :ref:`Traffic Management API <tmapi>` Limitations ----------- @@ -88,6 +90,20 @@ Limitations functionality. Current workaround is to reset board so that PPv2 has a chance to start in a sane state. +- MUSDK architecture does not support changing configuration in run time. + All nessesary configurations should be done before first dev_start(). + +- RX queue start/stop is not supported. + +- Current implementation does not support replacement of buffers in the HW buffer pool + at run time, so it is responsibility of the application to ensure that MTU does not exceed the configured buffer size. + +- Configuring TX flow control currently is not supported. + +- In current implementation, mechanism for acknowledging transmitted packets (``tx_done_cleanup``) is not supported. + +- Running more than one DPDK-MUSDK application simultaneously is not supported. + Prerequisites ------------- @@ -96,19 +112,19 @@ Prerequisites .. code-block:: console - git clone https://github.com/MarvellEmbeddedProcessors/linux-marvell.git -b linux-4.4.52-armada-17.10 + git clone https://github.com/MarvellEmbeddedProcessors/linux-marvell.git -b linux-4.4.120-armada-18.09 - Out of tree `mvpp2x_sysfs` kernel module sources .. code-block:: console - git clone https://github.com/MarvellEmbeddedProcessors/mvpp2x-marvell.git -b mvpp2x-armada-17.10 + git clone https://github.com/MarvellEmbeddedProcessors/mvpp2x-marvell.git -b mvpp2x-armada-18.09 - MUSDK (Marvell User-Space SDK) sources .. code-block:: console - git clone https://github.com/MarvellEmbeddedProcessors/musdk-marvell.git -b musdk-armada-17.10 + git clone https://github.com/MarvellEmbeddedProcessors/musdk-marvell.git -b musdk-armada-18.09 MUSDK is a light-weight library that provides direct access to Marvell's PPv2 (Packet Processor v2). Alternatively prebuilt MUSDK library can be @@ -119,12 +135,6 @@ Prerequisites To get better understanding of the library one can consult documentation available in the ``doc`` top level directory of the MUSDK sources. - MUSDK must be configured with the following features: - - .. code-block:: console - - --enable-bpool-dma=64 - - DPDK environment Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup @@ -140,6 +150,95 @@ The following options can be modified in the ``config`` file. Toggle compilation of the librte mvpp2 driver. + .. Note:: + + When MVPP2 PMD is enabled ``CONFIG_RTE_LIBRTE_MVNETA_PMD`` must be disabled + + +Building DPDK +------------- + +Driver needs precompiled MUSDK library during compilation. + +.. code-block:: console + + export CROSS_COMPILE=<toolchain>/bin/aarch64-linux-gnu- + ./bootstrap + ./configure --host=aarch64-linux-gnu + make install + +MUSDK will be installed to `usr/local` under current directory. +For the detailed build instructions please consult ``doc/musdk_get_started.txt``. + +Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with +the path to the MUSDK installation directory needs to be exported. + +For additional instructions regarding DPDK cross compilation please refer to :doc:`Cross compile DPDK for ARM64 <../linux_gsg/cross_build_dpdk_for_arm64>`. + +.. code-block:: console + + export LIBMUSDK_PATH=<musdk>/usr/local + export CROSS=<toolchain>/bin/aarch64-linux-gnu- + export RTE_KERNELDIR=<kernel-dir> + export RTE_TARGET=arm64-armv8a-linuxapp-gcc + + make config T=arm64-armv8a-linuxapp-gcc + sed -i "s/MVNETA_PMD=y/MVNETA_PMD=n/" build/.config + sed -i "s/MVPP2_PMD=n/MVPP2_PMD=y/" build/.config + make + +Usage Example +------------- + +MVPP2 PMD requires extra out of tree kernel modules to function properly. +`musdk_cma` sources are part of the MUSDK. Please consult +``doc/musdk_get_started.txt`` for the detailed build instructions. +For `mvpp2x_sysfs` please consult ``Documentation/pp22_sysfs.txt`` for the +detailed build instructions. + +.. code-block:: console + + insmod musdk_cma.ko + insmod mvpp2x_sysfs.ko + +Additionally interfaces used by DPDK application need to be put up: + +.. code-block:: console + + ip link set eth0 up + ip link set eth2 up + +In order to run testpmd example application following command can be used: + +.. code-block:: console + + ./testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2 -c 7 -- \ + --burst=128 --txd=2048 --rxd=1024 --rxq=2 --txq=2 --nb-cores=2 \ + -i -a --rss-udp + +.. _extstats: + +Extended stats +-------------- + +MVPP2 PMD supports the following extended statistics: + + - ``rx_bytes``: number of RX bytes + - ``rx_packets``: number of RX packets + - ``rx_unicast_packets``: number of RX unicast packets + - ``rx_errors``: number of RX MAC errors + - ``rx_fullq_dropped``: number of RX packets dropped due to full RX queue + - ``rx_bm_dropped``: number of RX packets dropped due to no available buffers in the HW pool + - ``rx_early_dropped``: number of RX packets that were early dropped + - ``rx_fifo_dropped``: number of RX packets dropped due to RX fifo overrun + - ``rx_cls_dropped``: number of RX packets dropped by classifier + - ``tx_bytes``: number of TX bytes + - ``tx_packets``: number of TX packets + - ``tx_unicast_packets``: number of TX unicast packets + - ``tx_errors``: number of TX MAC errors + + +.. _qossupport: QoS Configuration ----------------- @@ -152,20 +251,23 @@ Configuration syntax .. code-block:: console - [port <portnum> default] - default_tc = <default_tc> - mapping_priority = <mapping_priority> - policer_enable = <policer_enable> + [policer <policer_id>] token_unit = <token_unit> color = <color_mode> cir = <cir> ebs = <ebs> cbs = <cbs> + [port <portnum> default] + default_tc = <default_tc> + mapping_priority = <mapping_priority> + rate_limit_enable = <rate_limit_enable> rate_limit = <rate_limit> burst_size = <burst_size> + default_policer = <policer_id> + [port <portnum> tc <traffic_class>] rxq = <rx_queue_list> pcp = <pcp_list> @@ -201,7 +303,9 @@ Where: - ``<dscp_list>``: List of DSCP values to handle in particular TC (e.g. 0-12 32-48 63). -- ``<policer_enable>``: Enable ingress policer. +- ``<default_policer>``: Id of the policer configuration section to be used as default. + +- ``<policer_id>``: Id of the policer configuration section (0..31). - ``<token_unit>``: Policer token unit (`bytes` or `packets`). @@ -215,7 +319,7 @@ Where: - ``<default_color>``: Default color for specific tc. -- ``<rate_limit_enable>``: Enables per port or per txq rate limiting. +- ``<rate_limit_enable>``: Enables per port or per txq rate limiting (`0`/`1` to disable/enable). - ``<rate_limit>``: Committed information rate, in kilo bits per second. @@ -234,6 +338,13 @@ Configuration file example .. code-block:: console + [policer 0] + token_unit = bytes + color = blind + cir = 100000 + ebs = 64 + cbs = 64 + [port 0 default] default_tc = 0 mapping_priority = ip @@ -265,12 +376,7 @@ Configuration file example default_tc = 0 mapping_priority = vlan/ip - policer_enable = 1 - token_unit = bytes - color = blind - cir = 100000 - ebs = 64 - cbs = 64 + default_policer = 0 [port 1 tc 0] rxq = 0 @@ -297,38 +403,14 @@ Usage example ./testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2,cfg=/home/user/mrvl.conf \ -c 7 -- -i -a --disable-hw-vlan-strip --rxq=3 --txq=3 - -Building DPDK -------------- - -Driver needs precompiled MUSDK library during compilation. - -.. code-block:: console - - export CROSS_COMPILE=<toolchain>/bin/aarch64-linux-gnu- - ./bootstrap - ./configure --host=aarch64-linux-gnu --enable-bpool-dma=64 - make install - -MUSDK will be installed to `usr/local` under current directory. -For the detailed build instructions please consult ``doc/musdk_get_started.txt``. - -Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with -the path to the MUSDK installation directory needs to be exported. - -.. code-block:: console - - export LIBMUSDK_PATH=<musdk>/usr/local - export CROSS=aarch64-linux-gnu- - make config T=arm64-armv8a-linuxapp-gcc - sed -ri 's,(MVPP2_PMD=)n,\1y,' build/.config - make +.. _flowapi: Flow API -------- PPv2 offers packet classification capabilities via classifier engine which can be configured via generic flow API offered by DPDK. +For an additional description please refer to DPDK :ref:`Generic flow API <Generic_flow_API>`. Supported flow actions ~~~~~~~~~~~~~~~~~~~~~~ @@ -489,32 +571,239 @@ Following limitations need to be taken into account while creating flow rules: For additional information about classifier please consult ``doc/musdk_cls_user_guide.txt``. -Usage Example -------------- +.. _mtrapi: -MVPP2 PMD requires extra out of tree kernel modules to function properly. -`musdk_uio` and `mv_pp_uio` sources are part of the MUSDK. Please consult -``doc/musdk_get_started.txt`` for the detailed build instructions. -For `mvpp2x_sysfs` please consult ``Documentation/pp22_sysfs.txt`` for the -detailed build instructions. +Traffic metering and policing +----------------------------- -.. code-block:: console +MVPP2 PMD supports DPDK traffic metering and policing that allows the following: - insmod musdk_uio.ko - insmod mv_pp_uio.ko - insmod mvpp2x_sysfs.ko +1. Meter ingress traffic. +2. Do policing. +3. Gather statistics. -Additionally interfaces used by DPDK application need to be put up: +For an additional description please refer to DPDK :doc:`Traffic Metering and Policing API <../prog_guide/traffic_metering_and_policing>`. -.. code-block:: console +The policer objects defined by this feature can work with the default policer defined via config file as described in :ref:`QoS Support <qossupport>`. - ip link set eth0 up - ip link set eth2 up +Limitations +~~~~~~~~~~~ -In order to run testpmd example application following command can be used: +The following capabilities are not supported: -.. code-block:: console +- MTR object meter DSCP table update +- MTR object policer action update +- MTR object enabled statistics - ./testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2 -c 7 -- \ - --burst=128 --txd=2048 --rxd=1024 --rxq=2 --txq=2 --nb-cores=2 \ - -i -a --rss-udp +Usage example +~~~~~~~~~~~~~ + +1. Run testpmd user app: + + .. code-block:: console + + ./testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2 -c 6 -- -i -p 3 -a --txd 1024 --rxd 1024 + +2. Create meter profile: + + .. code-block:: console + + testpmd> add port meter profile 0 0 srtcm_rfc2697 2000 256 256 + +3. Create meter: + + .. code-block:: console + + testpmd> create port meter 0 0 0 yes d d d 0 1 0 + +4. Create flow rule witch meter attached: + + .. code-block:: console + + testpmd> flow create 0 ingress pattern ipv4 src is 10.10.10.1 / end actions meter mtr_id 0 / end + +For a detailed usage description please refer to "Traffic Metering and Policing" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`. + + + +.. _tmapi: + +Traffic Management API +---------------------- + +MVPP2 PMD supports generic DPDK Traffic Management API which allows to +configure the following features: + +1. Hierarchical scheduling +2. Traffic shaping +3. Congestion management +4. Packet marking + +Internally TM is represented by a hierarchy (tree) of nodes. +Node which has a parent is called a leaf whereas node without +parent is called a non-leaf (root). +MVPP2 PMD supports two level hierarchy where level 0 represents ports and level 1 represents tx queues of a given port. + +.. figure:: img/mvpp2_tm.svg + +Nodes hold following types of settings: + +- for egress scheduler configuration: weight +- for egress rate limiter: private shaper +- bitmask indicating which statistics counters will be read + +Hierarchy is always constructed from the top, i.e first a root node is added +then some number of leaf nodes. Number of leaf nodes cannot exceed number +of configured tx queues. + +After hierarchy is complete it can be committed. + + +For an additional description please refer to DPDK :doc:`Traffic Management API <../prog_guide/traffic_management>`. + +Limitations +~~~~~~~~~~~ + +The following capabilities are not supported: + +- Traffic manager WRED profile and WRED context +- Traffic manager shared shaper update +- Traffic manager packet marking +- Maximum number of levels in hierarchy is 2 +- Currently dynamic change of a hierarchy is not supported + +Usage example +~~~~~~~~~~~~~ + +For a detailed usage description please refer to "Traffic Management" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`. + +1. Run testpmd as follows: + + .. code-block:: console + + ./testpmd --vdev=net_mrvl,iface=eth0,iface=eth2,cfg=./qos_config -c 7 -- \ + -i -p 3 --disable-hw-vlan-strip --rxq 3 --txq 3 --txd 1024 --rxd 1024 + +2. Stop all ports: + + .. code-block:: console + + testpmd> port stop all + +3. Add shaper profile: + + .. code-block:: console + + testpmd> add port tm node shaper profile 0 0 900000 70000 0 + + Parameters have following meaning:: + + 0 - Id of a port. + 0 - Id of a new shaper profile. + 900000 - Shaper rate in bytes/s. + 70000 - Bucket size in bytes. + 0 - Packet length adjustment - ignored. + +4. Add non-leaf node for port 0: + + .. code-block:: console + + testpmd> add port tm nonleaf node 0 3 -1 0 0 0 0 0 1 3 0 + + Parameters have following meaning:: + + 0 - Id of a port + 3 - Id of a new node. + -1 - Indicate that root does not have a parent. + 0 - Priority of the node. + 0 - Weight of the node. + 0 - Id of a level. Since this is a root 0 is passed. + 0 - Id of the shaper profile. + 0 - Number of SP priorities. + 3 - Enable statistics for both number of transmitted packets and bytes. + 0 - Number of shared shapers. + +5. Add leaf node for tx queue 0: + + .. code-block:: console + + testpmd> add port tm leaf node 0 0 3 0 30 1 -1 0 0 1 0 + + Parameters have following meaning:: + + 0 - Id of a port. + 0 - Id of a new node. + 3 - Id of the parent node. + 0 - Priority of a node. + 30 - WRR weight. + 1 - Id of a level. Since this is a leaf node 1 is passed. + -1 - Id of a shaper. -1 indicates that shaper is not attached. + 0 - Congestion management is not supported. + 0 - Congestion management is not supported. + 1 - Enable statistics counter for number of transmitted packets. + 0 - Number of shared shapers. + +6. Add leaf node for tx queue 1: + + .. code-block:: console + + testpmd> add port tm leaf node 0 1 3 0 60 1 -1 0 0 1 0 + + Parameters have following meaning:: + + 0 - Id of a port. + 1 - Id of a new node. + 3 - Id of the parent node. + 0 - Priority of a node. + 60 - WRR weight. + 1 - Id of a level. Since this is a leaf node 1 is passed. + -1 - Id of a shaper. -1 indicates that shaper is not attached. + 0 - Congestion management is not supported. + 0 - Congestion management is not supported. + 1 - Enable statistics counter for number of transmitted packets. + 0 - Number of shared shapers. + +7. Add leaf node for tx queue 2: + + .. code-block:: console + + testpmd> add port tm leaf node 0 2 3 0 99 1 -1 0 0 1 0 + + Parameters have following meaning:: + + 0 - Id of a port. + 2 - Id of a new node. + 3 - Id of the parent node. + 0 - Priority of a node. + 99 - WRR weight. + 1 - Id of a level. Since this is a leaf node 1 is passed. + -1 - Id of a shaper. -1 indicates that shaper is not attached. + 0 - Congestion management is not supported. + 0 - Congestion management is not supported. + 1 - Enable statistics counter for number of transmitted packets. + 0 - Number of shared shapers. + +8. Commit hierarchy: + + .. code-block:: console + + testpmd> port tm hierarchy commit 0 no + + Parameters have following meaning:: + + 0 - Id of a port. + no - Do not flush TM hierarchy if commit fails. + +9. Start all ports + + .. code-block:: console + + testpmd> port start all + + + +10. Enable forwarding + + .. code-block:: console + + testpmd> start diff --git a/doc/guides/nics/netvsc.rst b/doc/guides/nics/netvsc.rst index 345f393c..87fabf5b 100644 --- a/doc/guides/nics/netvsc.rst +++ b/doc/guides/nics/netvsc.rst @@ -28,19 +28,16 @@ In this release, the hyper PMD driver provides the basic functionality of packet * VLAN tags are always stripped and presented in mbuf tci field. -* The Hyper-V driver does not use or support Link State or Rx interrupt. +* The Hyper-V driver does not use or support interrupts. Link state change + callback is done via change events in the packet ring. * The maximum number of queues is limited by the host (currently 64). When used with 4.16 kernel only a single queue is available. -.. note:: - This driver is intended for use with **Hyper-V only** and is - not recommended for use on Azure because accelerated Networking - (SR-IOV) is not supported. - - On Azure, use the :doc:`vdev_netvsc` which - automatically configures the necessary TAP and failsave drivers. - +* This driver supports SR-IOV network acceleration. + If SR-IOV is enabled then the driver will transparently manage the interface, + and send and receive packets using the VF path. + The VDEV_NETVSC and FAILSAFE drivers are *not* used when using netvsc PMD. Installation ------------ @@ -103,3 +100,19 @@ The following prerequisites apply: * Linux kernel support for UIO on vmbus is done with the uio_hv_generic driver. Full support of multiple queues requires the 4.17 kernel. It is possible to use the netvsc PMD with 4.16 kernel but it is limited to a single queue. + + +Netvsc PMD arguments +-------------------- + +The user can specify below argument in devargs. + +#. ``latency``: + + A netvsc device uses a mailbox page to indicate to the host that there + is something in the transmit queue. The host scans this page at a + periodic interval. This parameter allows adjusting the value that + is used by the host. Smaller values improve transmit latency, and larger + values save CPU cycles. This parameter is in microseconds. + If the value is too large or too small it will be + ignored by the host. (Default: 50) diff --git a/doc/guides/nics/octeontx.rst b/doc/guides/nics/octeontx.rst index f8eaaa63..f8111d3c 100644 --- a/doc/guides/nics/octeontx.rst +++ b/doc/guides/nics/octeontx.rst @@ -1,11 +1,11 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2017 Cavium, Inc -OCTEONTX Poll Mode driver -========================= +OCTEON TX Poll Mode driver +========================== -The OCTEONTX ETHDEV PMD (**librte_pmd_octeontx**) provides poll mode ethdev -driver support for the inbuilt network device found in the **Cavium OCTEONTX** +The OCTEON TX ETHDEV PMD (**librte_pmd_octeontx**) provides poll mode ethdev +driver support for the inbuilt network device found in the **Cavium OCTEON TX** SoC family as well as their virtual functions (VF) in SR-IOV context. More information can be found at `Cavium, Inc Official Website @@ -14,7 +14,7 @@ More information can be found at `Cavium, Inc Official Website Features -------- -Features of the OCTEONTX Ethdev PMD are: +Features of the OCTEON TX Ethdev PMD are: - Packet type information - Promiscuous mode @@ -26,8 +26,8 @@ Features of the OCTEONTX Ethdev PMD are: - Lock-free Tx queue - HW offloaded `ethdev Rx queue` to `eventdev event queue` packet injection -Supported OCTEONTX SoCs ------------------------ +Supported OCTEON TX SoCs +------------------------ - CN83xx @@ -65,7 +65,7 @@ Driver compilation and testing Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` for details. -To compile the OCTEONTX PMD for Linux arm64 gcc target, run the +To compile the OCTEON TX PMD for Linux arm64 gcc target, run the following ``make`` command: .. code-block:: console @@ -122,7 +122,7 @@ following ``make`` command: Initialization -------------- -The octeontx ethdev pmd is exposed as a vdev device which consists of a set +The OCTEON TX ethdev pmd is exposed as a vdev device which consists of a set of PKI and PKO PCIe VF devices. On EAL initialization, PKI/PKO PCIe VF devices will be probed and then the vdev device can be created from the application code, or from the EAL command line based on @@ -156,21 +156,21 @@ Limitations ``octeontx_fpavf`` external mempool handler dependency ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The OCTEONTX SoC family NIC has inbuilt HW assisted external mempool manager. +The OCTEON TX SoC family NIC has inbuilt HW assisted external mempool manager. This driver will only work with ``octeontx_fpavf`` external mempool handler as it is the most performance effective way for packet allocation and Tx buffer -recycling on OCTEONTX SoC platform. +recycling on OCTEON TX SoC platform. CRC striping ~~~~~~~~~~~~ -The OCTEONTX SoC family NICs strip the CRC for every packets coming into the +The OCTEON TX SoC family NICs strip the CRC for every packets coming into the host interface irrespective of the offload configuration. Maximum packet length ~~~~~~~~~~~~~~~~~~~~~ -The OCTEONTX SoC family NICs support a maximum of a 32K jumbo frame. The value +The OCTEON TX SoC family NICs support a maximum of a 32K jumbo frame. The value is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len`` member of ``struct rte_eth_conf`` is set to a value lower than 32k, frames up to 32k bytes can still reach the host interface. diff --git a/doc/guides/nics/pcap_ring.rst b/doc/guides/nics/pcap_ring.rst index 879e5430..c1ef9196 100644 --- a/doc/guides/nics/pcap_ring.rst +++ b/doc/guides/nics/pcap_ring.rst @@ -96,6 +96,16 @@ The different stream types are: iface=eth0 +Runtime Config Options +^^^^^^^^^^^^^^^^^^^^^^ + +- Use PCAP interface physical MAC + + In case ``iface=`` configuration is set, user may want to use the selected interface's physical MAC + address. This can be done with a ``devarg`` ``phy_mac``, for example:: + + --vdev 'net_pcap0,iface=eth0,phy_mac=1' + Examples of Usage ^^^^^^^^^^^^^^^^^ diff --git a/doc/guides/nics/sfc_efx.rst b/doc/guides/nics/sfc_efx.rst index 63939ec8..40065284 100644 --- a/doc/guides/nics/sfc_efx.rst +++ b/doc/guides/nics/sfc_efx.rst @@ -240,6 +240,10 @@ Supported NICs - 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 @@ -318,7 +322,7 @@ boolean parameters value. **efx** chooses libefx-based datapath which supports Rx scatter. **ef10** chooses EF10 (SFN7xxx, SFN8xxx, X2xxx) native datapath which is more efficient than libefx-based and provides richer packet type - classification, but lacks Rx scatter support. + classification. **ef10_esps** chooses SFNX2xxx equal stride packed stream datapath which may be used on DPDK firmware variant only (see notes about its limitations above). @@ -333,8 +337,7 @@ boolean parameters value. Mbuf segments may come from different mempools, and mbuf reference counters are treated responsibly. **ef10** chooses EF10 (SFN7xxx, SFN8xxx, X2xxx) native datapath which is - more efficient than libefx-based but has no VLAN insertion and TSO - support yet. + 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 diff --git a/doc/guides/nics/softnic.rst b/doc/guides/nics/softnic.rst index 6c2287a1..32a9cf22 100644 --- a/doc/guides/nics/softnic.rst +++ b/doc/guides/nics/softnic.rst @@ -248,3 +248,123 @@ command description provided in `softnic/rte_eth_softnic_cli.c`. thread 1 pipeline RX enable (Soft NIC rx pipeline enable on cpu thread id 1) thread 1 pipeline TX enable (Soft NIC tx pipeline enable on cpu thread id 1) + +QoS API Support: +---------------- + +SoftNIC PMD implements ethdev traffic management APIs ``rte_tm.h`` that +allow building and committing traffic manager hierarchy, configuring hierarchy +nodes of the Quality of Service (QoS) scheduler supported by DPDK librte_sched +library. Furthermore, APIs for run-time update to the traffic manager hierarchy +are supported by PMD. + +SoftNIC PMD also implements ethdev traffic metering and policing APIs +``rte_mtr.h`` that enables metering and marking of the packets with the +appropriate color (green, yellow or red), according to the traffic metering +algorithm. For the meter output color, policer actions like +`keep the packet color same`, `change the packet color` or `drop the packet` +can be configured. + +.. Note:: + + The SoftNIC does not support the meter object shared by several flows, + thus only supports creating meter object private to the flow. Once meter + object is successfully created, it can be linked to the specific flow by + specifying the ``meter`` flow action in the flow rule. + +Flow API support: +----------------- + +The SoftNIC PMD implements ethdev flow APIs ``rte_flow.h`` that allow validating +flow rules, adding flow rules to the SoftNIC pipeline as table rules, deleting +and querying the flow rules. The PMD provides new cli command for creating the +flow group and their mapping to the SoftNIC pipeline and table. This cli should +be configured as part of firmware file. + + .. code-block:: console + + flowapi map group <group_id> ingress | egress pipeline <pipeline_name> \ + table <table_id> + +From the flow attributes of the flow, PMD uses the group id to get the mapped +pipeline and table. PMD supports number of flow actions such as +``JMP, QUEUE, RSS, DROP, COUNT, METER, VXLAN`` etc. + +.. Note:: + + The flow must have one terminating actions i.e. + ``JMP or RSS or QUEUE or DROP``. For the count and drop actions the + underlying PMD doesn't support the functionality yet. So it is not + recommended for use. + +The flow API can be tested with the help of testpmd application. The SoftNIC +firmware specifies CLI commands for port configuration, pipeline creation, +action profile creation and table creation. Once application gets initialized, +the flow rules can be added through the testpmd CLI. +The PMD will translate the flow rules to the SoftNIC pipeline tables rules. + +Example: +~~~~~~~~ +Example demonstrates the flow queue action using the SoftNIC firmware and testpmd +commands. + +* Prepare SoftNIC firmware + + .. code-block:: console + + link LINK0 dev 0000:83:00.0 + link LINK1 dev 0000:81:00.0 + pipeline RX period 10 offset_port_id 0 + pipeline RX port in bsz 32 link LINK0 rxq 0 + pipeline RX port in bsz 32 link LINK1 rxq 0 + pipeline RX port out bsz 32 swq RXQ0 + pipeline RX port out bsz 32 swq RXQ1 + table action profile AP0 ipv4 offset 278 fwd + pipeline RX table match hash ext key 16 mask + 00FF0000FFFFFFFFFFFFFFFFFFFFFFFF \ + offset 278 buckets 16K size 65K action AP0 + pipeline RX port in 0 table 0 + pipeline RX port in 1 table 0 + flowapi map group 0 ingress pipeline RX table 0 + pipeline TX period 10 offset_port_id 0 + pipeline TX port in bsz 32 swq TXQ0 + pipeline TX port in bsz 32 swq TXQ1 + pipeline TX port out bsz 32 link LINK0 txq 0 + pipeline TX port out bsz 32 link LINK1 txq 0 + pipeline TX table match hash ext key 16 mask + 00FF0000FFFFFFFFFFFFFFFFFFFFFFFF \ + offset 278 buckets 16K size 65K action AP0 + pipeline TX port in 0 table 0 + pipeline TX port in 1 table 0 + pipeline TX table 0 rule add match hash ipv4_5tuple + 1.10.11.12 2.20.21.22 100 200 6 action fwd port 0 + pipeline TX table 0 rule add match hash ipv4_5tuple + 1.10.11.13 2.20.21.23 100 200 6 action fwd port 1 + thread 25 pipeline RX enable + thread 25 pipeline TX enable + +* Run testpmd: + + .. code-block:: console + + ./x86_64-native-linuxapp-gcc/app/testpmd -l 23-25 -n 4 \ + --vdev 'net_softnic0, \ + firmware=./drivers/net/softnic/ \ + firmware.cli, \ + cpu_id=1,conn_port=8086' -- \ + -i --forward-mode=softnic --rxq=2, \ + --txq=2, --disable-rss --portmask=0x4 + +* Configure flow rules on softnic: + + .. code-block:: console + + flow create 2 group 0 ingress pattern eth / ipv4 proto mask 255 src \ + mask 255.255.255.255 dst mask 255.255.255.255 src spec + 1.10.11.12 dst spec 2.20.21.22 proto spec 6 / tcp src mask 65535 \ + dst mask 65535 src spec 100 dst spec 200 / end actions queue \ + index 0 / end + flow create 2 group 0 ingress pattern eth / ipv4 proto mask 255 src \ + mask 255.255.255.255 dst mask 255.255.255.255 src spec 1.10.11.13 \ + dst spec 2.20.21.23 proto spec 6 / tcp src mask 65535 dst mask \ + 65535 src spec 100 dst spec 200 / end actions queue index 1 / end diff --git a/doc/guides/nics/tap.rst b/doc/guides/nics/tap.rst index 27148681..9a3d7b34 100644 --- a/doc/guides/nics/tap.rst +++ b/doc/guides/nics/tap.rst @@ -152,6 +152,22 @@ Distribute IPv4 TCP packets using RSS to a given MAC address over queues 0-3:: testpmd> flow create 0 priority 4 ingress pattern eth dst is 0a:0b:0c:0d:0e:0f \ / ipv4 / tcp / end actions rss queues 0 1 2 3 end / end +Multi-process sharing +--------------------- + +It is possible to attach an existing TAP device in a secondary process, +by declaring it as a vdev with the same name as in the primary process, +and without any parameter. + +The port attached in a secondary process will give access to the +statistics and the queues. +Therefore it can be used for monitoring or Rx/Tx processing. + +The IPC synchronization of Rx/Tx queues is currently limited: + + - Maximum 8 queues shared + - Synchronized on probing, but not on later port update + Example ------- diff --git a/doc/guides/nics/vhost.rst b/doc/guides/nics/vhost.rst index 4f7ae899..23f2e87a 100644 --- a/doc/guides/nics/vhost.rst +++ b/doc/guides/nics/vhost.rst @@ -71,6 +71,11 @@ The user can specify below arguments in `--vdev` option. It is used to enable iommu support in vhost library. (Default: 0 (disabled)) +#. ``postcopy-support``: + + It is used to enable postcopy live-migration support in vhost library. + (Default: 0 (disabled)) + Vhost PMD event handling ------------------------ diff --git a/doc/guides/nics/virtio.rst b/doc/guides/nics/virtio.rst index 7c099fb7..2ae875cb 100644 --- a/doc/guides/nics/virtio.rst +++ b/doc/guides/nics/virtio.rst @@ -47,7 +47,7 @@ In this release, the virtio PMD driver provides the basic functionality of packe * The descriptor number for the Rx/Tx queue is hard-coded to be 256 by qemu 2.7 and below. If given a different descriptor number by the upper application, the virtio PMD generates a warning and fall back to the hard-coded value. - Rx queue size can be configureable and up to 1024 since qemu 2.8 and above. Rx queue size is 256 + Rx queue size can be configurable and up to 1024 since qemu 2.8 and above. Rx queue size is 256 by default. Tx queue size is still hard-coded to be 256. * Features of mac/vlan filter are supported, negotiation with vhost/backend are needed to support them. |
