[dpdk-dev] [PATCH v1 9/9] raw/octeontx2_dma: add documentation

jerinj at marvell.com jerinj at marvell.com
Sat Jun 1 20:20:30 CEST 2019

From: Satha Rao <skoteshwar at marvell.com>

Add documentation and update MAINTAINERS file.

Cc: John McNamara <john.mcnamara at intel.com>
Cc: Thomas Monjalon <thomas at monjalon.net>

Signed-off-by: Satha Rao <skoteshwar at marvell.com>
Signed-off-by: Vamsi Attunuru <vattunuru at marvell.com>
Signed-off-by: Jerin Jacob <jerinj at marvell.com>
 MAINTAINERS                          |   6 ++
 doc/guides/platform/octeontx2.rst    |   5 ++
 doc/guides/rawdevs/index.rst         |   1 +
 doc/guides/rawdevs/octeontx2_dma.rst | 114 +++++++++++++++++++++++++++
 4 files changed, 126 insertions(+)
 create mode 100644 doc/guides/rawdevs/octeontx2_dma.rst

index 74ac6d41f..2434fc18c 100644
@@ -1062,6 +1062,12 @@ M: Nipun Gupta <nipun.gupta at nxp.com>
 F: drivers/raw/dpaa2_cmdif/
 F: doc/guides/rawdevs/dpaa2_cmdif.rst
+M: Satha Rao <skoteshwar at marvell.com>
+M: Vamsi Attunuru <vattunuru at marvell.com>
+F: drivers/raw/octeontx2_dma/
+F: doc/guides/rawdevs/octeontx2_dma.rst
 Packet processing
diff --git a/doc/guides/platform/octeontx2.rst b/doc/guides/platform/octeontx2.rst
index c9ea45647..e6bfa2052 100644
--- a/doc/guides/platform/octeontx2.rst
+++ b/doc/guides/platform/octeontx2.rst
@@ -101,6 +101,9 @@ This section lists dataplane H/W block(s) available in OCTEON TX2 SoC.
 #. **Mempool Driver**
    See :doc:`../mempool/octeontx2` for NPA mempool driver information.
+#. **DMA Rawdev Driver**
+   See :doc:`../rawdevs/octeontx2_dma` for DMA driver information.
 Procedure to Setup Platform
@@ -143,6 +146,8 @@ compatible board:
         # Enable if netdev VF driver required
+        # Enable if OCTEONTX2 DMA PF driver required
 2. **ARM64 Linux Tool Chain**
diff --git a/doc/guides/rawdevs/index.rst b/doc/guides/rawdevs/index.rst
index 7c3bd9586..1351d14e4 100644
--- a/doc/guides/rawdevs/index.rst
+++ b/doc/guides/rawdevs/index.rst
@@ -14,3 +14,4 @@ application through rawdev API.
+    octeontx2_dma
diff --git a/doc/guides/rawdevs/octeontx2_dma.rst b/doc/guides/rawdevs/octeontx2_dma.rst
new file mode 100644
index 000000000..7409c17ab
--- /dev/null
+++ b/doc/guides/rawdevs/octeontx2_dma.rst
@@ -0,0 +1,114 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2019 Marvell International Ltd.
+OCTEON TX2 has an internal DMA unit which can be used by applications to initiate
+DMA transaction internally, from/to host when OCTEON TX2 operates in PCIe End
+Point mode. The DMA PF function supports 8 VFs corresponding to 8 DMA queues.
+Each DMA queue was exposed as a VF function when SRIOV enabled.
+This DMA PMD supports below 3 modes of memory transfers
+#. Internal - OCTEON TX2 DRAM to DRAM without core intervention
+#. Inbound  - Host DRAM to OCTEON TX2 DRAM without host/OCTEON TX2 cores involvement
+#. Outbound - OCTEON TX2 DRAM to Host DRAM without host/OCTEON TX2 cores involvement
+Prerequisites and Compilation procedure
+   See :doc:`../platform/octeontx2` for setup information.
+Pre-Installation Configuration
+Config File Options
+The following options can be modified in the ``config`` file.
+  Toggle compilation of the ``lrte_pmd_octeontx2_dma`` driver.
+Enabling logs
+For enabling logs, use the following EAL parameter:
+.. code-block:: console
+   ./your_dma_application <EAL args> --log-level=pmd.raw.octeontx2.dpi,<level>
+Using ``pmd.raw.octeontx2.dpi`` as log matching criteria, all Event PMD logs
+can be enabled which are lower than logging ``level``.
+The number of DMA VFs (queues) enabled can be controlled by setting sysfs
+entry, `sriov_numvfs` for the corresponding PF driver.
+.. code-block:: console
+ echo <num_vfs> > /sys/bus/pci/drivers/octeontx2-dpi/0000\:05\:00.0/sriov_numvfs
+Once the required VFs are enabled, to be accessible from DPDK, VFs need to be
+bound to vfio-pci driver.
+Device Setup
+The DPI DMA HW device will need to be bound to a user-space IO driver for use.
+The script ``dpdk-devbind.py`` script included with DPDK can be used to view the
+state of the devices and to bind them to a suitable DPDK-supported kernel driver.
+When querying the status of the devices, they will appear under the category of
+"dma devices", i.e. the command ``dpdk-devbind.py --status-dev dma`` can be used
+to see the state of those devices alone.
+Device Configuration
+Configuring DMA rawdev device is done using the ``rte_rawdev_configure()``
+API, which takes the mempool as parameter. PMD uses this pool to submit DMA
+commands to HW.
+The following code shows how the device is configured
+.. code-block:: c
+   struct dpi_rawdev_conf_s conf = {0};
+   struct rte_rawdev_info rdev_info = {.dev_private = &conf};
+   conf.chunk_pool = (void *)rte_mempool_create_empty(...);
+   rte_mempool_set_ops_byname(conf.chunk_pool, rte_mbuf_platform_mempool_ops(), NULL);
+   rte_mempool_populate_default(conf.chunk_pool);
+   rte_rawdev_configure(dev_id, (rte_rawdev_obj_t)&rdev_info);
+Performing Data Transfer
+To perform data transfer using OCTEON TX2 DMA rawdev devices use standard
+``rte_rawdev_enqueue_buffers()`` and ``rte_rawdev_dequeue_buffers()`` APIs.
+Self test
+On EAL initialization, dma devices will be probed and populated into the
+raw devices. The rawdev ID of the device can be obtained using
+* Invoke ``rte_rawdev_get_dev_id("DPI:x")`` from the application
+  where x is the VF device's bus id specified in "bus:device.func" format. Use this
+  index for further rawdev function calls.
+* This PMD supports driver self test, to test DMA internal mode from test
+  application one can directly calls
+  ``rte_rawdev_selftest(rte_rawdev_get_dev_id("DPI:x"))``

More information about the dev mailing list