linux驱动开发学习笔记十三：设备树常用OF操作函数

       设备树描述了设备的详细信息，这些信息包括数字类型的、字符串类型的、数组类型的，我们在编写驱动的时候需要获取到这些信息。比如设备树使用 reg 属性描述了某个外设的寄存器地址为 0X02005482，长度为 0X400，我们在编写驱动的时候需要获取到reg属性的0X02005482和 0X400这两个值，然后初始化外设。Linux 内核给我们提供了一系列的函数来获取设备树中的节点或者属性信息，这一系列的函数都有一个统一的前缀“of_”，所以在很多资料里面也被叫做 OF 函数。这些 OF 函数原型都定义在include/linux/of.h文件中。

一、查找节点的 OF 函数

设备都是以节点的形式“挂”到设备树上的，因此要想获取这个设备的其他属性信息，必 须先获取到这个设备的节点。Linux 内核使用 device_node 结构体来描述一个节点，此结构体定义在文件 include/linux/of.h 中，定义如下：

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

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

• of_find_property 函数

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

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

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 的话表示内存映射失败。

四、程序案例

下面这个案例是以dts文件中的backlight节点为例，主要展示了如何获取节点和一些属性信息：

#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 

/*
	backlight {
		compatible = "pwm-backlight";
		pwms = ;
		brightness-levels = ;
		default-brightness-level = ;
		status = "okay";
	};
*/

/*
 * 模块入口
 */
static int __init dtsof_init(void)
{
    int ret = 0;
    struct device_node *bl_nd = NULL; /* 节点 */
    struct property     *comppro = NULL;
    const char *str;
    u32 def_value = 0;
    u32 elemsize = 0;
    u32 *brival;
    u8 i = 0;

    /*1、找到backlight节点，路径是:/backlight */
    bl_nd = of_find_node_by_path("/backlight");
	if (bl_nd == NULL) {    /* 失败 */
		ret = -EINVAL;
		goto fail_findnd;
	}

    /* 2、获取属性 */
    comppro = of_find_property(bl_nd, "compatible", NULL);
	if (comppro == NULL) {    /* 失败 */
		ret = -EINVAL;
		goto fail_finpro;
	} else {                /* 成功 */
        printk("compatible=%s\r\n", (char*)comppro->value);
    }

    ret = of_property_read_string(bl_nd, "status", &str);
    if(ret