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.