driver-api/dmaengine/client.rst

2 DMA Engine API Guide
7 .. note:: For DMA Engine usage in async_tx please see:
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
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
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
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
90     interleaved DMA transfers are also possible if supported by the channel by
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.
130   added and the descriptor must then be submitted. Some DMA engine
139      case for slave/cyclic DMA.
141      For slave DMA, the subsequent transaction may not be available
143      slave DMA callbacks are permitted to prepare and submit a new
146      For cyclic DMA, a callback function may wish to terminate the
147      DMA via dmaengine_terminate_async().
149      Therefore, it is important that DMA engine drivers drop any
153      Note that callbacks will always be invoked from the DMA
172     The metadata buffer is allocated/managed by the DMA driver. The client
176     Becasue the DMA driver manages the memory area containing the metadata,
228       4. use dmaengine_desc_set_metadata_len()  to tell the DMA engine the
252    added, it must be placed on the DMA engine drivers pending queue.
260    This returns a cookie can be used to check the progress of DMA engine
261    activity via other DMA engine calls not covered in this document.
263    dmaengine_submit() will not start the DMA operation, it merely adds
269       (``struct dma_async_tx_descriptor``) belongs to the DMA engine.
273 5. Issue pending DMA requests and wait for callback notification
279    On completion of each DMA operation, the next in queue is started and
300    This causes all activity for the DMA channel to be stopped, and may
301    discard data in the DMA FIFO which hasn't been fully transferred.
306    dmaengine_terminate_async() might not wait until the DMA has been fully
310    is safe to free the memory accessed by the DMA transfer or free resources
325    This pauses activity on the DMA channel without data loss.
333    Resume a previously paused DMA channel. It is invalid to resume a
349    completion of a specific DMA transaction.
353       Not all DMA engine drivers can return reliable information for
354       a running DMA channel. It is recommended that DMA engine users
364    Synchronize the termination of the DMA channel to the current context.
367    the termination of the DMA channel to the current context. The function will
371    If dmaengine_terminate_async() is used to stop the DMA channel this function