doc/guides/prog_guide/dmadev.rst

   1 .. SPDX-License-Identifier: BSD-3-Clause
   2    Copyright 2021 HiSilicon Limited
   3
   4 DMA Device Library
   5 ==================
   6
   7 The DMA library provides a DMA device framework for management and provisioning
   8 of hardware and software DMA poll mode drivers, defining generic API which
   9 support a number of different DMA operations.
  10
  11
  12 Design Principles
  13 -----------------
  14
  15 The DMA framework provides a generic DMA device framework which supports both
  16 physical (hardware) and virtual (software) DMA devices, as well as a generic DMA
  17 API which allows DMA devices to be managed and configured, and supports DMA
  18 operations to be provisioned on DMA poll mode driver.
  19
  20 .. _figure_dmadev:
  21
  22 .. figure:: img/dmadev.*
  23
  24 The above figure shows the model on which the DMA framework is built on:
  25
  26  * The DMA controller could have multiple hardware DMA channels (aka. hardware
  27    DMA queues), each hardware DMA channel should be represented by a dmadev.
  28  * The dmadev could create multiple virtual DMA channels, each virtual DMA
  29    channel represents a different transfer context.
  30  * The DMA operation request must be submitted to the virtual DMA channel.
  31
  32
  33 Device Management
  34 -----------------
  35
  36 Device Creation
  37 ~~~~~~~~~~~~~~~
  38
  39 Physical DMA controllers are discovered during the PCI probe/enumeration of the
  40 EAL function which is executed at DPDK initialization, this is based on their
  41 PCI BDF (bus/bridge, device, function). Specific physical DMA controllers, like
  42 other physical devices in DPDK can be listed using the EAL command line options.
  43
  44 The dmadevs are dynamically allocated by using the function
  45 ``rte_dma_pmd_allocate`` based on the number of hardware DMA channels.
  46
  47
  48 Device Identification
  49 ~~~~~~~~~~~~~~~~~~~~~
  50
  51 Each DMA device, whether physical or virtual is uniquely designated by two
  52 identifiers:
  53
  54 - A unique device index used to designate the DMA device in all functions
  55   exported by the DMA API.
  56
  57 - A device name used to designate the DMA device in console messages, for
  58   administration or debugging purposes.
  59
  60
  61 Device Features and Capabilities
  62 --------------------------------
  63
  64 DMA devices may support different feature sets. The ``rte_dma_info_get`` API
  65 can be used to get the device info and supported features.
  66
  67 Silent mode is a special device capability which does not require the
  68 application to invoke dequeue APIs.
  69
  70
  71 Enqueue / Dequeue APIs
  72 ~~~~~~~~~~~~~~~~~~~~~~
  73
  74 Enqueue APIs such as ``rte_dma_copy`` and ``rte_dma_fill`` can be used to
  75 enqueue operations to hardware. If an enqueue is successful, a ``ring_idx`` is
  76 returned. This ``ring_idx`` can be used by applications to track per operation
  77 metadata in an application-defined circular ring.
  78
  79 The ``rte_dma_submit`` API is used to issue doorbell to hardware.
  80 Alternatively the ``RTE_DMA_OP_FLAG_SUBMIT`` flag can be passed to the enqueue
  81 APIs to also issue the doorbell to hardware.
  82
  83 There are two dequeue APIs ``rte_dma_completed`` and
  84 ``rte_dma_completed_status``, these are used to obtain the results of the
  85 enqueue requests. ``rte_dma_completed`` will return the number of successfully
  86 completed operations. ``rte_dma_completed_status`` will return the number of
  87 completed operations along with the status of each operation (filled into the
  88 ``status`` array passed by user). These two APIs can also return the last
  89 completed operation's ``ring_idx`` which could help user track operations within
  90 their own application-defined rings.