linux内核驱动学习--设备树查找节点的 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
   };

查找节点有关

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

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

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

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

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 函数

of_get_parent 函数

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

struct device_node *of_get_parent(const struct device_node *node);

函数参数和返回值含义如下：
node：要查找的父节点的节点。
返回值： 找到的父节点。

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 中，内容如下：

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

of_find_property 函数

of_find_property 函数用于查找指定的属性，函数原型如下：

struct property *of_find_property(const struct device_node *np, const char *name, int *lenp);

函数参数和返回值含义如下：
np：设备节点。
name： 属性名字。
lenp：属性值的字节数
返回值： 找到的属性。

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：元素长度。
返回值： 得到的属性元素数量。

of_property_read_u32_index 函数

of_property_read_u32_index 函数用于从属性中获取指定标号的 u32 类型数据值(无符号 32
位)，比如某个属性有多个 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 表示属性值列表太小。

of_property_read_u8_array 函数

of_property_read_u16_array 函数

of_property_read_u32_array 函数

of_property_read_u64_array 函数

这 4 个函数分别是读取属性中 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);
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 表示属性值列表太小。

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

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，读取成功，负值，读取失败。

of_n_addr_cells 函数

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

int of_n_addr_cells(struct device_node *np);

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

of_n_size_cells 函数

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

int of_n_size_cells(struct device_node *np)

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

---

其他常用的 OF 函数

of_device_is_compatible 函数

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

int of_device_is_compatible(const struct device_node *device, const char *compat);

函数参数和返回值含义如下：
device：设备节点。
compat：要查看的字符串。
返回值： 0，节点的 compatible 属性中不包含 compat 指定的字符串； 正数，节点的 compatible
属性中包含 compat 指定的字符串。

of_get_address 函数

of_get_address 函数用于获取地址相关属性，主要是“reg”或者“assigned-addresses”属性
值，函数原型如下：

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 的话表示读取失败。

of_translate_address 函数

of_translate_address 函数负责将从设备树读取到的地址转换为物理地址，函数原型如下：

u64 of_translate_address(struct device_node *dev, const __be32 *in_addr);

函数参数和返回值含义如下：
dev：设备节点。
in_addr：要转换的地址。
返回值： 得到的物理地址，如果为 OF_BAD_ADDR 的话表示转换失败。

of_address_to_resource 函数

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

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 中，如下所示：

#define IORESOURCE_BITS 		0x000000ff
#define IORESOURCE_TYPE_BITS    0x00001f00
#define IORESOURCE_IO 			0x00000100
#define IORESOURCE_MEM		    0x00000200
#define IORESOURCE_REG          0x00000300
#define IORESOURCE_IRQ		    0x00000400
#define IORESOURCE_DMA 		    0x00000800
#define IORESOURCE_BUS		    0x00001000
#define IORESOURCE_PREFETCH     0x00002000
#define IORESOURCE_READONLY     0x00004000
#define IORESOURCE_CACHEABLE    0x00008000
#define IORESOURCE_RANGELENGTH  0x00010000
#define IORESOURCE_SHADOWABLE   0x00020000
#define IORESOURCE_SIZEALIGN    0x00040000
#define IORESOURCE_STARTALIGN   0x00080000
#define IORESOURCE_MEM_64 	    0x00100000
#define IORESOURCE_WINDOW 	    0x00200000
#define IORESOURCE_MUXED		0x00400000
#define IORESOURCE_EXCLUSIVE    0x08000000
#define IORESOURCE_DISABLED     0x10000000
#define IORESOURCE_UNSET        0x20000000
#define IORESOURCE_AUTO 		0x40000000
#define IORESOURCE_BUSY 		0x80000000

大家一般最常见的资源标志就是 IORESOURCE_MEM 、 IORESOURCE_REG 和
IORESOURCE_IRQ 等。接下来我们回到 of_address_to_resource 函数，此函数看名字像是从设
备树里面提取资源值，但是本质上就是将 reg 属性值，然后将其转换为 resource 结构体类型，
函数原型如下所示：

int of_address_to_resource(struct device_node *dev, int index, struct resource *r);

函数参数和返回值含义如下：
dev：设备节点。
index：地址资源标号。
r：得到的 resource 类型的资源值。
返回值： 0，成功；负值，失败。

of_iomap 函数

#include <linux/of_address.h>
of_iomap 函数用于直接内存映射，以前我们会通过 ioremap 函数来完成物理地址到虚拟地
址的映射，采用设备树以后就可以直接通过 of_iomap 函数来获取内存地址所对应的虚拟地址，
不需要使用 ioremap 函数了。当然了，你也可以使用 ioremap 函数来完成物理地址到虚拟地址
的内存映射，只是在采用设备树以后，大部分的驱动都使用 of_iomap 函数了。 of_iomap 函数本
质上也是将 reg 属性中地址信息转换为虚拟地址，如果 reg 属性有多段的话，可以通过 index 参
数指定要完成内存映射的是哪一段， of_iomap 函数原型如下：

void __iomem *of_iomap(struct device_node *np, int index);

函数参数和返回值含义如下：
np：设备节点。
index： reg 属性中要完成内存映射的段，如果 reg 属性只有一段的话 index 就设置为 0。
返回值： 经过内存映射后的虚拟内存首地址，如果为 NULL 的话表示内存映射失败。