Documentation/devicetree/usage-model.rst

1 .. SPDX-License-Identifier: GPL-2.0
7 The Linux usage model for device tree data
11 This article describes how Linux uses the device tree.  An overview of
12 the device tree data format can be found on the device tree usage page
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.
29 is defined for how data should appear in the tree to describe typical
44 ----------
48 Device Tree to discover the topology of the hardware at runtime, and
54 Device Tree.
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
60 Tree (FDT) was created which could be passed to the kernel as a binary
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.
74 -------------
75 If you haven't already read the Device Tree Usage\ [1]_ page,
79 -------------------
84 hardware configuration from the board and device driver support in the
86 it allows board and device support to become data driven; to make
88 per-machine hard coded selections.
98 3) device population.
101 ---------------------------
105 perfectly by the device tree in a consistent and reliable manner.
108 machine-specific fixups.
115 table and selects the machine_desc which best matches the device tree
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 -------------------------
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.
207 several times with different helper callbacks to parse device tree
209 the device tree and uses the helpers to extract information required
217 scanning of the device tree after selecting the correct machine_desc
220 2.4 Device population
221 ---------------------
226 This is also when machine-specific setup hooks will get called, like
232 As can be guessed by the names, .init_early() is used for any machine-
241 is primarily responsible for populating the Linux device model with
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,
255 platform devices roughly correspond to device nodes at the root of the
256 tree and children of simple memory mapped bus nodes.
259 device tree for the NVIDIA Tegra board::
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>;
325 However, looking at the tree, it is not immediately obvious what kind
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
331 represents not a device, but rather how other devices are connected
332 together to create the audio subsystem.  I know what each device is
336 The trick is that the kernel starts at the root of the tree and looks
338 assumed that any node with a 'compatible' property represents a device
340 of the tree is either directly attached to the processor bus, or is a
341 miscellaneous system device that cannot be described any other way.
350 same hierarchy is also found in the DT, where I2C device nodes only
353 device are platform_devices (and amba_devices, but more on that
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
361 tree, there is no need to provide a starting node (the first NULL), a
362 parent struct device (the last NULL), and we're not using a match
370 is for child devices to be registered by the parent's device driver at
371 driver .probe() time.  So, an i2c bus device driver will register a
377 device, a (theoretical) SoC device driver could bind to the SoC device,
378 and register platform_devices for /soc/interrupt-controller, /soc/serial,
383 device tree support code reflects that and makes the above example
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 ------------------------
406 ARM Primecells are a certain kind of device attached to the ARM AMBA
417 device creation model a little bit, but the solution turns out not to