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   - 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
121   .. code-block:: c
167   .. code-block:: c
184     completed, then the client must use completion callback.
186   .. code-block:: c
196   .. code-block:: c
205     - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
209       2. use dmaengine_desc_attach_metadata() to attach the buffer to the
213     - DMA_DEV_TO_MEM:
216       2. use dmaengine_desc_attach_metadata() to attach the buffer to the
224     - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
227       2. use dmaengine_desc_get_metadata_ptr() to get the pointer to the
230       4. use dmaengine_desc_set_metadata_len()  to tell the DMA engine the
234     - DMA_DEV_TO_MEM:
238       3. on transfer completion, use dmaengine_desc_get_metadata_ptr() to get
248      Mixed use of DESC_METADATA_CLIENT / DESC_METADATA_ENGINE is not allowed,
249      client drivers must use either of the modes per descriptor.
258    .. code-block:: c
278    issue_pending API. If channel is idle then the first transaction in
287    .. code-block:: c
292 ------------
296    .. code-block:: c
302    This causes all activity for the DMA channel to be stopped, and may
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
336    channel which is not currently paused.
340    .. code-block:: c
345    This can be used to check the status of the channel. Please see
356       a running DMA channel. It is recommended that DMA engine users
357       pause or stop (via dmaengine_terminate_all()) the channel before
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