doc/guides/nics/dpaa2.rst

   1 ..  BSD LICENSE
   2     Copyright 2016 NXP.
   3
   4     Redistribution and use in source and binary forms, with or without
   5     modification, are permitted provided that the following conditions
   6     are met:
   7
   8     * Redistributions of source code must retain the above copyright
   9     notice, this list of conditions and the following disclaimer.
  10     * Redistributions in binary form must reproduce the above copyright
  11     notice, this list of conditions and the following disclaimer in
  12     the documentation and/or other materials provided with the
  13     distribution.
  14     * Neither the name of NXP nor the names of its
  15     contributors may be used to endorse or promote products derived
  16     from this software without specific prior written permission.
  17
  18     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29
  30 DPAA2 Poll Mode Driver
  31 ======================
  32
  33 The DPAA2 NIC PMD (**librte_pmd_dpaa2**) provides poll mode driver
  34 support for the inbuilt NIC found in the **NXP DPAA2** SoC family.
  35
  36 More information can be found at `NXP Official Website
  37 <http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/qoriq-arm-processors:QORIQ-ARM>`_.
  38
  39 NXP DPAA2 (Data Path Acceleration Architecture Gen2)
  40 ----------------------------------------------------
  41
  42 This section provides an overview of the NXP DPAA2 architecture
  43 and how it is integrated into the DPDK.
  44
  45 Contents summary
  46
  47 - DPAA2 overview
  48 - Overview of DPAA2 objects
  49 - DPAA2 driver architecture overview
  50
  51 .. _dpaa2_overview:
  52
  53 DPAA2 Overview
  54 ~~~~~~~~~~~~~~
  55
  56 Reference: `FSL MC BUS in Linux Kernel <https://www.kernel.org/doc/readme/drivers-staging-fsl-mc-README.txt>`_.
  57
  58 DPAA2 is a hardware architecture designed for high-speed network
  59 packet processing.  DPAA2 consists of sophisticated mechanisms for
  60 processing Ethernet packets, queue management, buffer management,
  61 autonomous L2 switching, virtual Ethernet bridging, and accelerator
  62 (e.g. crypto) sharing.
  63
  64 A DPAA2 hardware component called the Management Complex (or MC) manages the
  65 DPAA2 hardware resources.  The MC provides an object-based abstraction for
  66 software drivers to use the DPAA2 hardware.
  67
  68 The MC uses DPAA2 hardware resources such as queues, buffer pools, and
  69 network ports to create functional objects/devices such as network
  70 interfaces, an L2 switch, or accelerator instances.
  71
  72 The MC provides memory-mapped I/O command interfaces (MC portals)
  73 which DPAA2 software drivers use to operate on DPAA2 objects:
  74
  75 The diagram below shows an overview of the DPAA2 resource management
  76 architecture:
  77
  78 .. code-block:: console
  79
  80   +--------------------------------------+
  81   |                  OS                  |
  82   |                        DPAA2 drivers |
  83   |                             |        |
  84   +-----------------------------|--------+
  85                                 |
  86                                 | (create,discover,connect
  87                                 |  config,use,destroy)
  88                                 |
  89                   DPAA2         |
  90   +------------------------| mc portal |-+
  91   |                             |        |
  92   |   +- - - - - - - - - - - - -V- - -+  |
  93   |   |                               |  |
  94   |   |   Management Complex (MC)     |  |
  95   |   |                               |  |
  96   |   +- - - - - - - - - - - - - - - -+  |
  97   |                                      |
  98   | Hardware                  Hardware   |
  99   | Resources                 Objects    |
 100   | ---------                 -------    |
 101   | -queues                   -DPRC      |
 102   | -buffer pools             -DPMCP     |
 103   | -Eth MACs/ports           -DPIO      |
 104   | -network interface        -DPNI      |
 105   |  profiles                 -DPMAC     |
 106   | -queue portals            -DPBP      |
 107   | -MC portals                ...       |
 108   |  ...                                 |
 109   |                                      |
 110   +--------------------------------------+
 111
 112 The MC mediates operations such as create, discover,
 113 connect, configuration, and destroy.  Fast-path operations
 114 on data, such as packet transmit/receive, are not mediated by
 115 the MC and are done directly using memory mapped regions in
 116 DPIO objects.
 117
 118 Overview of DPAA2 Objects
 119 ~~~~~~~~~~~~~~~~~~~~~~~~~
 120
 121 The section provides a brief overview of some key DPAA2 objects.
 122 A simple scenario is described illustrating the objects involved
 123 in creating a network interfaces.
 124
 125 DPRC (Datapath Resource Container)
 126
 127  A DPRC is a container object that holds all the other
 128  types of DPAA2 objects.  In the example diagram below there
 129  are 8 objects of 5 types (DPMCP, DPIO, DPBP, DPNI, and DPMAC)
 130  in the container.
 131
 132 .. code-block:: console
 133
 134     +---------------------------------------------------------+
 135     | DPRC                                                    |
 136     |                                                         |
 137     |  +-------+  +-------+  +-------+  +-------+  +-------+  |
 138     |  | DPMCP |  | DPIO  |  | DPBP  |  | DPNI  |  | DPMAC |  |
 139     |  +-------+  +-------+  +-------+  +---+---+  +---+---+  |
 140     |  | DPMCP |  | DPIO  |                                   |
 141     |  +-------+  +-------+                                   |
 142     |  | DPMCP |                                              |
 143     |  +-------+                                              |
 144     |                                                         |
 145     +---------------------------------------------------------+
 146
 147 From the point of view of an OS, a DPRC behaves similar to a plug and
 148 play bus, like PCI.  DPRC commands can be used to enumerate the contents
 149 of the DPRC, discover the hardware objects present (including mappable
 150 regions and interrupts).
 151
 152 .. code-block:: console
 153
 154     DPRC.1 (bus)
 155       |
 156       +--+--------+-------+-------+-------+
 157          |        |       |       |       |
 158        DPMCP.1  DPIO.1  DPBP.1  DPNI.1  DPMAC.1
 159        DPMCP.2  DPIO.2
 160        DPMCP.3
 161
 162 Hardware objects can be created and destroyed dynamically, providing
 163 the ability to hot plug/unplug objects in and out of the DPRC.
 164
 165 A DPRC has a mappable MMIO region (an MC portal) that can be used
 166 to send MC commands.  It has an interrupt for status events (like
 167 hotplug).
 168
 169 All objects in a container share the same hardware "isolation context".
 170 This means that with respect to an IOMMU the isolation granularity
 171 is at the DPRC (container) level, not at the individual object
 172 level.
 173
 174 DPRCs can be defined statically and populated with objects
 175 via a config file passed to the MC when firmware starts
 176 it.  There is also a Linux user space tool called "restool"
 177 that can be used to create/destroy containers and objects
 178 dynamically.
 179
 180 DPAA2 Objects for an Ethernet Network Interface
 181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 182
 183 A typical Ethernet NIC is monolithic-- the NIC device contains TX/RX
 184 queuing mechanisms, configuration mechanisms, buffer management,
 185 physical ports, and interrupts.  DPAA2 uses a more granular approach
 186 utilizing multiple hardware objects.  Each object provides specialized
 187 functions. Groups of these objects are used by software to provide
 188 Ethernet network interface functionality.  This approach provides
 189 efficient use of finite hardware resources, flexibility, and
 190 performance advantages.
 191
 192 The diagram below shows the objects needed for a simple
 193 network interface configuration on a system with 2 CPUs.
 194
 195 .. code-block:: console
 196
 197     +---+---+ +---+---+
 198        CPU0     CPU1
 199     +---+---+ +---+---+
 200         |         |
 201     +---+---+ +---+---+
 202        DPIO     DPIO
 203     +---+---+ +---+---+
 204           \     /
 205            \   /
 206             \ /
 207          +---+---+
 208             DPNI  --- DPBP,DPMCP
 209          +---+---+
 210              |
 211              |
 212          +---+---+
 213            DPMAC
 214          +---+---+
 215              |
 216           port/PHY
 217
 218 Below the objects are described.  For each object a brief description
 219 is provided along with a summary of the kinds of operations the object
 220 supports and a summary of key resources of the object (MMIO regions
 221 and IRQs).
 222
 223 DPMAC (Datapath Ethernet MAC): represents an Ethernet MAC, a
 224 hardware device that connects to an Ethernet PHY and allows
 225 physical transmission and reception of Ethernet frames.
 226
 227 - MMIO regions: none
 228 - IRQs: DPNI link change
 229 - commands: set link up/down, link config, get stats, IRQ config, enable, reset
 230
 231 DPNI (Datapath Network Interface): contains TX/RX queues,
 232 network interface configuration, and RX buffer pool configuration
 233 mechanisms.  The TX/RX queues are in memory and are identified by
 234 queue number.
 235
 236 - MMIO regions: none
 237 - IRQs: link state
 238 - commands: port config, offload config, queue config, parse/classify config, IRQ config, enable, reset
 239
 240 DPIO (Datapath I/O): provides interfaces to enqueue and dequeue
 241 packets and do hardware buffer pool management operations.  The DPAA2
 242 architecture separates the mechanism to access queues (the DPIO object)
 243 from the queues themselves.  The DPIO provides an MMIO interface to
 244 enqueue/dequeue packets.  To enqueue something a descriptor is written
 245 to the DPIO MMIO region, which includes the target queue number.
 246 There will typically be one DPIO assigned to each CPU.  This allows all
 247 CPUs to simultaneously perform enqueue/dequeued operations.  DPIOs are
 248 expected to be shared by different DPAA2 drivers.
 249
 250 - MMIO regions: queue operations, buffer management
 251 - IRQs: data availability, congestion notification, buffer pool depletion
 252 - commands: IRQ config, enable, reset
 253
 254 DPBP (Datapath Buffer Pool): represents a hardware buffer
 255 pool.
 256
 257 - MMIO regions: none
 258 - IRQs: none
 259 - commands: enable, reset
 260
 261 DPMCP (Datapath MC Portal): provides an MC command portal.
 262 Used by drivers to send commands to the MC to manage
 263 objects.
 264
 265 - MMIO regions: MC command portal
 266 - IRQs: command completion
 267 - commands: IRQ config, enable, reset
 268
 269 Object Connections
 270 ~~~~~~~~~~~~~~~~~~
 271
 272 Some objects have explicit relationships that must
 273 be configured:
 274
 275 - DPNI <--> DPMAC
 276 - DPNI <--> DPNI
 277 - DPNI <--> L2-switch-port
 278
 279 A DPNI must be connected to something such as a DPMAC,
 280 another DPNI, or L2 switch port.  The DPNI connection
 281 is made via a DPRC command.
 282
 283 .. code-block:: console
 284
 285     +-------+  +-------+
 286     | DPNI  |  | DPMAC |
 287     +---+---+  +---+---+
 288         |          |
 289         +==========+
 290
 291 - DPNI <--> DPBP
 292
 293 A network interface requires a 'buffer pool' (DPBP object) which provides
 294 a list of pointers to memory where received Ethernet data is to be copied.
 295 The Ethernet driver configures the DPBPs associated with the network
 296 interface.
 297
 298 Interrupts
 299 ~~~~~~~~~~
 300
 301 All interrupts generated by DPAA2 objects are message
 302 interrupts.  At the hardware level message interrupts
 303 generated by devices will normally have 3 components--
 304 1) a non-spoofable 'device-id' expressed on the hardware
 305 bus, 2) an address, 3) a data value.
 306
 307 In the case of DPAA2 devices/objects, all objects in the
 308 same container/DPRC share the same 'device-id'.
 309 For ARM-based SoC this is the same as the stream ID.
 310
 311
 312 DPAA2 DPDK - Poll Mode Driver Overview
 313 --------------------------------------
 314
 315 This section provides an overview of the drivers for
 316 DPAA2-- 1) the bus driver and associated "DPAA2 infrastructure"
 317 drivers and 2) functional object drivers (such as Ethernet).
 318
 319 As described previously, a DPRC is a container that holds the other
 320 types of DPAA2 objects.  It is functionally similar to a plug-and-play
 321 bus controller.
 322
 323 Each object in the DPRC is a Linux "device" and is bound to a driver.
 324 The diagram below shows the dpaa2 drivers involved in a networking
 325 scenario and the objects bound to each driver.  A brief description
 326 of each driver follows.
 327
 328 .. code-block: console
 329
 330
 331                                        +------------+
 332                                        | DPDK DPAA2 |
 333                                        |     PMD    |
 334                                        +------------+       +------------+
 335                                        |  Ethernet  |.......|  Mempool   |
 336                     . . . . . . . . .  |   (DPNI)   |       |  (DPBP)    |
 337                    .                   +---+---+----+       +-----+------+
 338                   .                        ^   |                  .
 339                  .                         |   |<enqueue,         .
 340                 .                          |   | dequeue>         .
 341                .                           |   |                  .
 342               .                        +---+---V----+             .
 343              .      . . . . . . . . . .| DPIO driver|             .
 344             .      .                   |  (DPIO)    |             .
 345            .      .                    +-----+------+             .
 346           .      .                     |  QBMAN     |             .
 347          .      .                      |  Driver    |             .
 348     +----+------+-------+              +-----+----- |             .
 349     |   dpaa2 bus       |                    |                    .
 350     |   VFIO fslmc-bus  |....................|.....................
 351     |                   |                    |
 352     |     /bus/fslmc    |                    |
 353     +-------------------+                    |
 354                                              |
 355     ========================== HARDWARE =====|=======================
 356                                            DPIO
 357                                              |
 358                                            DPNI---DPBP
 359                                              |
 360                                            DPMAC
 361                                              |
 362                                             PHY
 363     =========================================|========================
 364
 365
 366 A brief description of each driver is provided below.
 367
 368 DPAA2 bus driver
 369 ~~~~~~~~~~~~~~~~
 370
 371 The DPAA2 bus driver is a rte_bus driver which scans the fsl-mc bus.
 372 Key functions include:
 373
 374 - Reading the container and setting up vfio group
 375 - Scanning and parsing the various MC objects and adding them to
 376   their respective device list.
 377
 378 Additionally, it also provides the object driver for generic MC objects.
 379
 380 DPIO driver
 381 ~~~~~~~~~~~
 382
 383 The DPIO driver is bound to DPIO objects and provides services that allow
 384 other drivers such as the Ethernet driver to enqueue and dequeue data for
 385 their respective objects.
 386 Key services include:
 387
 388 - Data availability notifications
 389 - Hardware queuing operations (enqueue and dequeue of data)
 390 - Hardware buffer pool management
 391
 392 To transmit a packet the Ethernet driver puts data on a queue and
 393 invokes a DPIO API.  For receive, the Ethernet driver registers
 394 a data availability notification callback.  To dequeue a packet
 395 a DPIO API is used.
 396
 397 There is typically one DPIO object per physical CPU for optimum
 398 performance, allowing different CPUs to simultaneously enqueue
 399 and dequeue data.
 400
 401 The DPIO driver operates on behalf of all DPAA2 drivers
 402 active  --  Ethernet, crypto, compression, etc.
 403
 404 DPBP based Mempool driver
 405 ~~~~~~~~~~~~~~~~~~~~~~~~~
 406
 407 The DPBP driver is bound to a DPBP objects and provides sevices to
 408 create a hardware offloaded packet buffer mempool.
 409
 410 DPAA2 NIC Driver
 411 ~~~~~~~~~~~~~~~~
 412 The Ethernet driver is bound to a DPNI and implements the kernel
 413 interfaces needed to connect the DPAA2 network interface to
 414 the network stack.
 415
 416 Each DPNI corresponds to a DPDK network interface.
 417
 418 Features
 419 ^^^^^^^^
 420
 421 Features of the DPAA2 PMD are:
 422
 423 - Multiple queues for TX and RX
 424 - Receive Side Scaling (RSS)
 425 - MAC/VLAN filtering
 426 - Packet type information
 427 - Checksum offload
 428 - Promiscuous mode
 429 - Multicast mode
 430 - Port hardware statistics
 431 - Jumbo frames
 432 - Link flow control
 433 - Scattered and gather for TX and RX
 434
 435 Supported DPAA2 SoCs
 436 --------------------
 437
 438 - LS2080A/LS2040A
 439 - LS2084A/LS2044A
 440 - LS2088A/LS2048A
 441 - LS1088A/LS1048A
 442
 443 Prerequisites
 444 -------------
 445
 446 There are three main pre-requisities for executing DPAA2 PMD on a DPAA2
 447 compatible board:
 448
 449 1. **ARM 64 Tool Chain**
 450
 451    For example, the `*aarch64* Linaro Toolchain <https://releases.linaro.org/components/toolchain/binaries/6.4-2017.08/aarch64-linux-gnu/>`_.
 452
 453 2. **Linux Kernel**
 454
 455    It can be obtained from `NXP's Github hosting <https://github.com/qoriq-open-source/linux>`_.
 456
 457 3. **Rootfile system**
 458
 459    Any *aarch64* supporting filesystem can be used. For example,
 460    Ubuntu 15.10 (Wily) or 16.04 LTS (Xenial) userland which can be obtained
 461    from `here <http://cdimage.ubuntu.com/ubuntu-base/releases/16.04/release/ubuntu-base-16.04.1-base-arm64.tar.gz>`_.
 462
 463 As an alternative method, DPAA2 PMD can also be executed using images provided
 464 as part of SDK from NXP. The SDK includes all the above prerequisites necessary
 465 to bring up a DPAA2 board.
 466
 467 The following dependencies are not part of DPDK and must be installed
 468 separately:
 469
 470 - **NXP Linux SDK**
 471
 472   NXP Linux software development kit (SDK) includes support for family
 473   of QorIQ® ARM-Architecture-based system on chip (SoC) processors
 474   and corresponding boards.
 475
 476   It includes the Linux board support packages (BSPs) for NXP SoCs,
 477   a fully operational tool chain, kernel and board specific modules.
 478
 479   SDK and related information can be obtained from:  `NXP QorIQ SDK  <http://www.nxp.com/products/software-and-tools/run-time-software/linux-sdk/linux-sdk-for-qoriq-processors:SDKLINUX>`_.
 480
 481 - **DPDK Extra Scripts**
 482
 483   DPAA2 based resources can be configured easily with the help of ready scripts
 484   as provided in the DPDK Extra repository.
 485
 486   `DPDK Extras Scripts <https://github.com/qoriq-open-source/dpdk-extras>`_.
 487
 488 Currently supported by DPDK:
 489
 490 - NXP SDK **17.08+**.
 491 - MC Firmware version **10.3.1** and higher.
 492 - Supported architectures:  **arm64 LE**.
 493
 494 - Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.
 495
 496 .. note::
 497
 498    Some part of fslmc bus code (mc flib - object library) routines are
 499    dual licensed (BSD & GPLv2), however they are used as BSD in DPDK in userspace.
 500
 501 Pre-Installation Configuration
 502 ------------------------------
 503
 504 Config File Options
 505 ~~~~~~~~~~~~~~~~~~~
 506
 507 The following options can be modified in the ``config`` file.
 508 Please note that enabling debugging options may affect system performance.
 509
 510 - ``CONFIG_RTE_LIBRTE_FSLMC_BUS`` (default ``n``)
 511
 512   By default it is enabled only for defconfig_arm64-dpaa2-* config.
 513   Toggle compilation of the ``librte_bus_fslmc`` driver.
 514
 515 - ``CONFIG_RTE_LIBRTE_DPAA2_PMD`` (default ``n``)
 516
 517   By default it is enabled only for defconfig_arm64-dpaa2-* config.
 518   Toggle compilation of the ``librte_pmd_dpaa2`` driver.
 519
 520 - ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_DRIVER`` (default ``n``)
 521
 522   Toggle display of generic debugging messages
 523
 524 - ``CONFIG_RTE_LIBRTE_DPAA2_USE_PHYS_IOVA`` (default ``y``)
 525
 526   Toggle to use physical address vs virtual address for hardware accelerators.
 527
 528 - ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_INIT`` (default ``n``)
 529
 530   Toggle display of initialization related messages.
 531
 532 - ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_RX`` (default ``n``)
 533
 534   Toggle display of receive fast path run-time message
 535
 536 - ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_TX`` (default ``n``)
 537
 538   Toggle display of transmit fast path run-time message
 539
 540 - ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_TX_FREE`` (default ``n``)
 541
 542   Toggle display of transmit fast path buffer free run-time message
 543
 544 Driver compilation and testing
 545 ------------------------------
 546
 547 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 548 for details.
 549
 550 #. Running testpmd:
 551
 552    Follow instructions available in the document
 553    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 554    to run testpmd.
 555
 556    Example output:
 557
 558    .. code-block:: console
 559
 560       ./arm64-dpaa2-linuxapp-gcc/testpmd -c 0xff -n 1 \
 561         -- -i --portmask=0x3 --nb-cores=1 --no-flush-rx
 562
 563       .....
 564       EAL: Registered [pci] bus.
 565       EAL: Registered [fslmc] bus.
 566       EAL: Detected 8 lcore(s)
 567       EAL: Probing VFIO support...
 568       EAL: VFIO support initialized
 569       .....
 570       PMD: DPAA2: Processing Container = dprc.2
 571       EAL: fslmc: DPRC contains = 51 devices
 572       EAL: fslmc: Bus scan completed
 573       .....
 574       Configuring Port 0 (socket 0)
 575       Port 0: 00:00:00:00:00:01
 576       Configuring Port 1 (socket 0)
 577       Port 1: 00:00:00:00:00:02
 578       .....
 579       Checking link statuses...
 580       Port 0 Link Up - speed 10000 Mbps - full-duplex
 581       Port 1 Link Up - speed 10000 Mbps - full-duplex
 582       Done
 583       testpmd>
 584
 585 Limitations
 586 -----------
 587
 588 Platform Requirement
 589 ~~~~~~~~~~~~~~~~~~~~
 590 DPAA2 drivers for DPDK can only work on NXP SoCs as listed in the
 591 ``Supported DPAA2 SoCs``.
 592
 593 Maximum packet length
 594 ~~~~~~~~~~~~~~~~~~~~~
 595
 596 The DPAA2 SoC family support a maximum of a 10240 jumbo frame. The value
 597 is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
 598 member of ``struct rte_eth_conf`` is set to a value lower than 10240, frames
 599 up to 10240 bytes can still reach the host interface.
 600
 601 Other Limitations
 602 ~~~~~~~~~~~~~~~~~
 603
 604 - RSS hash key cannot be modified.
 605 - RSS RETA cannot be configured.
 606 - Secondary process packet I/O is not supported.