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    policer_enable = <policer_enable>
 153    token_unit = <token_unit>
 154    color = <color_mode>
 155    cir = <cir>
 156    ebs = <ebs>
 157    cbs = <cbs>
 158
 159    rate_limit_enable = <rate_limit_enable>
 160    rate_limit = <rate_limit>
 161    burst_size = <burst_size>
 162
 163    [port <portnum> tc <traffic_class>]
 164    rxq = <rx_queue_list>
 165    pcp = <pcp_list>
 166    dscp = <dscp_list>
 167    default_color = <default_color>
 168
 169    [port <portnum> tc <traffic_class>]
 170    rxq = <rx_queue_list>
 171    pcp = <pcp_list>
 172    dscp = <dscp_list>
 173
 174    [port <portnum> txq <txqnum>]
 175    sched_mode = <sched_mode>
 176    wrr_weight = <wrr_weight>
 177
 178    rate_limit_enable = <rate_limit_enable>
 179    rate_limit = <rate_limit>
 180    burst_size = <burst_size>
 181
 182 Where:
 183
 184 - ``<portnum>``: DPDK Port number (0..n).
 185
 186 - ``<default_tc>``: Default traffic class (e.g. 0)
 187
 188 - ``<mapping_priority>``: QoS priority for mapping (`ip`, `vlan`, `ip/vlan` or `vlan/ip`).
 189
 190 - ``<traffic_class>``: Traffic Class to be configured.
 191
 192 - ``<rx_queue_list>``: List of DPDK RX queues (e.g. 0 1 3-4)
 193
 194 - ``<pcp_list>``: List of PCP values to handle in particular TC (e.g. 0 1 3-4 7).
 195
 196 - ``<dscp_list>``: List of DSCP values to handle in particular TC (e.g. 0-12 32-48 63).
 197
 198 - ``<policer_enable>``: Enable ingress policer.
 199
 200 - ``<token_unit>``: Policer token unit (`bytes` or `packets`).
 201
 202 - ``<color_mode>``: Policer color mode (`aware` or `blind`).
 203
 204 - ``<cir>``: Committed information rate in unit of kilo bits per second (data rate) or packets per second.
 205
 206 - ``<cbs>``: Committed burst size in unit of kilo bytes or number of packets.
 207
 208 - ``<ebs>``: Excess burst size in unit of kilo bytes or number of packets.
 209
 210 - ``<default_color>``: Default color for specific tc.
 211
 212 - ``<rate_limit_enable>``: Enables per port or per txq rate limiting.
 213
 214 - ``<rate_limit>``: Committed information rate, in kilo bits per second.
 215
 216 - ``<burst_size>``: Committed burst size, in kilo bytes.
 217
 218 - ``<sched_mode>``: Egress scheduler mode (`wrr` or `sp`).
 219
 220 - ``<wrr_weight>``: Txq weight.
 221
 222 Setting PCP/DSCP values for the default TC is not required. All PCP/DSCP
 223 values not assigned explicitly to particular TC will be handled by the
 224 default TC.
 225
 226 Configuration file example
 227 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 228
 229 .. code-block:: console
 230
 231    [port 0 default]
 232    default_tc = 0
 233    mapping_priority = ip
 234
 235    rate_limit_enable = 1
 236    rate_limit = 1000
 237    burst_size = 2000
 238
 239    [port 0 tc 0]
 240    rxq = 0 1
 241
 242    [port 0 txq 0]
 243    sched_mode = wrr
 244    wrr_weight = 10
 245
 246    [port 0 txq 1]
 247    sched_mode = wrr
 248    wrr_weight = 100
 249
 250    [port 0 txq 2]
 251    sched_mode = sp
 252
 253    [port 0 tc 1]
 254    rxq = 2
 255    pcp = 5 6 7
 256    dscp = 26-38
 257
 258    [port 1 default]
 259    default_tc = 0
 260    mapping_priority = vlan/ip
 261
 262    policer_enable = 1
 263    token_unit = bytes
 264    color = blind
 265    cir = 100000
 266    ebs = 64
 267    cbs = 64
 268
 269    [port 1 tc 0]
 270    rxq = 0
 271    dscp = 10
 272
 273    [port 1 tc 1]
 274    rxq = 1
 275    dscp = 11-20
 276
 277    [port 1 tc 2]
 278    rxq = 2
 279    dscp = 30
 280
 281    [port 1 txq 0]
 282    rate_limit_enable = 1
 283    rate_limit = 10000
 284    burst_size = 2000
 285
 286 Usage example
 287 ^^^^^^^^^^^^^
 288
 289 .. code-block:: console
 290
 291    ./testpmd --vdev=eth_mrvl,iface=eth0,iface=eth2,cfg=/home/user/mrvl.conf \
 292      -c 7 -- -i -a --disable-hw-vlan-strip --rxq=3 --txq=3
 293
 294
 295 Building DPDK
 296 -------------
 297
 298 Driver needs precompiled MUSDK library during compilation.
 299
 300 .. code-block:: console
 301
 302    export CROSS_COMPILE=<toolchain>/bin/aarch64-linux-gnu-
 303    ./bootstrap
 304    ./configure --host=aarch64-linux-gnu --enable-bpool-dma=64
 305    make install
 306
 307 MUSDK will be installed to `usr/local` under current directory.
 308 For the detailed build instructions please consult ``doc/musdk_get_started.txt``.
 309
 310 Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with
 311 the path to the MUSDK installation directory needs to be exported.
 312
 313 .. code-block:: console
 314
 315    export LIBMUSDK_PATH=<musdk>/usr/local
 316    export CROSS=aarch64-linux-gnu-
 317    make config T=arm64-armv8a-linuxapp-gcc
 318    sed -ri 's,(MRVL_PMD=)n,\1y,' build/.config
 319    make
 320
 321 Usage Example
 322 -------------
 323
 324 MRVL PMD requires extra out of tree kernel modules to function properly.
 325 `musdk_uio` and `mv_pp_uio` sources are part of the MUSDK. Please consult
 326 ``doc/musdk_get_started.txt`` for the detailed build instructions.
 327 For `mvpp2x_sysfs` please consult ``Documentation/pp22_sysfs.txt`` for the
 328 detailed build instructions.
 329
 330 .. code-block:: console
 331
 332    insmod musdk_uio.ko
 333    insmod mv_pp_uio.ko
 334    insmod mvpp2x_sysfs.ko
 335
 336 Additionally interfaces used by DPDK application need to be put up:
 337
 338 .. code-block:: console
 339
 340    ip link set eth0 up
 341    ip link set eth2 up
 342
 343 In order to run testpmd example application following command can be used:
 344
 345 .. code-block:: console
 346
 347    ./testpmd --vdev=eth_mrvl,iface=eth0,iface=eth2 -c 7 -- \
 348      --burst=128 --txd=2048 --rxd=1024 --rxq=2 --txq=2  --nb-cores=2 \
 349      -i -a --rss-udp