driver-api/dmaengine/client.rst

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
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
40    .. code-block:: c
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
95     setting the DMA_PREP_REPEAT transfer flag.
97   A non-NULL return of this transfer API represents a "descriptor" for
102   .. code-block:: c
130   .. code-block:: c
153      for submission prior to callback function being invoked, so
157      For cyclic DMA, a callback function may wish to terminate the
161      locks before calling the callback function which may cause a
176   .. code-block:: c
189     after their transfer completion callback has run for the descriptor.
190     If no completion callback has been defined for the transfer, then the
192     In other words: if the aim is to read back metadata after the transfer is
195   .. code-block:: c
205   .. code-block:: c
214     - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
220       3. submit the transfer
222     - DMA_DEV_TO_MEM:
227       3. submit the transfer
228       4. when the transfer is completed, the metadata should be available in the
233     - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
241       5. submit the transfer
243     - DMA_DEV_TO_MEM:
246       2. submit the transfer
247       3. on transfer completion, use dmaengine_desc_get_metadata_ptr() to get
254      is no longer valid after the transfer has been completed (valid up to the
267    .. code-block:: c
279       After calling ``dmaengine_submit()`` the submitted transfer descriptor
296    .. code-block:: c
301 ------------
305    .. code-block:: c
315    Two variants of this function are available.
321    is safe to free the memory accessed by the DMA transfer or free resources
324    dmaengine_terminate_sync() will wait for the transfer and any running
325    complete callbacks to finish before it returns. But the function must not be
332    .. code-block:: c
340    .. code-block:: c
349    .. code-block:: c
371    .. code-block:: c
377    This function should be used after dmaengine_terminate_async() to synchronize
378    the termination of the DMA channel to the current context. The function will
379    wait for the transfer and any running complete callbacks to finish before it
382    If dmaengine_terminate_async() is used to stop the DMA channel this function
387    The behavior of this function is undefined if dma_async_issue_pending() has
388    been called between dmaengine_terminate_async() and this function.