From 13c5cbafa60a90fa4f5bb519ef213f1c7c08e745 Mon Sep 17 00:00:00 2001 From: Nipun Gupta Date: Fri, 4 May 2018 15:41:29 +0530 Subject: [PATCH] doc: add DPAA2 CMDIF rawdev guide Signed-off-by: Nipun Gupta Acked-by: Marko Kovacevic Acked-by: Shreyansh Jain --- MAINTAINERS | 1 + doc/guides/rawdevs/dpaa2_cmdif.rst | 144 +++++++++++++++++++++++++ doc/guides/rawdevs/index.rst | 1 + doc/guides/rel_notes/release_18_05.rst | 12 +++ 4 files changed, 158 insertions(+) create mode 100644 doc/guides/rawdevs/dpaa2_cmdif.rst diff --git a/MAINTAINERS b/MAINTAINERS index bfad7d575d..7105920f35 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -854,6 +854,7 @@ F: doc/guides/rawdevs/dpaa2_qdma.rst DPAA2 CMDIF M: Nipun Gupta F: drivers/raw/dpaa2_cmdif/ +F: doc/guides/rawdevs/dpaa2_cmdif.rst Packet processing diff --git a/doc/guides/rawdevs/dpaa2_cmdif.rst b/doc/guides/rawdevs/dpaa2_cmdif.rst new file mode 100644 index 0000000000..20a60993c3 --- /dev/null +++ b/doc/guides/rawdevs/dpaa2_cmdif.rst @@ -0,0 +1,144 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright 2018 NXP + +NXP DPAA2 CMDIF Driver +====================== + +The DPAA2 CMDIF is an implementation of the rawdev API, that provides +communication between the GPP and AIOP (Firmware). This is achieved +via using the DPCI devices exposed by MC for GPP <--> AIOP interaction. + +More information can be found at `NXP Official Website +`_. + +Features +-------- + +The DPAA2 CMDIF implements following features in the rawdev API; + +- Getting the object ID of the device (DPCI) using attributes +- I/O to and from the AIOP device using DPCI + +Supported DPAA2 SoCs +-------------------- + +- LS2084A/LS2044A +- LS2088A/LS2048A +- LS1088A/LS1048A + +Prerequisites +------------- + +There are three main pre-requisities for executing DPAA2 CMDIF 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 CMDIF 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 SDK **2.0+**. +- MC Firmware version **10.0.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_CMDIF_RAWDEV`` (default ``y``) + + Toggle compilation of the ``lrte_pmd_dpaa2_cmdif`` driver. + +Enabling logs +------------- + +For enabling logs, use the following EAL parameter: + +.. code-block:: console + + ./your_cmdif_application --log-level=pmd.raw.dpaa2.cmdif, + +Using ``pmd.raw.dpaa2.cmdif`` as log matching criteria, all Event PMD logs can be +enabled which are lower than logging ``level``. + +Driver Compilation +~~~~~~~~~~~~~~~~~~ + +To compile the DPAA2 CMDIF 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 CMDIF is exposed as a vdev device which consists of dpci devices. +On EAL initialization, dpci devices will be probed and then vdev device +can be created from the application code by + +* Invoking ``rte_vdev_init("dpaa2_dpci")`` from the application + +* Using ``--vdev="dpaa2_dpci"`` in the EAL options, which will call + rte_vdev_init() internally + +Example: + +.. code-block:: console + + ./your_cmdif_application --vdev="dpaa2_dpci" + +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 index 29b4f6c076..7769083559 100644 --- a/doc/guides/rawdevs/index.rst +++ b/doc/guides/rawdevs/index.rst @@ -11,4 +11,5 @@ application through rawdev API. :maxdepth: 2 :numbered: + dpaa2_cmdif dpaa2_qdma diff --git a/doc/guides/rel_notes/release_18_05.rst b/doc/guides/rel_notes/release_18_05.rst index 3bb312f079..7187348520 100644 --- a/doc/guides/rel_notes/release_18_05.rst +++ b/doc/guides/rel_notes/release_18_05.rst @@ -154,6 +154,17 @@ New Features See the :doc:`../rawdevs/dpaa2_qdma` guide for more details. +* **Added DPAA2 Command Interface Driver (in rawdev).** + + The DPAA2 CMDIF is an implementation of the rawdev API, that provides + communication between the GPP and NXP's QorIQ based AIOP Block (Firmware). + Advanced IO Processor i.e. AIOP is clusters of programmable RISC engines + optimised for flexible networking and I/O operations. The communication + between GPP and AIOP is achieved via using DPCI devices exposed by MC for + GPP <--> AIOP interaction. + + See the :doc:`../rawdevs/dpaa2_cmdif` guide for more details. + * **Added device event monitor framework.** Added a general device event monitor framework at EAL, for device dynamic management. @@ -455,6 +466,7 @@ The libraries prepended with a plus sign were incremented in this version. librte_pmd_bond.so.2 librte_pmd_i40e.so.2 librte_pmd_ixgbe.so.2 + + librte_pmd_dpaa2_cmdif.so.1 + librte_pmd_dpaa2_qdma.so.1 librte_pmd_ring.so.2 librte_pmd_softnic.so.1 -- 2.20.1