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