doc/guides/nics/mrvl.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2017 Marvell International Ltd.
   3     Copyright(c) 2017 Semihalf.
   4     All rights reserved.
   5
   6     Redistribution and use in source and binary forms, with or without
   7     modification, are permitted provided that the following conditions
   8     are met:
   9
  10       * Redistributions of source code must retain the above copyright
  11         notice, this list of conditions and the following disclaimer.
  12       * Redistributions in binary form must reproduce the above copyright
  13         notice, this list of conditions and the following disclaimer in
  14         the documentation and/or other materials provided with the
  15         distribution.
  16       * Neither the name of the copyright holder nor the names of its
  17         contributors may be used to endorse or promote products derived
  18         from this software without specific prior written permission.
  19
  20     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  23     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  24     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  30     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31
  32 MRVL Poll Mode Driver
  33 ======================
  34
  35 The MRVL PMD (librte_pmd_mrvl) provides poll mode driver support
  36 for the Marvell PPv2 (Packet Processor v2) 1/10 Gbps adapter.
  37
  38 Detailed information about SoCs that use PPv2 can be obtained here:
  39
  40 * https://www.marvell.com/embedded-processors/armada-70xx/
  41 * https://www.marvell.com/embedded-processors/armada-80xx/
  42
  43 .. Note::
  44
  45    Due to external dependencies, this driver is disabled by default. It must
  46    be enabled manually by setting relevant configuration option manually.
  47    Please refer to `Config File Options`_ section for further details.
  48
  49
  50 Features
  51 --------
  52
  53 Features of the MRVL PMD are:
  54
  55 - Speed capabilities
  56 - Link status
  57 - Queue start/stop
  58 - MTU update
  59 - Jumbo frame
  60 - Promiscuous mode
  61 - Allmulticast mode
  62 - Unicast MAC filter
  63 - Multicast MAC filter
  64 - RSS hash
  65 - VLAN filter
  66 - CRC offload
  67 - L3 checksum offload
  68 - L4 checksum offload
  69 - Packet type parsing
  70 - Basic stats
  71 - QoS
  72
  73
  74 Limitations
  75 -----------
  76
  77 - Number of lcores is limited to 9 by MUSDK internal design. If more lcores
  78   need to be allocated, locking will have to be considered. Number of available
  79   lcores can be changed via ``MRVL_MUSDK_HIFS_RESERVED`` define in
  80   ``mrvl_ethdev.c`` source file.
  81
  82 - Flushing vlans added for filtering is not possible due to MUSDK missing
  83   functionality. Current workaround is to reset board so that PPv2 has a
  84   chance to start in a sane state.
  85
  86
  87 Prerequisites
  88 -------------
  89
  90 - Custom Linux Kernel sources
  91
  92   .. code-block:: console
  93
  94      git clone https://github.com/MarvellEmbeddedProcessors/linux-marvell.git -b linux-4.4.52-armada-17.10
  95
  96 - Out of tree `mvpp2x_sysfs` kernel module sources
  97
  98   .. code-block:: console
  99
 100      git clone https://github.com/MarvellEmbeddedProcessors/mvpp2x-marvell.git -b mvpp2x-armada-17.10
 101
 102 - MUSDK (Marvell User-Space SDK) sources
 103
 104   .. code-block:: console
 105
 106      git clone https://github.com/MarvellEmbeddedProcessors/musdk-marvell.git -b musdk-armada-17.10
 107
 108   MUSDK is a light-weight library that provides direct access to Marvell's
 109   PPv2 (Packet Processor v2). Alternatively prebuilt MUSDK library can be
 110   requested from `Marvell Extranet <https://extranet.marvell.com>`_. Once
 111   approval has been granted, library can be found by typing ``musdk`` in
 112   the search box.
 113
 114   MUSDK must be configured with the following features:
 115
 116   .. code-block:: console
 117
 118      --enable-bpool-dma=64
 119
 120 - DPDK environment
 121
 122   Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup
 123   DPDK environment.
 124
 125
 126 Config File Options
 127 -------------------
 128
 129 The following options can be modified in the ``config`` file.
 130
 131 - ``CONFIG_RTE_LIBRTE_MRVL_PMD`` (default ``n``)
 132
 133     Toggle compilation of the librte_pmd_mrvl driver.
 134
 135
 136 QoS Configuration
 137 -----------------
 138
 139 QoS configuration is done through external configuration file. Path to the
 140 file must be given as `cfg` in driver's vdev parameter list.
 141
 142 Configuration syntax
 143 ~~~~~~~~~~~~~~~~~~~~
 144
 145 .. code-block:: console
 146
 147    [port <portnum> default]
 148    default_tc = <default_tc>
 149    mapping_priority = <mapping_priority>
 150
 151    [port <portnum> tc <traffic_class>]
 152    rxq = <rx_queue_list>
 153    pcp = <pcp_list>
 154    dscp = <dscp_list>
 155
 156    [port <portnum> tc <traffic_class>]
 157    rxq = <rx_queue_list>
 158    pcp = <pcp_list>
 159    dscp = <dscp_list>
 160
 161 Where:
 162
 163 - ``<portnum>``: DPDK Port number (0..n).
 164
 165 - ``<default_tc>``: Default traffic class (e.g. 0)
 166
 167 - ``<mapping_priority>``: QoS priority for mapping (`ip`, `vlan`, `ip/vlan` or `vlan/ip`).
 168
 169 - ``<traffic_class>``: Traffic Class to be configured.
 170
 171 - ``<rx_queue_list>``: List of DPDK RX queues (e.g. 0 1 3-4)
 172
 173 - ``<pcp_list>``: List of PCP values to handle in particular TC (e.g. 0 1 3-4 7).
 174
 175 - ``<dscp_list>``: List of DSCP values to handle in particular TC (e.g. 0-12 32-48 63).
 176
 177 Setting PCP/DSCP values for the default TC is not required. All PCP/DSCP
 178 values not assigned explicitly to particular TC will be handled by the
 179 default TC.
 180
 181 Configuration file example
 182 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 183
 184 .. code-block:: console
 185
 186    [port 0 default]
 187    default_tc = 0
 188    qos_mode = ip
 189
 190    [port 0 tc 0]
 191    rxq = 0 1
 192
 193    [port 0 tc 1]
 194    rxq = 2
 195    pcp = 5 6 7
 196    dscp = 26-38
 197
 198    [port 1 default]
 199    default_tc = 0
 200    qos_mode = vlan/ip
 201
 202    [port 1 tc 0]
 203    rxq = 0
 204
 205    [port 1 tc 1]
 206    rxq = 1 2
 207    pcp = 5 6 7
 208    dscp = 26-38
 209
 210 Usage example
 211 ^^^^^^^^^^^^^
 212
 213 .. code-block:: console
 214
 215    ./testpmd --vdev=eth_mrvl,iface=eth0,iface=eth2,cfg=/home/user/mrvl.conf \
 216      -c 7 -- -i -a --disable-hw-vlan-strip --rxq=2
 217
 218
 219 Building DPDK
 220 -------------
 221
 222 Driver needs precompiled MUSDK library during compilation. Please consult
 223 ``doc/musdk_get_started.txt`` for the detailed build instructions.
 224
 225 .. code-block:: console
 226
 227    export CROSS_COMPILE=<toolchain>/bin/aarch64-linux-gnu-
 228    ./bootstrap
 229    ./configure --enable-bpool-dma=64
 230    make install
 231
 232 MUSDK will be installed to `usr/local` under current directory.
 233 For the detailed build instructions please consult ``doc/musdk_get_started.txt``.
 234
 235 Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with
 236 the path to the MUSDK installation directory needs to be exported.
 237
 238 .. code-block:: console
 239
 240    export LIBMUSDK_PATH=<musdk>/usr/local
 241    export CROSS=aarch64-linux-gnu-
 242    make config T=arm64-armv8a-linuxapp-gcc
 243    sed -ri 's,(MRVL_PMD=)n,\1y,' build/.config
 244    make
 245
 246 Usage Example
 247 -------------
 248
 249 MRVL PMD requires extra out of tree kernel modules to function properly.
 250 `musdk_uio` and `mv_pp_uio` sources are part of the MUSDK. Please consult
 251 ``doc/musdk_get_started.txt`` for the detailed build instructions.
 252 For `mvpp2x_sysfs` please consult ``Documentation/pp22_sysfs.txt`` for the
 253 detailed build instructions.
 254
 255 .. code-block:: console
 256
 257    insmod musdk_uio.ko
 258    insmod mv_pp_uio.ko
 259    insmod mvpp2x_sysfs.ko
 260
 261 Additionally interfaces used by DPDK application need to be put up:
 262
 263 .. code-block:: console
 264
 265    ip link set eth0 up
 266    ip link set eth2 up
 267
 268 In order to run testpmd example application following command can be used:
 269
 270 .. code-block:: console
 271
 272    ./testpmd --vdev=eth_mrvl,iface=eth0,iface=eth2 -c 7 -- \
 273      --burst=128 --txd=2048 --rxd=1024 --rxq=2 --txq=2  --nb-cores=2 \
 274      -i -a --disable-hw-vlan-strip --rss-udp