异步传输/转换（APIAsynchronous Transfers/Transforms API）

1.引言
async_tx API是为描述一串的异步块级别的内存传输/转换提供的方法，并且支持内部事务依赖。这些API以dmaengine客户端的方式进行实现，屏蔽了不同的硬件降低负载的具体实现。由这些API编写的程序，可以对异步操作进行优化。这些API也对可以降低负载资源的一串操作适用。

2.GENEALOGY
这些API最早是为降低MD中的RAID5驱动中内存拷贝和XOR校验计算设计的，他利用了当前Intel(R) Xscale系列的I/O处理器以降低负载。它也建立在'dmaengine'层，适用于降低使用了Intel(R) I/OAT engines网络协议栈的内存拷贝负载。设计特征如下：
1）隐式的同步路径：API使用者不需要了解运行平台具有的降低负载的特征。当设备可用并且用其他的方法的软件正在运行时，操作的负载会被降低。
2）多通道依赖链：API允许一串有依赖关系的操作被提交，比如RAID5中的XOR->拷贝->XOR。API自动处理涉及硬件通道交换的、一个操作到另一个操作的转变。
3）dmaengine扩展了对多客户端和‘memcpy’之外的操作类别的支持。

3.使用

3.1 API的一般格式：struct dma_async_tx_descriptor *
async_<operation>(<op specific parameters>, struct async_submit ctl *submit)

3.2 支持的操作（operation字段）
memcpy - 源缓冲区到目标缓冲区的内存拷贝
memset - 用一个字节的值填充目标缓冲区
xor    - xor一系列的源缓冲区，将结果写入目标缓冲区
xor_val- xor一系列的源缓冲区，如果结果是0，置一个标志位。该实现试图避免写内存。
pq     - 从一系列的源缓冲区中，生成p+q(raid6 syndrome)
pq_val - 以一个给定的一系列源以同步的方式，令p q有效
datap  - (raid6_datap_recov)从给定的源中，修复一个RAID6的数据块和p校验块
2data  - (raid6_2data_recov)从给定的源中，修复两个RAID6数据块

3.3 描述符管理
当操作被插入异步处理队列的时候，返回值non-NULL，指向一个‘描述符’。在降低负载机器的控制下，描述符是回收的资源，完全以操作的方式被重用。当一个应用需要提交一串操作的时候，必须确保在依赖提交之前，描述符不会被自动回收。这要求了，在负载降低机器驱动被允许回收（或者释放）描述符之前，所有的描述符都需要被应用所知晓。一个描述符可以被下面的任何一种方法所知晓：
1）如果没有子操作被提交，置ASYNC_TX_ACK标志位
2）以到另一个async_tx调用的依赖的方式提交一个非ack的描述符，会隐式的设置ack状态
3）在描述符上面调用async_tx_ack()

3.4 操作何时被执行？
从async_<operation>调用返回之后，操作并不是立即被执行。负载降低机器将操作批次化，通过减少需要管理通道的mmio周期的数目以提升性能。一旦到达了驱动特定的阈值，驱动会自动的执行挂起的操作。操作可以通过调用async_tx_issue_pending_all()的方法强制该事件发生。由于应用不知道通道到操作的映射信息，操作会位于所有的通道上。

3.5 操作何时结束？
对于一个应用有两种方法知道操作完成:
1) 调用dma_wait_for_async_tx()。在操作完成的等待期间，该调用会引起CPU的自旋。这个方法用于处理有依赖关系的链和执行挂起的操作。
2）标记一个完成的回调函数。如果负载降低机器驱动支持中断，该回调函数历程运行在一个tasklet上下文中。如果操作是以软件方式的异步，该回调函数将被应用的上下文调用。该回调函数可以被async_<operation>的调用设置，或者当应用需要提交一串未知长度（的操作），可以调用async_trigger_callback()例程，在一串操作的末端设置一个完整的中断/回调函数。

3.6 约束
1）对async_<operation>的调用不允许在IRQ上下文中。其他上下文在不违背2#约束的基础上是允许的。
2）完整的回调例程不能提交新的操作。它将引起异步事件的递归操作，并且在这种异步的情况下，sping_locks会被请求两次。

3.7 范例
进行一个xor->copy->xor操作。并且每个操作依赖前之前操作的运行结果。

 

void callback(void *param)
{
       struct completion *cmp = param;

        complete(cmp);
}

void run_xor_copy_xor(struct page **xor_srcs,
                      int xor_src_cnt,
                      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;
        addr_conv_t addr_conv[xor_src_cnt];
        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, xor_src_cnt, 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, xor_src_cnt, xor_len, &submit);

        async_tx_issue_pending_all();

        wait_for_completion(&cmp);
}

 更多标志位的信息参见include/linux/sync_tx.h；更多的实现例子参加drivers/md/raid5.c的ops_run_*和ops_complete_*例程。

4.驱动开发笔记
4.1 构造点
为了适应由利用async_tx API的应用要求的假定，dmaengine驱动中有一些构造点是需要注意的：
1）回调函数的完成期望在tasklet的上下文发生
2）dma_async_tx_descriptor域从来不会被IRQ上下文左右
3）在描述符清理路径中使用async_tx_run_dependencies()，以处理有依赖关系操作的提交

4.2 “我的应用需要硬件通道的异步控制”
最基本的，这种要求来源于当一个DMA engine驱动被用来支持“设备到内存”的操作。由于很多平台的特殊性，提供这些操作的通道是不能被共享的。对于这种情况，要提供dma_request_channel()接口。
这种接口是： struct dma_chan *dma_request_channel(dma_cap_mask_t mask,dma_filter_fn filter_fn,void *filter_param);
其中，dma_filter_fn的定义为：
typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param);

当可选的‘filter_fn’参数置为NULL时，dma_request_channel简单的返回第一个满足有能力mask的通道。否则，当mask参数不足以区别必要的通道时候，filter_fn例程可以用来排列系统中可用的通道。filter_fn例程被系统中每个空闲的通道调用。当找到一个适合的通道的时候，filter_fn返回一个DMA_ACK，该标志和dma_request_channel的返回值相连。一个通道通过这个接口被分配，和调用者是异步的关系，直到dma_release_channel()被调用。

DMA_PRIVATE标志被用来标记不能用作一般目的分配器的DMA设备。如果知道一个通道将一直是私有的时候，该标志位需要被置位。否则，当dma_request_channel()发现一个没有使用的“共有”通道，要被置位。

以下是两个实现驱动和消费者需要注意的地方：
1）一旦一个通道已经被私有的分配，它将不再被当做一般目的的分配器对待，即使在调用dma_release_channel()之后。
2）由于许可是在设备层标识，一个带有多通道的DMA设备的通道要么都是共有的，要么都是私有的。

5.源程序
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_memset.c: memory fill offload
crypto/async_tx/async_xor.c: xor and xor zero sum offload