driver-api/dmaengine/client.rst

2 DMA Engine API Guide
7 .. note:: For DMA Engine usage in async_tx please see:
8           ``Documentation/crypto/async-tx-api.rst``
11 Below is a guide to device driver writers on how to use the Slave-DMA API of the
12 DMA Engine. This is applicable only for slave DMA usage only.
14 DMA usage
17 The slave DMA usage consists of following steps:
19 - Allocate a DMA slave channel
21 - Set slave and controller specific parameters
23 - Get a descriptor for transaction
25 - Submit the transaction
27 - Issue pending requests and wait for callback notification
31 1. Allocate a DMA slave channel
33    Channel allocation is slightly different in the slave DMA context,
34    client drivers typically need a channel from a particular DMA
40    .. code-block:: c
44    Which will find and return the ``name`` DMA channel associated with the 'dev'
53    Next step is always to pass some specific information to the DMA
54    driver. Most of the generic information which a slave DMA can use
56    DMA direction, DMA addresses, bus widths, DMA burst lengths etc
59    If some DMA controllers have more parameters to be sent then they
66    .. code-block:: c
79   DMA-engine are:
81   - slave_sg: DMA a list of scatter gather buffers from/to a peripheral
83   - dma_cyclic: Perform a cyclic DMA operation from/to a peripheral till the
86   - interleaved_dma: This is common to Slave as well as M2M clients. For slave
90     interleaved DMA transfers are also possible if supported by the channel by
93   A non-NULL return of this transfer API represents a "descriptor" for
98   .. code-block:: c
114   the DMA operation prior to calling dmaengine_prep_slave_sg(), and must
115   keep the scatterlist mapped until the DMA operation has completed.
116   The scatterlist must be mapped using the DMA struct device.
118   called using the DMA struct device, too.
121   .. code-block:: c
132   added and the descriptor must then be submitted. Some DMA engine
141      case for slave/cyclic DMA.
143      For slave DMA, the subsequent transaction may not be available
145      slave DMA callbacks are permitted to prepare and submit a new
148      For cyclic DMA, a callback function may wish to terminate the
149      DMA via dmaengine_terminate_async().
151      Therefore, it is important that DMA engine drivers drop any
155      Note that callbacks will always be invoked from the DMA
167   .. code-block:: c
174     The metadata buffer is allocated/managed by the DMA driver. The client
178     Because the DMA driver manages the memory area containing the metadata,
186   .. code-block:: c
196   .. code-block:: c
205     - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
213     - DMA_DEV_TO_MEM:
224     - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
228          engine's metadata area
230       4. use dmaengine_desc_set_metadata_len()  to tell the DMA engine the
234     - DMA_DEV_TO_MEM:
239          the pointer to the engine's metadata area
254    added, it must be placed on the DMA engine drivers pending queue.
258    .. code-block:: c
262    This returns a cookie can be used to check the progress of DMA engine
263    activity via other DMA engine calls not covered in this document.
265    dmaengine_submit() will not start the DMA operation, it merely adds
271       (``struct dma_async_tx_descriptor``) belongs to the DMA engine.
275 5. Issue pending DMA requests and wait for callback notification
281    On completion of each DMA operation, the next in queue is started and
287    .. code-block:: c
292 ------------
296    .. code-block:: c
302    This causes all activity for the DMA channel to be stopped, and may
303    discard data in the DMA FIFO which hasn't been fully transferred.
308    dmaengine_terminate_async() might not wait until the DMA has been fully
312    is safe to free the memory accessed by the DMA transfer or free resources
323    .. code-block:: c
327    This pauses activity on the DMA channel without data loss.
331    .. code-block:: c
335    Resume a previously paused DMA channel. It is invalid to resume a
340    .. code-block:: c
351    completion of a specific DMA transaction.
355       Not all DMA engine drivers can return reliable information for
356       a running DMA channel. It is recommended that DMA engine users
362    .. code-block:: c
366    Synchronize the termination of the DMA channel to the current context.
369    the termination of the DMA channel to the current context. The function will
373    If dmaengine_terminate_async() is used to stop the DMA channel this function