以Xilinx Zynq-7000为例说明设备树的运用 - 全文

注：由于内核版本的演变，设备树成了任何使用较高版本linux系统的设备平台所必须文件，然国内相关技术文档严重不足，本文是国外技术专栏的翻译.

本教程是针对Xilinx Zynq-7000设备写的，但其中的概念适用于所有使用了设备树的Linux内核。本文使用Xillinux发行版为例，该发行版运行于Zedboard硬件上。
 

设备树有什么好处

设想一下：bootloader刚刚将Linux内核复制到内存中，然后跳到内核的入口点开始执行。此时内核就像运行在处理器上的一个裸机程序。需要配置处理器，设置虚拟内存，向控制台打印一些信息。但是这些事情如何完成？所有的这些操作都要通过写寄存器来实现，但Linux内核如何知道这些寄存器的地址？如何知道当前有多少个CPU核可以使用？有多少内存可以访问？

最直接的办法就是在内核代码里为指定平台写好这些代码，由内核配置参数决定哪些平台代码将被启用。当一切都固定不变时这种方法还不错，比如在x86处理器上内部的寄存器，或是BIOS的访问。但对于变化量来说， 比如PCI/PCIe外设，就需要内核明确了解这些变化的细节。

ARM架构已经变成了Linux社区的一个在麻烦：即使处理器使用相同的编译器和函数，但具体到某一种芯片，它就有自己的寄存器地址和不同的配置方式。不仅如此，每种板子都有自己的外设。结果造成内核中有大量的头文件、补丁和特殊的配置参数，它们的一种组合就对应于一款芯片的一种特殊板型。总之，这造成了大量丑陋和不可维护的代码。

另外，每个编译出来的内核bin文件都是为某一款芯片的某一种板子，有点像为市场上某一款PC主板编译内核。所以很希望为所有ARM处理器编译内核时，让内核能以某种方式识别硬件，然后使用正确的驱动，就像一台PC一样。

怎么实现呢？在PC上，寄存器初始化是硬编码的，其他的信息由BIOS提供。所以当有另一块软件提供这些信息时，硬件自动检测也很容易。ARM处理器没有BIOS，Linux内核只能靠自己了。

解决方案是设备树devicetree, 也称作Open Firmware(OF)或FlattenedDevice Tree(FDT)。本质上是一个字节码格式的数据结构，其中包含信息在内核启动时非常有用。bootloader在跳到内核入口点之前将这一块数据复制到RAM中的已知地址。

设备树的严格的规范，却没有规定哪些内容可以放置其中以及放置的位置。内核可以搜索设备树中的任意路径和参数。程序员来决定哪些配置作为参数放进设备树里，以及放置在什么地方。

采取标准的树结构，则可用一套方便的API来操作。例如，约定好如何定义总线上的外设，那么API可以获取到驱动所需的基本信息：地址、中断和自定义变量。后面会介绍更多。

对于我们大多数人来说，我们用设备树来向内核描述对硬件的添加或删除操作，作为响应，内核就可以加载或卸载相应的驱动。硬件的特殊信息也可以通过设备树来向内核传达。

编译设备树
设备树有三种形式：
* 文本文件 (.dts) - 源
二进制对象 (.dtb) - 目标码
Linux系统中/proc/device-tree目录 - 调试和逆向信息

启用/proc/device-tree目录需要打开配置CONFIG_PROC_DEVICETREE:
Device Drivers --->
Device Tree and Open Firmware support --->
[*] Support for device tree in /proc

对于设备树，我们一般的使用流程是：编辑DTS文件，然后用一个工具将其编译成DTB文件，这个工具就在Linux内核源码scripts/dtc/目录下。

设备树编译器也可以单独下载并编译：
$ git clone git://www.jdl.com/software/dtc.git dtc
$ cd dtc
$ make

但是下文的描述都使用内核原码中的dtc工具。

设备树的语法在这里描述。注意这种语言并不作任何执行操作，不像XML，这只是一种组织数据的语法。一些架构有自动产生设备树的工具，来自于XPS项目。但目前对于Zynq EPP平台还没有此工具。

DTS编译为DTB：
$ scripts/dtc/dtc -I dts -O dtb -o /path/to/my-tree.dtb /path/to/my-tree.dts

这样就创建了my-tree.dtb二进制文件。dtc是主机上的一个程序。如果内核没有编译过，则先需要编译好DTS编译器：配置内核，也可以复制一份已有的配置文件到内核根目录下的.config。如下：
$ make ARCH=arm digilent_zed_defconfig

生成DTS编译器：
$ make ARCH=arm scripts

dtc也可以从一个DTB文件或/proc/device-tree文件系统反编译。例如从DTB反编译：
$ scripts/dtc/dtc -I dtb -O dts -o /path/to/fromdtb.dts/path/to/booted_with_this.dtb

生成的dts文件仍然可以被用来生成dtb。但最好还是使用最初的DTS文件，因为一些参考标签在反编译的DTS文件中显示为数字。

从运行中的内核生成DTS文件：
# scripts/dtc/dtc -I fs -O dts -o ~/effective.dts /proc/device-tree/

设备树结构

Zynq的设备树如下：
/dts-v1/;
/ {
#address-cells = <1>;
#size-cells = <1>;
compatible = "xlnx,zynq-zed";
interrupt-parent = <&gic>;
model = "Xillinux for Zedboard";
aliases {
serial0 = &ps7_uart_1;
} ;
chosen {
bootargs = "consoleblank=0 root=/dev/mmcblk0p2 rw rootwaitearlyprintk";
linux,stdout-path = "/axi@0/uart@E0001000";
};

cpus {

[ ... CPU definitions ... ]

} ;
ps7_ddr_0: memory@0 {
device_type = "memory";
reg = < 0x0 0x20000000 >;
} ;
ps7_axi_interconnect_0: axi@0 {
#address-cells = <1>;
#size-cells = <1>;
compatible = "xlnx,ps7-axi-interconnect-1.00.a","simple-bus";
ranges ;

[ ... Peripheral definitions... ]

} ;
} ;

这是Xillinux使用的设备树，删去了两个部分：一个描述CPUs(比较无趣)，另一个定义外设(太长了，后面再深入其中的信息)。

默认使用的dts是/boot/devicetree-3.3.0-xillinux-1.0.dts。

在第一行版本描述之后，设备树以一个斜杠/开始，表示这是树的根， 然后是大括号。从DTS编译器的角度来看，大括号包含大更深的层级(相当于文件系统里的目录结构)。内核代码会遍历这颗树，在某个路径上抓取到想要的信息(就像在文件系统的某个路径上读文件)。

树的结构是以内核期望为准。其中的赋值对dtc来说没有意义。事实上，树中的许多赋值语句都会被内核忽略掉，就像某个文件存在于文件系统中，但没有程序去打开它。

从用户空间访问数据

与文件系统作类比并不是想当然，内核真的实现了这个文件系统/proc/device-tree：每个大括号表示一个目录，目录名是大括号前面的字符串。

如：
# hexdump -C '/proc/device-tree/#size-cells'
00000000 00 00 00 01 |....|
00000004
# hexdump -C '/proc/device-tree/axi@0/compatible'
00000000 78 6c 6e 78 2c 70 73 37 2d 61 78 69 2d 69 6e 74 |xlnx,ps7-axi-int|
00000010 65 72 63 6f 6e 6e 65 63 74 2d 31 2e 30 30 2e 61 |erconnect-1.00.a|
00000020 00 73 69 6d 70 6c 65 2d 62 75 73 00 |.simple-bus.|
0000002c

或直接：
# cat '/proc/device-tree/axi@0/compatible'
xlnx,ps7-axi-interconnect-1.00.asimple-bus

:
ps7_axi_interconnect_0:

冒号之前的是标签，只出现在DTS文件中，而不会出现在DTB文件里。而靠近大括号的字符串为目录名。

如上示范，赋值操作在/proc里表示为一个文件，文件名为等号左边的字符串，文件内容为等号右边的字符串。如果只没有等号，则创建一个空文件。

上例显示，设备树即能方便地向用户空间程序传递信息，也能向内核传递信息， /proc/device-tree虚拟文件系统让这些信息变得可访问。毋须多言，内核中有一套API可访问设备树结构和数据。

你可能注意到了整型以大端形式表示，Zynq处理器是小端的，留意这点。

设备树里的启动参数
一般有三个地方可以放置内核启动命令：
. 内核配置的CONFIG_CMDLINE参数
. 由bootloader传递给内核
. 在设备树的chosen/bootargs下描述

使用哪一个取决于内核的配置。在Xillinux中，使用设备树chosen/bootargs里描述的cmdline。

选择哪个UART来输出内核启动信息是在初始代码里写死的。这里即使删掉ps7_uart_1: serial@e0001000这一行，启动信息仍会从UART中输出，只是不会再出现/dev/ttyPS0设备节点了。

"alias"和"linux,stdout-path"赋值语句是这个架构历史遗留的，在这里没有意义。

定义外设
可能你读本文是为了给你的设备写一个Linux驱动，在这方面要推荐著名的《Linux Device Driver》。但是在写一个设备驱动之前，允许我分享写Linux驱动的第一诫：永远不要为Linux写设备驱动。

更好的办法是找一个维护状态良好的类似功能的设备驱动，然后修改它。这不仅仅意味着更容易，更可能帮我们避免我们一些未意识到的问题。从其他驱动移植过来可以让这份驱动更容易被理解，可移植，更可能被内核树接受。

所以现在的重点变为理解其他驱动，然后做一点调整。有疑问的地方就照着别人的做法做。创新和个人风格在这里没什么用。

现在，回到设备树。让我们来看看第二部分省略的内容：
ps7_axi_interconnect_0: axi@0 {
#address-cells = <1>;
#size-cells = <1>;
compatible = "xlnx,ps7-axi-interconnect-1.00.a","simple-bus";
ranges ;
gic: interrupt-controller@f8f01000 {
#interrupt-cells = < 3 >;
compatible = "arm,cortex-a9-gic";
interrupt-controller ;
reg = < 0xf8f01000 0x1000 >,< 0xf8f00100 0x100 >;
} ;
pl310: pl310-controller@f8f02000 {
arm,data-latency = < 3 2 2 >;
arm,tag-latency = < 2 2 2 >;
cache-level = < 2 >;
cache-unified ;
compatible = "arm,pl310-cache";
interrupts = < 0 34 4 >;
reg = < 0xf8f02000 0x1000 >;
} ;

[ ... more items ... ]

xillybus_0:xillybus@50000000 {
compatible = "xlnx,xillybus-1.00.a";
reg = < 0x50000000 0x1000 >;
interrupts = < 0 59 1 >;
interrupt-parent = <&gic>;
xlnx,max-burst-len = <0x10>;
xlnx,native-data-width = <0x20>;
xlnx,slv-awidth = <0x20>;
xlnx,slv-dwidth = <0x20>;
xlnx,use-wstrb = <0x1>;
} ;
} ;

这里只列出原始DTS文件中的两个设备。

第一个条目：Zynq处理器的中断控制器。这个条目确保中断控制器被加载。注意它的标签是“gic"。这个标签被每个使用中断的设备引用。

终于可以讲述最有趣的部分了：以上说的这些如何与内核代码配合工作。

关于内核驱动
设备驱动加载和卸载时有四件事情会发生：
. 硬件存在时(比如在设备树中声明)，内核代码加载相应驱动
. 驱动需要了解设备的物理地址
. 驱动需要了解设备触发的中断号，用来注册中断处理函数。
. 一些特殊信息需要被获取

内核中有直接访问设备树的API，但是设备驱动使用专用接口更方便，这些专用接口受PCI/PCIe驱动的API影响。来看下xillybus_0条目，这是一个挂载于AXI总线上的典型逻辑设备。

标签和节点名
首先，标签("xillybus")和条目名()。标签可以省略，条目节点名的格式为()，最后在/sys下产生一个标准的条目(/sys/devices/axi.0/50000000.xillybus/)。，不过内核肯定不是从这里访问设备树的。

驱动自动加载
节点中的第一个赋值语句compatible = “xlnx,xillybus-1.00.a”是最重要的一句：它连接硬件和驱动。当内核在总线上扫描设备时(设备节点在设备树里挂在一个总线节点下)，内核检索"compatible"字段，然后将其字符串与一些已知的字符串比较。这个过程会在启动时自动发生两次：
. 内核启动时，编译进内核的驱动与设备树中某个"compatible"条目匹配
. 之后加载内核模块时，再触发一次匹配操作

内核驱动和"compatible"条目的连接由驱动代码中的一小段完成：
static struct of_device_id xillybus_of_match[] __devinitdata = {
{ .compatible = "xlnx,xillybus-1.00.a", },
{}
};

MODULE_DEVICE_TABLE(of,xillybus_of_match);

这段代码使得驱动与某一个"compatible"条目匹配。注意上面的id表中有一个空结构，用这个空意绪标志id表的结束。

在上段代码之后，一定有类似如下的一段代码：
static struct platform_driver xillybus_platform_driver = {
.probe = xilly_drv_probe,
.remove = xilly_drv_remove,
.driver = {
.name = "xillybus",
.owner = THIS_MODULE,
.of_match_table = xillybus_of_match,
},
};

platform_driver_register(&xillybus_platform_driver)在模块初始化里被调用。这个结构告诉内核，当驱动与某个硬件匹配时，xilly_drv_probe 被调用。

对内核来说，"compatible"字串需要与某个驱动名相同。”xlnx"前缀用于防止名字冲突。

另外，一个设备可以有多个"compatible"。因为一个设备可以有多个模块对应多个驱动。

可能会需要匹配硬件的名字和类型，但这不常用。

写内核模块时需要特别注意，自动加载机制依赖于/lib/modules/{kernel version}/modules.ofmap文件中的"compatible"字串，其他定义文件也在这个目录下。正确的方式是把*.ko文件复制到/lib/modules/{kernelversion}/kernel/drivers/下的相关目录中，然后：
depmod -a

获取资源信息

内核模块驱动加载之后，就开始把硬件资源管理起来，如读写寄存器、接收中断。

来看看设备树里的一条：
xillybus_0: xillybus@50000000 {
compatible = "xlnx,xillybus-1.00.a";
reg = < 0x50000000 0x1000 >;
interrupts = < 0 59 1 >;
interrupt-parent = <&gic>;

xlnx,max-burst-len =<0x10>;
xlnx,native-data-width = <0x20>;
xlnx,slv-awidth = <0x20>;
xlnx,slv-dwidth = <0x20>;
xlnx,use-wstrb = <0x1>;
} ;

驱动一般在探测函数里就取得了硬件内存段的所有权(探测函数就是probe指针指向的函数)。

来看看一个典型探测函数的框架：
static int __devinit xilly_drv_probe(struct platform_device *op)
{
const struct of_device_id *match;

match =of_match_device(xillybus_of_match, &op->dev);

if (!match)
return -EINVAL;

第一个操作就是检查probe是否作用在相关硬件上。

访问寄存器

下一步，分配一段内存并映射到虚拟内存中。
int rc = 0;
struct resource res;
void *registers;

rc = of_address_to_resource(&op->dev.of_node,0, &res);
if (rc) {
/* Fail */
}

if(!request_mem_region(res.start, resource_size(&res), "xillybus")){
/* Fail */
}

registers =of_iomap(op->dev.of_node, 0);

if (!registers) {
/* Fail */
}

of_address_to_resource() 在设备树中找到第一个"reg"，并将解析到的信息填充在"res"结构体里。这个例子里"reg = <0x50000000 0x1000 >”, 指的是分配一块起始物理地址是0x50000000，长度为0x1000字节的空间。of_address_to_resource()会设置res.start =0x50000000， res.end = 0x50000fff。

调用request_mem_region()是为了注册特殊的内存段。目的是避免两个驱动访问同一段寄存器空间而造成的冲突。resource_size()是个内联函数，返回segment的大小(此处是0x1000)。

of_iomap()函数是of_address_to_resource()和ioremap()的组合，本质上等效于ioremap(re.start, resource_size(&res)).确保物理段已经映射到虚拟内存中，函数返回内存段的虚拟地址空间起始地址。

显然，当模块卸载或某个错误发生时，这些操作都需要有恢复动作。

访问硬件寄存器请使用iowrite32(),ioread32()以及其他的函数和宏，而不要直接使用上面的"register"指针。

中断处理

这部分的驱动很简单，类似如下：
irq = irq_of_parse_and_map(op->dev.of_node, 0);

rc = request_irq(irq,xillybus_isr, 0, "xillybus", op->dev);

irq_of_parse_and_map()在设备树里查找中断的描述项，然后返回中断号，request_irq()将使用这个中断号来注册。第二个参数是0,表示使用设备树中的第一个中断。

设备树里面描述是：
interrupts = < 0 59 1 >;
interrupt-parent = <&gic>;

那么使用了这三个数据中的哪一个呢？

第一个0是一个标志，用于指示中断是否是SPI(共享中断，shared peripheral interrupt)。非0值表示它是SPI。事实上在Zynq硬件上，这些中断都是共享的，这里是为了方便才写0, 软件上认为它不共享。

第二个数据表示中断号。

第三个数字是中断类型，可以有如下值：

0 - 内核不改变它，开机或uboot设置它是什么样就什么样。
1 - 上升沿触发
4 - 电平触发，高电平表示来中断。
不允许有其他值，下降沿触发和低电平中断目前不支持，因为硬件不支持那些模式。如果需要这样的触发方式，就得在硬件上加一个非门。

值得注意的是第三个数字在设备树里通常都是0, 所以Linux内核不去改变中断模式。这通常意味着高电平触发。这也让驱动依赖于bootloader里的设置。

interrupt-parent 这一句，必须指向中断控制器&gic。如果反编译一个DTB文件，这里的&gic会被一个数字代替，通常是0x1。

Application-specific data
之前提过，设备树中是一些特殊信息，这样一个驱动可以管理数片类似的硬件。例如，一个LCD显示驱动，分辨率信息和物理尺寸可能出现在设备树中。串口信息要告诉驱动当前的时钟频率。

最简单的，最常用的形式，这个信息由一条赋值语句组成：
xlnx,slv-awidth = <0x20>;

"xlnx"前缀可以防止命名冲突。名字可以任意取，但最好能望文知意。这里的"xlnx"是使用软件自动生成设备树时加上的前缀。

为了抓取到这一条信息，代码可以这样写：
void *ptr;
ptr = of_get_property(op->dev.of_node, "xlnx,slv-awidth", NULL);

if (!ptr) {
/* Couldn't find the entry */
}

第三个参数NULL，是一个长度指针，可以返回数据的长度。

这条语句的值是一个数字：
int value;
value = be32_to_cpup(ptr);

be32_to_cpup读“ptr”指向的数据，从大端转到处理器的小端，然后就得到想要的数字了。

drivers/of/base.c中有大量读取这些信息的API。

总结
为一个外置写一个设备树entry很简单：
. 为"compatible"赋一个字符串"magicstring"，自动生成工具的生成格式一般是：名字+版本。
. 在数据手册里查看总线上设备的地址分配信息， 写一条 "reg=" 语句。
. "interrupt-parent=<&gic>"
. 中断号 "interrupt="
. 最后加上一些设备的自定义参数