设备树语法---OF操作函数

1 常用OF函数

驱动中使用linux内核提供的OF函数用来获取设备树中的详细属性信息，并在驱动中初始化相关设备。

想要在驱动中读取设备的相关属性，必须通过内核提供的众多OF函数。

在内核中，以结构体device_node来描述一个节点。

struct device_node {
 	const char *name; /*节点名字 */
 	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;
 #if defined(CONFIG_OF_KOBJ)
 	struct kobject kobj;
 #endif

 	unsigned long _flags;
 	void *data;
 #if defined(CONFIG_SPARC)
 	unsigned int unique_id;
 	struct of_irq_controller *irq_trans;
 #endif
 };

1.0 节点常用结构体

of_device_id ： 兼容性匹配列表结构体

property ： 描述设备属性的结构体

 struct property {

 	char *name; /* 属性名字 */
 	int length; /* 属性长度 */
 	void *value; /* 属性值 */

	 struct property *next; /* 下一个属性 */

 #if defined(CONFIG_OF_DYNAMIC) || defined(CONFIG_SPARC)
 	unsigned long _flags;
 #endif

 #if defined(CONFIG_OF_PROMTREE)
 	unsigned int unique_id;
 #endif

 #if defined(CONFIG_OF_KOBJ)
 	struct bin_attribute attr;
 #endif

 };

resource：描述片内外设寄存器对应的内存空间的结构体。

 struct resource {
21
 resource_size_t start;
22
 resource_size_t end;
23
 const char *name;
24
 unsigned long flags;
25
 unsigned long desc;
26
 struct resource *parent, *sibling, *child;
27
 };

device_node： 描述设备节点的结构体

1.1 查找节点的 OF 函数

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

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

根据 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 属性列表

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

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

inline struct device_node *of_find_node_by_path(const char *path)

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

1.2 查找父节点/子结点的OF函数

of_get_parent 函数

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

struct device_node *of_get_parent(const struct device_node *node)

**node:**要查找的父节点的节点。
**返回值:**找到的父节点。

of_get_next_child 函数

用迭代的查找子节点

struct device_node *of_get_next_child(const struct device_node *node,struct device_node *prev)

**node:**父节点。
**prev:**前一个子节点,也就是从哪一个子节点开始迭代的查找下一个子节点。可以设置为NULL,表示从第一个子节点开始。
**返回值:**找到的下一个子节点。

1.3 提取节点属性的OF函数

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

用于获取属性中元素的数量,比如 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 函数

用于从属性中获取指定标号的 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 函数

分别是读取属性中 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)

**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)

**np:**设备节点。
proname: 要读取的属性名字。
**out_value:**读取到的数组值。
**返回值:**0,读取成功,负值,读取失败,-EINVAL 表示属性不存在,-ENODATA 表示没有要读取的数据,-EOVERFLOW 表示属性值列表太小。

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

获取#address-cells 属性值

int of_n_addr_cells(struct device_node *np)

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

of_n_size_cells 函数

于获取#size-cells 属性值

int of_n_size_cells(struct device_node *np)

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

1.4 其他常用的OF函数

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

于获取地址相关属性,主要是“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 函数

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

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

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

of_address_to_resource 函数

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

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

**dev:**设备节点。
**index:**地址资源标号。
**r:**得到的 resource 类型的资源值。
返回值:0,成功;负值,失败。

of_iomap 函数

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

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