ION内存管理解读

1.android之
ION内存管理器（1）-- 简介
为什么需要ION
回顾2011年末[2]，LWN审查了android kernel patch[3]，以期望将这些patch合并到kernel主线中。

但是PMEM（android实现的一个内存分配器）使这个愿望破灭了。

为什么PMEM不被linux 社区接受的原因在[3]中有讲到。

从那开始，PMEM很明确会被完全抛弃，取而代之的是ION内存管理器。

ION是google在Android4.0 ICS为了解决内存碎片管理而引入的通用内存管理器，它会更加融合kernel。

目前QCOM MSM, NVDIA Tegra, TI OMAP, MRVL PXA都用ION替换PMEM。

如何获取source code
/kernel/common.git
ION codes reside in drivers/gpu/ion
Specific usage examples on omap4:
/kernel/omap.git
ION 框架[1]
ION 定义了四种不同的heap，实现不同的内存分配策略。

•ION_HEAP_TYPE_SYSTEM : 通过vmalloc分配内存
•ION_HEAP_TYPE_SYSTEM_CONTIG: 通过kmalloc分配内存
•ION_HEAP_TYPE_CARVEOUT: 在保留内存块中（reserve memory）分配内存
•ION_HEAP_TYPE_CUSTOM: 由客户自己定义
42
下图是两个client共享内存的示意图。

图中有2个heap（每种heap都有自己的
内存分配策略），每个heap中分配了若干个buffer。

client的handle管理到对应的buffer。

两个client是通过文件描述符fd来实现内存共享的。

ION APIs
用户空间 API
定义了6种 ioctl 接口，可以与用户应用程序交互。

•ION_IOC_ALLOC: 分配内存
•ION_IOC_FREE: 释放内存
•ION_IOC_MAP: 获取文件描述符进行mmap (? 在code中未使用这个定义) •ION_IOC_SHARE: 创建文件描述符来实现共享内存
•ION_IOC_IMPORT: 获取文件描述符
•ION_IOC_CUSTOM: 调用用户自定义的ioctl
ION_IOC_SHARE 及ION_IOC_IMPORT是基于DMABUF实现的，所以当共享
进程获取文件描述符后，可以直接调用mmap来操作共享内存。

mmap实现由DMABUF子系统调用ION子系统中mmap回调函数完成。

42
内核空间 API
内核驱动也可以注册为一个ION的客户端（client），可以选择使用哪种类型的heap来申请内存。

•ion_client_create: 分配一个客户端。

•ion_client_destroy: 释放一个客户端及绑定在它上面的所有ion handle. ion handle: 这里每个ion handle映射到一个buffer中，每个buffer关联一个heap。

也就是说一个客户端可以操作多块buffer。

Buffer 申请及释放函数:
•ion_alloc: 申请ion内存，返回ion handle
•ion_free: 释放ion handle
ION 通过handle来管理buffer，驱动需要可以访问到buffer的地址。

ION通过下面的函数来达到这个目的
•ion_phys: 返回buffer的物理地址(address)及大小(size)
•ion_map_kernel: 给指定的buffer创建内核内存映射
•ion_unmap_kernel: 销毁指定buffer的内核内存映射
•ion_map_dma: 为指定buffer创建dma 映射，返回sglist（scatter/gather list）
•ion_unmap_dma: 销毁指定buffer的dma映射
ION是通过handle而非buffer地址来实现驱动间共享内存，用户空间共享内存也是利用同样原理。

•ion_share: given a handle, obtain a buffer to pass to other clients
•ion_import: given an buffer in another client, import it
•ion_import_fd: given an fd obtained via ION_IOC_SHARE ioctl, import it Heap API
Heap 接口定义 [drivers/gpu/ion/ion_priv.h]
这些接口不是暴露给驱动或者用户应用程序的。

/**
* struct ion_heap_ops - ops to operate on a given heap
* @allocate: allocate memory
42
* @free: free memory
* @phys get physical address of a buffer (only define on physically contiguous heaps)
* @map_dma map the memory for dma to a scatterlist
* @unmap_dma unmap the memory for dma
* @map_kernel map memory to the kernel
* @unmap_kernel unmap memory to the kernel
* @map_user map memory to userspace
*/
struct ion_heap_ops {
int (*allocate) (struct ion_heap *heap, struct
ion_buffer *buffer, unsigned long len,unsigned long align, unsigned long flags);
void (*free) (struct ion_buffer *buffer);
int (*phys) (struct ion_heap *heap, struct
ion_buffer *buffer, ion_phys_addr_t *addr, size_t *len);
struct scatterlist *(*map_dma) (struct ion_heap
*heap, struct ion_buffer *buffer);
void (*unmap_dma) (struct ion_heap *heap, struct
ion_buffer *buffer);
void * (*map_kernel) (struct ion_heap *heap, struct ion_buffer *buffer);
void (*unmap_kernel) (struct ion_heap *heap, struct ion_buffer *buffer);
int (*map_user) (struct ion_heap *mapper, struct
ion_buffer *buffer, struct vm_area_struct *vma);
};
ION debug
ION 在/sys/kernel/debug/ion/ 提供一个debugfs 接口。

每个heap都有自己的debugfs目录，client内存使用状况显示在
/sys/kernel/debug/ion/<<heap name>>
$cat /sys/kernel/debug/ion/ion-heap-1
client pid size
test_ion 2890 16384
每个由pid标识的client也有一个debugfs目录/sys/kernel/debug/ion/<<pid>> $cat /sys/kernel/debug/ion/2890
heap_name: size_in_bytes
ion-heap-1: 40960 11
42
参考文献
1. https:///BenjaminGaignard/ion
2. /Articles/480055/
3. /Articles/472984/
2. android之ION内存管理器（2）-- cache
ION如何实现buffer共享的思路倒是很清晰的，但是深入代码研究，发现ION是依赖于DMA Mapping的，而DMA mapping模块对我而言还是挺复杂的，看这个模块遇到的第一个问题就是cache。

既然是DMA mapping，直接将申请的buffer设置为non-cacheable不就行了？这样就可以保证CPU通过DMA读写缓冲区的一致性了。

为什么还有Consistent DMA mappings 和 Streaming DMA mappings一说呢？下面先介绍一下Cache的概念。

Cache
Cache写机制：Write-through与Write-back[5]
Cache写机制分为write through和write back两种。

•Write-through- Write is done synchronously both to the cache and to the backing store.
•Write-back (or Write-behind) – Writing is done only to the cache. A modified cache block is written back to the store, just before it is replaced.
Write-through（直写模式）在数据更新时，同时写入缓存Cache和后端存储。

此模式的优点是操作简单；缺点是因为数据修改需要同时写入存储，数据写入速度较慢。

Write-back（回写模式）在数据更新时只写入缓存Cache。

只在数据被替换出缓存时，被修改的缓存数据才会被写到后端存储。

此模式的优点是数据写入速度快，因为不需要写存储；缺点是一旦更新后的数据未被写入存储时出现系统掉电的情况，数据将无法找回。

Write-misses写缺失的处理方式
对于写操作，存在写入缓存缺失数据的情况，这时有两种处理方式：
42
•Write allocate (aka Fetch on write) – Datum at the missed-write location is loaded to cache, followed by a write-hit operation. In this approach,
write misses are similar to read-misses.
•No-write allocate (aka Write-no-allocate, Write around) – Datum at the missed-write location is not loaded to cache, and is written directly to the
backing store. In this approach, actually only system reads are being
cached.
Write allocate方式将写入位置读入缓存，然后采用write-hit（缓存命中写入）操作。

写缺失操作与读缺失操作类似。

No-write allocate方式并不将写入位置读入缓存，而是直接将数据写入存储。

这种方式下，只有读操作会被缓存。

无论是Write-through还是Write-back都可以使用写缺失的两种方式之一。

只是通常Write-back采用Write allocate方式，而Write-through采用No-write allocate 方式；因为多次写入同一缓存时，Write allocate配合Write-back可以提升性能；而对于Write-through则没有帮助。

Cache的两个函数
--Flush
把Cache内容写回Memory,当Cache为Write through,不需要Flush
--Invalidate
把Cache内容直接丢掉不要。

Cache的使用场合
当有DMA在使用memory的时候，一般要用到cache的处理。

因为DMA在访问memory时是不经过cache的。

比较典型的比如在Ethernet，wireless,USB等driver里，DMA会操作descriptors和packet buffers,Driver要做这些处理
--如果driver使用descripter和packet buffer的地址都是cache的地址，那么 a).Driver在读descripter里一些状态,有没有收到包时，要对descripter当前结构里的内容做cache invalidate,收到packet后，也要对packet buffer做cache invalidate
b).Driver在写descripter里一些状态,要发送包时，要对descripter当前结构里的内容做cache flush,发送packet时，也要对packet buffer做cache flush
--有些driver会对descripter使用uncache 地址，那么上面两种情况里invalidate/flush就不用做了。

一般很少会对packet buffer也用uncache地址的，因为对packet内容的处理将会很频繁，使用uncache会很慢。

而descripter一般
42
42
由于结构比较小，如果也使用cache 地址的话，做invalidate/flush 的时间消耗可能会比uncache 的还要多。

下面文字采自于[6]
C B 位的具体含义
0 0 无cache ，无写缓冲(strongly-ordered)；任何对memory 的读写都反映到总线上。

对 memory 的操作过程中CPU 需要等待。

0 1 无cache ，有写缓冲(shareable device)；读操作直接反映到总线上；写操作，CPU 将数据写入到写缓冲后继续运行，由写缓冲进行写回操作。

1 0 有cache ，写通模式(write-through)；读操作首先考虑cache hit ；写操作时直接将数据写入写缓冲，如果同时出现cache hit ，那么也更新cache 。

1 1 有cache ，写回模式(write-back)；读操作首先考虑cache hit ；写操作也首先考虑cache hit 。

处理流程图
Write-through 模式处理流程：
A Write-Through cache with No-Write Allocation Write-back模式处理流程：
42
参考文献
1. https:///BenjaminGaignard/ion
2. /Articles/480055/
42
3. /Articles/472984/
4. 《linux设备驱动程序》第三版 JONATHAN CORBET
5. /cache-writing-policies.html
6. ARM Architecture Reference Manual, ARMv7-A and ARMv7-R
edition DDI0406C
3.linux之DMA API -- 通用设备的动态DMA映射
文描述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函数调用（详见下文）。

42
参数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);
42
从内存池中分配内存。

返回的内存同时满足申请的大小及对齐要求。

设置
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)
检测该掩码是否合法，如果合法，则更新设备参数。

即更新设备的寻址能力。

42
返回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。

42
警告：内存一致性操作基于高速缓存行(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)
42
对页进行映射/取消映射的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系统中，或者一些页正好是物理连续的）。

42
然后你就可以循环多次（可能小于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,
42
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)
{
....
42
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的幂次方。

42
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)
42
该函数用于覆盖特殊内存区域（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
42
[<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”作为启动参数，该参数会禁止该功能。

如果你想在系统启动后再次打开该功能，则必须重启系统。

42
如果你指向看到特定设备驱动的调试信息，则可以设置
“dma_debug_driver=<drivername>”作为参数。

它会在系统启动时使能驱动过滤器。

调试代码只会打印和该驱动相关的错误信息。

过滤器可以通过debugfs来关闭或者改变。

如果该调试功能在系统运行时自动关闭，则可能是超出了dma_debug_entries的最大限制。

这些debug条目在启动时就分配好了，条目数量由每个体系结构自己定义。

你可以在启动时使用“dma_debug_entries=<your_desired_number>”来重写该值。

参考文献
[1] documentation/DMA-API.txt
4. linux之DMA动态映射指南
本文通过伪代码指导驱动开发者如何正确使用DMA API。

关于API更精确的描述，请参考DMA-API.txt。

大多是64位平台有一些特殊硬件可以将总线地址（DMA地址）转换为物理地址。

这个和CPU如何利用页表或TLB将虚拟地址转换成物理地址有点像。

这种地址转换是有必要的，就像PCI设备可以在单个寻址周期里在64位物理地址空间寻址到任何一个页面。

以前linux上的64位平台需要人为设置系统的最大内存大小，这样virt_to_bus()就可以正在工作了（DMA地址转换页表在系统启动时简单初始化，通过__pa(bus_to_virt()可以将DMA地址转换为物理页地址）。

为了使linux可以使用DMA动态映射，它需要得到驱动的一些协助，也就是说需要考虑DMA地址只有在使用时才被映射，DMA传输后，需要取消映射。

当然下面这些API可以在没有这些硬件限制的情况下正常工作。

请注意这些DMA API可以在任何总线上工作，和体系结构无关。

你应该是用DMA API而不是特定总线的DMA API（比pci_dma_*）。

首先，你需要确定在你的驱动程序中
#include <linux/dma-mapping.h>
42。