3.1 General format of the API¶

struct dma_async_tx_descriptor *async_<operation>(<op specific parameters>, struct async_submit_ctl *submit)

3.2 Supported operations¶

3.3 Descriptor management¶

The return value is non-NULL and points to a ‘descriptor’ when the operationhas been queued to execute asynchronously. Descriptors are recycledresources, under control of the offload engine driver, to be reused asoperations complete. When an application needs to submit a chain ofoperations it must guarantee that the descriptor is not automatically recycledbefore the dependency is submitted. This requires that all descriptors beacknowledged by the application before the offload engine driver is allowed torecycle (or free) the descriptor. A descriptor can be acked by one of thefollowing methods:

1. setting the ASYNC_TX_ACK flag if no child operations are to be submitted

2. submitting an unacknowledged descriptor as a dependency to anotherasync_tx call will implicitly set the acknowledged state.

3. callingasync_tx_ack() on the descriptor.

3.4 When does the operation execute?¶

Operations do not immediately issue after return from theasync_<operation> call. Offload engine drivers batch operations toimprove performance by reducing the number of mmio cycles needed tomanage the channel. Once a driver-specific threshold is met the driverautomatically issues pending operations. An application can force thisevent by callingasync_tx_issue_pending_all(). This operates on allchannels since the application has no knowledge of channel to operationmapping.

3.5 When does the operation complete?¶

There are two methods for an application to learn about the completionof an operation.

1. Calldma_wait_for_async_tx(). This call causes the CPU to spin whileit polls for the completion of the operation. It handles dependencychains and issuing pending operations.

2. Specify a completion callback. The callback routine runs in taskletcontext if the offload engine driver supports interrupts, or it iscalled in application context if the operation is carried outsynchronously in software. The callback can be set in the call toasync_<operation>, or when the application needs to submit a chain ofunknown length it can use theasync_trigger_callback() routine to set acompletion interrupt/callback at the end of the chain.

3.6 Constraints¶

1. Calls to async_<operation> are not permitted in IRQ context. Othercontexts are permitted provided constraint #2 is not violated.

2. Completion callback routines cannot submit new operations. Thisresults in recursion in the synchronous case and spin_locks beingacquired twice in the asynchronous case.

3.7 Example¶

Perform a xor->copy->xor operation where each operation depends on theresult from the previous operation:

#include <linux/async_tx.h>static void callback(void *param){        complete(param);}#define NDISKS  2static void run_xor_copy_xor(struct page **xor_srcs,                             struct page *xor_dest,                             size_t xor_len,                             struct page *copy_src,                             struct page *copy_dest,                             size_t copy_len){        struct dma_async_tx_descriptor *tx;        struct async_submit_ctl submit;        addr_conv_t addr_conv[NDISKS];        struct completion cmp;        init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST, NULL, NULL, NULL,                        addr_conv);        tx = async_xor(xor_dest, xor_srcs, 0, NDISKS, xor_len, &submit);        submit.depend_tx = tx;        tx = async_memcpy(copy_dest, copy_src, 0, 0, copy_len, &submit);        init_completion(&cmp);        init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST | ASYNC_TX_ACK, tx,                        callback, &cmp, addr_conv);        tx = async_xor(xor_dest, xor_srcs, 0, NDISKS, xor_len, &submit);        async_tx_issue_pending_all();        wait_for_completion(&cmp);}

See include/linux/async_tx.h for more information on the flags. See theops_run_* and ops_complete_* routines in drivers/md/raid5.c for moreimplementation examples.

4.1 Conformance points¶

There are a few conformance points required in dmaengine drivers toaccommodate assumptions made by applications using the async_tx API:

1. Completion callbacks are expected to happen in tasklet context

2. dma_async_tx_descriptor fields are never manipulated in IRQ context

3. Useasync_tx_run_dependencies() in the descriptor clean up path tohandle submission of dependent operations

4.2 “My application needs exclusive control of hardware channels”¶

Primarily this requirement arises from cases where a DMA engine driveris being used to support device-to-memory operations. A channel that isperforming these operations cannot, for many platform specific reasons,be shared. For these cases thedma_request_channel() interface isprovided.

The interface is:

struct dma_chan *dma_request_channel(dma_cap_mask_t mask,                                     dma_filter_fn filter_fn,                                     void *filter_param);

Where dma_filter_fn is defined as:

typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param);

When the optional ‘filter_fn’ parameter is set to NULLdma_request_channel simply returns the first channel that satisfies thecapability mask. Otherwise, when the mask parameter is insufficient forspecifying the necessary channel, the filter_fn routine can be used todisposition the available channels in the system. The filter_fn routineis called once for each free channel in the system. Upon seeing asuitable channel filter_fn returns DMA_ACK which flags that channel tobe the return value from dma_request_channel. A channel allocated viathis interface is exclusive to the caller, untildma_release_channel()is called.

The DMA_PRIVATE capability flag is used to tag dma devices that shouldnot be used by the general-purpose allocator. It can be set atinitialization time if it is known that a channel will always beprivate. Alternatively, it is set whendma_request_channel() finds anunused “public” channel.

A couple caveats to note when implementing a driver and consumer:

1. Once a channel has been privately allocated it will no longer beconsidered by the general-purpose allocator even after a call todma_release_channel().

2. Since capabilities are specified at the device level a dma_devicewith multiple channels will either have all channels public, or allchannels private.

5. Source¶

include/linux/dmaengine.h:

core header file for DMA drivers and api users

drivers/dma/dmaengine.c:

offload engine channel management routines

drivers/dma/:

location for offload engine drivers

include/linux/async_tx.h:

core header file for the async_tx api

crypto/async_tx/async_tx.c:

async_tx interface to dmaengine and common code

crypto/async_tx/async_memcpy.c:

copy offload

crypto/async_tx/async_xor.c:

xor and xor zero sum offload