Documentation/devicetree/usage-model.rst

1 .. SPDX-License-Identifier: GPL-2.0
12 the device tree data format can be found on the device tree usage page
44 ----------
52 Since Open Firmware is commonly used on PowerPC and SPARC platforms,
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
61 blob without requiring a real Open Firmware implementation.  U-Boot,
66 existing non-DT aware firmware.
74 -------------
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
87 setup decisions based on data passed into the kernel instead of on
88 per-machine hard coded selections.
101 ---------------------------
108 machine-specific fixups.
111 kernel will instead select setup code based on the machine's core
112 CPU or SoC.  On ARM for example, setup_arch() in
125 successor, the BeagleBoard xM board might look like, respectively::
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
133 specific (exact board) to least specific (SoC family).
136 compatibility with the original Beagle board.  However, one should be
137 cautioned about doing so at the board level since there is typically a
138 high level of change from one board to another, even within the same
140 board claims to be compatible with another.  For the top level, it is
141 better to err on the side of caution and not claim one board is
143 board is a carrier for another, such as a CPU module attached to a
144 carrier board.
146 One more note on compatible values.  Any string used in a compatible
150 Again on ARM, for each machine_desc, the kernel looks to see if
155 on which entry in the compatible property each machine_desc matches
161 invariably there will be some exceptions where a specific board will
164 troublesome board(s) in generic setup code, but doing so very quickly
171 generic board support can claim compatibility with "ti,omap3" or
172 "ti,omap3450".  If a bug was discovered on the original beagleboard
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.
216 On ARM, the function setup_machine_fdt() is responsible for early
218 that supports the board.
221 ---------------------
222 After the board has been identified, and after the early configuration data
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-
242 data about the platform.  Historically this has been implemented on
244 platform_devices, and other data in the board support .c file, and
245 registering it en-masse in .init_machine().  When DT is used, then
253 by hardware, and for 'composite' or 'virtual' devices (more on those
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>;
323 At .init_machine() time, Tegra board support code will need to look at
333 because I'm familiar with the board design, but how does the kernel
353 device are platform_devices (and amba_devices, but more on that
358 Linux board support code calls of_platform_populate(NULL, NULL, NULL, NULL)
363 table (yet).  For a board that only needs to register devices,
376 children.  The board support code would allocate and register an SoC
378 and register platform_devices for /soc/interrupt-controller, /soc/serial,
395 "simple-bus" is defined in the Devicetree Specification as a property
397 could be written to just assume simple-bus compatible nodes will
399 board support code can always override the default behaviour.
404 ------------------------
410 not all devices on an AMBA bus are Primecells, and for Linux it is