Linux kernel scatterlist API介绍

作者:wowo 发布于:2017-10-13 22:20 分类:内存管理

1. 前言

我们在那些需要和用户空间交互大量数据的子系统(例如MMC[1]、Video、Audio等)中,经常看到scatterlist的影子。对我们这些“非英语母语”的人来说,初见这个词汇,脑袋瞬间就蒙圈了。scatter可翻译成“散开、分散”,list是“列表”的意思,因而scatterlist可翻译为“散列表”。“散列表”又是什么?太抽象了!

之所以抽象,是因为这个词省略了主语----物理内存(Physical memory),加上后,就好理解了多了,既:物理内存的散列表。再通俗一些,就是把一些分散的物理内存,以列表的形式组织起来。那么,也许你会问,有什么用处呢?

当然有用,具体可参考本文后续的介绍。

2. scatterlist产生的背景

我没有去考究scatterlist API是在哪个kernel版本中引入的(年代太久远了),凭猜测,我觉得应该和MMU有关。因为在引入MMU之后,linux系统中的软件将不得不面对一个困扰(下文将以图片1中所示的系统架构为例进行说明):

假设在一个系统中(参考下面图片1)有三个模块可以访问memory:CPU、DMA控制器和某个外设。CPU通过MMU以虚拟地址(VA)的形式访问memory;DMA直接以物理地址(PA)的形式访问memory;Device通过自己的IOMMU以设备地址(DA)的形式访问memory。

然后,某个“软件实体”分配并使用了一片存储空间(参考下面图片2)。该存储空间在CPU视角上(虚拟空间)是连续的,起始地址是va1(实际上,它映射到了3块不连续的物理内存上,我们以pa1,pa2,pa3表示)。

那么,如果该软件单纯的以CPU视角访问这块空间(操作va1),则完全没有问题,因为MMU实现了连续VA到非连续PA的映射。

不过,如果软件经过一系列操作后,要把该存储空间交给DMA控制器,最终由DMA控制器将其中的数据搬移给某个外设的时候,由于DMA控制器只能访问物理地址,只能以“不连续的物理内存块”为单位递交(而不是我们所熟悉的虚拟地址)。

此时,scatterlist就诞生了:为了方便,我们需要使用一个数据结构来描述这一个个“不连续的物理内存块”(起始地址、长度等信息),这个数据结构就是scatterlist(具体可参考下面第3章的说明)。而多个scatterlist组合在一起形成一个表(可以是一个struct scatterlist类型的数组,也可以是kernel帮忙抽象出来的struct sg_table),就可以完整的描述这个虚拟地址了。

最后,从本质上说:scatterlist(数组)是各种不同地址映射空间(PA、VA、DA、等等)的媒介(因为物理地址是真实的、实在的存在,因而可以作为通用语言),借助它,这些映射空间才能相互转换(例如从VA转到DA)。

cpu_dma_device_memory

图片1 cpu_dma_device_memory

    

cpu_view_memory

图片2 cpu_view_memory

3. scatterlist API介绍

3.1 struct scatterlist

struct scatterlist用于描述一个在物理地址上连续的内存块(以page为单位),它的定义位于“include/linux/scatterlist.h”中,如下:

struct scatterlist {
#ifdef CONFIG_DEBUG_SG
        unsigned long   sg_magic;
#endif
        unsigned long   page_link;
        unsigned int    offset;
        unsigned int    length;
        dma_addr_t      dma_address;
#ifdef CONFIG_NEED_SG_DMA_LENGTH
        unsigned int    dma_length;
#endif
};

page_link,指示该内存块所在的页面。bit0和bit1有特殊用途(可参考后面的介绍),因此要求page最低4字节对齐。
offset,指示该内存块在页面中的偏移(起始位置)。
length,该内存块的长度。

dma_address,该内存块实际的起始地址(PA,相比page更接近我们人类的语言)。
dma_length,相应的长度信息。

3.2 struct sg_table

在实际的应用场景中,单个的scatterlist是没有多少意义的,我们需要多个scatterlist组成一个数组,以表示在物理上不连续的虚拟地址空间。通常情况下,使用scatterlist功能的模块,会自行维护这个数组(指针和长度),例如[2]中所提到的struct mmc_data:

struct mmc_data {
    …

        unsigned int            sg_len;         /* size of scatter list */     
        struct scatterlist      *sg;            /* I/O scatter list */
         
        s32                     host_cookie;    /* host private data */        
};

 

不过呢,为了使用者可以偷懒,kernel抽象出来了一个简单的数据结构:struct sg_table,帮忙保存scatterlist的数组指针和长度:

struct sg_table {
        struct scatterlist *sgl;        /* the list */
        unsigned int nents;             /* number of mapped entries */
        unsigned int orig_nents;        /* original size of list */
};

其中sgl是内存块数组的首地址,orig_nents是内存块数组的size,nents是有效的内存块个数(可能会小于orig_nents)。

以上心思都比较直接,不过有一点,我们要仔细理解:

scatterlist数组中到底有多少有效内存块呢?这不是一个很直观的事情,主要有如下2个规则决定:

1)如果scatterlist数组中某个scatterlist的page_link的bit0为1,表示该scatterlist不是一个有效的内存块,而是一个chain(铰链),指向另一个scatterlist数组。通过这种机制,可以将不同的scatterlist数组链在一起,因为scatterlist也称作chain scatterlist。

2)如果scatterlist数组中某个scatterlist的page_link的bit1为1,表示该scatterlist是scatterlist数组中最后一个有效内存块(后面的就忽略不计了)。

3.3 API介绍

理解了scatterlist的含义之后,再去看“include/linux/scatterlist.h”中的API,就容易多了,例如(简单介绍一下,不再详细分析):

#define sg_dma_address(sg)      ((sg)->dma_address)

#ifdef CONFIG_NEED_SG_DMA_LENGTH
#define sg_dma_len(sg)          ((sg)->dma_length)
#else
#define sg_dma_len(sg)          ((sg)->length)
#endif

sg_dma_address、sg_dma_len,获取某一个scatterlist的物理地址和长度。

#define sg_is_chain(sg)         ((sg)->page_link & 0x01)
#define sg_is_last(sg)          ((sg)->page_link & 0x02)
#define sg_chain_ptr(sg)        \
        ((struct scatterlist *) ((sg)->page_link & ~0x03))

sg_is_chain可用来判断某个scatterlist是否为一个chain,sg_is_last可用来判断某个scatterlist是否是sg_table中最后一个scatterlist。

sg_chain_ptr可获取chain scatterlist指向的那个scatterlist。

static inline void sg_assign_page(struct scatterlist *sg, struct page *page)
static inline void sg_set_page(struct scatterlist *sg, struct page *page,
                               unsigned int len, unsigned int offset)
static inline struct page *sg_page(struct scatterlist *sg)
static inline void sg_set_buf(struct scatterlist *sg, const void *buf,
                               unsigned int buflen)

#define for_each_sg(sglist, sg, nr, __i)        \
        for (__i = 0, sg = (sglist); __i < (nr); __i++, sg = sg_next(sg))

static inline void sg_chain(struct scatterlist *prv, unsigned int prv_nents,
                             struct scatterlist *sgl)

static inline void sg_mark_end(struct scatterlist *sg)
static inline void sg_unmark_end(struct scatterlist *sg)

static inline dma_addr_t sg_phys(struct scatterlist *sg)
static inline void *sg_virt(struct scatterlist *sg)

sg_assign_page,将page赋给指定的scatterlist(设置page_link字段)。
sg_set_page,将page中指定offset、指定长度的内存赋给指定的scatterlist(设置page_link、offset、len字段)。
sg_page,获取scatterlist所对应的page指针。
sg_set_buf,将指定长度的buffer赋给scatterlist(从虚拟地址中获得page指针、在page中的offset之后,再调用sg_set_page)。

for_each_sg,遍历一个scatterlist数组(sglist)中所有的有效scatterlist(考虑sg_is_chain和sg_is_last的情况)。

sg_chain,将两个scatterlist 数组捆绑在一起。

sg_mark_end、sg_unmark_end,将某个scatterlist 标记(或者不标记)为the last one。

sg_phys、sg_virt,获取某个scatterlist的物理或者虚拟地址。

等等(不再罗列了,感兴趣的同学直接去看代码就行了)。

4. 参考文档

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

[2] The chained scatterlist API,https://lwn.net/Articles/256368/

 

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

标签: Linux Kernel 内核 scatterlist sg_table

评论:

小亮
2017-10-31 16:02
page_link除了存放page地址+flag标记外,还可以存放sg地址+flag,参见接口sg_chain()

发表评论:

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