とあるエンジニアの備忘log: Device Tree アクセス関数まとめ (Linux Kernel)

Linux Kernel の Device Tree 関連の関数をまとめました。

関数名は `of_` で始まり (OF = Open Firmware)、 `drivers/of/` ディレクトリ以下で定義されています。

### `of_n_addr_cells` (base.c:53)

int of_n_addr_cells(struct device_node *np)

ノード `np` の一つ上の親から上流に向かって探索し、 `#address-cells` プロパティが見つかるとその値を返す。
見つからない場合は、 `OF_ROOT_NODE_ADDR_CELLS_DEFAULT` を返す。

### `of_n_size_cells` (base.c:69)

int of_n_size_cells(struct device_node *np)

ノード `np` の一つ上の親から上流に向かって探索し、 `#size-cells` プロパティが見つかるとその値を返す。
見つからない場合は、 `OF_ROOT_NODE_SIZE_CELLS_DEFAULT` を返す。

### `of_node_get` (base.c:100)

struct device_node *of_node_get(struct device_node *node)

ノード `np` の参照カウンタを 1増やす。

### `of_find_property` (base.c:328)

struct property *of_find_property(const struct device_node *np,
                                      const char *name,
                                      int *lenp)

ノード `np` から `name` という名前のプロパティを探し、そのプロパティ構造体へのポインタを返す。
見つからなければ、`NULL` を返す。
`lenp` が与えられていれば、プロパティ値の長さを詰めて返す。

### `of_get_property` (base.c:383)

const void *of_get_property(const struct device_node *np, const char *name,
                                int *lenp)

ノード `np` から `name` という名前のプロパティを探し、そのプロパティ値へのポインタを返す。
該当するプロパティが見つからなければ `NULL` を返す。
`lenp` が与えられていれば、プロパティ値の長さを詰めて返す。

### `of_device_is_compatible` (base.c:566)

static int __of_device_is_compatible(const struct device_node *device,
                                         const char *compat)

ノード `np` がデバイス名 `compat` に対して compatible かどうかを調べる。
compatible なら 1、それ以外は 0 を返す。

ノード `np` の "compatible" という名前のプロパティの値に、文字列 `compat` が含まれるかどうかで判断される。

### `of_get_parent` (base.c:656)

struct device_node *of_get_parent(const struct device_node *node)

ノード `node` の親のノードを返す。

### `of_find_compatible_node` (base.c:870)

struct device_node *of_find_compatible_node(struct device_node *from,
            const char *type, const char *compatible)

全ノード中の `from` 以降から `compatible` に対して compatible なノードを探索する。

見つかれば、そのノードへのポインタを返す。
見つからない場合は、`NULL` を返す。

なお、`from` に `NULL` を渡した場合は、全ノードを探索する。
`from` は通常、前回の探索の続きを実行するときに用いられる。

`type` に `NULL` 以外が与えられていれば、 device_type に対してもマッチングが行われる。
(`type` と `compatible` のAND条件。)

`type` は Device Source Tree 中で `device_type` プロパティによって指定される。

### `of_match_node` (base.c:954)

const struct of_device_id *of_match_node(const struct of_device_id *matches,
                                             const struct device_node *node)

マッチングテーブル(の配列の先頭) `match` を探索し、ノード `node` に対して compatible かどうかを調べる。
compatible ならば、マッチングテーブルのエントリーを返し、 compatible でないなら `NULL` を返す。

### `of_find_matching_node_and_match` (base.c:981)

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` 以降から、マッチングテーブル `matches` に対して、 compatible なノードを探索する。

見つかると、マッチした マッチングテーブルのエントリーを `match` に詰め、ノードを返す。
見つからない場合は、 `NULL` を返す。

なお、`from` に `NULL` を渡した場合は、全ノードを探索する。
`from` は通常、前回の探索の続きを実行するときに用いられる。

### `of_find_node_by_phandle` (base.c:1041)

struct device_node *of_find_node_by_phandle(phandle handle)

全ノードの中から、phandle 番号 `handle` を持つノードを返す。
phandle は 1から始まる整数である。

見つからない場合は `NULL` を返す。

### `of_find_property_value_of_size` (base.c:1101)

static void *of_find_property_value_of_size(const struct device_node *np,
                            const char *propname, u32 len)

ノード `np` から `propname` という名前のプロパティを探し、そのプロパティ値へのポインタを返す。
その際、プロパティ値の長さチェックが行われる。
プロパティ値の長さが、 `len` に満たない場合は `-EOVERFLOW` を返す。

### `of_property_read_u32_array` (base.c:1228)

int of_property_read_u32_array(const struct device_node *np,
                                   const char *propname, u32 *out_values,
                                   size_t sz)

ノード `np` から `propname` という名前のプロパティを探し、プロパティ値を `sz * 4` byte 分、 `out_value` へコピーする。
プロパティ値の長さが `sz * 4` byte に満たない場合は、コピーは行われず、 `-EOVERFLOW` を返す。

### `of_property_read_u32` (of.h:692)

static inline int of_property_read_u32(const struct device_node *np,
                                           const char *propname,
                                           u32 *out_value)

ノード `np` から `propname` という名前のプロパティを探し、プロパティ値の先頭 4 byte を `out_value` へコピーする。
エラーが起きると、非ゼロを返す。

### `of_property_read_string_index` (base.c:1319)

int of_property_read_string_index(struct device_node *np, const char *propname,
                                      int index, const char **output)

ノード `np` の `propname` という名前のプロパティの値から、`index` 番目の文字列へのポインタを `output` に詰めて返す。
成功すると `0` を返す。

例えば、Device Tree Source で

node1 {
            prop1 = "foo", "bar";
    }

という記述になっていたとする。

`of_property_read_string_index(node1, "prop1", 1, output)` は `output` に `"bar"` をセットする。

### `of_property_match_string` (base.c:1356)

int of_property_match_string(struct device_node *np, const char *propname,
                                 const char *string)

ノード `np` から `propname` という名前のプロパティを探し、そのプロパティ値のリスト中から文字列 `string` を検索する。
見つかった場合、リスト中の index を返す。

例えば、Device Tree Source の記述が

clock-name = "foo", "bar";

のようであったとする。
その場合、

`of_property_match_string(np, "clock_name", "foo")` は `0` を

`of_property_match_string(np, "clock_name", "bar")` は `1` を返す。

`of_property_match_string(np, "clock_name", "baz")` は `-ENODATA` (見つからない)を返す。

### `of_parse_phandle_with_args` (base.c:1602)

int of_parse_phandle_with_args(const struct device_node *np, const char *list_name,
                                    const char *cells_name, int index,
                                    struct of_phandle_args *out_args)

ノード `np` から `list_name` という名前のプロパティを探し、そのプロパティ値 (phandle のリストになっている)
の中から、`index` 番目の phandle の情報を、 `out_args` に詰めて返す。
エラーが起きると、非ゼロを返す。
`out_args->np` には指している phandle のノードを、`out_args->args_count` には引数の個数、`out_args->args[]` には引数を詰める。

例えば、 Device Tree Source の記述が以下のようになっていたとする。
クロック情報を受け渡しするときの典型的な書き方である。

clk1: node1 {
            #clock-cells = <2>;
    }

clk2: node2 {
            #clock-cells = <1>;
    }

node3 {
            clocks = <&clk1 5 6>, <&clk2 7>
    }

この時、
`of_parse_phandle_with_args(node3, "clocks", "#clock-cells", 0, out_args);`

は `out_args` に `clk1` の情報を詰めて返す。

out_args->np = node1;
    out_args->args_count = 2;
    out_args->args[0] = 5;
    out_args->args[1] = 6;

といった具合。

`of_parse_phandle_with_args(node3, "clocks", "#clock-cells", 1, out_args);`

は `out_args` に `clk2` の情報を詰めて返す。

### `of_count_phandle_with_args` (base.c:1606)

int of_count_phandle_with_args(const struct device_node *np, const char *list_name,
                                   const char *cells_name)

ノード `np` の `list_name` という名前のプロパティに、 phandle とその引数の組みが
何組含まれているかを返す。

### `of_bus_default_count_cells` (address.c:50)

static void of_bus_default_count_cells(struct device_node *dev,
                                           int *addrc, int *sizec)

ノード `dev` の `#address-cells` および `#size-cells` の値をそれぞれ `addrc` と `sizec` に詰めて返す。

### `of_translate_address` (address.c:555)

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

ノード `dev` の アドレス `addr` を CPU View のアドレス空間に変換する。
ノードを上流に向かって探索し、`ranges` プロパティに記載されている変換ルールに従って、アドレス変換を行う。
この変換はルートノードに達するまで再帰的に行われる。

親ノードは必ず `range` プロパティを持っていなくてはならないが、値は空でもよい。
`range` プロパティの値が空の場合は 1:1変換が行われる。

### `of_get_address` (address.c:586)

const __be32 *of_get_address(struct device_node *dev, int index, u64 *size,
                        unsigned int *flags)

ノード `dev` の `index` 番目のアドレスとサイズ (通常は `reg` というプロパティの格納されている。PCIバスなどは異なる)を返す。

`size` が与えられていれば サイズを詰める。
`flags` が与えられていれば、通常バスの場合は `IORESOURCE_MEM` を詰める。
アドレスへのポインタを返す。

### `of_address_to_resource` (address.c:669)

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

ノード `dev` の `index` 番目のメモリリソース情報を `r` に詰めて返す。

具体的には、`reg` プロパティと親ノードの `range` プロパティによって CPU View に変換された物理アドレスが `r->start` と `r->end` にセットされる。
`reg-names` プロパティを持つ場合は、その値が `r->name` にセットされ、持たない場合は `dev->full_name` がセットされる。

### `of_iomap` (address.c:714)

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

ノード `np` の `index` 番目の物理アドレスを取得し、 `ioremap` を行い、仮想アドレスを返す。

とあるエンジニアの備忘log

2014年5月28日水曜日

Device Tree アクセス関数まとめ (Linux Kernel)

0 件のコメント:

コメントを投稿