doc/guides/nics/mrvl.rst

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