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