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