Documentation/devicetree/usage-model.rst

1 .. SPDX-License-Identifier: GPL-2.0
17 The "Open Firmware Device Tree", or simply Devicetree (DT), is a data
23 Structurally, the DT is a tree, or acyclic graph with named nodes, and
34 maximize use of existing support code, but since property and node
44 ----------
45 The DT was originally created by Open Firmware as part of the
56 In 2005, when PowerPC Linux began a major cleanup and to merge 32-bit
57 and 64-bit support, the decision was made to require DT support on all
59 Firmware.  To do this, a DT representation called the Flattened Device
61 blob without requiring a real Open Firmware implementation.  U-Boot,
63 Device Tree Binary (dtb) and to modify a dtb at boot time.  DT was
66 existing non-DT aware firmware.
71 out of mainline (nios) have some level of DT support.
74 -------------
79 -------------------
80 The most important thing to understand is that the DT is simply a data
88 per-machine hard coded selections.
94 Linux uses DT data for three major purposes:
101 ---------------------------
102 First and foremost, the kernel will use data in the DT to identify the
108 machine-specific fixups.
117 property in the root device tree node, and comparing it with the
121 The 'compatible' property contains a sorted list of strings starting
127 	compatible = "ti,omap3-beagleboard", "ti,omap3450", "ti,omap3";
128 	compatible = "ti,omap3-beagleboard-xm", "ti,omap3450", "ti,omap3";
130 Where "ti,omap3-beagleboard-xm" specifies the exact model, it also
147 property must be documented as to what it indicates.  Add
151 any of the dt_compat list entries appear in the compatible property.
155 on which entry in the compatible property each machine_desc matches
175 matches on "ti,omap3-beagleboard".
184 -------------------------
185 In most cases, a DT will be the sole method of communicating data from
195 		initrd-start = <0xc8000000>;
196 		initrd-end = <0xc8200000>;
199 The bootargs property contains the kernel arguments, and the initrd-*
201 initrd-end is the first address after the initrd image, so this doesn't
204 platform-specific configuration data.
212 early_init_dt_scan_root() to initialize the DT address space model,
221 ---------------------
226 This is also when machine-specific setup hooks will get called, like
230 thing when using a DT.
232 As can be guessed by the names, .init_early() is used for any machine-
234 and .init_irq() is used to set up interrupt handling.  Using a DT
236 If a DT is provided, then both .init_early() and .init_irq() are able
237 to call any of the DT query functions (of_* in include/linux/of*.h) to
240 The most interesting hook in the DT context is .init_machine() which
245 registering it en-masse in .init_machine().  When DT is used, then
247 devices can be obtained by parsing the DT, and allocating device
254 later).  While there is no 'platform device' terminology for the DT,
263 	#address-cells = <1>;
264 	#size-cells = <1>;
265 	interrupt-parent = <&intc>;
276 		compatible = "nvidia,tegra20-soc", "simple-bus";
277 		#address-cells = <1>;
278 		#size-cells = <1>;
281 		intc: interrupt-controller@50041000 {
282 			compatible = "nvidia,tegra20-gic";
283 			interrupt-controller;
284 			#interrupt-cells = <1>;
289 			compatible = "nvidia,tegra20-uart";
295 			compatible = "nvidia,tegra20-i2s";
302 			compatible = "nvidia,tegra20-i2c";
303 			#address-cells = <1>;
304 			#size-cells = <0>;
317 		compatible = "nvidia,harmony-sound";
318 		i2s-controller = <&i2s1>;
319 		i2s-codec = <&wm8903>;
324 this DT and decide which nodes to create platform_devices for.
337 for nodes that have a 'compatible' property.  First, it is generally
338 assumed that any node with a 'compatible' property represents a device
350 same hierarchy is also found in the DT, where I2C device nodes only
355 tree.  Therefore, if a DT node is at the root of the tree, then it
369 as platform devices too?  For Linux DT support, the generic behaviour
378 and register platform_devices for /soc/interrupt-controller, /soc/serial,
395 "simple-bus" is defined in the Devicetree Specification as a property
397 could be written to just assume simple-bus compatible nodes will
404 ------------------------
414 When using the DT, this creates problems for of_platform_populate()