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 Setup
  67 -------------
  68
  69 The OCTEON TX2 DPI DMA HW devices will need to be bound to a
  70 user-space IO driver for use. The script ``dpdk-devbind.py`` script
  71 included with DPDK can be used to view the state of the devices and to bind
  72 them to a suitable DPDK-supported kernel driver. When querying the status
  73 of the devices, they will appear under the category of "Misc (rawdev)
  74 devices", i.e. the command ``dpdk-devbind.py --status-dev misc`` can be
  75 used to see the state of those devices alone.
  76
  77 Device Configuration
  78 --------------------
  79
  80 Configuring DMA rawdev device is done using the ``rte_rawdev_configure()``
  81 API, which takes the mempool as parameter. PMD uses this pool to submit DMA
  82 commands to HW.
  83
  84 The following code shows how the device is configured
  85
  86 .. code-block:: c
  87
  88    struct dpi_rawdev_conf_s conf = {0};
  89    struct rte_rawdev_info rdev_info = {.dev_private = &conf};
  90
  91    conf.chunk_pool = (void *)rte_mempool_create_empty(...);
  92    rte_mempool_set_ops_byname(conf.chunk_pool, rte_mbuf_platform_mempool_ops(), NULL);
  93    rte_mempool_populate_default(conf.chunk_pool);
  94
  95    rte_rawdev_configure(dev_id, (rte_rawdev_obj_t)&rdev_info, sizeof(conf));
  96
  97 Performing Data Transfer
  98 ------------------------
  99
 100 To perform data transfer using OCTEON TX2 DMA rawdev devices use standard
 101 ``rte_rawdev_enqueue_buffers()`` and ``rte_rawdev_dequeue_buffers()`` APIs.
 102
 103 Self test
 104 ---------
 105
 106 On EAL initialization, dma devices will be probed and populated into the
 107 raw devices. The rawdev ID of the device can be obtained using
 108
 109 * Invoke ``rte_rawdev_get_dev_id("DPI:x")`` from the application
 110   where x is the VF device's bus id specified in "bus:device.func" format. Use this
 111   index for further rawdev function calls.
 112
 113 * This PMD supports driver self test, to test DMA internal mode from test
 114   application one can directly calls
 115   ``rte_rawdev_selftest(rte_rawdev_get_dev_id("DPI:x"))``