Lines Matching +full:a +full:- +full:child +full:- +full:node +full:- +full:property
1 .. SPDX-License-Identifier: GPL-2.0
17 The "Open Firmware Device Tree", or simply Devicetree (DT), is a data
19 is a description of hardware that is readable by an operating system
23 Structurally, the DT is a tree, or acyclic graph with named nodes, and
25 arbitrary data. A mechanism also exists to create arbitrary
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
44 ----------
46 communication method for passing data from Open Firmware to a client
49 thereby support a majority of available hardware without hard coded
53 the Linux support for those architectures has for a long time used 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
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,
62 kexec, and other bootloaders were modified to support both passing a
63 Device Tree Binary (dtb) and to modify a dtb at boot time. DT was
65 a dtb could be wrapped up with the kernel image to support booting
66 existing non-DT aware firmware.
74 -------------
79 -------------------
80 The most important thing to understand is that the DT is simply a data
83 go away. What it does do is provide a language for decoupling the
88 per-machine hard coded selections.
91 duplication and make it easier to support a wide range of hardware
92 with a single kernel image.
101 ---------------------------
103 specific machine. In a perfect world, the specific platform shouldn't
105 perfectly by the device tree in a consistent and reliable manner.
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
137 cautioned about doing so at the board level since there is typically a
143 board is a carrier for another, such as a CPU module attached to a
146 One more note on compatible values. Any string used in a compatible
147 property must be documented as to what it indicates. Add
151 any of the dt_compat list entries appear in the compatible property.
152 If one does, then that machine_desc is a candidate for driving the
155 on which entry in the compatible property each machine_desc matches
159 of cases, a single machine_desc can support a large number of boards
161 invariably there will be some exceptions where a specific board will
165 becomes ugly and/or unmaintainable if it is more than just a couple of
168 Instead, the compatible list allows a generic machine_desc to provide
169 support for a wide common set of boards by specifying "less
172 "ti,omap3450". If a bug was discovered on the original beagleboard
173 that required special workaround code during early boot, then a new
175 matches on "ti,omap3-beagleboard".
177 PowerPC uses a slightly different scheme where it calls the .probe()
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,
221 ---------------------
225 to convert the data into a more efficient runtime representation.
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
243 embedded platforms by defining a set of static clock structures,
245 registering it en-masse in .init_machine(). When DT is used, then
251 registering a block of platform_devices. A platform_device is a concept
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>;
308 wm8903: codec@1a {
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
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
334 know what to do with each node?
337 for nodes that have a 'compatible' property. First, it is generally
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
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
343 platform_device, which in turn may get bound to a platform_driver.
345 Why is using a platform_device for these nodes a safe assumption?
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
355 tree. Therefore, if a DT node is at the root of the tree, then it
356 really probably is best registered as a platform_device.
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
363 table (yet). For a board that only needs to register devices,
368 what about the children of the SoC node? Shouldn't they be registered
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
372 i2c_client for each child node, an SPI bus driver will register
374 According to that model, a driver could be written that binds to the
375 SoC node and simply registers platform_devices for each of its
377 device, a (theoretical) SoC device driver could bind to the SoC device,
378 and register platform_devices for /soc/interrupt-controller, /soc/serial,
382 platform_devices as more platform_devices is a common pattern, and the
385 of_device_id table, and any node that matches an entry in that table
386 will also get its child nodes registered. In the Tegra case, the code
395 "simple-bus" is defined in the Devicetree Specification as a property
396 meaning a simple memory mapped bus, so the of_platform_populate() code
397 could be written to just assume simple-bus compatible nodes will
401 [Need to add discussion of adding i2c/spi/etc child devices]
403 Appendix A: AMBA devices
404 ------------------------
406 ARM Primecells are a certain kind of device attached to the ARM AMBA
415 because it must decide whether to register each node as either a
417 device creation model a little bit, but the solution turns out not to
418 be too invasive. If a node is compatible with "arm,primecell", then
419 of_platform_populate() will register it as an amba_device instead of a