doc/guides/rawdevs/dpaa2_qdma.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright 2018 NXP
   3
   4 NXP DPAA2 QDMA Driver
   5 =====================
   6
   7 The DPAA2 QDMA is an implementation of the rawdev API, that provide means
   8 to initiate a DMA transaction from CPU. The initiated DMA is performed
   9 without CPU being involved in the actual DMA transaction. This is achieved
  10 via using the DPDMAI device exposed by MC.
  11
  12 More information can be found at `NXP Official Website
  13 <http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/qoriq-arm-processors:QORIQ-ARM>`_.
  14
  15 Features
  16 --------
  17
  18 The DPAA2 QDMA implements following features in the rawdev API;
  19
  20 - Supports issuing DMA of data within memory without hogging CPU while
  21   performing DMA operation.
  22 - Supports configuring to optionally get status of the DMA translation on
  23   per DMA operation basis.
  24
  25 Supported DPAA2 SoCs
  26 --------------------
  27
  28 - LS2084A/LS2044A
  29 - LS2088A/LS2048A
  30 - LS1088A/LS1048A
  31
  32 Prerequisites
  33 -------------
  34
  35 There are three main pre-requisities for executing DPAA2 QDMA on a DPAA2
  36 compatible board:
  37
  38 1. **ARM 64 Tool Chain**
  39
  40    For example, the `*aarch64* Linaro Toolchain <https://releases.linaro.org/components/toolchain/binaries/6.3-2017.02/aarch64-linux-gnu>`_.
  41
  42 2. **Linux Kernel**
  43
  44    It can be obtained from `NXP's Github hosting <https://github.com/qoriq-open-source/linux>`_.
  45
  46 3. **Rootfile system**
  47
  48    Any *aarch64* supporting filesystem can be used. For example,
  49    Ubuntu 15.10 (Wily) or 16.04 LTS (Xenial) userland which can be obtained
  50    from `here <http://cdimage.ubuntu.com/ubuntu-base/releases/16.04/release/ubuntu-base-16.04.1-base-arm64.tar.gz>`_.
  51
  52 As an alternative method, DPAA2 QDMA can also be executed using images provided
  53 as part of SDK from NXP. The SDK includes all the above prerequisites necessary
  54 to bring up a DPAA2 board.
  55
  56 The following dependencies are not part of DPDK and must be installed
  57 separately:
  58
  59 - **NXP Linux SDK**
  60
  61   NXP Linux software development kit (SDK) includes support for family
  62   of QorIQ® ARM-Architecture-based system on chip (SoC) processors
  63   and corresponding boards.
  64
  65   It includes the Linux board support packages (BSPs) for NXP SoCs,
  66   a fully operational tool chain, kernel and board specific modules.
  67
  68   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>`_.
  69
  70 - **DPDK Extra Scripts**
  71
  72   DPAA2 based resources can be configured easily with the help of ready scripts
  73   as provided in the DPDK Extra repository.
  74
  75   `DPDK Extras Scripts <https://github.com/qoriq-open-source/dpdk-extras>`_.
  76
  77 Currently supported by DPDK:
  78
  79 - NXP LSDK **17.12+**.
  80 - MC Firmware version **10.3.0** and higher.
  81 - Supported architectures:  **arm64 LE**.
  82
  83 - Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.
  84
  85 .. note::
  86
  87    Some part of fslmc bus code (mc flib - object library) routines are
  88    dual licensed (BSD & GPLv2).
  89
  90 Pre-Installation Configuration
  91 ------------------------------
  92
  93 Config File Options
  94 ~~~~~~~~~~~~~~~~~~~
  95
  96 The following options can be modified in the ``config`` file.
  97
  98 - ``CONFIG_RTE_LIBRTE_PMD_DPAA2_QDMA_RAWDEV`` (default ``y``)
  99
 100   Toggle compilation of the ``lrte_pmd_dpaa2_qdma`` driver.
 101
 102 Enabling logs
 103 -------------
 104
 105 For enabling logs, use the following EAL parameter:
 106
 107 .. code-block:: console
 108
 109    ./your_qdma_application <EAL args> --log-level=pmd.raw.dpaa2.qdma,<level>
 110
 111 Using ``pmd.raw.dpaa2.qdma`` as log matching criteria, all Event PMD logs can be
 112 enabled which are lower than logging ``level``.
 113
 114 Driver Compilation
 115 ~~~~~~~~~~~~~~~~~~
 116
 117 To compile the DPAA2 QDMA PMD for Linux arm64 gcc target, run the
 118 following ``make`` command:
 119
 120 .. code-block:: console
 121
 122    cd <DPDK-source-directory>
 123    make config T=arm64-dpaa2-linuxapp-gcc install
 124
 125 Initialization
 126 --------------
 127
 128 The DPAA2 QDMA is exposed as a vdev device which consists of dpdmai devices.
 129 On EAL initialization, dpdmai devices will be probed and populated into the
 130 rawdevices. The rawdev ID of the device can be obtained using
 131
 132 * Invoking ``rte_rawdev_get_dev_id("dpdmai.x")`` from the application
 133   where x is the object ID of the DPDMAI object created by MC. Use can
 134   use this index for further rawdev function calls.
 135
 136 Platform Requirement
 137 ~~~~~~~~~~~~~~~~~~~~
 138
 139 DPAA2 drivers for DPDK can only work on NXP SoCs as listed in the
 140 ``Supported DPAA2 SoCs``.