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 available
  91   `here <https://github.com/MarvellEmbeddedProcessors/linux-marvell/tree/linux-4.4.52-armada-17.08>`__.
  92
  93 - Out of tree `mvpp2x_sysfs` kernel module sources available
  94   `here <https://github.com/MarvellEmbeddedProcessors/mvpp2x-marvell/tree/mvpp2x-armada-17.08>`__.
  95
  96 - MUSDK (Marvell User-Space SDK) sources available
  97   `here <https://github.com/MarvellEmbeddedProcessors/musdk-marvell/tree/musdk-armada-17.08>`__.
  98
  99     MUSDK is a light-weight library that provides direct access to Marvell's
 100     PPv2 (Packet Processor v2). Alternatively prebuilt MUSDK library can be
 101     requested from `Marvell Extranet <https://extranet.marvell.com>`_. Once
 102     approval has been granted, library can be found by typing ``musdk`` in
 103     the search box.
 104
 105     MUSDK must be configured with the following features:
 106
 107     .. code-block:: console
 108
 109        --enable-bpool-dma=64
 110
 111 - DPDK environment
 112
 113     Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup
 114     DPDK environment.
 115
 116
 117 Config File Options
 118 -------------------
 119
 120 The following options can be modified in the ``config`` file.
 121
 122 - ``CONFIG_RTE_LIBRTE_MRVL_PMD`` (default ``n``)
 123
 124     Toggle compilation of the librte_pmd_mrvl driver.
 125
 126 - ``CONFIG_RTE_MRVL_MUSDK_DMA_MEMSIZE`` (default ``41943040``)
 127
 128     Size in bytes of the contiguous memory region that MUSDK will allocate
 129     for run-time DMA-able data buffers.
 130
 131
 132 QoS Configuration
 133 -----------------
 134
 135 QoS configuration is done through external configuration file. Path to the
 136 file must be given as `cfg` in driver's vdev parameter list.
 137
 138 Configuration syntax
 139 ~~~~~~~~~~~~~~~~~~~~
 140
 141 .. code-block:: console
 142
 143    [port <portnum> default]
 144    default_tc = <default_tc>
 145    qos_mode = <qos_priority>
 146
 147    [port <portnum> tc <traffic_class>]
 148    rxq = <rx_queue_list>
 149    pcp = <pcp_list>
 150    dscp = <dscp_list>
 151
 152    [port <portnum> tc <traffic_class>]
 153    rxq = <rx_queue_list>
 154    pcp = <pcp_list>
 155    dscp = <dscp_list>
 156
 157 Where:
 158
 159 - ``<portnum>``: DPDK Port number (0..n).
 160
 161 - ``<default_tc>``: Default traffic class (e.g. 0)
 162
 163 - ``<qos_priority>``: QoS priority for mapping (`ip`, `vlan`, `ip/vlan` or `vlan/ip`).
 164
 165 - ``<traffic_class>``: Traffic Class to be configured.
 166
 167 - ``<rx_queue_list>``: List of DPDK RX queues (e.g. 0 1 3-4)
 168
 169 - ``<pcp_list>``: List of PCP values to handle in particular TC (e.g. 0 1 3-4 7).
 170
 171 - ``<dscp_list>``: List of DSCP values to handle in particular TC (e.g. 0-12 32-48 63).
 172
 173 Setting PCP/DSCP values for the default TC is not required. All PCP/DSCP
 174 values not assigned explicitly to particular TC will be handled by the
 175 default TC.
 176
 177 Configuration file example
 178 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 179
 180 .. code-block:: console
 181
 182    [port 0 default]
 183    default_tc = 0
 184    qos_mode = ip
 185
 186    [port 0 tc 0]
 187    rxq = 0 1
 188
 189    [port 0 tc 1]
 190    rxq = 2
 191    pcp = 5 6 7
 192    dscp = 26-38
 193
 194    [port 1 default]
 195    default_tc = 0
 196    qos_mode = vlan/ip
 197
 198    [port 1 tc 0]
 199    rxq = 0
 200
 201    [port 1 tc 1]
 202    rxq = 1 2
 203    pcp = 5 6 7
 204    dscp = 26-38
 205
 206 Usage example
 207 ^^^^^^^^^^^^^
 208
 209 .. code-block:: console
 210
 211    ./testpmd --vdev=eth_mrvl,iface=eth0,iface=eth2,cfg=/home/user/mrvl.conf \
 212      -c 7 -- -i -a --disable-hw-vlan-strip --rxq=2
 213
 214
 215 Building DPDK
 216 -------------
 217
 218 Driver needs precompiled MUSDK library during compilation. Please consult
 219 ``doc/musdk_get_started.txt`` for the detailed build instructions.
 220
 221 Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with
 222 the path to the MUSDK installation directory needs to be exported.
 223
 224
 225 Usage Example
 226 -------------
 227
 228 MRVL PMD requires extra out of tree kernel modules to function properly.
 229 `musdk_uio` and `mv_pp_uio` sources are part of the MUSDK. Please consult
 230 ``doc/musdk_get_started.txt`` for the detailed build instructions.
 231 For `mvpp2x_sysfs` please consult ``Documentation/pp22_sysfs.txt`` for the
 232 detailed build instructions.
 233
 234 .. code-block:: console
 235
 236    insmod musdk_uio.ko
 237    insmod mv_pp_uio.ko
 238    insmod mvpp2x_sysfs.ko
 239
 240 Additionally interfaces used by DPDK application need to be put up:
 241
 242 .. code-block:: console
 243
 244    ip link set eth0 up
 245    ip link set eth1 up
 246
 247 In order to run testpmd example application following command can be used:
 248
 249 .. code-block:: console
 250
 251    ./testpmd --vdev=eth_mrvl,iface=eth0,iface=eth2 -c 7 -- \
 252      --burst=128 --txd=2048 --rxd=1024 --rxq=2 --txq=2  --nb-cores=2 \
 253      -i -a --disable-hw-vlan-strip --rss-udp