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   To get better understanding of the library one can consult documentation
 117   available in the ``doc`` top level directory of the MUSDK sources.
 118
 119   MUSDK must be configured with the following features:
 120
 121   .. code-block:: console
 122
 123      --enable-bpool-dma=64
 124
 125 - DPDK environment
 126
 127   Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup
 128   DPDK environment.
 129
 130
 131 Config File Options
 132 -------------------
 133
 134 The following options can be modified in the ``config`` file.
 135
 136 - ``CONFIG_RTE_LIBRTE_MRVL_PMD`` (default ``n``)
 137
 138     Toggle compilation of the librte_pmd_mrvl driver.
 139
 140
 141 QoS Configuration
 142 -----------------
 143
 144 QoS configuration is done through external configuration file. Path to the
 145 file must be given as `cfg` in driver's vdev parameter list.
 146
 147 Configuration syntax
 148 ~~~~~~~~~~~~~~~~~~~~
 149
 150 .. code-block:: console
 151
 152    [port <portnum> default]
 153    default_tc = <default_tc>
 154    mapping_priority = <mapping_priority>
 155    policer_enable = <policer_enable>
 156    token_unit = <token_unit>
 157    color = <color_mode>
 158    cir = <cir>
 159    ebs = <ebs>
 160    cbs = <cbs>
 161
 162    rate_limit_enable = <rate_limit_enable>
 163    rate_limit = <rate_limit>
 164    burst_size = <burst_size>
 165
 166    [port <portnum> tc <traffic_class>]
 167    rxq = <rx_queue_list>
 168    pcp = <pcp_list>
 169    dscp = <dscp_list>
 170    default_color = <default_color>
 171
 172    [port <portnum> tc <traffic_class>]
 173    rxq = <rx_queue_list>
 174    pcp = <pcp_list>
 175    dscp = <dscp_list>
 176
 177    [port <portnum> txq <txqnum>]
 178    sched_mode = <sched_mode>
 179    wrr_weight = <wrr_weight>
 180
 181    rate_limit_enable = <rate_limit_enable>
 182    rate_limit = <rate_limit>
 183    burst_size = <burst_size>
 184
 185 Where:
 186
 187 - ``<portnum>``: DPDK Port number (0..n).
 188
 189 - ``<default_tc>``: Default traffic class (e.g. 0)
 190
 191 - ``<mapping_priority>``: QoS priority for mapping (`ip`, `vlan`, `ip/vlan` or `vlan/ip`).
 192
 193 - ``<traffic_class>``: Traffic Class to be configured.
 194
 195 - ``<rx_queue_list>``: List of DPDK RX queues (e.g. 0 1 3-4)
 196
 197 - ``<pcp_list>``: List of PCP values to handle in particular TC (e.g. 0 1 3-4 7).
 198
 199 - ``<dscp_list>``: List of DSCP values to handle in particular TC (e.g. 0-12 32-48 63).
 200
 201 - ``<policer_enable>``: Enable ingress policer.
 202
 203 - ``<token_unit>``: Policer token unit (`bytes` or `packets`).
 204
 205 - ``<color_mode>``: Policer color mode (`aware` or `blind`).
 206
 207 - ``<cir>``: Committed information rate in unit of kilo bits per second (data rate) or packets per second.
 208
 209 - ``<cbs>``: Committed burst size in unit of kilo bytes or number of packets.
 210
 211 - ``<ebs>``: Excess burst size in unit of kilo bytes or number of packets.
 212
 213 - ``<default_color>``: Default color for specific tc.
 214
 215 - ``<rate_limit_enable>``: Enables per port or per txq rate limiting.
 216
 217 - ``<rate_limit>``: Committed information rate, in kilo bits per second.
 218
 219 - ``<burst_size>``: Committed burst size, in kilo bytes.
 220
 221 - ``<sched_mode>``: Egress scheduler mode (`wrr` or `sp`).
 222
 223 - ``<wrr_weight>``: Txq weight.
 224
 225 Setting PCP/DSCP values for the default TC is not required. All PCP/DSCP
 226 values not assigned explicitly to particular TC will be handled by the
 227 default TC.
 228
 229 Configuration file example
 230 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 231
 232 .. code-block:: console
 233
 234    [port 0 default]
 235    default_tc = 0
 236    mapping_priority = ip
 237
 238    rate_limit_enable = 1
 239    rate_limit = 1000
 240    burst_size = 2000
 241
 242    [port 0 tc 0]
 243    rxq = 0 1
 244
 245    [port 0 txq 0]
 246    sched_mode = wrr
 247    wrr_weight = 10
 248
 249    [port 0 txq 1]
 250    sched_mode = wrr
 251    wrr_weight = 100
 252
 253    [port 0 txq 2]
 254    sched_mode = sp
 255
 256    [port 0 tc 1]
 257    rxq = 2
 258    pcp = 5 6 7
 259    dscp = 26-38
 260
 261    [port 1 default]
 262    default_tc = 0
 263    mapping_priority = vlan/ip
 264
 265    policer_enable = 1
 266    token_unit = bytes
 267    color = blind
 268    cir = 100000
 269    ebs = 64
 270    cbs = 64
 271
 272    [port 1 tc 0]
 273    rxq = 0
 274    dscp = 10
 275
 276    [port 1 tc 1]
 277    rxq = 1
 278    dscp = 11-20
 279
 280    [port 1 tc 2]
 281    rxq = 2
 282    dscp = 30
 283
 284    [port 1 txq 0]
 285    rate_limit_enable = 1
 286    rate_limit = 10000
 287    burst_size = 2000
 288
 289 Usage example
 290 ^^^^^^^^^^^^^
 291
 292 .. code-block:: console
 293
 294    ./testpmd --vdev=eth_mrvl,iface=eth0,iface=eth2,cfg=/home/user/mrvl.conf \
 295      -c 7 -- -i -a --disable-hw-vlan-strip --rxq=3 --txq=3
 296
 297
 298 Building DPDK
 299 -------------
 300
 301 Driver needs precompiled MUSDK library during compilation.
 302
 303 .. code-block:: console
 304
 305    export CROSS_COMPILE=<toolchain>/bin/aarch64-linux-gnu-
 306    ./bootstrap
 307    ./configure --host=aarch64-linux-gnu --enable-bpool-dma=64
 308    make install
 309
 310 MUSDK will be installed to `usr/local` under current directory.
 311 For the detailed build instructions please consult ``doc/musdk_get_started.txt``.
 312
 313 Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with
 314 the path to the MUSDK installation directory needs to be exported.
 315
 316 .. code-block:: console
 317
 318    export LIBMUSDK_PATH=<musdk>/usr/local
 319    export CROSS=aarch64-linux-gnu-
 320    make config T=arm64-armv8a-linuxapp-gcc
 321    sed -ri 's,(MRVL_PMD=)n,\1y,' build/.config
 322    make
 323
 324 Flow API
 325 --------
 326
 327 PPv2 offers packet classification capabilities via classifier engine which
 328 can be configured via generic flow API offered by DPDK.
 329
 330 Supported flow actions
 331 ~~~~~~~~~~~~~~~~~~~~~~
 332
 333 Following flow action items are supported by the driver:
 334
 335 * DROP
 336 * QUEUE
 337
 338 Supported flow items
 339 ~~~~~~~~~~~~~~~~~~~~
 340
 341 Following flow items and their respective fields are supported by the driver:
 342
 343 * ETH
 344
 345   * source MAC
 346   * destination MAC
 347   * ethertype
 348
 349 * VLAN
 350
 351   * PCP
 352   * VID
 353
 354 * IPV4
 355
 356   * DSCP
 357   * protocol
 358   * source address
 359   * destination address
 360
 361 * IPV6
 362
 363   * flow label
 364   * next header
 365   * source address
 366   * destination address
 367
 368 * UDP
 369
 370   * source port
 371   * destination port
 372
 373 * TCP
 374
 375   * source port
 376   * destination port
 377
 378 Classifier match engine
 379 ~~~~~~~~~~~~~~~~~~~~~~~
 380
 381 Classifier has an internal match engine which can be configured to
 382 operate in either exact or maskable mode.
 383
 384 Mode is selected upon creation of the first unique flow rule as follows:
 385
 386 * maskable, if key size is up to 8 bytes.
 387 * exact, otherwise, i.e for keys bigger than 8 bytes.
 388
 389 Where the key size equals the number of bytes of all fields specified
 390 in the flow items.
 391
 392 .. table:: Examples of key size calculation
 393
 394    +----------------------------------------------------------------------------+-------------------+-------------+
 395    | Flow pattern                                                               | Key size in bytes | Used engine |
 396    +============================================================================+===================+=============+
 397    | ETH (destination MAC) / VLAN (VID)                                         | 6 + 2 = 8         | Maskable    |
 398    +----------------------------------------------------------------------------+-------------------+-------------+
 399    | VLAN (VID) / IPV4 (source address)                                         | 2 + 4 = 6         | Maskable    |
 400    +----------------------------------------------------------------------------+-------------------+-------------+
 401    | TCP (source port, destination port)                                        | 2 + 2 = 4         | Maskable    |
 402    +----------------------------------------------------------------------------+-------------------+-------------+
 403    | VLAN (priority) / IPV4 (source address)                                    | 1 + 4 = 5         | Maskable    |
 404    +----------------------------------------------------------------------------+-------------------+-------------+
 405    | IPV4 (destination address) / UDP (source port, destination port)           | 6 + 2 + 2 = 10    | Exact       |
 406    +----------------------------------------------------------------------------+-------------------+-------------+
 407    | VLAN (VID) / IPV6 (flow label, destination address)                        | 2 + 3 + 16 = 21   | Exact       |
 408    +----------------------------------------------------------------------------+-------------------+-------------+
 409    | IPV4 (DSCP, source address, destination address)                           | 1 + 4 + 4 = 9     | Exact       |
 410    +----------------------------------------------------------------------------+-------------------+-------------+
 411    | IPV6 (flow label, source address, destination address)                     | 3 + 16 + 16 = 35  | Exact       |
 412    +----------------------------------------------------------------------------+-------------------+-------------+
 413
 414 From the user perspective maskable mode means that masks specified
 415 via flow rules are respected. In case of exact match mode, masks
 416 which do not provide exact matching (all bits masked) are ignored.
 417
 418 If the flow matches more than one classifier rule the first
 419 (with the lowest index) matched takes precedence.
 420
 421 Flow rules usage example
 422 ~~~~~~~~~~~~~~~~~~~~~~~~
 423
 424 Before proceeding run testpmd user application:
 425
 426 .. code-block:: console
 427
 428    ./testpmd --vdev=net_mrvl,iface=eth0,iface=eth2 -c 3 -- -i --p 3 -a --disable-hw-vlan-strip
 429
 430 Example #1
 431 ^^^^^^^^^^
 432
 433 .. code-block:: console
 434
 435    testpmd> flow create 0 ingress pattern eth src is 10:11:12:13:14:15 / end actions drop / end
 436
 437 In this case key size is 6 bytes thus maskable type is selected. Testpmd
 438 will set mask to ff:ff:ff:ff:ff:ff i.e traffic explicitly matching
 439 above rule will be dropped.
 440
 441 Example #2
 442 ^^^^^^^^^^
 443
 444 .. code-block:: console
 445
 446    testpmd> flow create 0 ingress pattern ipv4 src spec 10.10.10.0 src mask 255.255.255.0 / tcp src spec 0x10 src mask 0x10 / end action drop / end
 447
 448 In this case key size is 8 bytes thus maskable type is selected.
 449 Flows which have IPv4 source addresses ranging from 10.10.10.0 to 10.10.10.255
 450 and tcp source port set to 16 will be dropped.
 451
 452 Example #3
 453 ^^^^^^^^^^
 454
 455 .. code-block:: console
 456
 457    testpmd> flow create 0 ingress pattern vlan vid spec 0x10 vid mask 0x10 / ipv4 src spec 10.10.1.1 src mask 255.255.0.0 dst spec 11.11.11.1 dst mask 255.255.255.0 / end actions drop / end
 458
 459 In this case key size is 10 bytes thus exact type is selected.
 460 Even though each item has partial mask set, masks will be ignored.
 461 As a result only flows with VID set to 16 and IPv4 source and destination
 462 addresses set to 10.10.1.1 and 11.11.11.1 respectively will be dropped.
 463
 464 Limitations
 465 ~~~~~~~~~~~
 466
 467 Following limitations need to be taken into account while creating flow rules:
 468
 469 * For IPv4 exact match type the key size must be up to 12 bytes.
 470 * For IPv6 exact match type the key size must be up to 36 bytes.
 471 * Following fields cannot be partially masked (all masks are treated as
 472   if they were exact):
 473
 474   * ETH: ethertype
 475   * VLAN: PCP, VID
 476   * IPv4: protocol
 477   * IPv6: next header
 478   * TCP/UDP: source port, destination port
 479
 480 * Only one classifier table can be created thus all rules in the table
 481   have to match table format. Table format is set during creation of
 482   the first unique flow rule.
 483 * Up to 5 fields can be specified per flow rule.
 484 * Up to 20 flow rules can be added.
 485
 486 For additional information about classifier please consult
 487 ``doc/musdk_cls_user_guide.txt``.
 488
 489 Usage Example
 490 -------------
 491
 492 MRVL PMD requires extra out of tree kernel modules to function properly.
 493 `musdk_uio` and `mv_pp_uio` sources are part of the MUSDK. Please consult
 494 ``doc/musdk_get_started.txt`` for the detailed build instructions.
 495 For `mvpp2x_sysfs` please consult ``Documentation/pp22_sysfs.txt`` for the
 496 detailed build instructions.
 497
 498 .. code-block:: console
 499
 500    insmod musdk_uio.ko
 501    insmod mv_pp_uio.ko
 502    insmod mvpp2x_sysfs.ko
 503
 504 Additionally interfaces used by DPDK application need to be put up:
 505
 506 .. code-block:: console
 507
 508    ip link set eth0 up
 509    ip link set eth2 up
 510
 511 In order to run testpmd example application following command can be used:
 512
 513 .. code-block:: console
 514
 515    ./testpmd --vdev=eth_mrvl,iface=eth0,iface=eth2 -c 7 -- \
 516      --burst=128 --txd=2048 --rxd=1024 --rxq=2 --txq=2  --nb-cores=2 \
 517      -i -a --rss-udp