748f4dbd49352c0e1473c3ec44fbb3969ddff649
[dpdk.git] / doc / guides / rawdevs / octeontx2_dma.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2019 Marvell International Ltd.
3
4 OCTEON TX2 DMA Driver
5 =====================
6
7 OCTEON TX2 has an internal DMA unit which can be used by applications to initiate
8 DMA transaction internally, from/to host when OCTEON TX2 operates in PCIe End
9 Point mode. The DMA PF function supports 8 VFs corresponding to 8 DMA queues.
10 Each DMA queue was exposed as a VF function when SRIOV enabled.
11
12 Features
13 --------
14
15 This DMA PMD supports below 3 modes of memory transfers
16
17 #. Internal - OCTEON TX2 DRAM to DRAM without core intervention
18
19 #. Inbound  - Host DRAM to OCTEON TX2 DRAM without host/OCTEON TX2 cores involvement
20
21 #. Outbound - OCTEON TX2 DRAM to Host DRAM without host/OCTEON TX2 cores involvement
22
23 Prerequisites and Compilation procedure
24 ---------------------------------------
25
26    See :doc:`../platform/octeontx2` for setup information.
27
28
29 Pre-Installation Configuration
30 ------------------------------
31
32 Config File Options
33 ~~~~~~~~~~~~~~~~~~~
34
35 The following options can be modified in the ``config`` file.
36
37 - ``CONFIG_RTE_LIBRTE_PMD_OCTEONTX2_DMA_RAWDEV`` (default ``y``)
38
39   Toggle compilation of the ``lrte_pmd_octeontx2_dma`` driver.
40
41 Enabling logs
42 -------------
43
44 For enabling logs, use the following EAL parameter:
45
46 .. code-block:: console
47
48    ./your_dma_application <EAL args> --log-level=pmd.raw.octeontx2.dpi,<level>
49
50 Using ``pmd.raw.octeontx2.dpi`` as log matching criteria, all Event PMD logs
51 can be enabled which are lower than logging ``level``.
52
53 Initialization
54 --------------
55
56 The number of DMA VFs (queues) enabled can be controlled by setting sysfs
57 entry, `sriov_numvfs` for the corresponding PF driver.
58
59 .. code-block:: console
60
61  echo <num_vfs> > /sys/bus/pci/drivers/octeontx2-dpi/0000\:05\:00.0/sriov_numvfs
62
63 Once the required VFs are enabled, to be accessible from DPDK, VFs need to be
64 bound to vfio-pci driver.
65
66 Device Configuration
67 --------------------
68
69 Configuring DMA rawdev device is done using the ``rte_rawdev_configure()``
70 API, which takes the mempool as parameter. PMD uses this pool to submit DMA
71 commands to HW.
72
73 The following code shows how the device is configured
74
75 .. code-block:: c
76
77    struct dpi_rawdev_conf_s conf = {0};
78    struct rte_rawdev_info rdev_info = {.dev_private = &conf};
79
80    conf.chunk_pool = (void *)rte_mempool_create_empty(...);
81    rte_mempool_set_ops_byname(conf.chunk_pool, rte_mbuf_platform_mempool_ops(), NULL);
82    rte_mempool_populate_default(conf.chunk_pool);
83
84    rte_rawdev_configure(dev_id, (rte_rawdev_obj_t)&rdev_info);
85
86 Performing Data Transfer
87 ------------------------
88
89 To perform data transfer using OCTEON TX2 DMA rawdev devices use standard
90 ``rte_rawdev_enqueue_buffers()`` and ``rte_rawdev_dequeue_buffers()`` APIs.