设备树常用 OF 操作函数

设备树描述了设备的详细信息，这些信息包括数字类型的、字符串类型的、数组类型的，在编写驱动的时候需要获取到这些信息。比如设备树使用 reg 属性描述了某个外设的寄存器地址为 0X02005482，长度为 0X400，我们在编写驱动的时候需要获取到 reg 属性0X02005482和 0X400 这两个值，然后初始化外设。

Linux 内核给我们提供了一系列的函数来获取设备树中的节点或者属性信息，这一系列的函数都有一个统一的前缀“of_”，所以在很多资料里面也被叫做 OF 函数。这些 OF 函数原型都定义在 include/linux/of.h 文件中。

linux内核使用device_code结构体来描述一个节点，此结构体定义在include/linux/of.h

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
struct device_node {
	const char *name; /* 节点名字 */
	const char *type; /* 设备类型 */
	phandle phandle;
	const char *full_name; /* 节点全名 */
	struct fwnode_handle fwnode;

	struct property *properties; /* 属性 */
	struct property *deadprops; /* removed 属性 */
	struct device_node *parent; /* 父节点 */
	struct device_node *child; /* 子节点 */
	struct device_node *sibling;
	struct kobject kobj;
	unsigned long _flags;
	void *data;
#if defined(CONFIG_SPARC)
	const char *path_component_name;
	unsigned int unique_id;
	struct of_irq_controller *irq_trans;
#endif
};

查找节点of函数

1、通过节点名字查找指定节点

1
2
3
struct device_node *of_find_node_by_name(struct device_node *from, const char *name)
//from开始查找的节点 
//name要查找的节点名字返回找到的节点，NULL表示失败

2、通过device_type属性查找指定的节点

1
2
3
4
struct device_node *of_find_node_by_type(struct device_node *from, const char *type)
//from开始查找的节点，NULL表示从根节点查找整个设备树 
//type要查找的节点对应的type字符串，
//返回值为找到的节点，NULL失败

3、根据device_type和compatible两个属性查找指定的节点

1
2
3
4
5
struct device_node *of_find_compatible_node(struct device_node *from,const char *type, const char *compatible)
//from 开始查找的节点NULL表示从根节点查找整个设备树
//type 要查找的节点对应的type字符串（device_type属性值），NULL表示忽略device_type属性
//compatible 要查找的节点所对应的compatible属性列表
//返回值： 找到的节点，如果为 NULL 表示查找失败

4、通过of_device_id匹配表来查找节点

1
2
3
4
5
6
7
struct device_node *of_find_matching_node_and_match(struct device_node *from, 
                                                    const struct of_device_id *matches,
                                                    const struct of_device_id **match)
//from开始查找的节点，NULL代表从根节点查找整个设备树
//matches of_device_id匹配表，在匹配表里查找节点
//match 找到的匹配的of_device_id
//返回值：找到的节点，NULL表示失败，

5、通过路径来查找指定的节点

1
2
3
inline struct device_node *of_find_node_by_path(const char *path)
//path:带有全路径的节点名
//返回值找到的节点，NULL表示失败

查找父/子节点的of函数

1、获取指定节点的父节点

1
2
3
struct device_node *of_get_parent(const struct device_node *node)
//node：要查找的父节点的节点。
//返回值： 找到的父节点。

2、用迭代方式查找子节点

1
2
3
4
struct device_node *of_get_next_child(const struct device_node *node , struct device_node *prev)
//node父节点
//prev前一个子节点，也就是从哪一个子节点开始迭代的查找下一个子节点。可以设置为NULL，表示从第一个子节点开始。
//返回值： 找到的下一个子节点。

提取属性值的of函数

节点的属性信息里面保存了驱动所需要的内容，因此对于属性值的提取非常重要， Linux 内核中使用结构体 property 表示属性，此结构体同样定义在文件 include/linux/of.h 中。

1
2
3
4
5
6
7
8
9
struct property {
	char *name; /* 属性名字 */	
	int length; /* 属性长度 */
	void *value; /* 属性值 */
	struct property *next; /* 下一个属性 */
	unsigned long _flags;
	unsigned int unique_id;
	struct bin_attribute attr;
};

1、用于查找指定的属性

1
2
3
4
5
property *of_find_property(const struct device_node *np, const char *name, int *lenp)
//np 设备节点
//name 属性名字
//lenp 属性值的字节树
//返回值找到的属性

2、用于获取属性中元素的数量

1
2
3
4
5
int of_property_count_elems_of_size(const struct device_node *np,const char *propname，int elem_size)
//np：设备节点。
//proname： 需要统计元素数量的属性名字。
//elem_size：元素长度。
//返回值： 得到的属性元素数量

3、用于从属性中获取指定标号的 u32 类型数据值 

1
2
3
4
5
6
7
8
9
int of_property_read_u32_index(const struct device_node *np,
                               const char *propname,
                               u32 index,
                               u32 *out_value               )
//np：设备节点。
//proname： 要读取的属性名字。
//index：要读取的值标号。
//out_value：读取到的值
//返回值： 0 读取成功，负值，读取失败， -EINVAL 表示属性不存在， -ENODATA 表示没有要读取的数据， -EOVERFLOW 表示属性值列表太小。

4、读取属性中 u8、 u16、 u32 和 u64 类型的数组数据 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
int of_property_read_u8_array(const struct device_node *np,
															const char *propname,
															u8 *out_values,
															size_t sz)
int of_property_read_u16_array(const struct device_node *np,
															 const char *propname,
											 				 u16 *out_values,
															 size_t sz)
int of_property_read_u32_array(const struct device_node *np,
															 const char *propname,
															 u32 *out_values,
															 size_t sz)
int of_property_read_u64_array(const struct device_node *np,
															 const char *propname,
															 u64 *out_values,
															 size_t sz)
//np：设备节点。
//proname： 要读取的属性名字。
//out_value：读取到的数组值，分别为 u8、 u16、 u32 和 u64。
//sz： 要读取的数组元素数量。
//返回值： 0，读取成功，负值，读取失败， -EINVAL 表示属性不存在， -ENODATA 表示没有要读取的数据， -EOVERFLOW 表示属性值列表太小。

5、用于读取这种只有一个整形值的属性，分别用于读取 u8、 u16、 u32 和 u64 类型属性值 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
int of_property_read_u8(const struct device_node *np,
												const char *propname,
												u8 *out_value)
int of_property_read_u16(const struct device_node *np,
												 const char *propname,
												u16 *out_value)
int of_property_read_u32(const struct device_node *np,
												 const char *propname,
											 	 u32 *out_value)
int of_property_read_u64(const struct device_node *np,
												 const char *propname,
												 u64 *out_value)
//np：设备节点。
//proname： 要读取的属性名字。
//out_value：读取到的数组值。
//返回值： 0，读取成功，负值，读取失败， -EINVAL 表示属性不存在， -ENODATA 表示没有要读取的数据， -EOVERFLOW 表示属性值列表太小。

6、用于读取属性中字符串值 

1
2
3
4
5
int of_property_read_string(struct device_node *np,const char *propname,const char **out_string)
//np：设备节点。
//proname： 要读取的属性名字。
//out_string：读取到的字符串值。
//返回值： 0，读取成功，负值，读取失败。

7、用于获取#address-cells 属性值 

1
2
3
int of_n_addr_cells(struct device_node *np)
//np：设备节点。
//返回值： 获取到的#address-cells 属性值。

8、用于获取#size-cells 属性值 

1
2
3
int of_n_size_cells(struct device_node *np)
//np 设备节点
//获取到的size-cells

其他常用的 OF 函数

1、查看节点的compatible属性是否包含compat指定的字符串，也就是检查设备节点的兼容性

1
2
3
4
int of_device_is_compatible(const struct device_node *device,const char *compat)
//device：设备节点
//compat：要查看的字符串
//返回值： 0，节点的 compatible 属性中不包含 compat 指定的字符串； 正数，节点的 compatible属性中包含 compat 指定的字符串。

2、用于获取地址相关属性，主要是reg和assigned-address属性值

1
2
3
4
5
6
const __be32 *of_get_address(struct device_node *dev,int index,u64 *size,unsigned int *flags)
//dev设备节点
//index：要读取的地址标号。
//size：地址长度。
//flags：参数，比如 IORESOURCE_IO、 IORESOURCE_MEM 等
//返回值： 读取到的地址数据首地址，为 NULL 的话表示读取失败。

3、负责将从设备树读取到的地址转换为物理地址 

1
2
3
4
u64 of_translate_address(struct device_node *dev，const__be32	*in_addr)
//dev：设备节点。
//in_addr：要转换的地址。
//返回值： 得到的物理地址，如果为 OF_BAD_ADDR 的话表示转换失败

4、IIC、 SPI、 GPIO 等这些外设都有对应的寄存器，这些寄存器其实就是一组内存空间， Linux内核使用 resource 结构体来描述一段内存空间，“resource”翻译出来就是“资源”，因此用 resource结构体描述的都是设备资源信息， resource 结构体定义在文件 include/linux/ioport.h 中，定义如下： 

1
2
3
4
5
6
7
struct resource {
	resource_size_t start;
	resource_size_t end;
	const char *name;
	unsigned long flags;
	struct resource *parent, *sibling, *child;
};

对于 32 位的 SOC 来说， resource_size_t 是 u32 类型的。其中 start 表示开始地址， end 表示结束地址， name 是这个资源的名字， flags 是资源标志位，一般表示资源类型，可选的资源标志定义在文件 include/linux/ioport.h 中 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
1 #define IORESOURCE_BITS 0x000000ff
2 #define IORESOURCE_TYPE_BITS 0x00001f00
3 #define IORESOURCE_IO 0x00000100
4 #define IORESOURCE_MEM 0x00000200
5 #define IORESOURCE_REG 0x00000300
6 #define IORESOURCE_IRQ 0x00000400
7 #define IORESOURCE_DMA 0x00000800
8 #define IORESOURCE_BUS 0x00001000
9 #define IORESOURCE_PREFETCH 0x00002000
10 #define IORESOURCE_READONLY 0x00004000
11 #define IORESOURCE_CACHEABLE 0x00008000
12 #define IORESOURCE_RANGELENGTH 0x00010000
13 #define IORESOURCE_SHADOWABLE 0x00020000
14 #define IORESOURCE_SIZEALIGN 0x00040000
15 #define IORESOURCE_STARTALIGN 0x00080000
16 #define IORESOURCE_MEM_64 0x00100000
17 #define IORESOURCE_WINDOW 0x00200000
18 #define IORESOURCE_MUXED 0x00400000
19 #define IORESOURCE_EXCLUSIVE 0x08000000
20 #define IORESOURCE_DISABLED 0x10000000
21 #define IORESOURCE_UNSET 0x20000000
22 #define IORESOURCE_AUTO 0x40000000
23 #define IORESOURCE_BUSY 0x80000000

将 reg 属性值，然后将其转换为 resource 结构体类型， 

1
2
3
4
5
int of_address_to_resource(struct device_node *dev,int index,struct resource *r)
//dev：设备节点。
//index：地址资源标号。
//r：得到的 resource 类型的资源值。
//返回值： 0，成功；负值，失败