doc/guides/nics/mvneta.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018 Marvell International Ltd.
   3     Copyright(c) 2018 Semihalf.
   4     All rights reserved.
   5
   6 MVNETA Poll Mode Driver
   7 =======================
   8
   9 The MVNETA PMD (librte_pmd_mvneta) provides poll mode driver support
  10 for the Marvell NETA 1/2.5 Gbps adapter.
  11
  12 Detailed information about SoCs that use PPv2 can be obtained here:
  13
  14 * https://www.marvell.com/embedded-processors/armada-3700/
  15
  16 .. Note::
  17
  18    Due to external dependencies, this driver is disabled by default. It must
  19    be enabled manually by setting relevant configuration option manually.
  20    Please refer to `Config File Options`_ section for further details.
  21
  22
  23 Features
  24 --------
  25
  26 Features of the MVNETA PMD are:
  27
  28 - Start/stop
  29 - tx/rx_queue_setup
  30 - tx/rx_burst
  31 - Speed capabilities
  32 - Jumbo frame
  33 - MTU update
  34 - Promiscuous mode
  35 - Unicast MAC filter
  36 - Link status
  37 - CRC offload
  38 - L3 checksum offload
  39 - L4 checksum offload
  40 - Packet type parsing
  41 - Basic stats
  42
  43
  44 Limitations
  45 -----------
  46
  47 - Flushing vlans added for filtering is not possible due to MUSDK missing
  48   functionality. Current workaround is to reset board so that NETA has a
  49   chance to start in a sane state.
  50
  51 Prerequisites
  52 -------------
  53
  54 - Custom Linux Kernel sources
  55
  56   .. code-block:: console
  57
  58      git clone https://github.com/MarvellEmbeddedProcessors/linux-marvell.git -b linux-4.4.120-armada-18.09
  59
  60
  61 - MUSDK (Marvell User-Space SDK) sources
  62
  63   .. code-block:: console
  64
  65      git clone https://github.com/MarvellEmbeddedProcessors/musdk-marvell.git -b musdk-armada-18.09
  66
  67   MUSDK is a light-weight library that provides direct access to Marvell's
  68   NETA. Alternatively prebuilt MUSDK library can be
  69   requested from `Marvell Extranet <https://extranet.marvell.com>`_. Once
  70   approval has been granted, library can be found by typing ``musdk`` in
  71   the search box.
  72
  73   MUSDK must be configured with the following features:
  74
  75   .. code-block:: console
  76
  77      --enable-pp2=no --enable-neta
  78
  79 - DPDK environment
  80
  81   Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup
  82   DPDK environment.
  83
  84 Pre-Installation Configuration
  85 ------------------------------
  86
  87 Config File Options
  88 ~~~~~~~~~~~~~~~~~~~
  89
  90 The following options can be modified in the ``config`` file.
  91
  92 - ``CONFIG_RTE_LIBRTE_MVNETA_PMD`` (default ``n``)
  93
  94     Toggle compilation of the librte_pmd_mvneta driver.
  95
  96 Runtime options
  97 ~~~~~~~~~~~~~~~
  98
  99 The following ``devargs`` options can be enabled at runtime. They must
 100 be passed as part of EAL arguments.
 101
 102 - ``iface`` (mandatory, with no default value)
 103
 104   The name of port (owned by MUSDK) that should be enabled in DPDK.
 105   This options can be repeated resulting in a list of ports to be
 106   enabled.  For instance below will enable ``eth0`` and ``eth1`` ports.
 107
 108 .. code-block:: console
 109
 110    ./testpmd --vdev=net_mvneta,iface=eth0,iface=eth1 \
 111     -c 3 -- -i --p 3 -a
 112
 113
 114 Building DPDK
 115 -------------
 116
 117 Driver needs precompiled MUSDK library during compilation.
 118
 119 .. code-block:: console
 120
 121    export CROSS_COMPILE=<toolchain>/bin/aarch64-linux-gnu-
 122    ./bootstrap
 123    ./configure --host=aarch64-linux-gnu --enable-pp2=no --enable-neta
 124    make install
 125
 126 MUSDK will be installed to `usr/local` under current directory.
 127 For the detailed build instructions please consult ``doc/musdk_get_started.txt``.
 128
 129 Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with
 130 the path to the MUSDK installation directory needs to be exported.
 131
 132 .. code-block:: console
 133
 134    export LIBMUSDK_PATH=<musdk>/usr/local
 135    export CROSS=aarch64-linux-gnu-
 136    make config T=arm64-armv8a-linux-gcc
 137    sed -ri 's,(MVNETA_PMD=)n,\1y,' build/.config
 138    make
 139
 140 Usage Example
 141 -------------
 142
 143 MVNETA PMD requires extra out of tree kernel modules to function properly.
 144 `musdk_uio` and `mv_neta_uio` sources are part of the MUSDK. Please consult
 145 ``doc/musdk_get_started.txt`` for the detailed build instructions.
 146
 147 .. code-block:: console
 148
 149    insmod musdk_uio.ko
 150    insmod mv_neta_uio.ko
 151
 152 Additionally interfaces used by DPDK application need to be put up:
 153
 154 .. code-block:: console
 155
 156    ip link set eth0 up
 157    ip link set eth1 up
 158
 159 In order to run testpmd example application following command can be used:
 160
 161 .. code-block:: console
 162
 163    ./testpmd --vdev=net_mvneta,iface=eth0,iface=eth1 -c 3 -- \
 164      -i --p 3 -a --txd 256 --rxd 128 --rxq=1 --txq=1  --nb-cores=1
 165
 166
 167 In order to run l2fwd example application following command can be used:
 168
 169 .. code-block:: console
 170
 171    ./l2fwd --vdev=net_mvneta,iface=eth0,iface=eth1 -c 3 -- -T 1 -p 3