1..  SPDX-License-Identifier: BSD-3-Clause
2    Copyright(c) 2019 Marvell International Ltd.
3
4OCTEON TX2 DMA Driver
5=====================
6
7OCTEON TX2 has an internal DMA unit which can be used by applications to initiate
8DMA transaction internally, from/to host when OCTEON TX2 operates in PCIe End
9Point mode. The DMA PF function supports 8 VFs corresponding to 8 DMA queues.
10Each DMA queue was exposed as a VF function when SRIOV enabled.
11
12Features
13--------
14
15This 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
23Prerequisites and Compilation procedure
24---------------------------------------
25
26   See :doc:`../platform/octeontx2` for setup information.
27
28
29Enabling logs
30-------------
31
32For enabling logs, use the following EAL parameter:
33
34.. code-block:: console
35
36   ./your_dma_application <EAL args> --log-level=pmd.raw.octeontx2.dpi,<level>
37
38Using ``pmd.raw.octeontx2.dpi`` as log matching criteria, all Event PMD logs
39can be enabled which are lower than logging ``level``.
40
41Initialization
42--------------
43
44The number of DMA VFs (queues) enabled can be controlled by setting sysfs
45entry, `sriov_numvfs` for the corresponding PF driver.
46
47.. code-block:: console
48
49 echo <num_vfs> > /sys/bus/pci/drivers/octeontx2-dpi/0000\:05\:00.0/sriov_numvfs
50
51Once the required VFs are enabled, to be accessible from DPDK, VFs need to be
52bound to vfio-pci driver.
53
54Device Setup
55-------------
56
57The OCTEON TX2 DPI DMA HW devices will need to be bound to a
58user-space IO driver for use. The script ``dpdk-devbind.py`` script
59included with DPDK can be used to view the state of the devices and to bind
60them to a suitable DPDK-supported kernel driver. When querying the status
61of the devices, they will appear under the category of "Misc (rawdev)
62devices", i.e. the command ``dpdk-devbind.py --status-dev misc`` can be
63used to see the state of those devices alone.
64
65Device Configuration
66--------------------
67
68Configuring DMA rawdev device is done using the ``rte_rawdev_configure()``
69API, which takes the mempool as parameter. PMD uses this pool to submit DMA
70commands to HW.
71
72The following code shows how the device is configured
73
74.. code-block:: c
75
76   struct dpi_rawdev_conf_s conf = {0};
77   struct rte_rawdev_info rdev_info = {.dev_private = &conf};
78
79   conf.chunk_pool = (void *)rte_mempool_create_empty(...);
80   rte_mempool_set_ops_byname(conf.chunk_pool, rte_mbuf_platform_mempool_ops(), NULL);
81   rte_mempool_populate_default(conf.chunk_pool);
82
83   rte_rawdev_configure(dev_id, (rte_rawdev_obj_t)&rdev_info, sizeof(conf));
84
85Performing Data Transfer
86------------------------
87
88To perform data transfer using OCTEON TX2 DMA rawdev devices use standard
89``rte_rawdev_enqueue_buffers()`` and ``rte_rawdev_dequeue_buffers()`` APIs.
90
91Self test
92---------
93
94On EAL initialization, dma devices will be probed and populated into the
95raw devices. The rawdev ID of the device can be obtained using
96
97* Invoke ``rte_rawdev_get_dev_id("DPI:x")`` from the application
98  where x is the VF device's bus id specified in "bus:device.func" format. Use this
99  index for further rawdev function calls.
100
101* This PMD supports driver self test, to test DMA internal mode from test
102  application one can directly calls
103  ``rte_rawdev_selftest(rte_rawdev_get_dev_id("DPI:x"))``
104