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
26 links from one node to another outside of the natural tree structure.
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
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
175 matches on "ti,omap3-beagleboard".
184 -------------------------
185 In most cases, a DT will be the sole method of communicating data from
190 Most of this data is contained in the /chosen node, and when booting
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
202 match the usual semantic of struct resource.  The chosen node may also
204 platform-specific configuration data.
211 is used to parse the chosen node including kernel parameters,
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.
326 of device each node represents, or even if a node represents a device
329 considered a device).  The children of the /soc node are memory mapped
330 devices, but the codec@1a is an i2c device, and the sound node
334 know what to do with each node?
338 assumed that any node with a 'compatible' property represents a device
339 of some kind, and second, it can be assumed that any node at the root
350 same hierarchy is also found in the DT, where I2C device nodes only
351 ever appear as children of an I2C bus node.  Ditto for SPI, MDIO, USB,
355 tree.  Therefore, if a DT node is at the root of the tree, then it
361 tree, there is no need to provide a starting node (the first NULL), a
368 what about the children of the SoC node?  Shouldn't they be registered
369 as platform devices too?  For Linux DT support, the generic behaviour
372 i2c_client for each child node, an SPI bus driver will register
375 SoC node and simply registers platform_devices for each of its
378 and register platform_devices for /soc/interrupt-controller, /soc/serial,
385 of_device_id table, and any node that matches an entry in that table
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()
415 because it must decide whether to register each node as either a
418 be too invasive.  If a node is compatible with "arm,primecell", then