linux之DMA API -- 通用设备的动态DMA映射

通用设备的动态DMA映射

by JHJ(jianghuijun211@gmail.com)

 

本文描述DMA API。更详细的介绍请参看Documentation/DMA-API-HOWTO.txt。

API分为两部分,第一部分描述API,第二部分描述可以支持非一致性内存机器的扩展API。你应该使用第一部分所描述的API,除非你知道你的驱动必须要支持非一致性平台。

第一部分 DMA API

为了可以引用DMA API,你必须 #include <linux/dma-mapping.h>

1-1 使用大块DMA一致性缓冲区(dma-coherent buffers)

void *
dma_alloc_coherent
(struct device *dev, size_t size,
                    dma_addr_t *dma_handle, gfp_t flag)

一致性内存:设备对一块内存进行写操作,处理器可以立即进行读操作,而无需担心处理器高速缓存(cache)的影响。同样的,处理器对一块内存进行些操作,设备可以立即进行读操作。(在告诉设备读内存时,你可能需要确定刷新处理器的写缓存。)

此函数申请一段大小为size字节的一致性内存,返回两个参数。一个是dma_handle,它可以用作这段内存的物理地址。 另一个是指向被分配内存的指针(处理器的虚拟地址)。

注意:由于在某些平台上,使用一致性内存代价很高,比如最小的分配长度为一个页。因此你应该尽可能合并申请一致性内存的请求。最简单的办法是使用dma_pool函数调用(详见下文)。

参数flag(仅存在于dma_alloc_coherent中)运行调用者定义申请内存时的GFP_flags(详见kmalloc)。

void *
dma_zalloc_coherent
(struct device *dev, size_t size,
                    dma_addr_t *dma_handle, gfp_t flag)

对dma_alloc_coherent()的封装,如果内存分配成功,则返回清零的内存。

void
dma_free_coherent
(struct device *dev, size_t size, void *cpu_addr,
                    dma_addr_t dma_handle)

释放之前申请的一致性内存。dev, size及dma_handle必须和申请一致性内存的函数参数相同。cpu_addr必须为申请一致性内存函数的返回虚拟地址。

注意:和其他内存分配函数不同,这些函数必须要在中断使能的情况下使用。

1-2 使用小块DMA一致性缓冲区

如果要使用这部分DMA API,必须#include <linux/dmapool.h>。

许多驱动程序需要为DMA描述符或者I/O内存申请大量小块DMA一致性内存。你可以使用DMA 内存池,而不是申请以页为单位的内存块或者调用dma_alloc_coherent()。这种机制有点像struct kmem_cache,只是它利用了DMA一致性内存分配器,而不是调用 __get_free_pages()。同样地,DMA 内存池知道通用硬件的对齐限制,比如队列头需要N字节对齐。

struct dma_pool *
dma_pool_create
(const char *name, struct device *dev,
                size_t size, size_t align, size_t alloc);

create( )函数为设备初始化DMA一致性内存的内存池。它必须要在可睡眠上下文调用。

name为内存池的名字(就像struct kmem_cache name一样)。dev及size就如dma_alloc_coherent()参数一样。align为设备硬件需要的对齐大小(单位为字节,必须为2的幂次方)。如果设备没有边界限制,可以设置该参数为0。如果设置为4096,则表示从内存池分配的内存不能超过4K字节的边界。

void *
dma_pool_alloc
(struct dma_pool *pool, gfp_t gfp_flags,
                dma_addr_t *dma_handle);

从内存池中分配内存。返回的内存同时满足申请的大小及对齐要求。设置GFP_ATOMIC可以确保内存分配被block,设置GFP_KERNEL(不能再中断上下文,不会保持SMP锁)允许内存分配被block。和dma_alloc_coherent()一样,这个函数会返回两个值:一个值是cpu可以使用的虚拟地址,另一个值是内存池设备可以使用的dma物理地址。

void
dma_pool_free
(struct dma_pool *pool, void *vaddr,
                dma_addr_t addr);

返回内存给内存池。参数pool为传递给dma_pool_alloc()的pool,参数vaddr及addr为dma_pool_alloc()的返回值。

void
dma_pool_destroy
(struct dma_pool *pool);

内存池析构函数用于释放内存池的资源。这个函数在可睡眠上下文调用。请确认在调用此函数时,所有从该内存池申请的内存必须都要归还给内存池。

1-3 DMA寻址限制

int
dma_supported
(struct device *dev, u64 mask)

用来检测该设备是否支持掩码所表示的DMA寻址能力。比如mask为0x0FFFFFF,则检测该设备是否支持24位寻址。

返回1表示支持,0表示不支持。

注意:该函数很少用于检测是否掩码为可用的,它不会改变当前掩码设置。它是一个内部API而非供驱动者使用的外部API。

int
dma_set_mask
(struct device *dev, u64 mask)

检测该掩码是否合法,如果合法,则更新设备参数。即更新设备的寻址能力。

返回0表示成功,返回负值表示失败。

int
dma_set_coherent_mask
(struct device *dev, u64 mask)

检测该掩码是否合法,如果合法,则更新设备参数。即更新设备的寻址能力。

返回0表示成功,返回负值表示失败。

u64
dma_get_required_mask
(struct device *dev)

该函数返回平台可以高效工作的掩码。通常这意味着返回掩码是可以寻址到所有内存的最小值。检查该值可以让DMA描述符的大小尽量的小。

请求平台需要的掩码并不会改变当前掩码。如果你想利用这点,可以利用改返回值通过dma_set_mask()设置当前掩码。

1-4 流式DMA映射

dma_addr_t
dma_map_single
(struct device *dev, void *cpu_addr, size_t size,
                enum dma_data_direction direction)

映射一块处理器的虚拟地址,这样可以让外设访问。该函数返回内存的物理地址。

在dma_API中强烈建议使用表示DMA传输方向的枚举类型。

DMA_NONE    仅用于调试目的
DMA_TO_DEVICE    数据从内存传输到设备,可认为是写操作。
DMA_FROM_DEVICE    数据从设备传输到内存,可认为是读操作。
DMA_BIDIRECTIONAL    不清楚传输方向则可用该类型。

请注意:并非一台机器上所有的内存区域都可以用这个API映射。进一步说,对于内核连续虚拟地址空间所对应的物理地址并不一定连续(比如这段地址空间由vmalloc申请)。因为这种函数并未提供任何分散/聚集能力,因此用户在企图映射一块非物理连续的内存时,会返回失败。基于此原因,如果想使用该函数,则必须确保缓冲区的物理内存连续(比如使用kmalloc)。

更进一步,所申请内存的物理地址必须要在设备的dma_mask寻址范围内(dma_mask表示与设备寻址能力对应的位)。为了确保由kmalloc申请的内存在dma_mask中,驱动程序需要定义板级相关的标志位来限制分配的物理内存范围(比如在x86上,GFP_DMA用于保证申请的内存在可用物理内存的前16Mb空间,可以由ISA设备使用)。

同时还需注意,如果平台有IOMMU(设备拥有MMU单元,可以进行I/O内存总线和设备的映射,即总线地址和内存物理地址的映射),则上述物理地址连续性及外设寻址能力的限制就不存在了。当然为了方便起见,设备驱动开发者可以假设不存在IOMMU。

警告:内存一致性操作基于高速缓存行(cache line)的宽度。为了可以正确操作该API创建的内存映射,该映射区域的起始地址和结束地址都必须是高速缓存行的边界(防止在一个高速缓存行中有两个或多个独立的映射区域)。因为在编译时无法知道高速缓存行的大小,所以该API无法确保该需求。因此建议那些对高速缓存行的大小不特别关注的驱动开发者们,在映射虚拟内存时保证起始地址和结束地址都是页对齐的(页对齐会保证高速缓存行边界对齐的)。

DMA_TO_DEVICE    软件对内存区域做最后一次修改后,且在传输给设备前,需要做一次同步。一旦该使用该原语,内存区域可被视作设备只读缓冲区。如果设备需要对该内存区域进行写操作,则应该使用DMA_BIDIRECTIONAL(如下所示)

DMA_FROM_DEVICE    驱动在访问数据前必须做一次同步,因为数据可能被设备修改了。内存缓冲区应该被当做驱动只读缓冲区。如果驱动需要进行写操作,应该使用DMA_BIDIRECTIONAL(如下所示)。

DMA_BIDIRECTIONAL    需要特别处理:这意味着驱动并不确定内存数据传输到设备前,内存是否被修改了,同时也不确定设备是否会修改内存。因此,你必须需要两次同步双向内存:一次在内存数据传输到设备前(确保所有缓冲区数据改变都从处理器的高速缓存刷新到内存中),另一次是在设备可能访问该缓冲区数据前(确保所有处理器的高速缓存行都得到了更新,设备可能改变了缓冲区数据)。即在处理器写操作完成时,需要做一次刷高速缓存的操作,以确保数据都同步到了内存缓冲区中。在处理器读操作前,需要更新高速缓冲区的行,已确保设备对内存缓冲区的改变都同步到了高速缓冲区中。

void
dma_unmap_single
(struct device *dev, dma_addr_t dma_addr, size_t size,
                enum dma_data_direction direction)

取消先前的内存映射。传入该函数的所有参数必须和映射API函数的传入(包括返回)参数相同。

dma_addr_t
dma_map_page(struct device *dev, struct page *page,
                    unsigned long offset, size_t size,
                    enum dma_data_direction direction)

void
dma_unmap_page
(struct device *dev, dma_addr_t dma_address, size_t size,
                enum dma_data_direction direction)

对页进行映射/取消映射的API。对其他映射API的注意事项及警告对此都使用。同样的,参数<offset>及<size>用于部分页映射,如果你对高速缓存行的宽度不清楚的话,建议你不要使用这些参数。

int
dma_mapping_error
(struct device *dev, dma_addr_t dma_addr)

在某些场景下,通过dma_map_single及dma_map_page创建映射可能会失败。驱动程序可以通过此函数来检测这些错误。一个非零返回值表示未成功创建映射,驱动程序需要采取适当措施(比如降低当前DMA映射使用率或者等待一段时间再尝试)。

int
dma_map_sg(struct device *dev, struct scatterlist *sg,
        int nents, enum dma_data_direction direction)

返回值:被映射的物理内存块的数量(如果在分散/聚集链表中一些元素是物理地址或虚拟地址相邻的,切IOMMU可以将它们映射成单个内存块,则返回值可能比输入值<nents>小)。

请注意如果sg已经映射过了,其不能再次被映射。再次映射会销毁sg中的信息。

如果返回0,则表示dma_map_sg映射失败,驱动程序需要采取适当措施。驱动程序在此时做一些事情显得格外重要,一个阻塞驱动中断请求或者oopsing都总比什么都不做导致文件系统瘫痪强很多。

下面是个分散/聚集映射的例子,假设scatterlists已经存在。

int i, count = dma_map_sg(dev, sglist, nents, direction);
struct scatterlist *sg;

for_each_sg(sglist, sg, count, i) {
        hw_address[i] = sg_dma_address(sg);
        hw_len[i] = sg_dma_len(sg);
}

其中nents为sglist条目的个数。

这种实现可以很方便将几个连续的sglist条目合并成一个(比如在IOMMU系统中,或者一些页正好是物理连续的)。

然后你就可以循环多次(可能小于nents次)使用sg_dma_address() 及sg_dma_len()来获取sg的物理地址及长度。

void
dma_unmap_sg
(struct device *dev, struct scatterlist *sg,
        int nhwentries, enum dma_data_direction direction)

取消先前分散/聚集链表的映射。所有参数和分散/聚集映射API的参数相同。

注意:<nents>是传入的参数,不一定是实际返回条目的数值。

void dma_sync_single_for_cpu(struct device *dev, dma_addr_t dma_handle, size_t size,
                                enum dma_data_direction direction)

void dma_sync_single_for_device(struct device *dev, dma_addr_t dma_handle, size_t size,
                                enum dma_data_direction direction)

void dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg, int nelems,
                            enum dma_data_direction direction)

void dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg, int nelems,
                            enum dma_data_direction direction)

为CPU及外设同步single contiguous或分散/聚集映射。

注意:你必须要做这个工作,

  • 在CPU读操作前,此时缓冲区由设备通过DMA写入数据(DMA_FROM_DEVICE)

  • 在CPU写操作后,缓冲区数据将通过DMA传输到设备(DMA_TO_DEVICE)

  • 在传输数据到设备前后(DMA_BIDIRECTIONAL)

dma_addr_t
dma_map_single_attrs
(struct device *dev, void *cpu_addr, size_t size,
                    enum dma_data_direction dir,
                    struct dma_attrs *attrs)

void
dma_unmap_single_attrs
(struct device *dev, dma_addr_t dma_addr,
                    size_t size, enum dma_data_direction dir,
                    struct dma_attrs *attrs)

int
dma_map_sg_attrs
(struct device *dev, struct scatterlist *sgl,
                int nents, enum dma_data_direction dir,
                struct dma_attrs *attrs)

void
dma_unmap_sg_attrs
(struct device *dev, struct scatterlist *sgl,
                    int nents, enum dma_data_direction dir,
                    struct dma_attrs *attrs)

这四个函数除了传入可选的struct dma_attrs*之外,其他和不带_attrs后缀的函数一样。

struct dma_attrs概述了一组DMA属性。struct dma_attrs详细定义请参见linux/dma-attrs.h。

DMA属性的定义是和体系结构相关的,并且Documentation/DMA-attributes.txt有详细描述。

如果struct dma_attrs* 为空,则这些函数可以认为和不带_attrs后缀的函数相同。

下面给出一个如何使用*_attrs 函数的例子,当进行DMA内存映射时,如何传入一个名为DMA_ATTR_FOO的属性:

#include <linux/dma-attrs.h>
/* DMA_ATTR_FOO should be defined in linux/dma-attrs.h and
* documented in Documentation/DMA-attributes.txt */
...
        DEFINE_DMA_ATTRS(attrs);
        dma_set_attr(DMA_ATTR_FOO, &attrs);
        ....
        n = dma_map_sg_attrs(dev, sg, nents, DMA_TO_DEVICE, &attr);
        ....

在映射/取消映射的函数中,可以检查DMA_ATTR_FOO是否存在:

void whizco_dma_map_sg_attrs(struct device *dev, dma_addr_t dma_addr,
                            size_t size, enum dma_data_direction dir,
                            struct dma_attrs *attrs)
{
        ....
        int foo = dma_get_attr(DMA_ATTR_FOO, attrs);
        ....
        if (foo)
            /* twizzle the frobnozzle */
        ....

第二部分  高级DMA使用方法

警告:下面这些DMA API在大多数情况下不应该被使用。因为它们为一些特殊的需求而准备的,大部分驱动程序并没有这些需求。

如果你不清楚如何确保桥接处理器和I/O设备之间的高速缓存行的一致性,你就根本不应该使用该部分所提到的API。

void *
dma_alloc_noncoherent(struct device *dev, size_t size,
                            dma_addr_t *dma_handle, gfp_t flag)

平台会根据自身适应条件来选择返回一致性或非一致性内存,其他和dma_alloc_coherent()相同。在使用该函数时,你应该确保在驱动程序中对该内存做了正确的和必要的同步操作。

注意,如果返回一致性内存,则它会确保所有同步操作都变成空操作。

警告:处理非一致性内存是件痛苦的事情。如果你确信你的驱动要在非常罕见的平台上(通常是非PCI平台)运行,这些平台无法分配一致性内存时,你才可以使用该API。

void
dma_free_noncoherent(struct device *dev, size_t size, void *cpu_addr,
                            dma_addr_t dma_handle)

释放由非一致性API申请的内存。

int
dma_get_cache_alignment(void)

返回处理器高速缓存对齐值。应该注意在你打算映射内存或者做局部映射时,该值为最小对齐值。

注意:该API可能返回一个比实际缓存行的大的值。通常为了方便对齐,该值为2的幂次方。

void
dma_cache_sync(struct device *dev, void *vaddr, size_t size,
                enum dma_data_direction direction)

对由dma_alloc_noncoherent()申请的内存做局部映射,其实虚拟地址为vaddr。在做该操作时,请注意缓存行的边界。

int
dma_declare_coherent_memory(struct device *dev, dma_addr_t bus_addr,
                            dma_addr_t device_addr, size_t size, int flags)

当设备需要一段一致性内存时,申请由dma_alloc_coherent分配的一段内存区域。

flag 可以由下面这些标志位进行或操作。

DMA_MEMORY_MAP    请求由dma_alloc_coherent()申请的内存为直接可写。

DMA_MEMORY_IO    请求由dma_alloc_coherent()申请的内存可以通过read/write/memcpy_toio等函数寻址到。

flag必须包含上述其中一个或者两个标志位。

DMA_MEMORY_INCLUDES_CHILDREN   

DMA_MEMORY_EXCLUSIVE   

为了使操作简单化,每个设备只能申申明一个该内存区域。

处于效率考虑的目的,大多数平台选择页对齐的区域。对于更小的内存分配,可以使用dma_pool() API。

void
dma_release_declared_memory(struct device *dev)

从系统中移除先前申明的内存区域。该函数不会检测当前区域是否在使用。确保该内存区域当前没有被使用这是驱动程序的事情。

void *
dma_mark_declared_memory_occupied(struct device *dev,
                dma_addr_t device_addr, size_t size)

该函数用于覆盖特殊内存区域(dma_alloc_coherent()会分配出第一个可用内存区域)。

返回值为指向该内存的处理器虚拟地址,或者如果其中福分区域被覆盖,则返回一个错误(通过PRT_ERR())。

第三部分  调试驱动程序对DMA-API的使用情况

DMA-API如前文所述有一些限制。在支持硬件IOMMU的系统中,驱动程序不能违反这些限制将变得更加重要。最糟糕的情况是,如果违反了这些限制准则,会导致数据出错知道摧毁文件系统。

为了debug驱动程序及发现使用DMA-API时的bug,检测代码可以编译到kernel中,它们可以告诉开发者那些违规行为。如果你的体系结构支持,你可以选择编译选项“Enable debugging of DMA-API usage”,使能这个选项会影响系统性能,所以请勿在产品内核中加入该选项。

如果你用使能debug选项的内核启动,那么它会记录哪些设备会使用什么DMA内存。如果检测到错误信息,则会在内核log中打印一些警告信息。下面是一个警告提示的例子:

------------[ cut here ]------------
WARNING: at /data2/repos/linux-2.6-iommu/lib/dma-debug.c:448
        check_unmap+0x203/0x490()
Hardware name:
forcedeth 0000:00:08.0: DMA-API: device driver frees DMA memory with wrong
        function [device address=0x00000000640444be] [size=66 bytes] [mapped as
single] [unmapped as page]
Modules linked in: nfsd exportfs bridge stp llc r8169
Pid: 0, comm: swapper Tainted: G W 2.6.28-dmatest-09289-g8bb99c0 #1
Call Trace:
<IRQ> [<ffffffff80240b22>] warn_slowpath+0xf2/0x130
[<ffffffff80647b70>] _spin_unlock+0x10/0x30
[<ffffffff80537e75>] usb_hcd_link_urb_to_ep+0x75/0xc0
[<ffffffff80647c22>] _spin_unlock_irqrestore+0x12/0x40
[<ffffffff8055347f>] ohci_urb_enqueue+0x19f/0x7c0
[<ffffffff80252f96>] queue_work+0x56/0x60
[<ffffffff80237e10>] enqueue_task_fair+0x20/0x50
[<ffffffff80539279>] usb_hcd_submit_urb+0x379/0xbc0
[<ffffffff803b78c3>] cpumask_next_and+0x23/0x40
[<ffffffff80235177>] find_busiest_group+0x207/0x8a0
[<ffffffff8064784f>] _spin_lock_irqsave+0x1f/0x50
[<ffffffff803c7ea3>] check_unmap+0x203/0x490
[<ffffffff803c8259>] debug_dma_unmap_page+0x49/0x50
[<ffffffff80485f26>] nv_tx_done_optimized+0xc6/0x2c0
[<ffffffff80486c13>] nv_nic_irq_optimized+0x73/0x2b0
[<ffffffff8026df84>] handle_IRQ_event+0x34/0x70
[<ffffffff8026ffe9>] handle_edge_irq+0xc9/0x150
[<ffffffff8020e3ab>] do_IRQ+0xcb/0x1c0
[<ffffffff8020c093>] ret_from_intr+0x0/0xa
<EOI> <4>---[ end trace f6435a98e2a38c0e ]---

驱动开发者可以通过DMA-API的栈回溯信息找出什么导致这些警告。

默认情况下只有第一个错误会打印警告信息,其他错误不会打印警告信息。这种机制保证当前警告打印信息不会冲了你的内核信息。为了debug设备驱动,可以通过debugfs禁止该功能。请看下面详细的defbugfs接口文档。

调试DMA-API代码的debugfs目录叫dma-api/。下列文件存在于该个目录下:

dma-api/all_errors    该文件节点包含一个数值。如果该值不为零,则调试代码会在遇到每个错误的时候都打印警告信息。请注意这个选项会轻易覆盖你的内核信息缓冲区。

dma-api/disabled    只读文件节点,如果禁止调试代码则显示字符“Y”。当系统没有足够内存或者在系统启动时禁止调试功能时,该节点显示“Y”。

dma-api/error_count    只读文件节点,显示发现错误的次数。

dma-api/num_errors    该文件节点显示在打印停止前一共打印多少个警告信息。该值在系统启动时初始化为1,通过写该文件节点来设置该值。

dma-api/min_free_entries    只读文件节点,显示分配器记录的可用dma_debug_entries的最小数目。如果该值变为零,则禁止调试代码。

dma-api/num_free_entries    当前分配器可用dma_debug_entries的数目。

dma-api/driver-filter    通过向该文件节点写入驱动的名字来限制特定驱动的调试输出。如果向该节点输入空字符,则可以再次看到全部错误信息。

如果这些代码默认编译到你的内核中,该调试功能被默认打开。如果在启动时你不想使用该功能,则可以设置“dma_debug=off”作为启动参数,该参数会禁止该功能。如果你想在系统启动后再次打开该功能,则必须重启系统。

如果你指向看到特定设备驱动的调试信息,则可以设置“dma_debug_driver=<drivername>”作为参数。它会在系统启动时使能驱动过滤器。调试代码只会打印和该驱动相关的错误信息。过滤器可以通过debugfs来关闭或者改变。

如果该调试功能在系统运行时自动关闭,则可能是超出了dma_debug_entries的最大限制。这些debug条目在启动时就分配好了,条目数量由每个体系结构自己定义。你可以在启动时使用“dma_debug_entries=<your_desired_number>”来重写该值。 

参考文献

[1] documentation/DMA-API.txt

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值