Linux设备树常用的OF函数总结

一 查找结点的OF函数

Linux 内核使用 device_node 结构体来描述一个节点，此结构体定义在文件 include/linux/of.h 中，定义如下：

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
};

1. 1 of_find_node_by_name
of_find_node_by_name 函数通过节点名字查找指定的节点，函数原型如下：

struct device_node *of_find_node_by_name(struct device_node *from,
const char *name);
函数参数和返回值含义如下：
from：开始查找的节点，如果为 NULL 表示从根节点开始查找整个设备树。
name：要查找的节点名字。
返回值： 找到的节点，如果为 NULL 表示查找失败。

1.2 of_find_node_by_type 函数
of_find_node_by_type 函数通过 device_type 属性查找指定的节点，函数原型如下：

struct device_node *of_find_node_by_type(struct device_node *from, const char *type)
函数参数和返回值含义如下：
from：开始查找的节点，如果为 NULL 表示从根节点开始查找整个设备树。
type：要查找的节点对应的 type 字符串，也就是 device_type 属性值。
返回值： 找到的节点，如果为 NULL 表示查找失败。

1.3 of_find_compatible_node 函数

of_find_compatible_node 函数根据 device_type 和 compatible 这两个属性查找指定的节点，
函数原型如下：
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 表示查找失败

1. 4 of_find_matching_node_and_match 函数
of_find_matching_node_and_match 函数通过 of_device_id 匹配表来查找指定的节点，函数原型如下：

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 表示查找失败

1.5 of_find_node_by_path 函数
of_find_node_by_path 函数通过路径来查找指定的节点，函数原型如下:

inline struct device_node *of_find_node_by_path(const char *path)
函数参数和返回值含义如下：
path：带有全路径的节点名，可以使用节点的别名，比如“/backlight”就是 backlight 这个
节点的全路径。
返回值： 找到的节点，如果为 NULL 表示查找失败

二、查找父/子节点的 OF 函数

2.1 of_get_parent 函数
of_get_parent 函数用于获取指定节点的父节点(如果有父节点的话)，函数原型如下：

struct device_node *of_get_parent(const struct device_node *node)
函数参数和返回值含义如下：
node：要查找的父节点的节点。
返回值： 找到的父节点。

2.2 of_get_next_child 函数
of_get_next_child 函数用迭代的查找子节点，函数原型如下：

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 中，property 结构体如下

struct property {
	char *name; /* 属性名字 */
	int length; /* 属性长度 */
	void *value; /* 属性值 */
	struct property *next; /* 下一个属性 */
	unsigned long _flags;
	unsigned int unique_id;
	struct bin_attribute attr;
};

内核也提供的提取属性值的 OF 函数：
3.1 of_find_property
of_find_property 函数用于查找指定的属性，函数原型如下：

property *of_find_property(const struct device_node *np,const char *name,int *lenp)
函数参数和返回值含义如下：
np：设备节点。
name： 属性名字。
lenp：属性值的字节数
返回值： 找到的属性。

3.2 of_property_count_elems_of_size 函数
of_property_count_elems_of_size 函数用于获取属性中元素的数量，比如 reg 属性值是一个数组，那么使用此函数可以获取到这个数组的大小，此函数原型如下：

int of_property_count_elems_of_size(const struct device_node *np,const char *propname, int elem_size)
函数参数和返回值含义如下：
np：设备节点。
proname： 需要统计元素数量的属性名字。
elem_size：元素长度。
返回值： 得到的属性元素数量。

3.3 of_property_read_u32_index 函数
of_property_read_u32_index 函数用于从属性中获取指定标号的 u32 类型数据值，某属性有多个 u32 类型的值，也可以使用此函数来获取指定标号的数据值，此函数原型如下：

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 表示属性值列表太小。

3.4 of_property_read_u8_array 函数
of_property_read_u16_array 函数
of_property_read_u32_array 函数
of_property_read_u64_array 函数
这组函数读取属性中 u8、 u16、 u32 和 u64 类型的数组数据，比如大多数的 reg 属
性都是数组数据，可以使用这 4 个函数一次读取出 reg 属性中的所有数据。函数的原型如下：

int of_property_read_u8_array(const struct device_node *np,
							const char *propname,
							u8 *out_values,
							size_t sz)
函数参数和返回值含义如下：
np：设备节点。
proname： 要读取的属性名字。
out_value：读取到的数组值，分别为 u8、 u16、 u32 和 u64。
sz： 要读取的数组元素数量。
返回值： 0，读取成功，负值，读取失败， -EINVAL 表示属性不存在， -ENODATA 表示没有要读取的数据， -EOVERFLOW 表示属性值列表太小。

3.5 of_property_read_u8 函数
of_property_read_u16 函数
of_property_read_u32 函数
of_property_read_u64 函数
用于读取只有一个整形值的属性，分别用于读取 u8、 u16、 u32 和 u64 类型属性值，函数原型如下：

int of_property_read_u8(const struct device_node *np,
						const char *propname,
						u8 *out_value)
函数参数和返回值含义如下：
np：设备节点。
proname： 要读取的属性名字。
out_value：读取到的数组值。
返回值： 0，读取成功，负值，读取失败， -EINVAL 表示属性不存在， -ENODATA 表示没有要读取的数据， -EOVERFLOW 表示属性值列表太小。

3.6 of_property_read_string 函数
of_property_read_string 函数用于读取属性中字符串值，函数原型如下：

int of_property_read_string(struct device_node *np,
						const char *propname,
						const char **out_string)
函数参数和返回值含义如下：
np：设备节点。
proname： 要读取的属性名字。
out_string：读取到的字符串值。
返回值： 0，读取成功，负值，读取失败。

3.7 of_n_addr_cells 函数
of_n_addr_cells 函数用于获取#address-cells 属性值，函数原型如下：

int of_n_addr_cells(struct device_node *np)
函数参数和返回值含义如下：
np：设备节点。
返回值： 获取到的#address-cells 属性值。

3.8 of_n_size_cells 函数
of_size_cells 函数用于获取#size-cells 属性值，函数原型如下：

int of_n_size_cells(struct device_node *np)
函数参数和返回值含义如下：
np：设备节点。
返回值： 获取到的#size-cells 属性值。

四、其他常用的 OF 函数

4.1 of_device_is_compatible 函数
of_device_is_compatible 函数用于查看节点的 compatible 属性是否有指定的字符串，检查设备节点的兼容性，函数原型如下：

int of_device_is_compatible(const struct device_node *device,const char *compat)
函数参数和返回值含义如下：
device：设备节点。
compat：要查看的字符串。
返回值： 0，节点的 compatible 属性中包含 compat 指定的字符串；其他值，节点的 compatible
属性中不包含 compat 指定的字符串。

to be continued…