Linux 核心：利用of_函式讀取裝置樹結點/屬性資訊

背景

裝置樹描述了裝置的詳細資訊，這些資訊包括數字型別的、字串型別的、陣列型別的，我們在編寫驅動的時候需要獲取到這些資訊。

Linux 核心給我們提供了一系列的函式來獲取裝置樹中的節點或者屬性資訊，這一系列的函式都有一個統一的字首“of_”，所以在很多資料裡面也被叫做 OF 。

這些 OF原型都定義在include/linux/of.h 檔案中。

我們看看在實際中如何使用裝置樹。

參考：

• https://blog.csdn.net/qq_43121830/article/details/104866557
• https://blog.csdn.net/qq_35031421/article/details/105107629

判斷根節點相容性OF函式

在Linux核心中，常常使用如下OF函式來判斷根節點的相容性：

int of_machine_is_compatible(const char *compat);

DT裝置的.dt_compat可能包含多個電路板，通過該函式可以判斷根節點compatible的屬性，當該函式的compat引數與根據點的compatible匹配時，返回一個正整數。
用法，例如：

of_machine_is_compatible("samsung,exynos4");

查詢節點的 OF

裝置都是以節點的形式“掛”到裝置樹上的，因此要想獲取這個裝置的其他屬性資訊，必
須先獲取到這個裝置的節點。 Linux 核心使用 device_node 結構體來描述一個節點，此結構體定義在檔案 include/linux/of.h

struct device_node {
	const char *name;  /*節點的名字*/
	const char *type;  /*裝置型別，來自節點中的device_type屬性, 如果沒有該屬性, 則設為"NULL"*/
	phandle phandle;
	const char *full_name;  /*節點的全名，node-name[@unit-address]*/
	struct fwnode_handle fwnode;

	struct	property *properties;  /*節點的屬性*/
	struct	property *deadprops;	/* removed properties */
	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)
	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： 要查詢的節點名字。

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

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_get_next_child

節點的屬性資訊裡面儲存了驅動所需要的內容，因此對於屬性值的提取非常重要， 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;
};

提取屬性值

Linux 核心也提供了提取屬性值的 OF。

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_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

resource結構體描述的都是裝置資源資訊， resource 結構體定義在檔案include/linux/ioport.h 中，定義如下：

struct resource {
	resource_size_t start; /*起始地址，對於32位soc，resource_size_t 的資料型別是u32*/
	resource_size_t end; /*結束地址*/
	const char *name;  /*資源的名字*/
	unsigned long flags; /*資源標誌位，一般表示資源型別,可選的資源標誌定義在檔案 include/linux/ioport.h,如IORESOURCE_BITS、IORESOURCE_MEM、IORESOURCE_IRQ等 */
	struct resource *parent, *sibling, *child;
};

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了。該函式的原型如下：

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

函式引數和返回值含義如下：

• np： 裝置節點。
• index： reg 屬性中要完成記憶體對映的段，如果 reg 屬性只有一段的話 index 就設定為 0。

返回值： 經過記憶體對映後的虛擬記憶體首地址，如果為 NULL 的話表示記憶體對映失敗。

例子

目的：期望通過linux/of.h中相關函式，在驅動中讀取裝置樹相關結點資訊和屬性資訊

要求：

• ①讀取裝置樹/backlight結點下的屬性，以及屬性資訊，合理處理返回值和錯誤資訊
• ②設計一個能夠讀取u32型別屬性的通用函式，並在init函式中輸出資訊

裝置樹

/ {
    backlight {
        compatible = "pwm-backlight";
        pwms = <&pwm1 0 5000000>;
        brightness-levels = <0 4 8 16 32 64 128 255>;
        default-brightness-level = <6>;
        status = "okay";
        wp-inverted ;
    };
};

驅動程式

/* 此檔案為linux 核心 of函式測試檔案
 *  實驗目的：在init函式中使用of函式讀取裝置樹中的 根節點下xxx裝置節點資訊
 *  其路徑為： 
 */

#include <linux/types.h>
#include <linux/kernel.h>
#include <linux/delay.h>
#include <linux/init.h>
#include <linux/module.h>
#include <linux/fs.h>
#include <linux/uaccess.h>
#include <linux/io.h>
#include <linux/cdev.h>
#include <linux/device.h>
#include <linux/of.h>
#include <linux/of_platform.h>
#include <linux/of_device.h>
#include <linux/slab.h>

struct device_node* ofdts_node;
struct property*    blprop;
int ret = 0;
const char* out_string;
int result = 0;
int mem_count = 0;
u32* out_values;
static u32 show_members(int mem_count, char* prop_name)
{
    u8 i;

    if(mem_count < 0){
        printk("fail_property_count_elems_of_size!!!\n");
        return -ENODEV;
    }
    else if (mem_count == 0)
    {   
        printk("%s中有%d個元素\n",prop_name, mem_count);
    }else if(mem_count == 1){
        printk("%s中有%d個元素\n",prop_name, mem_count);
        out_values = kmalloc(sizeof(u32) * mem_count,GFP_KERNEL);
        if(!out_values){
            printk("fail_mem\n");
            return -ENODEV;
        }
        ret = of_property_read_u32(ofdts_node, prop_name, out_values);
        if(ret < 0){
            printk("fail_read_u32!!!\n");
            kfree(out_values);
            return -ENODEV;
        }
        printk("%s中的元素為：%d\n",prop_name, *out_values);  
    }
    else{
        printk("%s中有%d個元素\n",prop_name, mem_count);
        out_values = kmalloc(sizeof(u32) * mem_count,GFP_KERNEL);
        ret = of_property_read_u32_array(ofdts_node, prop_name, out_values,mem_count);
        if(ret < 0){
            printk("fail_read_u32_array!!!\n");
            kfree(out_values);
            return -ENODEV;
        }
        printk("%s中有元素為:",prop_name); 
        for(i = 0; i < mem_count; i++){
            printk("%d\t",out_values[i]); 
        }
    }
    return 0;
}

static int __init ofdts_init(void)
{
    printk("\nofdts_initing.........\n");
    /* 0. 提取 backlight 節點*/
    ofdts_node = of_find_node_by_name(NULL, "backlight");
    if(!ofdts_node){
        goto fail_node;
    }else{
        printk("0. 獲取節點：%s 成功~\n", ofdts_node->name);
    }

    /* 1. 獲取compatible = "pwm-backlight"  和 status = "okay"這倆都是字串型別的，使用兩個不同的函式分別測試*/
    // 1 compatible
    ret = of_property_read_string(ofdts_node, "compatible", &out_string);
    if(ret < 0){
        goto fail_property_read_string;
    }else{
        printk("1.0 獲取compatible成功：%s\n", out_string);
    }
    // 2 status
    blprop = of_find_property(ofdts_node, "status", NULL);
    if(!blprop){
        goto fail_find_property;
    }else{
        printk("1.1 獲取status成功：%s\n", (char*)blprop->value);
    }

    /* 2. 獲取default-brightness-level = <6>; */
    mem_count = of_property_count_elems_of_size(ofdts_node, "default-brightness-level", sizeof(u32));
    result = show_members(mem_count, "default-brightness-level");
    if(result < 0){
        return result;
    }
    /* 3. brightness-levels = <0 4 8 16 32 64 128 255>; */
    mem_count = of_property_count_elems_of_size(ofdts_node, "brightness-levels", sizeof(u32));
    result = show_members(mem_count, "brightness-levels");

    printk("ofdts_init.........OK!!!\n");   
    return result;

    fail_find_property:
    fail_property_read_string:
    printk("fail_property_read_string!!!\n");
    return -ENODEV;
    fail_node:
    printk("fail_find_node_byname!!!\n");
    return -ENODEV;
}


static void __exit ofdts_exit(void)
{
    kfree(out_values);
    printk("ofdts_exit.........OK!!!\n");
}



/* 註冊函式 */
module_init(ofdts_init);
module_exit(ofdts_exit);

/* license和作者*/
MODULE_LICENSE("GPL");
MODULE_AUTHOR("QJY");

注意：程式能夠測試通過，可能返回值處理以及錯誤處理有不合理之處，作者並未排查，本程式僅作為練習測試使用；

測試結果：

lib/modules/4.1.15 #modprobe ofdts
ofdts_initing. . . .. . . . .
0．獲取節點: backlight成功~
1.0獲取compatible成功:pwm-backlight
1.1 獲取status成功:okay
default-brightness-level中有1個元素
default-brightness-level中的元素為:6
brightness-levels中有8個元素
brightness-levels中有元素為:0 4 8 16 32 64 128 255
ofdts_init....OK!!