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/6.4-2017.08/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 <https://github.com/qoriq-open-source/fmc>`_.
 222
 223    This tool needs configuration files which are available in the
 224    :ref:`DPDK Extra Scripts <extra_scripts>`, described below for DPDK usages.
 225
 226 As an alternative method, DPAA PMD can also be executed using images provided
 227 as part of SDK from NXP. The SDK includes all the above prerequisites necessary
 228 to bring up a DPAA board.
 229
 230 The following dependencies are not part of DPDK and must be installed
 231 separately:
 232
 233 - **NXP Linux SDK**
 234
 235   NXP Linux software development kit (SDK) includes support for family
 236   of QorIQ® ARM-Architecture-based system on chip (SoC) processors
 237   and corresponding boards.
 238
 239   It includes the Linux board support packages (BSPs) for NXP SoCs,
 240   a fully operational tool chain, kernel and board specific modules.
 241
 242   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>`_.
 243
 244
 245 .. _extra_scripts:
 246
 247 - **DPDK Extra Scripts**
 248
 249   DPAA based resources can be configured easily with the help of ready scripts
 250   as provided in the DPDK Extra repository.
 251
 252   `DPDK Extras Scripts <https://github.com/qoriq-open-source/dpdk-extras>`_.
 253
 254 Currently supported by DPDK:
 255
 256 - NXP SDK **2.0+**.
 257 - Supported architectures:  **arm64 LE**.
 258
 259 - Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>`
 260   to setup the basic DPDK environment.
 261
 262 .. note::
 263
 264    Some part of dpaa bus code (qbman and fman - library) routines are
 265    dual licensed (BSD & GPLv2), however they are used as BSD in DPDK in userspace.
 266
 267 Pre-Installation Configuration
 268 ------------------------------
 269
 270 Config File Options
 271 ~~~~~~~~~~~~~~~~~~~
 272
 273 The following options can be modified in the ``config`` file.
 274 Please note that enabling debugging options may affect system performance.
 275
 276 - ``CONFIG_RTE_LIBRTE_DPAA_BUS`` (default ``n``)
 277
 278   By default it is enabled only for defconfig_arm64-dpaa-* config.
 279   Toggle compilation of the ``librte_bus_dpaa`` driver.
 280
 281 - ``CONFIG_RTE_LIBRTE_DPAA_PMD`` (default ``n``)
 282
 283   By default it is enabled only for defconfig_arm64-dpaa-* config.
 284   Toggle compilation of the ``librte_pmd_dpaa`` driver.
 285
 286 - ``CONFIG_RTE_LIBRTE_DPAA_DEBUG_DRIVER`` (default ``n``)
 287
 288   Toggles display of bus configurations and enables a debugging queue
 289   to fetch error (Rx/Tx) packets to driver. By default, packets with errors
 290   (like wrong checksum) are dropped by the hardware.
 291
 292 - ``CONFIG_RTE_LIBRTE_DPAA_HWDEBUG`` (default ``n``)
 293
 294   Enables debugging of the Queue and Buffer Manager layer which interacts
 295   with the DPAA hardware.
 296
 297 - ``CONFIG_RTE_MBUF_DEFAULT_MEMPOOL_OPS`` (default ``dpaa``)
 298
 299   This is not a DPAA specific configuration - it is a generic RTE config.
 300   For optimal performance and hardware utilization, it is expected that DPAA
 301   Mempool driver is used for mempools. For that, this configuration needs to
 302   enabled.
 303
 304 Environment Variables
 305 ~~~~~~~~~~~~~~~~~~~~~
 306
 307 DPAA drivers uses the following environment variables to configure its
 308 state during application initialization:
 309
 310 - ``DPAA_NUM_RX_QUEUES`` (default 1)
 311
 312   This defines the number of Rx queues configured for an application, per
 313   port. Hardware would distribute across these many number of queues on Rx
 314   of packets.
 315   In case the application is configured to use lesser number of queues than
 316   configured above, it might result in packet loss (because of distribution).
 317
 318
 319 Driver compilation and testing
 320 ------------------------------
 321
 322 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 323 for details.
 324
 325 #. Running testpmd:
 326
 327    Follow instructions available in the document
 328    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 329    to run testpmd.
 330
 331    Example output:
 332
 333    .. code-block:: console
 334
 335       ./arm64-dpaa-linuxapp-gcc/testpmd -c 0xff -n 1 \
 336         -- -i --portmask=0x3 --nb-cores=1 --no-flush-rx
 337
 338       .....
 339       EAL: Registered [pci] bus.
 340       EAL: Registered [dpaa] bus.
 341       EAL: Detected 4 lcore(s)
 342       .....
 343       EAL: dpaa: Bus scan completed
 344       .....
 345       Configuring Port 0 (socket 0)
 346       Port 0: 00:00:00:00:00:01
 347       Configuring Port 1 (socket 0)
 348       Port 1: 00:00:00:00:00:02
 349       .....
 350       Checking link statuses...
 351       Port 0 Link Up - speed 10000 Mbps - full-duplex
 352       Port 1 Link Up - speed 10000 Mbps - full-duplex
 353       Done
 354       testpmd>
 355
 356 Limitations
 357 -----------
 358
 359 Platform Requirement
 360 ~~~~~~~~~~~~~~~~~~~~
 361
 362 DPAA drivers for DPDK can only work on NXP SoCs as listed in the
 363 ``Supported DPAA SoCs``.
 364
 365 Maximum packet length
 366 ~~~~~~~~~~~~~~~~~~~~~
 367
 368 The DPAA SoC family support a maximum of a 10240 jumbo frame. The value
 369 is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
 370 member of ``struct rte_eth_conf`` is set to a value lower than 10240, frames
 371 up to 10240 bytes can still reach the host interface.
 372
 373 Multiprocess Support
 374 ~~~~~~~~~~~~~~~~~~~~
 375
 376 Current version of DPAA driver doesn't support multi-process applications
 377 where I/O is performed using secondary processes. This feature would be
 378 implemented in subsequent versions.