From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nipun Gupta Subject: [PATCH RESEND v7 8/8] doc: add DPAA2 QDMA rawdev guide Date: Thu, 3 May 2018 21:36:10 +0530 Message-ID: <1525363570-23542-9-git-send-email-nipun.gupta@nxp.com> References: <1525280972-27736-1-git-send-email-nipun.gupta@nxp.com> <1525363570-23542-1-git-send-email-nipun.gupta@nxp.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: dev@dpdk.org, Nipun Gupta To: thomas@monjalon.net, hemant.agrawal@nxp.com, shreyansh.jain@nxp.com Return-path: Received: from EUR03-DB5-obe.outbound.protection.outlook.com (mail-eopbgr40056.outbound.protection.outlook.com [40.107.4.56]) by dpdk.org (Postfix) with ESMTP id 59DDC4C8D for ; Thu, 3 May 2018 18:06:59 +0200 (CEST) In-Reply-To: <1525363570-23542-1-git-send-email-nipun.gupta@nxp.com> List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Signed-off-by: Nipun Gupta Acked-by: Shreyansh Jain --- MAINTAINERS | 1 + doc/guides/index.rst | 1 + doc/guides/rawdevs/dpaa2_qdma.rst | 140 +++++++++++++++++++++++++++++++++ doc/guides/rawdevs/index.rst | 14 ++++ doc/guides/rel_notes/release_18_05.rst | 8 ++ 5 files changed, 164 insertions(+) create mode 100644 doc/guides/rawdevs/dpaa2_qdma.rst create mode 100644 doc/guides/rawdevs/index.rst diff --git a/MAINTAINERS b/MAINTAINERS index f8017d3..b72b048 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -808,6 +808,7 @@ Rawdev Drivers NXP DPAA2 QDMA M: Nipun Gupta F: drivers/raw/dpaa2_qdma/ +F: doc/guides/rawdevs/dpaa2_qdma.rst Eventdev Drivers diff --git a/doc/guides/index.rst b/doc/guides/index.rst index d60529d..a93baac 100644 --- a/doc/guides/index.rst +++ b/doc/guides/index.rst @@ -20,6 +20,7 @@ DPDK documentation eventdevs/index mempool/index platform/index + rawdevs/index contributing/index rel_notes/index faq/index diff --git a/doc/guides/rawdevs/dpaa2_qdma.rst b/doc/guides/rawdevs/dpaa2_qdma.rst new file mode 100644 index 0000000..b9bc4ec --- /dev/null +++ b/doc/guides/rawdevs/dpaa2_qdma.rst @@ -0,0 +1,140 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright 2018 NXP + +NXP DPAA2 QDMA Driver +===================== + +The DPAA2 QDMA is an implementation of the rawdev API, that provide means +to initiate a DMA transaction from CPU. The initiated DMA is performed +without CPU being involved in the actual DMA transaction. This is achieved +via using the DPDMAI device exposed by MC. + +More information can be found at `NXP Official Website +`_. + +Features +-------- + +The DPAA2 QDMA implements following features in the rawdev API; + +- Supports issuing DMA of data within memory without hogging CPU while + performing DMA operation. +- Supports configuring to optionally get status of the DMA translation on + per DMA operation basis. + +Supported DPAA2 SoCs +-------------------- + +- LS2084A/LS2044A +- LS2088A/LS2048A +- LS1088A/LS1048A + +Prerequisites +------------- + +There are three main pre-requisities for executing DPAA2 QDMA on a DPAA2 +compatible board: + +1. **ARM 64 Tool Chain** + + For example, the `*aarch64* Linaro Toolchain `_. + +2. **Linux Kernel** + + It can be obtained from `NXP's Github hosting `_. + +3. **Rootfile system** + + Any *aarch64* supporting filesystem can be used. For example, + Ubuntu 15.10 (Wily) or 16.04 LTS (Xenial) userland which can be obtained + from `here `_. + +As an alternative method, DPAA2 QDMA can also be executed using images provided +as part of SDK from NXP. The SDK includes all the above prerequisites necessary +to bring up a DPAA2 board. + +The following dependencies are not part of DPDK and must be installed +separately: + +- **NXP Linux SDK** + + NXP Linux software development kit (SDK) includes support for family + of QorIQ® ARM-Architecture-based system on chip (SoC) processors + and corresponding boards. + + It includes the Linux board support packages (BSPs) for NXP SoCs, + a fully operational tool chain, kernel and board specific modules. + + SDK and related information can be obtained from: `NXP QorIQ SDK `_. + +- **DPDK Extra Scripts** + + DPAA2 based resources can be configured easily with the help of ready scripts + as provided in the DPDK Extra repository. + + `DPDK Extras Scripts `_. + +Currently supported by DPDK: + +- NXP LSDK **17.12+**. +- MC Firmware version **10.3.0** and higher. +- Supported architectures: **arm64 LE**. + +- Follow the DPDK :ref:`Getting Started Guide for Linux ` to setup the basic DPDK environment. + +.. note:: + + Some part of fslmc bus code (mc flib - object library) routines are + dual licensed (BSD & GPLv2). + +Pre-Installation Configuration +------------------------------ + +Config File Options +~~~~~~~~~~~~~~~~~~~ + +The following options can be modified in the ``config`` file. + +- ``CONFIG_RTE_LIBRTE_PMD_DPAA2_QDMA_RAWDEV`` (default ``y``) + + Toggle compilation of the ``lrte_pmd_dpaa2_qdma`` driver. + +Enabling logs +------------- + +For enabling logs, use the following EAL parameter: + +.. code-block:: console + + ./your_qdma_application --log-level=pmd.raw.dpaa2.qdma, + +Using ``pmd.raw.dpaa2.qdma`` as log matching criteria, all Event PMD logs can be +enabled which are lower than logging ``level``. + +Driver Compilation +~~~~~~~~~~~~~~~~~~ + +To compile the DPAA2 QDMA PMD for Linux arm64 gcc target, run the +following ``make`` command: + +.. code-block:: console + + cd + make config T=arm64-dpaa2-linuxapp-gcc install + +Initialization +-------------- + +The DPAA2 QDMA is exposed as a vdev device which consists of dpdmai devices. +On EAL initialization, dpdmai devices will be probed and populated into the +rawdevices. The rawdev ID of the device can be obtained using + +* Invoking ``rte_rawdev_get_dev_id("dpdmai.x")`` from the application + where x is the object ID of the DPDMAI object created by MC. Use can + use this index for further rawdev function calls. + +Platform Requirement +~~~~~~~~~~~~~~~~~~~~ + +DPAA2 drivers for DPDK can only work on NXP SoCs as listed in the +``Supported DPAA2 SoCs``. diff --git a/doc/guides/rawdevs/index.rst b/doc/guides/rawdevs/index.rst new file mode 100644 index 0000000..29b4f6c --- /dev/null +++ b/doc/guides/rawdevs/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright 2018 NXP + +Rawdev Drivers +============== + +The following are a list of raw device PMDs, which can be used from an +application through rawdev API. + +.. toctree:: + :maxdepth: 2 + :numbered: + + dpaa2_qdma diff --git a/doc/guides/rel_notes/release_18_05.rst b/doc/guides/rel_notes/release_18_05.rst index 0ae61e8..22fa74d 100644 --- a/doc/guides/rel_notes/release_18_05.rst +++ b/doc/guides/rel_notes/release_18_05.rst @@ -164,6 +164,14 @@ New Features stats/xstats on shared memory from secondary process, and also pdump packets on those virtual devices. +* **Added DPAA2 QDMA Driver (in rawdev).** + + The DPAA2 QDMA is an implementation of the rawdev API, that provide means + to initiate a DMA transaction from CPU. The initiated DMA is performed + without CPU being involved in the actual DMA transaction. + + See the :doc:`../rawdevs/dpaa2_qdma` guide for more details. + API Changes ----------- -- 1.9.1