Documentation/devicetree/usage-model.rst

1 .. SPDX-License-Identifier: GPL-2.0
11 This article describes how Linux uses the device tree.  An overview of
19 is a description of hardware that is readable by an operating system
20 so that the operating system doesn't need to hard code details of the
24 nodes may have an arbitrary number of named properties encapsulating
26 links from one node to another outside of the natural tree structure.
28 Conceptually, a common set of usage conventions, called 'bindings',
34 maximize use of existing support code, but since property and node
37 however, of creating a new binding without first doing some homework
40 binding was created without first investigating how i2c devices were
44 ----------
45 The DT was originally created by Open Firmware as part of the
48 Device Tree to discover the topology of the hardware at runtime, and
49 thereby support a majority of available hardware without hard coded
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
58 powerpc platforms, regardless of whether or not they used Open
61 blob without requiring a real Open Firmware implementation.  U-Boot,
65 a dtb could be wrapped up with the kernel image to support booting
66 existing non-DT aware firmware.
69 all architectures.  At the time of this writing, 6 mainlined
71 out of mainline (nios) have some level of DT support.
74 -------------
79 -------------------
87 setup decisions based on data passed into the kernel instead of on
88 per-machine hard coded selections.
91 duplication and make it easier to support a wide range of hardware
101 ---------------------------
108 machine-specific fixups.
110 In the majority of cases, the machine identity is irrelevant, and the
121 The 'compatible' property contains a sorted list of strings starting
122 with the exact name of the machine, followed by an optional list of
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
132 of SoCs in general.  You'll notice that the list is sorted from most
138 high level of change from one board to another, even within the same
141 better to err on the side of caution and not claim one board is
151 any of the dt_compat list entries appear in the compatible property.
153 machine.  After searching the entire table of machine_descs,
159 of cases, a single machine_desc can support a large number of boards
160 if they all use the same SoC, or same family of SoCs.  However,
165 becomes ugly and/or unmaintainable if it is more than just a couple of
169 support for a wide common set of boards by specifying "less
175 matches on "ti,omap3-beagleboard".
179 However, this approach does not take into account the priority of the
184 -------------------------
185 In most cases, a DT will be the sole method of communicating data from
188 of an initrd image.
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-*
200 properties define the address and size of an initrd blob.  Note that
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
203 optionally contain an arbitrary number of additional properties for
204 platform-specific configuration data.
214 location of usable RAM.
217 scanning of the device tree after selecting the correct machine_desc
221 ---------------------
226 This is also when machine-specific setup hooks will get called, like
228 on ARM.  The remainder of this section uses examples from the ARM
232 As can be guessed by the names, .init_early() is used for any machine-
235 doesn't materially change the behaviour of either of these functions.
237 to call any of the DT query functions (of_* in include/linux/of*.h) to
243 embedded platforms by defining a set of static clock structures,
245 registering it en-masse in .init_machine().  When DT is used, then
246 instead of hard coding static devices for each platform, the list of
251 registering a block of platform_devices.  A platform_device is a concept
255 platform devices roughly correspond to device nodes at the root of the
256 tree and children of simple memory mapped bus nodes.
258 About now is a good time to lay out an example.  Here is part of the
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>;
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
336 The trick is that the kernel starts at the root of the tree and looks
339 of some kind, and second, it can be assumed that any node at the root
340 of the tree is either directly attached to the processor bus, or is a
342 For each of these nodes, Linux allocates and registers a
347 assume that its devices are children of a bus controller.  For
348 example, each i2c_client is a child of an i2c_master.  Each spi_device
349 is a child of an SPI bus.  Similarly for USB, PCI, MDIO, etc.  The
351 ever appear as children of an I2C bus node.  Ditto for SPI, MDIO, USB,
352 etc.  The only devices which do not require a specific type of parent
354 later), which will happily live at the base of the Linux /sys/devices
355 tree.  Therefore, if a DT node is at the root of the tree, then it
359 to kick off discovery of devices at the root of the tree.  The
360 parameters are all NULL because when starting from the root of the
368 what about the children of the SoC node?  Shouldn't they be registered
375 SoC node and simply registers platform_devices for each of its
378 and register platform_devices for /soc/interrupt-controller, /soc/serial,
381 Actually, it turns out that registering children of some
395 "simple-bus" is defined in the Devicetree Specification as a property
397 could be written to just assume simple-bus compatible nodes will
401 [Need to add discussion of adding i2c/spi/etc child devices]
404 ------------------------
406 ARM Primecells are a certain kind of device attached to the ARM AMBA
412 siblings of the same bus segment.
419 of_platform_populate() will register it as an amba_device instead of a