1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
@page page_device_ofw_base OFW nodes and properties
# OFW core (`base.c`, `ofw.c`)
Node tree, properties, phandles, matching, stubs, and **`rt_ofw_parse_object`**. Boot: @ref page_device_ofw_boot. IO: @ref page_device_ofw_io. IRQ: @ref page_device_ofw_irq.
Headers: **`drivers/ofw.h`**. Sources: **`components/drivers/ofw/base.c`**, **`ofw.c`**.
---
## Core types
| Type | Role |
| --- | --- |
| **`struct rt_ofw_prop`** | Property list entry: **`name`**, **`length`**, **`value`** |
| **`struct rt_ofw_node`** | **`full_name`**, **`phandle`**, **`props`**, tree links, **`ref`**, **`flags`**, **`rt_data`**, optional **`dev`** |
| **`struct rt_ofw_cell_args`** | Parsed phandle + specifier (**`args[]`**, max **`RT_OFW_MAX_CELL_ARGS`**) |
| **`struct rt_ofw_node_id`** | **`compatible`** / **`name`** / **`type`** match table row |
| **`struct rt_ofw_stub`** | Early probe: **`ids`**, **`handler(np, id)`** |
### Node flags (`RT_OFW_F_*`)
| Flag | Meaning |
| --- | --- |
| **`RT_OFW_F_SYSTEM`** | Meta node (`/`, `/cpus`, `/chosen`, …) — platform walk skips |
| **`RT_OFW_F_READLY`** | Stub or driver already bound |
| **`RT_OFW_F_PLATFORM`** | **`rt_platform_device`** created |
| **`RT_OFW_F_OVERLAY`** | From applied DT overlay |
APIs: **`rt_ofw_node_set_flag`**, **`rt_ofw_node_test_flag`**, **`rt_ofw_node_clear_flag`**.
---
## Lifetime
| API | Role |
| --- | --- |
| **`rt_ofw_node_get` / `rt_ofw_node_put`** | Reference count on **`np`** |
| **`rt_ofw_node_destroy`** | Tear down subtree when applicable |
| **`rt_ofw_data(np)`** | Driver private pointer in **`np->rt_data`** |
---
## Finding nodes
| API | Role |
| --- | --- |
| **`rt_ofw_find_node_by_path`** | Absolute path (`/soc/uart@1000`) |
| **`rt_ofw_find_node_by_compatible`** | DFS from **`from`** (**`RT_NULL`** = whole tree) |
| **`rt_ofw_find_node_by_ids` / `_r`** | Match **`rt_ofw_node_id`** table |
| **`rt_ofw_find_node_by_phandle`** | Resolve numeric phandle |
| **`rt_ofw_find_node_by_name`**, **`_by_prop`**, **`_by_tag`**, **`_by_type`** | Other keys |
| **`rt_ofw_get_parent`**, **`rt_ofw_get_next_*`** | Walk tree |
| **`rt_ofw_foreach_*` macros** | Prefer macros in **`ofw.h`** over manual sibling loops |
**Availability**: **`rt_ofw_node_is_available`** (**`status`**), **`rt_ofw_machine_is_compatible`** (root).
---
## Properties
| API | Role |
| --- | --- |
| **`rt_ofw_get_prop`** | Find property by name |
| **`rt_ofw_prop_read_raw`** | Blob + length |
| **`rt_ofw_prop_read_u8/u16/u32/s32/u64/string/bool`** | Typed index 0 |
| **`rt_ofw_prop_read_*_index`**, **`*_array_index`** | Multi-element |
| **`rt_ofw_prop_count_of_u32`** (etc.) | Element count |
| **`rt_ofw_append_prop`** | Runtime append (rare) |
---
## Phandles
| API | Role |
| --- | --- |
| **`rt_ofw_parse_phandle`** | Single phandle property by index |
| **`rt_ofw_parse_phandle_cells`** | List + **`#*-cells`** → **`rt_ofw_cell_args`** |
| **`rt_ofw_count_phandle_cells`** | Entry count in list |
| **`rt_ofw_parse_object`** | Find named object in composite **`rt_ofw_data`** |
**`ofw.c`** registers **`#clock-cells`**, **`#reset-cells`**, **`#power-domain-cells`** object layouts when those subsystems are enabled.
---
## Matching and stubs
| API / macro | Role |
| --- | --- |
| **`rt_ofw_node_match`**, **`rt_ofw_prop_match`** | Match **`compatible`** against **`rt_ofw_node_id[]`** |
| **`RT_OFW_STUB_EXPORT`** | Link stub into **`.rt_ofw_data.stub.*`** |
| **`rt_ofw_stub_probe_range`** | Run stubs on a node (class ranges via **`RT_OFW_STUB_RANGE_EXPORT`**) |
Used by early serial, hwcache, and other non-platform bindings.
---
## Aliases and CPU
| API | Role |
| --- | --- |
| **`rt_ofw_get_alias_node`**, **`rt_ofw_get_alias_id`** | **`/aliases`** resolution |
| **`rt_ofw_get_cpu_node`**, **`rt_ofw_foreach_cpu_node`** | CPU nodes under **`/cpus`** |
| **`rt_ofw_get_cpu_id`**, **`rt_ofw_get_cpu_hwid`** | MPIDR / hardware ID |
| **`rt_ofw_map_id`** | Generic **`*-map`** / **`*-map-mask`** lookup |
**`ofw_alias_scan`** runs during unflatten (**`base.c`**).
---
## Console and debug
| API | Role |
| --- | --- |
| **`rt_ofw_console_setup`** | Console from **`/chosen`** |
| **`rt_ofw_node_dump_dts`** | Print subtree as DTS-like text (**`RT_USING_CONSOLE`**) |
---
## Pitfalls
| Issue | Mitigation |
| --- | --- |
| Leaked **`np`** | Always **`put`** after **`get`** |
| Wrong phandle index | Check **`rt_ofw_count_phandle_cells`** and **`*-names`** |
| **`compatible` order** | Most specific first in driver **`ids[]`** |
| **`rt_ofw_data` before probe** | **`rt_platform_ofw_request`** on provider |
## See also
- @ref page_device_ofw
- @ref page_device_ofw_platform
- @ref page_device_ofw_io
- @ref page_device_ofw_irq
|
