设备树种常用 OF 操作函数

常用 OF 操作函数
查找节点的 OF 函数
查找父/子节点的 OF 函数
提取属性值的 OF 函数
其他常用的 OF 函数
参考文件：

正点原子的嵌入式驱动开发手册

摘要：

  Linux 内核给我们提供了一系列的函数来获取设备树中的节点或者属性信息，这一系列的函数都有一个统一的前缀“of_”，所以在很多资料里面也被叫做 OF 函数。这些 OF 函数原型都定义在 include/linux/of.h 文件中。

查找节点的 OF 函数

1. of_find_node_by_name 函数
/***************************************************************************//**
 * @brief 通过节点名字查找指定的节点.
 *
 * @param from - 开始查找的节点，如果为 NULL 表示从根节点开始查找整个设备树.
 * @param name - 要查找的节点名字.
 *
 * @return 找到的节点，如果为 NULL 表示查找失败.
*******************************************************************************/
 struct device_node *of_find_node_by_name(struct device_node *from, const char *name);

2. of_find_node_by_type 函数
/***************************************************************************//**
 * @brief 通过 device_type 属性查找指定的节点.
 *
 * @param from - 开始查找的节点，如果为 NULL 表示从根节点开始查找整个设备树.
 * @param type - 要查找的节点对应的 type 字符串，也就是 device_type 属性值.
 *
 * @return 找到的节点，如果为 NULL 表示查找失败.
*******************************************************************************/
struct device_node *of_find_node_by_type(struct device_node *from, const char *type);

3. of_find_compatible_node 函数
/***************************************************************************//**
 * @brief 根据 device_type 和 compatible 这两个属性查找指定的节点.
 *
 * @param from - 开始查找的节点，如果为 NULL 表示从根节点开始查找整个设备树.
 * @param type - 要查找的节点对应的 type 字符串，也就是 device_type 属性值,可以为 NULL，表示忽略掉 device_type 属性。
 * @param compatible - 要查找的节点所对应的 compatible 属性列表.
 *
 * @return 找到的节点，如果为 NULL 表示查找失败.
*******************************************************************************/
struct device_node *of_find_compatible_node(struct device_node *from, const char *type, const char *compatible);

4. of_find_matching_node_and_match 函数
/***************************************************************************//**
 * @brief 通过 of_device_id 匹配表来查找指定的节点.
 *
 * @param from - 开始查找的节点，如果为 NULL 表示从根节点开始查找整个设备树.
 * @param matches - of_device_id 匹配表，也就是在此匹配表里面查找节点.
 * @param match - 找到的匹配的 of_device_id.
 *
 * @return 找到的节点，如果为 NULL 表示查找失败.
*******************************************************************************/
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)；

5. of_find_node_by_path 函数
/***************************************************************************//**
 * @brief 通过路径来查找指定的节点.
 *
 * @param path - 带有全路径的节点名，可以使用节点的别名，比如“/backlight”就是 backlight 这个节点的全路径.
 *
 * @return 找到的节点，如果为 NULL 表示查找失败.
*******************************************************************************/
inline struct device_node *of_find_node_by_path(const char *path);
 

查找父/子节点的 OF 函数
6. of_get_parent 函数
/***************************************************************************//**
 * @brief 获取指定节点的父节点(如果有父节点的话).
 *
 * @param node - 要查找的父节点的节点.
 *
 * @return 找到的父节点.
*******************************************************************************/
struct device_node *of_get_parent(const struct device_node *node);

7. of_get_next_child 函数
/***************************************************************************//**
 * @brief 迭代法查找子节点.
 *
 * @param node - 父节点.
 * @param prev - 前一个子节点，也就是从哪一个子节点开始迭代的查找下一个子节点。可以设置为NULL，表示从第一个子节点开始.
 *
 * @return 找到的下一个子节点.
*******************************************************************************/
struct device_node *of_get_next_child(const struct device_node *node, struct device_node *prev);
 

提取属性值的 OF 函数
8. of_find_property 函数
/***************************************************************************//**
 * @brief 查找指定的属性.
 *
 * @param np - 设备节点.
 * @param name - 属性名字.
 * @param lenp - 属性值的字节数.
 *
 * @return 找到的属性.
*******************************************************************************/
property *of_find_property(const struct device_node *np,const char *name, int *lenp);

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

9. of_property_count_elems_of_size 函数
/***************************************************************************//**
 * @brief 获取属性中元素的数量，比如 reg 属性值是一个数组，那么使用此函数可以获取到这个数组的大小.
 *
 * @param np - 设备节点.
 * @param propname - 需要统计元素数量的属性名字.
 * @param elem_size - 元素长度.
 *
 * @return 得到的属性元素数量.
*******************************************************************************/
int of_property_count_elems_of_size(const struct device_node *np, const char *propname, int elem_size);

10. of_property_read_u32_index 函数
/***************************************************************************//**
 * @brief 从属性中获取指定标号的 u32 类型数据值(无符号32位)，比如某个属性有多个 u32 类型的值，那么就可以使用此函数来获取指定标号的数据值.
 *
 * @param np - 设备节点.
 * @param propname - 要读取的属性名字.
 * @param index - 要读取的值标号.
 * @param out_value - 读取到的值.
 *
 * @return 0 读取成功，负值，读取失败，-EINVAL 表示属性不存在，-ENODATA 表示没有要读取的数据，-EOVERFLOW 表示属性值列表太小.
*******************************************************************************/
int of_property_read_u32_index(const struct device_node *np, const char *propname,
                                u32 index, u32 *out_value);

of_property_read_u8_array 函数
of_property_read_u16_array 函数
of_property_read_u32_array 函数
of_property_read_u64_array 函数
/***************************************************************************//**
 * @brief 读取属性中 u8、u16、u32 和 u64 类型的数组数据，比如大多数的 reg 属性都是数组数据，可以使用这 4 个函数一次读取出 reg 属性中的所有数据.
 *
 * @param node - 设备节点.
 * @param propname - 要读取的属性名字.
 * @param out_values - 读取到的数组值，分别为 u8、u16、u32 和 u64.
 * @param sz - 要读取的数组元素数量.
 *
 * @return 0，读取成功，负值，读取失败，-EINVAL 表示属性不存在，-ENODATA 表示没有要读取的数据，-EOVERFLOW 表示属性值列表太小.
*******************************************************************************/
int of_property_read_u8_array(const struct device_node *np, const char *propname, u8 *out_values, size_t sz);

of_property_read_u8 函数
of_property_read_u16 函数
of_property_read_u32 函数
of_property_read_u64 函数
/***************************************************************************//**
 * @brief 有些属性只有一个整形值，这四个函数就是用于读取这种只有一个整形值的属性，分别用于读取 u8、u16、u32 和 u64 类型属性值.
 *
 * @param node - 设备节点.
 * @param propname - 要读取的属性名字.
 * @param out_values - 读取到的数组值，分别为 u8、u16、u32 和 u64.
 *
 * @return 0，读取成功，负值，读取失败，-EINVAL 表示属性不存在，-ENODATA 表示没有要读取的数据，-EOVERFLOW 表示属性值列表太小.
*******************************************************************************/
int of_property_read_u16(const struct device_node *np, const char *propname, u16 *out_value);

11. of_property_read_string 函数
/***************************************************************************//**
 * @brief 读取属性中字符串值.
 *
 * @param np - 设备节点.
 * @param propname - 要读取的属性名字.
 * @param out_string - 读取到的字符串值.
 *
 * @return 0，读取成功，负值，读取失败.
*******************************************************************************/
int of_property_read_string(struct device_node *np, const char *propname, const char **out_string);

12. of_n_addr_cells 函数
/***************************************************************************//**
 * @brief 获取#address-cells 属性值.
 *
 * @param np - 设备节点.
 *
 * @return 获取到的#address-cells 属性值.
*******************************************************************************/
int of_n_addr_cells(struct device_node *np);

13. of_n_size_cells 函数
/***************************************************************************//**
 * @brief 获取#size-cells 属性值.
 *
 * @param np - 设备节点.
 *
 * @return 获取到的#size-cells 属性值.
*******************************************************************************/
int of_n_size_cells(struct device_node *np);
 

其他常用的 OF 函数
14 . of_device_is_compatible 函数
/***************************************************************************//**
 * @brief 查看节点的 compatible 属性是否有包含 compat 指定的字符串，也就是检查设备节点的兼容性.
 *
 * @param device- 设备节点.
 * @param compat - 要查看的字符串.
 *
 * @return 0，节点的 compatible 属性中不包含 compat 指定的字符串；正数，节点的 compatible属性中包含 compat 指定的字符串.
*******************************************************************************/
int of_device_is_compatible(const struct device_node *device, const char *compat);

15  of_get_address 函数
/***************************************************************************//**
 * @brief 获取地址相关属性，主要是“reg”或者“assigned-addresses”属性值.
 *
 * @param dev - 设备节点.
 * @param index - 要读取的地址标号.
 * @param size - 地址长度.
 * @param flags - 参数，比如 IORESOURCE_IO、IORESOURCE_MEM 等.
 *
 * @return 读取到的地址数据首地址，为 NULL 的话表示读取失败.
*******************************************************************************/
const __be32 *of_get_address(struct device_node *dev, int index, u64 *size, unsigned int *flags);

16.  of_translate_address 函数
/***************************************************************************//**
 * @brief 将从设备树读取到的地址转换为物理地址.
 *
 * @param dev - 设备节点.
 * @param in_addr - 要转换的地址.
 *
 * @return 得到的物理地址，如果为 OF_BAD_ADDR 的话表示转换失败.
*******************************************************************************/
u64 of_translate_address(struct device_node *dev, const __be32 *in_addr);

17. of_address_to_resource 函数
/***************************************************************************//**
 * @brief 此函数看名字像是从设备树里面提取资源值，但是本质上就是将 reg 属性值，然后将其转换为 resource 结构体类型.
 *
 * @param dev - 设备节点.
 * @param index - 地址资源标号.
 * @param r - 得到的 resource 类型的资源值.
 *
 * @return 0，成功；负值，失败.
*******************************************************************************/
int of_address_to_resource(struct device_node *dev, int index, struct resource *r);

18. of_iomap 函数
/***************************************************************************//**
 * @brief of_iomap 函数本
质上也是将 reg 属性中地址信息转换为虚拟地址，如果 reg 属性有多段的话，可以通过 index 参数指定要完成内存映射的是哪一段.
 *
 * @param np - 设备节点.
 * @param index - reg 属性中要完成内存映射的段，如果 reg 属性只有一段的话 index 就设置为 0.
 *
 * @return 经过内存映射后的虚拟内存首地址，如果为 NULL 的话表示内存映射失败.
*******************************************************************************/
void __iomem *of_iomap(struct device_node *np, int index);