Lines Matching +full:dma +full:- +full:engine
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 - peripheral_dma_vec: DMA an array of scatter gather buffers from/to a
87 - dma_cyclic: Perform a cyclic DMA operation from/to a peripheral till the
90 - interleaved_dma: This is common to Slave as well as M2M clients. For slave
94 interleaved DMA transfers are also possible if supported by the channel by
97 A non-NULL return of this transfer API represents a "descriptor" for
102 .. code-block:: c
123 the DMA operation prior to calling dmaengine_prep_slave_sg(), and must
124 keep the scatterlist mapped until the DMA operation has completed.
125 The scatterlist must be mapped using the DMA struct device.
127 called using the DMA struct device, too.
130 .. code-block:: c
141 added and the descriptor must then be submitted. Some DMA engine
150 case for slave/cyclic DMA.
152 For slave DMA, the subsequent transaction may not be available
154 slave DMA callbacks are permitted to prepare and submit a new
157 For cyclic DMA, a callback function may wish to terminate the
158 DMA via dmaengine_terminate_async().
160 Therefore, it is important that DMA engine drivers drop any
164 Note that callbacks will always be invoked from the DMA
176 .. code-block:: c
183 The metadata buffer is allocated/managed by the DMA driver. The client
187 Because the DMA driver manages the memory area containing the metadata,
195 .. code-block:: c
205 .. code-block:: c
214 - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
222 - DMA_DEV_TO_MEM:
233 - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
237 engine's metadata area
239 4. use dmaengine_desc_set_metadata_len() to tell the DMA engine the
243 - DMA_DEV_TO_MEM:
248 the pointer to the engine's metadata area
263 added, it must be placed on the DMA engine drivers pending queue.
267 .. code-block:: c
271 This returns a cookie can be used to check the progress of DMA engine
272 activity via other DMA engine calls not covered in this document.
274 dmaengine_submit() will not start the DMA operation, it merely adds
280 (``struct dma_async_tx_descriptor``) belongs to the DMA engine.
284 5. Issue pending DMA requests and wait for callback notification
290 On completion of each DMA operation, the next in queue is started and
296 .. code-block:: c
301 ------------
305 .. code-block:: c
311 This causes all activity for the DMA channel to be stopped, and may
312 discard data in the DMA FIFO which hasn't been fully transferred.
317 dmaengine_terminate_async() might not wait until the DMA has been fully
321 is safe to free the memory accessed by the DMA transfer or free resources
332 .. code-block:: c
336 This pauses activity on the DMA channel without data loss.
340 .. code-block:: c
344 Resume a previously paused DMA channel. It is invalid to resume a
349 .. code-block:: c
360 completion of a specific DMA transaction.
364 Not all DMA engine drivers can return reliable information for
365 a running DMA channel. It is recommended that DMA engine users
371 .. code-block:: c
375 Synchronize the termination of the DMA channel to the current context.
378 the termination of the DMA channel to the current context. The function will
382 If dmaengine_terminate_async() is used to stop the DMA channel this function