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
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
35    controller only and even in some cases a specific channel is desired.
36    To request a channel dma_request_chan() API is used.
40    .. code-block:: c
44    Which will find and return the ``name`` DMA channel associated with the 'dev'
48    A channel allocated via this interface is exclusive to the caller,
54    driver. Most of the generic information which a slave DMA can use
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
130   .. code-block:: c
176   .. code-block:: c
193     completed, then the client must use completion callback.
195   .. code-block:: c
205   .. code-block:: c
214     - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
218       2. use dmaengine_desc_attach_metadata() to attach the buffer to the
222     - DMA_DEV_TO_MEM:
225       2. use dmaengine_desc_attach_metadata() to attach the buffer to the
233     - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
236       2. use dmaengine_desc_get_metadata_ptr() to get the pointer to the
239       4. use dmaengine_desc_set_metadata_len()  to tell the DMA engine the
243     - DMA_DEV_TO_MEM:
247       3. on transfer completion, use dmaengine_desc_get_metadata_ptr() to get
257      Mixed use of DESC_METADATA_CLIENT / DESC_METADATA_ENGINE is not allowed,
258      client drivers must use either of the modes per descriptor.
267    .. code-block:: c
287    issue_pending API. If channel is idle then the first transaction in
296    .. code-block:: c
301 ------------
305    .. code-block:: c
311    This causes all activity for the DMA channel to be stopped, and may
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
345    channel which is not currently paused.
349    .. code-block:: c
354    This can be used to check the status of the channel. Please see
365       a running DMA channel. It is recommended that DMA engine users
366       pause or stop (via dmaengine_terminate_all()) the channel before
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