Documentation/driver-api/dmaengine/client.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/dmaengine/client.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/dmaengine/client.rst
Extension
.rst
Size
13748 bytes
Lines
389
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

====================
DMA Engine API Guide
====================

Vinod Koul <vinod dot koul at intel.com>

.. note:: For DMA Engine usage in async_tx please see:
          ``Documentation/crypto/async-tx-api.rst``


Below is a guide to device driver writers on how to use the Slave-DMA API of the
DMA Engine. This is applicable only for slave DMA usage only.

DMA usage
=========

The slave DMA usage consists of following steps:

- Allocate a DMA slave channel

- Set slave and controller specific parameters

- Get a descriptor for transaction

- Submit the transaction

- Issue pending requests and wait for callback notification

The details of these operations are:

1. Allocate a DMA slave channel

   Channel allocation is slightly different in the slave DMA context,
   client drivers typically need a channel from a particular DMA
   controller only and even in some cases a specific channel is desired.
   To request a channel dma_request_chan() API is used.

   Interface:

   .. code-block:: c

      struct dma_chan *dma_request_chan(struct device *dev, const char *name);

   Which will find and return the ``name`` DMA channel associated with the 'dev'
   device. The association is done via DT, ACPI or board file based
   dma_slave_map matching table.

   A channel allocated via this interface is exclusive to the caller,
   until dma_release_channel() is called.

2. Set slave and controller specific parameters

   Next step is always to pass some specific information to the DMA
   driver. Most of the generic information which a slave DMA can use
   is in struct dma_slave_config. This allows the clients to specify
   DMA direction, DMA addresses, bus widths, DMA burst lengths etc
   for the peripheral.

   If some DMA controllers have more parameters to be sent then they
   should try to embed struct dma_slave_config in their controller
   specific structure. That gives flexibility to client to pass more
   parameters, if required.

   Interface:

   .. code-block:: c

      int dmaengine_slave_config(struct dma_chan *chan,
			struct dma_slave_config *config)

Annotation

Implementation Notes