Linux 設備樹操作API

Linux設備樹語法詳解一文中介紹了設備樹的語法，這裡主要介紹內核中提供的操作設備樹的API，這些API通常都在"include/of.h"中聲明。

device_node

內核中用下面的這個結構描述設備樹中的一個節點，後面的API都需要一個device_node對象作為參數傳入。

//include/of.h
 46 struct device_node {
 47         const char *name;
 48         const char *type;
 49         phandle phandle;
 50         const char *full_name;
 51 
 52         struct  property *properties;
 53         struct  property *deadprops;    /* removed properties */
 54         struct  device_node *parent;
 55         struct  device_node *child;
 56         struct  device_node *sibling;
 57         struct  device_node *next;      /* next device of same type */
 58         struct  device_node *allnext;   /* next in list of all nodes */
 59         struct  proc_dir_entry *pde;    /* this node's proc directory */
 60         struct  kref kref;
 61         unsigned long _flags;
 62         void    *data;
 63 #if defined(CONFIG_SPARC)
 64         const char *path_component_name;
 65         unsigned int unique_id;
 66         struct of_irq_controller *irq_trans;
 67 #endif
 68 };

struct device_node
--47-->節點名
--48-->設備類型
--50-->全路徑節點名
--54-->父節點指針
--55-->子節點指針

查找節點API

/**
 * of_find_compatible_node - 通過compatible屬性查找指定節點
 * @from - 指向開始路徑的節點，如果為NULL，則從根節點開始
 * @type - device_type設備類型，可以為NULL
 * @compat - 指向節點的compatible屬性的值（字符串）的首地址
 * 成功：得到節點的首地址；失敗：NULL
 */
struct device_node *of_find_compatible_node(struct device_node *from,const char *type, const char *compat);

/**
 * of_find_matching_node - 通過compatible屬性查找指定節點
 * @from - 指向開始路徑的節點，如果為NULL，則從根節點開始
 * @matches - 指向設備ID表，注意ID表必須以NULL結束
 * 范例：  const struct of_device_id mydemo_of_match[] = {
                { .compatible = "fs4412,mydemo", },
                {}
            };      
 * 成功：得到節點的首地址；失敗：NULL
 */
struct device_node *of_find_matching_node(struct device_node *from,const struct of_device_id *matches);

/**
 * of_find_node_by_path - 通過路徑查找指定節點
 * @path - 帶全路徑的節點名，也可以是節點的別名
 * 成功：得到節點的首地址；失敗：NULL
 */
struct device_node *of_find_node_by_path(const char *path);

/**
 * of_find_node_by_name - 通過節點名查找指定節點
 * @from - 開始查找節點，如果為NULL，則從根節點開始
 * @name- 節點名
 *  成功：得到節點的首地址；失敗：NULL
 */
struct device_node *of_find_node_by_name(struct device_node *from,const char *name);

提取通用屬性API

/** 
 * of_find_property - 提取指定屬性的值
 * @np - 設備節點指針
 * @name - 屬性名稱
 * @lenp - 屬性值的字節數
 * 成功：屬性值的首地址；失敗：NULL
 */
struct property *of_find_property(const struct device_node *np, const char *name, int *lenp);

/**
 * of_property_count_elems_of_size - 得到屬性值中數據的數量
 * @np - 設備節點指針
 * @propname  - 屬性名稱
 * @elem_size - 每個數據的單位（字節數）
 * 成功：屬性值的數據個數；失敗：負數，絕對值是錯誤碼
 */
int of_property_count_elems_of_size(const struct device_node *np,const char *propname, int elem_size);

/** 
 * of_property_read_u32_index - 得到屬性值中指定標號的32位數據值
 * @np - 設備節點指針
 * @propname  - 屬性名稱
 * @index  - 屬性值中指定數據的標號
 * @out_value - 輸出參數，得到指定數據的值
 * 成功：0；失敗：負數，絕對值是錯誤碼
 */
int of_property_read_u32_index(const struct device_node *np, const char *propname, u32 index, u32 *out_value);

/**
 * of_property_read_string - 提取字符串（屬性值）
 * @np - 設備節點指針
 * @propname  - 屬性名稱
 * @out_string - 輸出參數，指向字符串（屬性值）
 * 成功：0；失敗：負數，絕對值是錯誤碼
 */
int of_property_read_string(struct device_node *np, const char *propname, const char **out_string);

提取addr屬性API

/**
 * of_n_addr_cells - 提取默認屬性“#address-cells”的值
 * @np - 設備節點指針
 * 成功：地址的數量；失敗：負數，絕對值是錯誤碼
 */
int of_n_addr_cells(struct device_node *np);

/**
 * of_n_size_cells - 提取默認屬性“#size-cells”的值
 * @np - 設備節點指針
 * 成功：地址長度的數量；失敗：負數，絕對值是錯誤碼
 */
int of_n_size_cells(struct device_node *np);

/**
 * of_get_address - 提取I/O口地址
 * @np - 設備節點指針
 * @index - 地址的標號
 * @size - 輸出參數，I/O口地址的長度
 * @flags - 輸出參數，類型（IORESOURCE_IO、IORESOURCE_MEM）
 * 成功：I/O口地址的首地址；失敗：NULL
 */
__be32 *of_get_address(struct device_node *dev, int index, u64 *size, unsigned int *flags);

/**
 * of_translate_address - 從設備樹中提取I/O口地址轉換成物理地址
 * @np - 設備節點指針
 * @in_addr - 設備樹提取的I/O地址
 * 成功：物理地址；失敗：OF_BAD_ADDR
 */
u64 of_translate_address(struct device_node *dev, const __be32 *in_addr);

/**
 * of_iomap - 提取I/O口地址並映射成虛擬地址
 * @np - 設備節點指針
 * @index - I/O地址的標號
 * 成功：映射好虛擬地址；失敗：NULL
 */
void __iomem *of_iomap(struct device_node *np, int index);

/**
 * 功能：提取I/O口地址並申請I/O資源及映射成虛擬地址
 * @np - 設備節點指針
 * @index - I/O地址的標號
 * @name - 設備名，申請I/O地址時使用
 * 成功：映射好虛擬地址；失敗：NULL
 */
void __iomem *of_io_request_and_map(struct device_node *np, int index, const char *name);

提取resource屬性API

/** 
 * of_address_to_resource - 從設備樹中提取資源resource（I/O地址）
 * @np - 設備節點指針
 * @index - I/O地址資源的標號
 * @r - 輸出參數，指向資源resource（I/O地址） 
 * 成功：0；失敗：負數，絕對值是錯誤碼
 */
int of_address_to_resource(struct device_node *dev, int index, struct resource *r);

提取GPIO屬性API

/**
 * include/of_gpio.h
 * of_get_named_gpio - 從設備樹中提取gpio口
 * @np - 設備節點指針
 * @propname - 屬性名
 * @index - gpio口引腳標號 
 * 成功：得到GPIO口編號；失敗：負數，絕對值是錯誤碼
 */
int of_get_named_gpio(struct device_node *np, const char *propname, int index);

提取irq屬性API

/**
 * of_irq_count從設備樹中提取中斷的數量
 * @np - 設備節點指針
 * 成功：大於等於0，實際中斷數量，0則表示沒有中斷
 */
int of_irq_count(struct device_node *dev);

/**
 * of_irq_get - 從設備樹中提取中斷號
 * @np - 設備節點指針
 * @index - 要提取的中斷號的標號
 * 成功：中斷號；失敗：負數，其絕對值是錯誤碼
int of_irq_get(struct device_node *dev, int index);

提取其他屬性API

/** 
 * of_get_mac_address - 從設備樹中提取MAC地址
 * @np - 設備節點指針
 * @成功：MAC（6字節）的首地址；失敗：NULL
 */
void *of_get_mac_address(struct device_node *np);