From: Tomasz Duszynski Date: Mon, 9 Oct 2017 15:00:44 +0000 (+0200) Subject: doc: add mrvl NIC guide X-Git-Tag: spdx-start~1482 X-Git-Url: http://git.droids-corp.org/?a=commitdiff_plain;h=1a286a1139f287d67a81cbc20e72abf14589b6e6;p=dpdk.git doc: add mrvl NIC guide Add documentation for the MRVL NET PMD driver. Signed-off-by: Jacek Siuda Signed-off-by: Tomasz Duszynski --- diff --git a/MAINTAINERS b/MAINTAINERS index 0e2377452b..65a931c4dc 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -408,6 +408,8 @@ M: Dmitri Epshtein M: Natalie Samsonov M: Jianbo Liu F: drivers/net/mrvl/ +F: doc/guides/nics/mrvl.rst +F: doc/guides/nics/features/mrvl.ini Netcope szedata2 M: Matej Vido diff --git a/doc/guides/nics/features/mrvl.ini b/doc/guides/nics/features/mrvl.ini index 3643b8b505..00d96218b0 100644 --- a/doc/guides/nics/features/mrvl.ini +++ b/doc/guides/nics/features/mrvl.ini @@ -19,3 +19,5 @@ 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/index.rst b/doc/guides/nics/index.rst index 48d874fcbd..23babe9339 100644 --- a/doc/guides/nics/index.rst +++ b/doc/guides/nics/index.rst @@ -56,6 +56,7 @@ Network Interface Controller Drivers liquidio mlx4 mlx5 + mrvl nfp octeontx qede diff --git a/doc/guides/nics/mrvl.rst b/doc/guides/nics/mrvl.rst new file mode 100644 index 0000000000..462bc0e9d1 --- /dev/null +++ b/doc/guides/nics/mrvl.rst @@ -0,0 +1,256 @@ +.. BSD LICENSE + Copyright(c) 2017 Semihalf. 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 Semihalf 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. + +MRVL Poll Mode Driver +====================== + +The MRVL PMD (librte_pmd_mrvl) provides poll mode driver support +for the Marvell PPv2 (Packet Processor v2) 1/10 Gbps adapter. + +Detailed information about SoCs that use PPv2 can be obtained here: + +* https://www.marvell.com/embedded-processors/armada-70xx/ +* https://www.marvell.com/embedded-processors/armada-80xx/ + +.. 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 MRVL PMD are: + +- Speed capabilities +- Link status +- Queue start/stop +- MTU update +- Jumbo frame +- Promiscuous mode +- Allmulticast mode +- Unicast MAC filter +- Multicast MAC filter +- RSS hash +- VLAN filter +- CRC offload +- L3 checksum offload +- L4 checksum offload +- Packet type parsing +- Basic stats +- QoS + + +Limitations +----------- + +- Number of lcores is limited to 9 by MUSDK internal design. If more lcores + need to be allocated, locking will have to be considered. Number of available + lcores can be changed via ``MRVL_MUSDK_HIFS_RESERVED`` define in + ``mrvl_ethdev.c`` source file. + +- Flushing vlans added for filtering is not possible due to MUSDK missing + functionality. Current workaround is to reset board so that PPv2 has a + chance to start in a sane state. + + +Prerequisites +------------- + +- Custom Linux Kernel sources available + `here `__. + +- Out of tree `mvpp2x_sysfs` kernel module sources available + `here `__. + +- MUSDK (Marvell User-Space SDK) sources available + `here `__. + + MUSDK is a light-weight library that provides direct access to Marvell's + PPv2 (Packet Processor v2). Alternatively prebuilt MUSDK library can be + requested from `Marvell Extranet `_. 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-bpool-dma=64 + +- DPDK environment + + Follow the DPDK :ref:`Getting Started Guide for Linux ` to setup + DPDK environment. + + +Config File Options +------------------- + +The following options can be modified in the ``config`` file. + +- ``CONFIG_RTE_LIBRTE_MRVL_PMD`` (default ``n``) + + Toggle compilation of the librte_pmd_mrvl driver. + +- ``CONFIG_RTE_LIBRTE_MRVL_DEBUG`` (default ``n``) + + Toggle display of debugging messages. + +- ``CONFIG_RTE_MRVL_MUSDK_DMA_MEMSIZE`` (default ``41943040``) + + Size in bytes of the contiguous memory region that MUSDK will allocate + for run-time DMA-able data buffers. + + +QoS Configuration +----------------- + +QoS configuration is done through external configuration file. Path to the +file must be given as `cfg` in driver's vdev parameter list. + +Configuration syntax +~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + [port default] + default_tc = + qos_mode = + + [port tc ] + rxq = + pcp = + dscp = + + [port tc ] + rxq = + pcp = + dscp = + +Where: + +- ````: DPDK Port number (0..n). + +- ````: Default traffic class (e.g. 0) + +- ````: QoS priority for mapping (`ip`, `vlan`, `ip/vlan` or `vlan/ip`). + +- ````: Traffic Class to be configured. + +- ````: List of DPDK RX queues (e.g. 0 1 3-4) + +- ````: List of PCP values to handle in particular TC (e.g. 0 1 3-4 7). + +- ````: List of DSCP values to handle in particular TC (e.g. 0-12 32-48 63). + +Setting PCP/DSCP values for the default TC is not required. All PCP/DSCP +values not assigned explicitly to particular TC will be handled by the +default TC. + +Configuration file example +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: console + + [port 0 default] + default_tc = 0 + qos_mode = ip + + [port 0 tc 0] + rxq = 0 1 + + [port 0 tc 1] + rxq = 2 + pcp = 5 6 7 + dscp = 26-38 + + [port 1 default] + default_tc = 0 + qos_mode = vlan/ip + + [port 1 tc 0] + rxq = 0 + + [port 1 tc 1] + rxq = 1 2 + pcp = 5 6 7 + dscp = 26-38 + +Usage example +^^^^^^^^^^^^^ + +.. code-block:: console + + ./testpmd --vdev=eth_mrvl,iface=eth0,iface=eth2,cfg=/home/user/mrvl.conf \ + -c 7 -- -i -a --disable-hw-vlan-strip --rxq=2 + + +Building DPDK +------------- + +Driver needs precompiled MUSDK library during compilation. Please consult +``doc/musdk_get_started.txt`` for the detailed build instructions. + +Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with +the path to the MUSDK installation directory needs to be exported. + + +Usage Example +------------- + +MRVL 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. + +.. code-block:: console + + insmod musdk_uio.ko + insmod mv_pp_uio.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 eth1 up + +In order to run testpmd example application following command can be used: + +.. code-block:: console + + ./testpmd --vdev=eth_mrvl,iface=eth0,iface=eth2 -c 7 -- \ + --burst=128 --txd=2048 --rxd=1024 --rxq=2 --txq=2 --nb-cores=2 \ + -i -a --disable-hw-vlan-strip --rss-udp