【Linux驱动开发】008 设备树常用OF操作函数

一、前言

设备树描述了设备的详细信息，这些信息包括数字类型的、字符串类型的、数组类型的，我们在编写驱动的时候需要获取到这些信息。

Linux 内核给我们提供了一系列的函数来获取设备树中的节点或者属性信息，这一系列的函数都有一个统一的前缀“of_”，所以在很多资料里面也被叫做 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、of_find_node_by_name 函数 

通过节点名字查找指定的节点：

struct device_node *of_find_node_by_name(struct device_node    *from,   const char        *name); 

• from：开始查找的节点，如果为 NULL 表示从根节点开始查找整个设备树。 
• name：要查找的节点名字。 
• 返回值：找到的节点，如果为 NULL 表示查找失败。 

2、of_find_node_by_type 函数 

通过 device_type 属性(标准属性的第8个，已经被弃用，上一篇文章未提及)查找指定的节点：

struct device_node *of_find_node_by_type(struct device_node *from, const char *type) 

• from：开始查找的节点，如果为 NULL 表示从根节点开始查找整个设备树。 
• type：要查找的节点对应的 type 字符串，也就是 device_type 属性值。 
• 返回值：找到的节点，如果为 NULL 表示查找失败。 

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

4、of_find_matching_node_and_match 函数 

这些函数都是在驱动中使用的，而一般驱动程序文件都会有一个 OF 匹配表，此 OF 匹配表保存着一些 compatible 值，因此可以通过 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 表示查找失败 

5、of_find_node_by_path 函数 

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

inline struct device_node *of_find_node_by_path(const char *path)

• path：带有全路径的节点名，可以使用节点的别名，比如“/backlight”就是 backlight 这个节点的全路径。 
• 返回值：找到的节点，如果为 NULL 表示查找失败 

---

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

1、of_get_parent 函数 

用于获取指定节点的父节点(如果有父节点的话)：

struct device_node *of_get_parent(const struct device_node *node) 

• node：要查找的父节点的节点。   
• 返回值：找到的父节点。 

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

1、of_find_property 函数 

用于查找指定的属性：

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

• np：设备节点。 
• name：属性名字。 
• lenp：属性值的字节数 
• 返回值：找到的属性。

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

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 类型的数组数据：

int of_property_read_u8_array(const struct device_node    *np, 
                                               const char          *propname,   
                                               bu8                       *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、of_property_read_u8 函数 
of_property_read_u16 函数 
of_property_read_u32 函数 
of_property_read_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 表示属性值列表太小。 

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

7、of_n_addr_cells 函数 

获取#address-cells 属性值：

int of_n_addr_cells(struct device_node *np)

• np：设备节点。 
• 返回值：获取到的#address-cells 属性值。 

8、of_n_size_cells 函数 

用于获取#size-cells 属性值：

int of_n_size_cells(struct device_node *np) 

• np：设备节点。 
• 返回值：获取到的#size-cells 属性值。 

---

五、其他常用的 OF 函数 

1、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 指定的字符串。 

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

3、of_translate_address 函数 

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

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

• dev：设备节点。 
• in_addr：要转换的地址。 
• 返回值：得到的物理地址，如果为 OF_BAD_ADDR 的话表示转换失败。 

4、of_address_to_resource 函数 

IIC、SPI、GPIO 等这些外设都有对应的寄存器，这些寄存器其实就是一组内存空间，Linux
内核使用 resource 结构体来描述一段内存空间，用 resource结构体描述的都是设备资源信息。

本质上就是获取 reg 属性值，然后将其转换为 resource 结构体类型：

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

• dev：设备节点。 
• index：地址资源标号。 
• r：得到的 resource 类型的资源值。 
• 返回值：0，成功；负值，失败。 

5、of_iomap 函数 

用于直接内存映射，以前我们会通过 ioremap 函数来完成物理地址到虚拟地址的映射，采用设备树以后就可以直接通过 of_iomap 函数来获取内存地址所对应的虚拟地址，不需要使用 ioremap 函数了。

of_iomap 函数本质上也是将 reg 属性中地址信息转换为虚拟地址，如果 reg 属性有多段的话，可以通过 index 参数指定要完成内存映射的是哪一段。

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

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