Linux DMA Engine framework(2)_功能介绍及解接口分析

作者:wowo 发布于:2017-5-2 22:47 分类:Linux内核分析

1. 前言

从我们的直观感受来说,DMA并不是一个复杂的东西,要做的事情也很单纯直白。因此Linux kernel对它的抽象和实现,也应该简洁、易懂才是。不过现实却不甚乐观(个人感觉),Linux kernel dmaengine framework的实现,真有点晦涩的感觉。为什么会这样呢?

如果一个软件模块比较复杂、晦涩,要么是设计者的功力不够,要么是需求使然。当然,我们不敢对Linux kernel的那些大神们有丝毫怀疑和不敬,只能从需求上下功夫了:难道Linux kernel中的driver对DMA的使用上,有一些超出了我们日常的认知范围?

要回答这些问题并不难,将dmaengine framework为consumers提供的功能和API梳理一遍就可以了,这就是本文的目的。当然,也可以借助这个过程,加深对DMA的理解,以便在编写那些需要DMA传输的driver的时候,可以更游刃有余。

2. Slave-DMA API和Async TX API

从方向上来说,DMA传输可以分为4类:memory到memory、memory到device、device到memory以及device到device。Linux kernel作为CPU的代理人,从它的视角看,外设都是slave,因此称这些有device参与的传输(MEM2DEV、DEV2MEM、DEV2DEV)为Slave-DMA传输。而另一种memory到memory的传输,被称为Async TX。

为什么强调这种差别呢?因为Linux为了方便基于DMA的memcpy、memset等操作,在dma engine之上,封装了一层更为简洁的API(如下面图片1所示),这种API就是Async TX API(以async_开头,例如async_memcpy、async_memset、async_xor等)。

dma_api

图片1 DMA Engine API示意图

最后,因为memory到memory的DMA传输有了比较简洁的API,没必要直接使用dma engine提供的API,最后就导致dma engine所提供的API就特指为Slave-DMA API(把mem2mem剔除了)。

本文主要介绍dma engine为consumers提供的功能和API,因此就不再涉及Async TX API了(具体可参考本站后续的文章。

注1:Slave-DMA中的“slave”,指的是参与DMA传输的设备。而对应的,“master”就是指DMA controller自身。一定要明白“slave”的概念,才能更好的理解kernel dma engine中有关的术语和逻辑。

3. dma engine的使用步骤

注2:本文大部分内容翻译自kernel document[1],喜欢读英语的读者可以自行参考。

对设备驱动的编写者来说,要基于dma engine提供的Slave-DMA API进行DMA传输的话,需要如下的操作步骤:

1)申请一个DMA channel。

2)根据设备(slave)的特性,配置DMA channel的参数。

3)要进行DMA传输的时候,获取一个用于识别本次传输(transaction)的描述符(descriptor)。

4)将本次传输(transaction)提交给dma engine并启动传输。

5)等待传输(transaction)结束。

然后,重复3~5即可。

上面5个步骤,除了3有点不好理解外,其它的都比较直观易懂,具体可参考后面的介绍。

3.1 申请DMA channel

任何consumer(文档[1]中称作client,也可称作slave driver,意思都差不多,不再特意区分)在开始DMA传输之前,都要申请一个DMA channel(有关DMA channel的概念,请参考[2]中的介绍)。

DMA channel(在kernel中由“struct dma_chan”数据结构表示)由provider(或者是DMA controller)提供,被consumer(或者client)使用。对consumer来说,不需要关心该数据结构的具体内容(我们会在dmaengine provider的介绍中在详细介绍)。

consumer可以通过如下的API申请DMA channel:

struct dma_chan *dma_request_chan(struct device *dev, const char *name);

该接口会返回绑定在指定设备(dev)上名称为name的dma channel。dma engine的provider和consumer可以使用device tree、ACPI或者struct dma_slave_map类型的match table提供这种绑定关系,具体可参考XXXX章节的介绍。

最后,申请得到的dma channel可以在不需要使用的时候通过下面的API释放掉:

void dma_release_channel(struct dma_chan *chan);

3.2 配置DMA channel的参数

driver申请到一个为自己使用的DMA channel之后,需要根据自身的实际情况,以及DMA controller的能力,对该channel进行一些配置。可配置的内容由struct dma_slave_config数据结构表示(具体可参考4.1小节的介绍)。driver将它们填充到一个struct dma_slave_config变量中后,可以调用如下API将这些信息告诉给DMA controller:

int dmaengine_slave_config(struct dma_chan *chan, struct dma_slave_config *config)

 

3.3 获取传输描述(tx descriptor)

DMA传输属于异步传输,在启动传输之前,slave driver需要将此次传输的一些信息(例如src/dst的buffer、传输的方向等)提交给dma engine(本质上是dma controller driver),dma engine确认okay后,返回一个描述符(由struct dma_async_tx_descriptor抽象)。此后,slave driver就可以以该描述符为单位,控制并跟踪此次传输。

struct dma_async_tx_descriptor数据结构可参考4.2小节的介绍。根据传输模式的不同,slave driver可以使用下面三个API获取传输描述符(具体可参考Documentation/dmaengine/client.txt[1]中的说明):

struct dma_async_tx_descriptor *dmaengine_prep_slave_sg(
        struct dma_chan *chan, struct scatterlist *sgl,
        unsigned int sg_len, enum dma_data_direction direction,
        unsigned long flags);

struct dma_async_tx_descriptor *dmaengine_prep_dma_cyclic(
        struct dma_chan *chan, dma_addr_t buf_addr, size_t buf_len,
        size_t period_len, enum dma_data_direction direction);

struct dma_async_tx_descriptor *dmaengine_prep_interleaved_dma(
        struct dma_chan *chan, struct dma_interleaved_template *xt,
        unsigned long flags);

dmaengine_prep_slave_sg用于在“scatter gather buffers”列表和总线设备之间进行DMA传输,参数如下:
注3:有关scatterlist 我们在[3][2]中有提及,后续会有专门的文章介绍它,这里暂且按下不表。

chan,本次传输所使用的dma channel。

sgl,要传输的“scatter gather buffers”数组的地址;
sg_len,“scatter gather buffers”数组的长度。

direction,数据传输的方向,具体可参考enum dma_data_direction (include/linux/dma-direction.h)的定义。

flags,可用于向dma controller driver传递一些额外的信息,包括(具体可参考enum dma_ctrl_flags中以DMA_PREP_开头的定义):
DMA_PREP_INTERRUPT,告诉DMA controller driver,本次传输完成后,产生一个中断,并调用client提供的回调函数(可在该函数返回后,通过设置struct dma_async_tx_descriptor指针中的相关字段,提供回调函数,具体可参考4.2小节的介绍);
DMA_PREP_FENCE,告诉DMA controller driver,后续的传输,依赖本次传输的结果(这样controller driver就会小心的组织多个dma传输之间的顺序);
DMA_PREP_PQ_DISABLE_P、DMA_PREP_PQ_DISABLE_Q、DMA_PREP_CONTINUE,PQ有关的操作,TODO。

dmaengine_prep_dma_cyclic常用于音频等场景中,在进行一定长度的dma传输(buf_addr&buf_len)的过程中,每传输一定的byte(period_len),就会调用一次传输完成的回调函数,参数包括:

chan,本次传输所使用的dma channel。

buf_addr、buf_len,传输的buffer地址和长度。

period_len,每隔多久(单位为byte)调用一次回调函数。需要注意的是,buf_len应该是period_len的整数倍。

direction,数据传输的方向。

dmaengine_prep_interleaved_dma可进行不连续的、交叉的DMA传输,通常用在图像处理、显示等场景中,具体可参考struct dma_interleaved_template结构的定义和解释(这里不再详细介绍,需要用到的时候,再去学习也okay)。

3.4 启动传输

通过3.3章节介绍的API获取传输描述符之后,client driver可以通过dmaengine_submit接口将该描述符放到传输队列上,然后调用dma_async_issue_pending接口,启动传输。

dmaengine_submit的原型如下:

dma_cookie_t dmaengine_submit(struct dma_async_tx_descriptor *desc)

参数为传输描述符指针,返回一个唯一识别该描述符的cookie,用于后续的跟踪、监控。

dma_async_issue_pending的原型如下:

void dma_async_issue_pending(struct dma_chan *chan);

参数为dma channel,无返回值。

注4:由上面两个API的特征可知,kernel dma engine鼓励client driver一次提交多个传输,然后由kernel(或者dma controller driver)统一完成这些传输。

3.5 等待传输结束

传输请求被提交之后,client driver可以通过回调函数获取传输完成的消息,当然,也可以通过dma_async_is_tx_complete等API,测试传输是否完成。不再详细说明了。

最后,如果等不及了,也可以使用dmaengine_pause、dmaengine_resume、dmaengine_terminate_xxx等API,暂停、终止传输,具体请参考kernel document[1]以及source code。

4. 重要数据结构说明

4.1 struct dma_slave_config

中包含了完成一次DMA传输所需要的所有可能的参数,其定义如下:

/* include/linux/dmaengine.h */

struct dma_slave_config {
        enum dma_transfer_direction direction;
        phys_addr_t src_addr;
        phys_addr_t dst_addr;
        enum dma_slave_buswidth src_addr_width;
        enum dma_slave_buswidth dst_addr_width;
        u32 src_maxburst;
        u32 dst_maxburst;
        bool device_fc;
        unsigned int slave_id;
};

direction,指明传输的方向,包括(具体可参考enum dma_transfer_direction的定义和注释):
    DMA_MEM_TO_MEM,memory到memory的传输;
    DMA_MEM_TO_DEV,memory到设备的传输;
    DMA_DEV_TO_MEM,设备到memory的传输;
    DMA_DEV_TO_DEV,设备到设备的传输。
    注5:controller不一定支持所有的DMA传输方向,具体要看provider的实现。
    注6:参考第2章的介绍,MEM to MEM的传输,一般不会直接使用dma engine提供的API。

src_addr,传输方向是dev2mem或者dev2dev时,读取数据的位置(通常是固定的FIFO地址)。对mem2dev类型的channel,不需配置该参数(每次传输的时候会指定);
dst_addr,传输方向是mem2dev或者dev2dev时,写入数据的位置(通常是固定的FIFO地址)。对dev2mem类型的channel,不需配置该参数(每次传输的时候会指定);
src_addr_width、dst_addr_width,src/dst地址的宽度,包括1、2、3、4、8、16、32、64(bytes)等(具体可参考enum dma_slave_buswidth 的定义)。

src_maxburst、dst_maxburst,src/dst最大可传输的burst size(可参考[2]中有关burst size的介绍),单位是src_addr_width/dst_addr_width(注意,不是byte)。

device_fc,当外设是Flow Controller(流控制器)的时候,需要将该字段设置为true。CPU中有关DMA和外部设备之间连接方式的设计中,决定DMA传输是否结束的模块,称作flow controller,DMA controller或者外部设备,都可以作为flow controller,具体要看外设和DMA controller的设计原理、信号连接方式等,不在详细说明(感兴趣的同学可参考[4]中的介绍)。

slave_id,外部设备通过slave_id告诉dma controller自己是谁(一般和某个request line对应)。很多dma controller并不区分slave,只要给它src、dst、len等信息,它就可以进行传输,因此slave_id可以忽略。而有些controller,必须清晰地知道此次传输的对象是哪个外设,就必须要提供slave_id了(至于怎么提供,可dma controller的硬件以及驱动有关,要具体场景具体对待)。

4.2 struct dma_async_tx_descriptor

传输描述符用于描述一次DMA传输(类似于一个文件句柄)。client driver将自己的传输请求通过3.3中介绍的API提交给dma controller driver后,controller driver会返回给client driver一个描述符。

client driver获取描述符后,可以以它为单位,进行后续的操作(启动传输、等待传输完成、等等)。也可以将自己的回调函数通过描述符提供给controller driver。

传输描述符的定义如下:

struct dma_async_tx_descriptor {
         dma_cookie_t cookie;
         enum dma_ctrl_flags flags; /* not a 'long' to pack with cookie */
         dma_addr_t phys;
         struct dma_chan *chan;
         dma_cookie_t (*tx_submit)(struct dma_async_tx_descriptor *tx);
         int (*desc_free)(struct dma_async_tx_descriptor *tx);
         dma_async_tx_callback callback;
         void *callback_param;
         struct dmaengine_unmap_data *unmap;
#ifdef CONFIG_ASYNC_TX_ENABLE_CHANNEL_SWITCH
         struct dma_async_tx_descriptor *next;
         struct dma_async_tx_descriptor *parent;
         spinlock_t lock;
#endif
};

cookie,一个整型数,用于追踪本次传输。一般情况下,dma controller driver会在内部维护一个递增的number,每当client获取传输描述的时候(参考3.3中的介绍),都会将该number赋予cookie,然后加一。
注7:有关cookie的使用场景,我们会在后续的文章中再详细介绍。

flags, DMA_CTRL_开头的标记,包括:
DMA_CTRL_REUSE,表明这个描述符可以被重复使用,直到它被清除或者释放;
DMA_CTRL_ACK,如果该flag为0,表明暂时不能被重复使用。

phys,该描述符的物理地址??不太懂!

chan,对应的dma channel。

tx_submit,controller driver提供的回调函数,用于把改描述符提交到待传输列表。通常由dma engine调用,client driver不会直接和该接口打交道。

desc_free,用于释放该描述符的回调函数,由controller driver提供,dma engine调用,client driver不会直接和该接口打交道。

callback、callback_param,传输完成的回调函数(及其参数),由client driver提供。

后面其它参数,client driver不需要关心,暂不描述了。

5. 参考文档

[1] Documentation/dmaengine/client.txt

[2] Linux DMA Engine framework(1)_概述

[3] Linux MMC framework(2)_host controller driver

[4] https://forums.xilinx.com/xlnx/attachments/xlnx/ELINUX/10658/1/drivers-session4-dma-4public.pdf

 

原创文章,转发请注明出处。蜗窝科技www.wowotech.net

标签: Linux Kernel 内核 API dma engine

评论:

秋暮离
2017-06-19 11:37
wowo好,
最近在学习V4L2时产生一些疑问,麻烦wowo帮忙点拨以下理解是否正确?
1、在驱动实现的mmap接口函数中,可以使用dma_mmap_attrs把外部sensor申请的DMA缓冲区mmap到用户空间,此时之前申请DMA缓冲区的函数必须是dma_alloc_attrs,mmap之后相当于有两块虚拟地址对应了同一块物理地址。
2、dma_alloc_attrs和dma_alloc_coherent在用法上有什么区分吗?适用场景?
3、我看到像一些fb驱动实现的mmap调用的都是remap_pfn_range,网上说可以使用它来映射内存中的保留页、设备I/O、framebuffer、camera等内存。那是不是可以这样理解:remap_pfn_range作用是用来将物理地址映射到用户空间,ioremap作用是用来将物理地址映射到内核空间。
4、在videobuf2-dma-config.c中有dma-buf的实现,大概是一个供用户空间或其他设备驱动共享DMA buffer的技术,虽然使用步骤很简单(调用几个API)但我这里还是不太理解:假设1中的想法正确的话,那它和dma_mmap_attrs映射DMA缓冲区到用户空间的手段有什么区别吗,感觉dma_mmap_attrs也有“共享”的意思,ISP负责向DMA buffer放数据,用户空间负责从DMA buffer取数据。
5、ISP各个子模块间流通数据需要内存额外开辟buffer中转吗(比如preview、resizer、H3A之间),还是它们有相应的硬件缓冲区,只需要将最终处理完的数据放到内存buffer就OK了
6、像camera、framebuffer用的大内存都来自保留内存吗(mem=size),感觉这种方式比较粗放、浪费,有其它更好的技术吗?
以上问题麻烦wowo前辈解惑,等您不帮时回复即可,不胜感激!
wowo
2017-06-19 17:18
@秋暮离:这个问题留在这篇文章下面有点不符啊,因为此dma非彼dma(dmaengine)啊。memory的事情,让@linuxer大神回答吧,不敢班门弄斧啊~~
秋暮离
2017-06-19 18:55
@wowo:抱歉,这些问题是不太符合本文,那我贴到讨论区好了,看看@linuxer大神有时间解答。
秋暮离
2017-05-28 21:51
wowo好,
麻烦请教一个问题,spi-pl022.c有如下代码:
pl022_transfer_one_message
    do_interrupt_dma_transfer(pl022);
        /* If we're using DMA, set up DMA here */
    if (pl022->cur_chip->enable_dma) {
        /* Configure DMA transfer */
        if (configure_dma(pl022)) {
            dev_dbg(&pl022->adev->dev,
            "configuration of DMA failed, fall back to interrupt mode\n");
        goto err_config_dma;
        }
        /* Disable interrupts in DMA mode, IRQ from DMA controller */
        irqflags = DISABLE_ALL_INTERRUPTS; //禁掉SSP的所有中断
            /* Enable SSP, turn on interrupts */
        writew((readw(SSP_CR1(pl022->virtbase)) | SSP_CR1_MASK_SSE),
               SSP_CR1(pl022->virtbase));
        writew(irqflags, SSP_IMSC(pl022->virtbase));

它这里判断如果是采用DMA传输message,就禁掉SPI控制器的所有中断,意思是数据的后续推进全部交由DMA控制器负责,但这里有一点我不是很明确,麻烦请教:DMA传输也经由设备FIFO中转,这里把FIFO相关中断都禁掉了,那DMA传输期间设备FIFO是否可用,是不是就应该由SPI控制器通过DMA请求线告知DMA控制器?但他这里似乎没有写寄存器的动作来设置自己使用DMA传输?是禁掉所有中断默认就是DMA传输吗?
另外,想知道是不是所有平台控制器采用DMA传输时,都像这样禁掉自身所有中断,然后一切交给DMA负责的路子?
wowo
2017-05-31 17:25
@秋暮离:FIFO是否可用,和“FIFO是否产生中断”,是两个独立的功能,没有依赖。
如果用DMA传输,SPI控制器不需要向CPU产生中断,但它会向DMA控制器产生一些信号,而DMA控制器在传输的过程中会产生中断。

至于怎么启动dma传输,和这个平台的实现有关,看看spec就行了。
秋暮离
2017-05-24 20:46
wowo好,
__dma_request_channel和dma_request_slave_channel应用场景有什么不同吗?我看到一些驱动里面用dma_request_slave_channel的情形好像更多一些。
wowo
2017-05-25 10:14
@秋暮离:dma_request_channel----直接找一个符合规则的dma channel。
dma_request_slave_channel---配合device tree等,获取和对应设备绑定的dma channel(一般是在dts中指定了)。

发表评论:

Copyright @ 2013-2015 蜗窝科技 All rights reserved. Powered by emlog