Documentation/devicetree/usage-model.rst

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
28 Conceptually, a common set of usage conventions, called 'bindings',
37 however, of creating a new binding without first doing some homework
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
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
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
91 duplication and make it easier to support a wide range of hardware
92 with a single kernel image.
103 specific machine.  In a perfect world, the specific platform shouldn't
105 perfectly by the device tree in a consistent and reliable manner.
121 The 'compatible' property contains a sorted list of strings starting
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
152 If one does, then that machine_desc is a candidate for driving the
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
177 PowerPC uses a slightly different scheme where it calls the .probe()
185 In most cases, a DT will be the sole method of communicating data from
225 to convert the data into a more efficient runtime representation.
230 thing when using a DT.
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,
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
308 			wm8903: codec@1a {
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
337 for nodes that have a 'compatible' property.  First, it is generally
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
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
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,
371 driver .probe() time.  So, an i2c bus device driver will register a
374 According to that model, a driver could be written that binds to the
377 device, a (theoretical) SoC device driver could bind to the SoC device,
382 platform_devices as more platform_devices is a common pattern, and the
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
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