07.设备树基础OF操作函数

查找节点的OF函数
查找父/子节点的OF函数
- of_get_parent函数
- of_get_next_child函数
提取属性值的OF函数
其他常用的OF函数

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

查找节点的`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_find_node_with_property函数
of_find_node_with_property函数根据节点属性的name查找device_node，函数原型如下:
```
struct device_node *of_find_node_with_property(struct device_node *from,const char *prop_name)
```
函数参数和返回值含义如下：
from：开始查找的节点，如果为NULL表示从根节点开始查找整个设备树。
prop_name：属性的名字。
返回值：找到的节点，如果为NULL表示查找失败。

of_find_node_by_phandle函数
of_find_node_by_phandle函数根据phandle查找device_node，函数原型:
```
struct device_node *of_find_node_by_phandle(phandle handle)
```
函数参数和返回值含义如下：
handle：要查找的phandle值。
返回值：找到的节点，如果为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函数用于查找指定的属性，函数原型如下：
```
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_n_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函数
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的话表示内存映射失败。

设备树

查找节点的`OF函数`

`of_find_node_by_name`函数

`of_find_node_by_type`函数

`of_find_compatible_node`函数

`of_find_matching_node_and_match`函数

`of_find_node_by_path`函数

`of_find_node_with_property`函数

`of_find_node_by_phandle`函数

查找父/子节点的`OF函数`

`of_get_parent`函数

`of_get_next_child`函数

提取属性值的`OF函数`

`of_find_property`函数

`of_property_count_elems_of_size`函数

`of_property_read_u32_index`函数

`of_property_read_u8_array`函数、`of_property_read_u16_array`函数、`of_property_read_u32_array`函数、`of_property_read_u64_array`函数

`of_property_read_u8`函数、`of_property_read_u16`函数、`of_property_read_u32`函数、`of_property_read_u64`函数

`of_property_read_string`函数

`of_n_addr_cells`函数

`of_n_size_cells`函数

其他常用的`OF函数`

`of_device_is_compatible`函数

`of_get_address`函数

`of_translate_address`函数

`of_address_to_resource`函数

`of_iomap`函数

07.设备树基础OF操作函数

查找节点的OF函数

of_find_node_by_name函数

of_find_node_by_type函数

of_find_compatible_node函数

of_find_matching_node_and_match函数

of_find_node_by_path函数

of_find_node_with_property函数

of_find_node_by_phandle函数

查找父/子节点的OF函数

of_get_parent函数

of_get_next_child函数

提取属性值的OF函数

of_find_property函数

of_property_count_elems_of_size函数

of_property_read_u32_index函数

of_property_read_u8_array函数、of_property_read_u16_array函数、of_property_read_u32_array函数、of_property_read_u64_array函数

of_property_read_u8函数、of_property_read_u16函数、of_property_read_u32函数、of_property_read_u64函数

of_property_read_string函数

of_n_addr_cells函数

of_n_size_cells函数

其他常用的OF函数

of_device_is_compatible函数

of_get_address函数

of_translate_address函数

of_address_to_resource函数

of_iomap函数

查找节点的`OF函数`

`of_find_node_by_name`函数

`of_find_node_by_type`函数

`of_find_compatible_node`函数

`of_find_matching_node_and_match`函数

`of_find_node_by_path`函数

`of_find_node_with_property`函数

`of_find_node_by_phandle`函数

查找父/子节点的`OF函数`

`of_get_parent`函数

`of_get_next_child`函数

提取属性值的`OF函数`

`of_find_property`函数

`of_property_count_elems_of_size`函数

`of_property_read_u32_index`函数

`of_property_read_u8_array`函数、`of_property_read_u16_array`函数、`of_property_read_u32_array`函数、`of_property_read_u64_array`函数

`of_property_read_u8`函数、`of_property_read_u16`函数、`of_property_read_u32`函数、`of_property_read_u64`函数

`of_property_read_string`函数

`of_n_addr_cells`函数

`of_n_size_cells`函数

其他常用的`OF函数`

`of_device_is_compatible`函数

`of_get_address`函数

`of_translate_address`函数

`of_address_to_resource`函数

`of_iomap`函数