doc/guides/nics/dpaa.rst

   1 ..  BSD LICENSE
   2     Copyright 2017 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 DPAA Poll Mode Driver
  31 =====================
  32
  33 The DPAA NIC PMD (**librte_pmd_dpaa**) provides poll mode driver
  34 support for the inbuilt NIC found in the **NXP DPAA** 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 DPAA (Data Path Acceleration Architecture - Gen 1)
  40 ------------------------------------------------------
  41
  42 This section provides an overview of the NXP DPAA architecture
  43 and how it is integrated into the DPDK.
  44
  45 Contents summary
  46
  47 - DPAA overview
  48 - DPAA driver architecture overview
  49
  50 .. _dpaa_overview:
  51
  52 DPAA Overview
  53 ~~~~~~~~~~~~~
  54
  55 Reference: `FSL DPAA Architecture <http://www.nxp.com/assets/documents/data/en/white-papers/QORIQDPAAWP.pdf>`_.
  56
  57 The QorIQ Data Path Acceleration Architecture (DPAA) is a set of hardware
  58 components on specific QorIQ series multicore processors. This architecture
  59 provides the infrastructure to support simplified sharing of networking
  60 interfaces and accelerators by multiple CPU cores, and the accelerators
  61 themselves.
  62
  63 DPAA includes:
  64
  65 - Cores
  66 - Network and packet I/O
  67 - Hardware offload accelerators
  68 - Infrastructure required to facilitate flow of packets between the components above
  69
  70 Infrastructure components are:
  71
  72 - The Queue Manager (QMan) is a hardware accelerator that manages frame queues.
  73   It allows  CPUs and other accelerators connected to the SoC datapath to
  74   enqueue and dequeue ethernet frames, thus providing the infrastructure for
  75   data exchange among CPUs and datapath accelerators.
  76 - The Buffer Manager (BMan) is a hardware buffer pool management block that
  77   allows software and accelerators on the datapath to acquire and release
  78   buffers in order to build frames.
  79
  80 Hardware accelerators are:
  81
  82 - SEC - Cryptographic accelerator
  83 - PME - Pattern matching engine
  84
  85 The Network and packet I/O component:
  86
  87 - The Frame Manager (FMan) is a key component in the DPAA and makes use of the
  88   DPAA infrastructure (QMan and BMan). FMan  is responsible for packet
  89   distribution and policing. Each frame can be parsed, classified and results
  90   may be attached to the frame. This meta data can be used to select
  91   particular QMan queue, which the packet is forwarded to.
  92
  93
  94 DPAA DPDK - Poll Mode Driver Overview
  95 -------------------------------------
  96
  97 This section provides an overview of the drivers for DPAA:
  98
  99 * Bus driver and associated "DPAA infrastructure" drivers
 100 * Functional object drivers (such as Ethernet).
 101
 102 Brief description of each driver is provided in layout below as well as
 103 in the following sections.
 104
 105 .. code-block:: console
 106
 107                                        +------------+
 108                                        | DPDK DPAA  |
 109                                        |    PMD     |
 110                                        +-----+------+
 111                                              |
 112                                        +-----+------+       +---------------+
 113                                        :  Ethernet  :.......| DPDK DPAA     |
 114                     . . . . . . . . .  :   (FMAN)   :       | Mempool driver|
 115                    .                   +---+---+----+       |  (BMAN)       |
 116                   .                        ^   |            +-----+---------+
 117                  .                         |   |<enqueue,         .
 118                 .                          |   | dequeue>         .
 119                .                           |   |                  .
 120               .                        +---+---V----+             .
 121              .      . . . . . . . . . .: Portal drv :             .
 122             .      .                   :            :             .
 123            .      .                    +-----+------+             .
 124           .      .                     :   QMAN     :             .
 125          .      .                      :  Driver    :             .
 126     +----+------+-------+              +-----+------+             .
 127     |   DPDK DPAA Bus   |                    |                    .
 128     |   driver          |....................|.....................
 129     |   /bus/dpaa       |                    |
 130     +-------------------+                    |
 131                                              |
 132     ========================== HARDWARE =====|========================
 133                                             PHY
 134     =========================================|========================
 135
 136 In the above representation, solid lines represent components which interface
 137 with DPDK RTE Framework and dotted lines represent DPAA internal components.
 138
 139 DPAA Bus driver
 140 ~~~~~~~~~~~~~~~
 141
 142 The DPAA bus driver is a ``rte_bus`` driver which scans the platform like bus.
 143 Key functions include:
 144
 145 - Scanning and parsing the various objects and adding them to their respective
 146   device list.
 147 - Performing probe for available drivers against each scanned device
 148 - Creating necessary ethernet instance before passing control to the PMD
 149
 150 DPAA NIC Driver (PMD)
 151 ~~~~~~~~~~~~~~~~~~~~~
 152
 153 DPAA PMD is traditional DPDK PMD which provides necessary interface between
 154 RTE framework and DPAA internal components/drivers.
 155
 156 - Once devices have been identified by DPAA Bus, each device is associated
 157   with the PMD
 158 - PMD is responsible for implementing necessary glue layer between RTE APIs
 159   and lower level QMan and FMan blocks.
 160   The Ethernet driver is bound to a FMAN port and implements the interfaces
 161   needed to connect the DPAA network interface to the network stack.
 162   Each FMAN Port corresponds to a DPDK network interface.
 163
 164
 165 Features
 166 ^^^^^^^^
 167
 168   Features of the DPAA PMD are:
 169
 170   - Multiple queues for TX and RX
 171   - Receive Side Scaling (RSS)
 172   - Packet type information
 173   - Checksum offload
 174   - Promiscuous mode
 175
 176 DPAA Mempool Driver
 177 ~~~~~~~~~~~~~~~~~~~
 178
 179 DPAA has a hardware offloaded buffer pool manager, called BMan, or Buffer
 180 Manager.
 181
 182 - Using standard Mempools operations RTE API, the mempool driver interfaces
 183   with RTE to service each mempool creation, deletion, buffer allocation and
 184   deallocation requests.
 185 - Each FMAN instance has a BMan pool attached to it during initialization.
 186   Each Tx frame can be automatically released by hardware, if allocated from
 187   this pool.
 188
 189
 190 Supported DPAA SoCs
 191 -------------------
 192
 193 - LS1043A/LS1023A
 194 - LS1046A/LS1026A
 195
 196 Prerequisites
 197 -------------
 198
 199 There are three main pre-requisities for executing DPAA PMD on a DPAA
 200 compatible board:
 201
 202 1. **ARM 64 Tool Chain**
 203
 204    For example, the `*aarch64* Linaro Toolchain <https://releases.linaro.org/components/toolchain/binaries/4.9-2017.01/aarch64-linux-gnu>`_.
 205
 206 2. **Linux Kernel**
 207
 208    It can be obtained from `NXP's Github hosting <https://github.com/qoriq-open-source/linux>`_.
 209
 210 3. **Rootfile system**
 211
 212    Any *aarch64* supporting filesystem can be used. For example,
 213    Ubuntu 15.10 (Wily) or 16.04 LTS (Xenial) userland which can be obtained
 214    from `here <http://cdimage.ubuntu.com/ubuntu-base/releases/16.04/release/ubuntu-base-16.04.1-base-arm64.tar.gz>`_.
 215
 216 4. **FMC Tool**
 217
 218    Before any DPDK application can be executed, the Frame Manager Configuration
 219    Tool (FMC) need to be executed to set the configurations of the queues. This
 220    includes the queue state, RSS and other policies.
 221    This tool can be obtained from `NXP (Freescale) Public Git Repository <http://git.freescale.com/git/cgit.cgi/ppc/sdk/fmc.git>`_.
 222    This tool needs configuration files which are available in the
 223    :ref:`DPDK Extra Scripts <extra_scripts>`, described below.
 224
 225 As an alternative method, DPAA PMD can also be executed using images provided
 226 as part of SDK from NXP. The SDK includes all the above prerequisites necessary
 227 to bring up a DPAA board.
 228
 229 The following dependencies are not part of DPDK and must be installed
 230 separately:
 231
 232 - **NXP Linux SDK**
 233
 234   NXP Linux software development kit (SDK) includes support for family
 235   of QorIQ® ARM-Architecture-based system on chip (SoC) processors
 236   and corresponding boards.
 237
 238   It includes the Linux board support packages (BSPs) for NXP SoCs,
 239   a fully operational tool chain, kernel and board specific modules.
 240
 241   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>`_.
 242
 243
 244 .. _extra_scripts:
 245
 246 - **DPDK Extra Scripts**
 247
 248   DPAA based resources can be configured easily with the help of ready scripts
 249   as provided in the DPDK Extra repository.
 250
 251   `DPDK Extras Scripts <https://github.com/qoriq-open-source/dpdk-extras>`_.
 252
 253 Currently supported by DPDK:
 254
 255 - NXP SDK **2.0+**.
 256 - Supported architectures:  **arm64 LE**.
 257
 258 - Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>`
 259   to setup the basic DPDK environment.
 260
 261 .. note::
 262
 263    Some part of dpaa bus code (qbman and fman - library) routines are
 264    dual licensed (BSD & GPLv2).
 265
 266 Pre-Installation Configuration
 267 ------------------------------
 268
 269 Config File Options
 270 ~~~~~~~~~~~~~~~~~~~
 271
 272 The following options can be modified in the ``config`` file.
 273 Please note that enabling debugging options may affect system performance.
 274
 275 - ``CONFIG_RTE_LIBRTE_DPAA_BUS`` (default ``n``)
 276
 277   By default it is enabled only for defconfig_arm64-dpaa-* config.
 278   Toggle compilation of the ``librte_bus_dpaa`` driver.
 279
 280 - ``CONFIG_RTE_LIBRTE_DPAA_PMD`` (default ``n``)
 281
 282   By default it is enabled only for defconfig_arm64-dpaa-* config.
 283   Toggle compilation of the ``librte_pmd_dpaa`` driver.
 284
 285 - ``CONFIG_RTE_LIBRTE_DPAA_DEBUG_DRIVER`` (default ``n``)
 286
 287   Toggles display of bus configurations and enables a debugging queue
 288   to fetch error (Rx/Tx) packets to driver. By default, packets with errors
 289   (like wrong checksum) are dropped by the hardware.
 290
 291 - ``CONFIG_RTE_LIBRTE_DPAA_HWDEBUG`` (default ``n``)
 292
 293   Enables debugging of the Queue and Buffer Manager layer which interacts
 294   with the DPAA hardware.
 295
 296 - ``CONFIG_RTE_MBUF_DEFAULT_MEMPOOL_OPS`` (default ``dpaa``)
 297
 298   This is not a DPAA specific configuration - it is a generic RTE config.
 299   For optimal performance and hardware utilization, it is expected that DPAA
 300   Mempool driver is used for mempools. For that, this configuration needs to
 301   enabled.
 302
 303 Environment Variables
 304 ~~~~~~~~~~~~~~~~~~~~~
 305
 306 DPAA drivers uses the following environment variables to configure its
 307 state during application initialization:
 308
 309 - ``DPAA_NUM_RX_QUEUES`` (default 1)
 310
 311   This defines the number of Rx queues configured for an application, per
 312   port. Hardware would distribute across these many number of queues on Rx
 313   of packets.
 314   In case the application is configured to use lesser number of queues than
 315   configured above, it might result in packet loss (because of distribution).
 316
 317
 318 Driver compilation and testing
 319 ------------------------------
 320
 321 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 322 for details.
 323
 324 #. Running testpmd:
 325
 326    Follow instructions available in the document
 327    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 328    to run testpmd.
 329
 330    Example output:
 331
 332    .. code-block:: console
 333
 334       ./arm64-dpaa-linuxapp-gcc/testpmd -c 0xff -n 1 \
 335         -- -i --portmask=0x3 --nb-cores=1 --no-flush-rx
 336
 337       .....
 338       EAL: Registered [pci] bus.
 339       EAL: Registered [dpaa] bus.
 340       EAL: Detected 4 lcore(s)
 341       .....
 342       EAL: dpaa: Bus scan completed
 343       .....
 344       Configuring Port 0 (socket 0)
 345       Port 0: 00:00:00:00:00:01
 346       Configuring Port 1 (socket 0)
 347       Port 1: 00:00:00:00:00:02
 348       .....
 349       Checking link statuses...
 350       Port 0 Link Up - speed 10000 Mbps - full-duplex
 351       Port 1 Link Up - speed 10000 Mbps - full-duplex
 352       Done
 353       testpmd>
 354
 355 Limitations
 356 -----------
 357
 358 Platform Requirement
 359 ~~~~~~~~~~~~~~~~~~~~
 360
 361 DPAA drivers for DPDK can only work on NXP SoCs as listed in the
 362 ``Supported DPAA SoCs``.
 363
 364 Maximum packet length
 365 ~~~~~~~~~~~~~~~~~~~~~
 366
 367 The DPAA SoC family support a maximum of a 10240 jumbo frame. The value
 368 is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
 369 member of ``struct rte_eth_conf`` is set to a value lower than 10240, frames
 370 up to 10240 bytes can still reach the host interface.
 371
 372 Multiprocess Support
 373 ~~~~~~~~~~~~~~~~~~~~
 374
 375 Current version of DPAA driver doesn't support multi-process applications
 376 where I/O is performed using secondary processes. This feature would be
 377 implemented in subsequent versions.