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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
.. _bareboxdt:
Barebox devicetree handling and bindings
========================================
The preferred way of adding board support to barebox is to have devices
on non-enumerable buses probed from device tree.
barebox provide both the Linux OpenFirmware ``of_*`` and the libfdt ``fdt_`` APIs
for device tree parsing. The former makes porting the device tree specific
bits from Linux device drivers very straight forward, while the latter can be
used for very early (PBL) handling of flattened device trees, should this be
necessary.
Additionally, barebox has support for programmatically fixing up device trees
it passes to the kernel, either directly via ``of_register_fixup`` or via device
tree overlays.
Upstream Device Trees
---------------------
barebox regularly synchronizes with the Linux kernel device tree definitions
via the `kernel.org Split device-tree repository`_.
They are located under the top-level ``dts/`` directory.
Patches against ``dts/`` and its subdirectories are not accepted upstream.
.. _kernel.org Split device-tree repository: https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git/
barebox Device Trees
--------------------
For supporting architectures, barebox device trees are located in
``arch/$ARCH/dts``. Usually the barebox ``board.dts`` imports the upstream
device tree under ``dts/src/$ARCH`` with ``#include "$ARCH/board.dts"`` and
then extends it with barebox-specifics like :ref:`barebox,state`,
environment or boot-time device configuration.
Device Tree probing largely happens via compatible properties with no special
meaning to the node names themselves. It's thus paramount that any device tree
nodes extended in the barebox device tree are referenced by label (e.g.
``<&phandle>``, not by path, to avoid run-time breakage like this::
# Upstream dts/src/$ARCH/board.dts
/ {
leds {
led-red { /* formerly named red when the barebox DTS was written */
/* ... */
};
};
};
# barebox arch/$ARCH/dts/board.dts
#include <$ARCH/board.dts>
/ {
leds {
red {
barebox,default-trigger = "heartbeat";
};
};
};
In the previous example, a device tree sync with upstream resulted in a regression
as the former override became a new node with a single property without effect.
The preferred way around this is to use labels directly::
# Upstream dts/src/$ARCH/board.dts
/ {
leds {
status_led: red { };
};
};
# barebox arch/$ARCH/dts/board.dts
#include <$ARCH/board.dts>
&status_led {
barebox,default-trigger = "heartbeat";
};
If there's no label defined upstream for the node, but for a parent,
a new label can be constructed from that label and a relative path::
# Upstream dts/src/$ARCH/board.dts
/ {
led_controller: leds {
red { };
};
};
# barebox arch/$ARCH/dts/board.dts
#include <$ARCH/board.dts>
&{led_controller/red} {
barebox,default-trigger = "heartbeat";
};
As last resort, the full path shall be used::
&{/leds/red} {
barebox,default-trigger = "heartbeat";
};
Any of these three approaches would lead to a compile error should the
``/leds/red`` path be renamed or removed. This also applies to uses
of ``/delete-node/``.
Only exception to this rule are well-known node names that are specified by
the `specification`_ to be parsed by name. These are: ``chosen``, ``aliases``
and ``cpus``, but **not** ``memory``.
.. _specification: https://www.devicetree.org/specifications/
Device Tree Compiler
--------------------
barebox makes use of the ``dtc`` and ``fdtget`` and the underlying ``libfdt``
from the `Device-Tree Compiler`_ project.
.. _Device-Tree Compiler: https://git.kernel.org/pub/scm/utils/dtc/dtc.git
These utilities are built as part of the barebox build process. Additionally,
libfdt is compiled once more as part of the ``CONFIG_BOARD_ARM_GENERIC_DT``
if selected.
Steps to update ``scripts/dtc``:
* Place a ``git-checkout`` of the upstream ``dtc`` directory in the parent
directory of your barebox ``git-checkout``.
* Run ``scripts/dtc/update-dtc-source.sh`` from the top-level barebox directory.
* Wait till ``dtc`` build, test, install and commit conclude.
* Compile-test with ``CONFIG_BOARD_ARM_GENERIC_DT=y``.
* If ``scripts/dtc/Makefile`` or barebox include file changes are necessary,
apply them manually in a commit preceding the ``dtc`` update.
barebox-specific Bindings
-------------------------
Contents:
.. toctree::
:glob:
:maxdepth: 1
bindings/barebox/*
bindings/firmware/*
bindings/leds/*
bindings/misc/*
bindings/mtd/*
bindings/power/*
bindings/regulator/*
bindings/rtc/*
bindings/watchdog/*
Automatic Boot Argument Fixups to the Devicetree
------------------------------------------------
barebox automatically fixes up some boot and system information in the device tree.
In the device tree root, barebox fixes up
* serial-number (if available)
* machine compatible (if overridden)
In the ``chosen``-node, barebox fixes up
* barebox-version
* reset-source
* reset-source-instance (if available)
* reset-source-device (node-path, only if available)
* bootsource
* boot-hartid (only on RISC-V)
These values can be read from the booted linux system in ``/proc/device-tree/``
or ``/sys/firmware/devicetree/base``.
|
